pychum Documentation

Ecosystem Overview

pychum generates simulation input files. It sits next to rgpycrumbs (core + CLI) and chemparseplot (parse + plot). pychum writes inputs; chemparseplot reads the outputs.

Getting Started

Installation

pip install pychum

For development:

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

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

Tutorials

Step-by-step guides for common workflows:

Tutorials

• Tutorial

How-to

How-to

• Installation Guide
• Frequently Asked Questions
• Troubleshooting Guide

Reference

Reference

• API Reference
  • pychum
• Glossary
• Used By

Explanation

Explanation

• How to Cite pychum
• Testing
• Release Process

Development

Development

• Developer Documentation
• Contributing Guidelines
• Input Generation Pipeline
• Template System
• Input Validation
• Dataclass Hierarchy
• ORCA Input Block System
• Lazy Imports
• Best Practices

Library API

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

render_orca(toml_path)

Load a TOML configuration and return an ORCA input string.

render_nwchem(pos_file, settings_path, ...)

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

Engine Details

ORCA

Details about ORCA input generation.

NWChem

Details about NWChem input generation for eOn’s SocketNWChemPot.

Architecture

Design Philosophy

pychum is designed with the following principles:

1. Inputs only: pychum writes engine inputs; suite unit conversion lives in chemparseplot.units

2. Template-based: Jinja2 templates for flexible input generation

3. Type-safe: Full type hints with mypy validation

4. Workflow-ready: Integration with jobflow and Fireworks

Package Structure

pychum/
├── main.py          # Public API (render_orca, render_nwchem)
├── _base.py         # Abstract base class
├── units.py         # deprecation stub; use chemparseplot.units
└── 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

Contributing

See CONTRIBUTING.md for development setup and guidelines.