Table of Contents

• About
  • Ecosystem Overview
  • Features
    • Supported Engines
  • Rationale
• Usage
• Development
  • Adding ORCA blocks
  • Documentation
    • Readme
• License

About

A pure-python project to generate input files for various common computational chemistry workflows. This means:

• Generating input structures for jobflow / Fireworks
  • From unified toml inputs
• ORCA blocks (NEB, geometry scans, extras) and eOn renderers via Jinja templates
• Shared units and helpers with rgpycrumbs (rgpycrumbs>=1.9.16). Suite pins/config live in rgpkgs (~/.config/rgpkgs/config.toml, project rgpkgs.toml) — pychum does not define its own pin file

This is a spin-off from wailord (here) which is meant to handle aggregated runs in a specific workflow, while pychum is meant to generate single runs. It is also a companion to chemparseplot (v1.8+ recommended) which provides uniform visualizations for the outputs of various computational chemistry programs. Install with pip install pychum (Python ≥3.10); develop with pixi run -e test test or uv sync --extra test.

Ecosystem Overview

pychum is part of the rgpycrumbs suite of interlinked libraries.

Features

• Jobflow support
  • Along with Fireworks
• Unit aware conversions
  • Via pint

Supported Engines

• NEB calculations
  • ORCA
  • EON
• Single point calculations
  • ORCA
  • EON

Rationale

I needed to run a bunch of systems. jobflow / Fireworks / AiiDA were ideal, until I realized only VASP is really well supported by them.

Also there were some minor problems with the ORCA input parser…

• It chokes on multiple # symbols, so # MaxIter 50 # something will error out on SOMETHING
• No real ordering or syntax highlighting in major IDEs

Along with other minor inconveniences which make for enough friction over time to necessitate this library.

Usage

The simplest usage is via the CLI:

uv run pychum --help
# Or alternatively
python -m pychum.cli --help

Development

Before writing tests and incorporating the functions into the CLI it is helpful to often visualize the intermediate steps. For this we can setup a complete development environment including the notebook server.

uv sync --all-extras
uv run jupyter lab --ServerApp.allow_remote_access=1 \
    --ServerApp.open_browser=False --port=8889

Then go through the nb folder notebooks.

Adding ORCA blocks

Changes are to be made in the following files under the pychum/engine/orca/ folder:

• The relevant .jinja file in the _blocks directory
• The configuration loading mechanism in config_loader.py
• The dataclasses folder
• A sample test .toml file under tests/test_orca

While working on this, it may be instructive to use the nb folder notebooks. Also all PRs must include a full test suite for the new blocks.

Documentation

Readme

The readme can be constructed via:

./scripts/org_to_md.sh readme_src.org readme.md

License

MIT. However, this is an academic resource, so please cite as much as possible via:

• The Zenodo DOI for general use.
• The wailord paper for ORCA usage