pychum Documentation ¶

Author:

Rohit Goswami

1 Ecosystem Overview ¶

pychum is a library within the rgpycrumbs ecosystem that generates input files for simulation engines.

2 Getting Started ¶

2.1 Installation ¶

pip install pychum

For development:

git clone https://github.com/HaoZeke/pychum
cd pychum
uv sync --all-extras

2.2 Quick Example ¶

Generate an ORCA input file from TOML configuration:

# input.toml
[calculation]
type = "single_point"
functional = "PBE0"
basis = "def2-SVP"

[geometry]
method = "xyz"
file = "molecule.xyz"

pychum orca --config input.toml --output calculation.inp

3 Tutorials ¶

Step-by-step guides for common workflows:

Tutorial

4 Library API ¶

pychum is a library. The public API lives in pychum.main.

4.1 `render_orca(toml_path)`¶

Load a TOML configuration and return an ORCA input string.

4.2 `render_nwchem(pos_file, settings_path, ...)`¶

Generate an NWChem socket input file for eOn’s SocketNWChemPot.

5 Engine Details ¶

5.1 ORCA ¶

Details about ORCA input generation.

5.2 NWChem ¶

Details about NWChem input generation for eOn’s SocketNWChemPot.

6 Architecture ¶

6.1 Design Philosophy ¶

pychum is designed with the following principles:

Unit-aware: All physical quantities use pint for automatic unit conversion
Template-based: Jinja2 templates for flexible input generation
Type-safe: Full type hints with mypy validation
Workflow-ready: Integration with jobflow and Fireworks

6.2 Package Structure ¶

pychum/
├── main.py          # Public API (render_orca, render_nwchem)
├── _base.py         # Abstract base class
├── units.py         # pint unit registry
└── engine/          # Engine-specific generators
    ├── orca/        # ORCA input generation
    │   ├── config_loader.py   # TOML loading
    │   ├── _renderer.py       # Jinja2 rendering
    │   ├── _dataclasses.py    # Configuration dataclasses
    │   └── _blocks/           # Jinja2 templates
    └── eon/         # eOn/NWChem input generation
        ├── _renderer.py       # NWChem rendering
        └── _dataclasses.py    # NWChem dataclasses

7 Contributing ¶

See CONTRIBUTING.md for development setup and guidelines.