Dataclass Hierarchy #

Overview #

pychum represents all configuration data as Python dataclasses. The ORCA engine defines 15+ dataclasses in pychum/engine/orca/_dataclasses.py. The eOn engine defines 2 in pychum/engine/eon/_dataclasses.py.

Abstract Base #

OrcaBlock is an abstract base class. Concrete blocks (NebBlock, GeomBlock) must implement block_type() returning a BlockType enum value.

class BlockType(Enum):
    NEB = "neb"
    GEOM = "geom"

class OrcaBlock(ABC):
    @abstractmethod
    def block_type(self) -> BlockType:
        pass

Top-level Dataclasses #

OrcaConfig #

The root configuration object:

Field	Type	Description
`kwlines`	`str`	ORCA keyword lines (the `! ...` header)
`coords`	`Coords`	Coordinate block
`blocks`	`dict[BlockType, OrcaBlock]`	Named blocks (neb, geom)
`extra_blocks`	`dict[str, str]`	Arbitrary blocks as raw text

Coords #

Field	Type	Default	Description
`charge`	`int`	required	System charge
`multiplicity`	`int`	required	Spin multiplicity
`fmt`	`str`	required	Format: xyz, int, gzmt, xyzfile, gzmtfile
`filedat`	`str`	`""`	External file path (for xyzfile/gzmtfile)
`atoms`	`list[Atom]`	`[]`	Atom definitions

Atom #

The Atom dataclass has fields for three coordinate formats (xyz, internal, Gaussian Z-matrix) and special atom flags:

Field	Type	Default	Description
`x`, `y`, `z`	`float`	`0.0`	Cartesian coordinates
`symbol`	`str`	`None`	Element symbol (required unless point charge)
`is_ghost`	`bool`	`False`	Ghost atom (appends `:`)
`embedding_potential`	`bool`	`False`	Embedding potential (appends `>`)
`is_frozen`	`bool`	`False`	Freeze all coordinates (Cartesian only)
`is_frozen_x/y/z`	`bool`	`False`	Freeze individual coordinates
`isotope`	`float or None`	`None`	Isotope mass
`nuclear_charge`	`float or None`	`None`	Custom nuclear charge
`fragment_number`	`int or None`	`None`	Fragment assignment
`is_dummy`	`bool`	`False`	Dummy atom (rendered as `DA`)
`point_charge`	`float or None`	`None`	Point charge value (forces symbol to `Q`)
`bond_atom`	`int or None`	`None`	Bonded atom index (internal coords)
`bond_length`	`float or None`	`None`	Bond length (internal coords)
`angle_atom`	`int or None`	`None`	Angle reference atom (internal coords)
`angle`	`float or None`	`None`	Bond angle (internal coords)
`dihedral_atom`	`int or None`	`None`	Dihedral reference atom (internal coords)
`dihedral`	`float or None`	`None`	Dihedral angle (internal coords)

Validation in __post_init__: if point_charge is set, symbol is forced to "Q". Otherwise, symbol is required.

NEB Settings Dataclasses #

NebBlock is a large dataclass (OrcaBlock subclass) with 17 direct fields and 12 settings sub-objects:

Direct NEB Fields #

Field	Type	Default	Validated against
`end_xyz`	`str`	required	–
`nimgs`	`int`	required	–
`convtype`	`str`	`"CIONLY"`	all, cionly
`interpolation`	`str`	`"IDPP"`	IDPP, LINEAR, XTB1TS, XTB1, XTB2TS, XTB2
`quatern`	`str`	`"ALWAYS"`	no, startonly, always
`tangent`	`str`	`"IMPROVED"`	improved, original
`neb_ts`	`bool`	`False`	–
`neb_ci`	`bool`	`False`	–
`climbingimage`	`bool`	`True`	–
`preopt`	`bool`	`False`	–

Settings Sub-objects #

Each settings class has defaults and is created with field(default_factory…)=:

Class	Fields	Validation
`OptimSettings`	method, maxmove, stepsize, maxiter, local	method in {LBFGS, VPO, FIRE}
`LBFGSSettings`	reparam_on_restart, memory, precondition, dr, restart_on_maxmove	none
`FIRESettings`	init_damp, damp_decr, step_incr, step_decr, max_step, retention	none
`IDPPSettings`	tol_maxf, maxmove, alpha, nmax, quatern, ksp, debug	none
`ZoomSettings`	tol_turn_on, offset, auto, tol_scale, alpha, interpolation, printfulltrj	interpolation in {linear, cubic}
`ReparamSettings`	interp, every, tol	interp in {linear, cubic}
`ConvTolSettings`	units, maxfp_i, rmsfp_i, maxf_ci, rmsf_ci, turn_on_ci, scale	none
`FreeEndSettings`	use, opt_type, ec, ec_end, kappa	opt_typein {PERP, CONTOUR, FULL}
`SpringSettings`	spring_kind, const1, const2, energy_weighted, perpspring, llt_cos	spring_kindin {image, dof, ideal}; perpspring in {no, cos, tan, cosTan, DNEB}
`RestartSettings`	gbw_basename, allxyz	mutually exclusive (raises ValueError)
`TSGuessSettings`	xyz_struct, pdb_struct, ts_img	xyz_structand pdb_structmutually exclusive
`FixCenterSettings`	active, remove_extern_force	none

Geometry Dataclasses #

GeomScan #

Field	Type	Description
`atoms`	`list[int]`	Atom indices (2 for bonds, 3 for angles, 4 for dihedrals)
`range`	`list[float]`	Start and end values
`points`	`int`	Number of scan points

GeomBlock #

OrcaBlock subclass with three lists of GeomScan:

bonds
dihedrals
angles

Utility Dataclasses #

UnitConversion #

Field	Type
`inp`	`str`
`out`	`str`

Schema for optional [units.*] TOML tables. ConfigLoader does not construct these objects; the tables are documentation-only tags. Suite unit conversion lives in chemparseplot.units.

eOn/NWChem Dataclasses #

NWChemAtom #

Field	Type	Description
`symbol`	`str`	Element symbol
`x`, `y`, `z`	`float`	Cartesian coordinates

NWChemSocketConfig #

Field	Type	Default	Description
`atoms`	`list[NWChemAtom]`	required	Atom list
`settings_path`	`Path`	required	Path to NWChem settings file
`socket_address`	`str`	required	Socket address for eOn
`unix_mode`	`bool`	`False`	Use Unix domain socket
`mem_in_gb`	`int`	`2`	Memory allocation in GB
`output_path`	`Path`	`nwchem_socket.nwi`	Output file path