API Reference¶

Using the Python API, you can easily derive alternate workflows.

Core Modules¶

Molecule¶

class pymerk.molecule.Molecule(symbols: list[str], positions: ndarray[tuple[Any, ...], dtype[_ScalarT]], charge: int = 0, multiplicity: int = 1, energy: float = 0.0, gnorm: float = 0, converged: bool = False, name: str = '')¶

Bases: object

Represents a molecular geometry with atomic positions and associated properties.

This class stores atomic symbols, their 3D positions, and quantum chemical properties such as energy, convergence status, and gradient norm.

symbols¶: List of atomic symbols (e.g., [‘C’, ‘H’, ‘O’]).

positions¶: (N, 3) array of atomic coordinates in Angstroms.

charge¶: Total molecular charge in elementary charge units. Defaults to 0.

multiplicity¶: Spin multiplicity (2S+1). Defaults to 1 (singlet).

energy¶: Electronic/Gibbs free energy in Hartree. Defaults to 0.0.

gnorm¶: Gradient norm (max. atomic force) in Hartree/Bohr. Defaults to 0.

converged¶: Whether geometry optimization has converged. Defaults to False.

name¶: Identifier for this geometry (e.g., ‘Conformer #1’). Defaults to empty string.

__init__(symbols: list[str], positions: ndarray[tuple[Any, ...], dtype[_ScalarT]], charge: int = 0, multiplicity: int = 1, energy: float = 0.0, gnorm: float = 0, converged: bool = False, name: str = '')¶

Initialize a Molecule instance.

Parameters:

symbols – List of atomic element symbols.
positions – (N, 3) numpy array of atomic coordinates.
charge – Total molecular charge. Defaults to 0.
multiplicity – Spin multiplicity. Defaults to 1.
energy – Electronic energy in Hartree. Defaults to 0.0.
gnorm – Gradient norm in Hartree/Bohr. Defaults to 0.
converged – Convergence status flag. Defaults to False.
name – Geometry identifier string. Defaults to empty string.

Raises:

AssertionError – If positions shape is not (len(symbols), 3).

copy() → Molecule¶

Create a deep copy of this molecule.

Returns a new Molecule instance with independent copies of positions and symbols to ensure modifications do not affect the original.

Returns:: A new Molecule instance with copied data.

static from_multi_xyz(f: ~typing.TextIO, charge: int = 0, multiplicity: int = 1, names: ~typing.Callable[[int], str] = <function Molecule.<lambda>>) → list[Molecule]¶

Read multiple geometries from an XYZ file.

Reads consecutive XYZ blocks from a file, creating one Molecule per block. Stops at EOF.

Parameters:

f – File object opened in read mode.
charge – Total molecular charge. Defaults to 0.
multiplicity – Spin multiplicity. Defaults to 1.
names – Function mapping geometry index to name. Defaults to string representation of index.

Returns:

List of Molecule instances parsed from the file.

classmethod from_xyz(f: TextIO, charge: int = 0, multiplicity: int = 1, energy: float = 0.0, gnorm: float = 0, converged: bool = False, name: str = '') → Molecule¶

Read a single geometry from an XYZ format file, and add a bunch of properties.

Parameters:

f – File object opened in read mode.
charge – Total molecular charge. Defaults to 0.
multiplicity – Spin multiplicity. Defaults to 1.
energy – Electronic energy in Hartree. Defaults to 0.0.
gnorm – Gradient norm. Defaults to 0.
converged – Convergence flag. Defaults to False.
name – Geometry identifier. Defaults to empty string.

Returns:

A new Molecule instance parsed from the file.

Raises:

EOFError – If no data is found in the file.
RuntimeError – If XYZ format is invalid (each atom line must have 4 chunks).

to_string() → str¶

Generate XYZ atom block (symbols and coordinates) as a string.

Returns:: Formatted string with atom coordinates.

to_xyz(title: str | None = None) → str¶

Generate complete XYZ format representation of this Molecule.

Parameters:: title – Optional title/comment line. If None, uses self.name.
Returns:: Complete XYZ formatted string.

Ensemble¶

class pymerk.ensemble.Ensemble(elements: list[Molecule])¶

Bases: object

Container for a collection of Molecule instances with associated properties.

An ensemble represents multiple conformations or isomers of the same molecular structure. All geometries must have the same number of atoms. This class provides operations for filtering, I/O, and bulk manipulation of conformers.

elements¶: List of Molecule instances representing each geometry.

__init__(elements: list[Molecule])¶

Initialize an Ensemble.

Parameters:: elements – List of Molecule instances to include in the ensemble.
Raises:: ValueError – If molecules have different numbers of atoms.

as_multi_xyz(f: TextIO)¶

Write the ensemble to a file in multi-XYZ format.

Writes each geometry as an XYZ block with title containing the name and energy. Consecutive blocks are separated by a blank line.

Parameters:: f – File object opened in write mode.

filter(predicate) → Ensemble¶

Filter geometries by a predicate function.

Creates a new ensemble containing only molecules for which predicate returns True.

Parameters:: predicate – Callable that takes a Molecule and returns bool.
Returns:: A new Ensemble with filtered molecules. Returns empty ensemble if no molecules match.

classmethod from_multi_xyz(f: TextIO, charge: int = 0, multiplicity: int = 1) → Ensemble¶

Create an ensemble by reading multiple geometries from an XYZ file.

Reads consecutive XYZ blocks from the file and creates one Molecule per block. Each geometry is automatically named ‘Conformer #N’ where N is the 1-based index.

Parameters:

f – File object opened in read mode containing XYZ format data.
charge – Total molecular charge for all geometries. Defaults to 0.
multiplicity – Spin multiplicity for all geometries. Defaults to 1.

Returns:

A new Ensemble instance containing all parsed geometries.

Driver¶

class pymerk.driver.BaseDriver(workdir: Path)¶

Bases: object

Abstract base class for quantum chemistry program interfaces.

Defines the interface for computing electronic energies, Gibbs free energies, and optimized geometries using external QM programs.

workdir¶: Working directory for temporary files and program output.

__init__(workdir: Path)¶

Initialize a BaseDriver.

Parameters:: workdir – Path to working directory.

clear_workdir()¶: Remove all files and directories from the working directory.

get_energy(geometry: Molecule, add_solvent: bool = False, output: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>) → float | tuple[float, float]¶

Compute the electronic energy of a geometry.

Parameters:

geometry – Molecule to evaluate.
add_solvent – If True, compute solvated energy. Defaults to False.
output – File object for writing program output. Defaults to sys.stdout.

Returns:

Electronic energy in Hartree if add_solvent=False. Tuple of (electronic_energy, solvated_energy) if add_solvent=True.

Raises:

NotImplementedError – Must be implemented by subclasses.

get_gibbs_free_energy(geometry: Molecule, T: float = 298.15, add_solvent: bool = False, output: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>) → tuple[float, float] | tuple[float, float, float]¶

Compute electronic and Gibbs free energy of a geometry.

Parameters:

geometry – Molecule to evaluate.
T – Temperature in Kelvin. Defaults to 298.15.
add_solvent – If True, include solvation corrections. Defaults to False.
output – File object for writing program output. Defaults to sys.stdout.

Returns:

Tuple of (electronic_energy, gibbs_free_energy) if add_solvent=False. Tuple of (electronic_energy, solvated_energy, gibbs_free_energy) if add_solvent=True. All energies in Hartree.

Raises:

NotImplementedError – Must be implemented by subclasses.

optimize_geometry(geometry: Molecule, add_solvent: bool = False, output: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, maxcycle: int = -1, optlevel: str = 'normal') → Molecule¶

Optimize the geometry of a molecule.

Performs geometry optimization and returns the optimized geometry with its energy and convergence status.

Parameters:

geometry – Molecule to optimize.
add_solvent – If True, optimize with solvation model. Defaults to False.
output – File object for writing program output. Defaults to sys.stdout.
maxcycle – Maximum optimization cycles. If -1, use default. Defaults to -1.
optlevel – Optimization level (‘loose’, ‘normal’, ‘tight’, etc.). Defaults to ‘normal’.

Returns:

Optimized Molecule with converged flag set and gradient norm computed.

Raises:

NotImplementedError – Must be implemented by subclasses.

property workdir: Path¶

Get the working directory.

Returns:: Path object of the working directory.

pymerk.driver.OPTLEVELS = {'loose': (5e-05, 0.004, 0.006, 0.008, 0.012), 'normal': (5e-06, 0.001, 0.0015, 0.005, 0.0075), 'tight': (1e-06, 0.0008, 0.0012, 0.001, 0.0015)}¶

(E, grms, gmax, drms, dmax)

Type:: Convergence thresholds

class pymerk.driver.OrcaDriver(workdir: Path, exe_path: str | Path, method: str, basis: str, solvatation_model: str | None = None, solvent: str | float | None = None, nprocs: int = 1)¶

Bases: QMDriver

Interface for the Orca quantum chemistry program.

Supports arbitrary functionals and basis sets with optional solvation (CPCM or SMD). Provides support for single-point energy calculations and geometry optimizations.

exe_path¶: Path to Orca executable.

solvatation_model¶: Solvation model (‘cpcm’ or ‘smd’). None for gas-phase.

solvent¶: Solvent parameter (epsilon for CPCM, solvent name for SMD).

nprocs¶: Number of processors for parallel calculation. Defaults to 1.

__init__(workdir: Path, exe_path: str | Path, method: str, basis: str, solvatation_model: str | None = None, solvent: str | float | None = None, nprocs: int = 1)¶: Initialize a OrcaDriver.

get_energy(geometry: Molecule, add_solvent: bool = False, output: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>) → float | tuple[float, float]¶

Compute the electronic energy of a geometry.

Parameters:

geometry – Molecule to evaluate.
add_solvent – If True, compute solvated energy. Defaults to False.
output – File object for writing program output. Defaults to sys.stdout.

Returns:

Electronic energy in Hartree if add_solvent=False. Tuple of (electronic_energy, solvated_energy) if add_solvent=True.

Raises:

NotImplementedError – Must be implemented by subclasses.

Optimize the geometry of a molecule.

Performs geometry optimization and returns the optimized geometry with its energy and convergence status.

Parameters:

geometry – Molecule to optimize.
add_solvent – If True, optimize with solvation model. Defaults to False.
output – File object for writing program output. Defaults to sys.stdout.
maxcycle – Maximum optimization cycles. If -1, use default. Defaults to -1.
optlevel – Optimization level (‘loose’, ‘normal’, ‘tight’, etc.). Defaults to ‘normal’.

Returns:

Optimized Molecule with converged flag set and gradient norm computed.

Raises:

NotImplementedError – Must be implemented by subclasses.

class pymerk.driver.QMDriver(workdir: Path, method: str, basis: str)¶

Bases: BaseDriver

Abstract base class for quantum chemistry drivers.

Extends BaseDriver with method and basis set information common to all QM programs.

method¶: Exchange-correlation functional or QM method name.

basis¶: Basis set specification.

__init__(workdir: Path, method: str, basis: str)¶

Initialize a QMDriver.

Parameters:

workdir – Path to working directory.
method – QM method or functional name.
basis – Basis set name.

class pymerk.driver.VlxDriver(workdir: Path, exe_path: str | Path, method: str, basis: str, solvatation_model: str | None = None, solvent: str | float | None = None)¶

Bases: QMDriver

Interface for the VeloxChem program.

Supports arbitrary functionals and basis sets with optional solvation (CPCM or SMD). Provides support for prescreening, screening, and full optimizations.

exe_path¶: Path to VeloxChem executable.

solvatation_model¶: Solvation model (‘cpcm’ or ‘smd’). None for gas-phase.

solvent¶: Solvent parameter (epsilon for CPCM, solvent name for SMD).

__init__(workdir: Path, exe_path: str | Path, method: str, basis: str, solvatation_model: str | None = None, solvent: str | float | None = None)¶

Initialize a VlxDriver.

Parameters:

workdir – Path to working directory.
exe_path – Path to VeloxChem executable.
method – Functional name (e.g., ‘pbe0’, ‘rcam-b3lyp’).
basis – Basis set (e.g., ‘def2-svp’, ‘def2-tzvpd’).
solvatation_model – Solvation model (‘cpcm’ or ‘smd’). Defaults to None.
solvent – Solvent specification. Defaults to None.

get_energy(geometry: Molecule, add_solvent: bool = False, output: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>) → float | tuple[float, float]¶

Compute the electronic energy of a geometry.

Parameters:

geometry – Molecule to evaluate.
add_solvent – If True, compute solvated energy. Defaults to False.
output – File object for writing program output. Defaults to sys.stdout.

Returns:

Electronic energy in Hartree if add_solvent=False. Tuple of (electronic_energy, solvated_energy) if add_solvent=True.

Raises:

NotImplementedError – Must be implemented by subclasses.

Optimize the geometry of a molecule.

Performs geometry optimization and returns the optimized geometry with its energy and convergence status.

Parameters:

geometry – Molecule to optimize.
add_solvent – If True, optimize with solvation model. Defaults to False.
output – File object for writing program output. Defaults to sys.stdout.
maxcycle – Maximum optimization cycles. If -1, use default. Defaults to -1.
optlevel – Optimization level (‘loose’, ‘normal’, ‘tight’, etc.). Defaults to ‘normal’.

Returns:

Optimized Molecule with converged flag set and gradient norm computed.

Raises:

NotImplementedError – Must be implemented by subclasses.

class pymerk.driver.XtbDriver(workdir: Path, exe_path: str | Path, version: str = 'gfn2', use_bhess: bool = True, imagthr: float = -100, sthr: float = 50, scale: float = 1.0, solvatation_model: str = None, solvent: str = None)¶

Bases: BaseDriver

Interface for the xTB semiempirical QM program.

Supports GFN1, GFN2, and GFNFF methods with optional solvation corrections.

exe_path¶: Path to xtb executable.

version¶: xTB method version (‘gfn1’, ‘gfn2’, ‘gfnff’).

solvatation_model¶: Solvation model name (e.g., ‘gbsa’). None for gas-phase.

solvent¶: Solvent name or identifier.

use_bhess¶: If True, use Bhess for Hessian. Defaults to True.

imagthr¶: Imaginary frequency threshold in cm⁻¹. Defaults to -100.

sthr¶: Wave number threshold in cm⁻¹. Defaults to 50.

scale¶: Frequency scaling factor. Defaults to 1.0.

__init__(workdir: Path, exe_path: str | Path, version: str = 'gfn2', use_bhess: bool = True, imagthr: float = -100, sthr: float = 50, scale: float = 1.0, solvatation_model: str = None, solvent: str = None)¶

Initialize an XtbDriver.

Parameters:

workdir – Path to working directory.
exe_path – Path to xtb executable.
version – xTB version to use. Defaults to ‘gfn2’.
use_bhess – Use Bhess for Hessian computation. Defaults to True.
imagthr – Imaginary frequency threshold. Defaults to -100.
sthr – Wave number threshold. Defaults to 50.
scale – Frequency scaling factor. Defaults to 1.0.
solvatation_model – Solvation model name. Defaults to None.
solvent – Solvent identifier. Defaults to None.

get_energy(geometry: Molecule, add_solvent: bool = False, output: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>) → float | tuple[float, float]¶

Compute the electronic energy of a geometry.

Parameters:

geometry – Molecule to evaluate.
add_solvent – If True, compute solvated energy. Defaults to False.
output – File object for writing program output. Defaults to sys.stdout.

Returns:

Electronic energy in Hartree if add_solvent=False. Tuple of (electronic_energy, solvated_energy) if add_solvent=True.

Raises:

NotImplementedError – Must be implemented by subclasses.

Compute electronic and Gibbs free energy of a geometry.

Parameters:

geometry – Molecule to evaluate.
T – Temperature in Kelvin. Defaults to 298.15.
add_solvent – If True, include solvation corrections. Defaults to False.
output – File object for writing program output. Defaults to sys.stdout.

Returns:

Tuple of (electronic_energy, gibbs_free_energy) if add_solvent=False. Tuple of (electronic_energy, solvated_energy, gibbs_free_energy) if add_solvent=True. All energies in Hartree.

Raises:

NotImplementedError – Must be implemented by subclasses.

Optimize the geometry of a molecule.

Performs geometry optimization and returns the optimized geometry with its energy and convergence status.

Parameters:

geometry – Molecule to optimize.
add_solvent – If True, optimize with solvation model. Defaults to False.
output – File object for writing program output. Defaults to sys.stdout.
maxcycle – Maximum optimization cycles. If -1, use default. Defaults to -1.
optlevel – Optimization level (‘loose’, ‘normal’, ‘tight’, etc.). Defaults to ‘normal’.

Returns:

Optimized Molecule with converged flag set and gradient norm computed.

Raises:

NotImplementedError – Must be implemented by subclasses.

Scripts and Workflows¶

Filter¶

class pymerk.scripts.filter.BaseFilter(driver: BaseDriver, aux_driver: BaseDriver | None = None, label: str = 'E')¶

Bases: object

Abstract base class for ensemble filtering operations.

Provides shared infrastructure for computing energies, reporting results, and filtering ensembles based on various criteria. Supports dual-driver evaluation where solvation and thermal corrections can come from different sources.

main_driver¶: Primary BaseDriver for computing electronic energies.

aux_driver¶: Optional secondary BaseDriver for auxiliary corrections.

label¶: Energy label for reporting (e.g., ‘E’, ‘G’). Defaults to ‘E’.

__init__(driver: BaseDriver, aux_driver: BaseDriver | None = None, label: str = 'E')¶

Initialize a BaseFilter.

Parameters:

driver – Primary BaseDriver instance.
aux_driver – Optional secondary BaseDriver for auxiliary corrections. Defaults to None.
label – Label for energy reporting. Defaults to ‘E’.

filter(ensemble: Ensemble, output: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, T: float = 298.15) → Ensemble¶

Filter ensemble by a criterion implemented in subclasses.

Parameters:

ensemble – Input Ensemble to filter.
output – File object for driver output. Defaults to sys.stdout.
T – Temperature in Kelvin. Defaults to 298.15.

Returns:

Filtered Ensemble with retained geometries.

Raises:

NotImplementedError – Must be implemented by subclasses.

class pymerk.scripts.filter.BoltzmannFilter(driver: BaseDriver, pthr: float, gsolv_component: SelectDriver | None = None, gtrv_component: SelectDriver | None = None, aux_driver: BaseDriver = None, label: str = 'E')¶

Bases: BaseFilter

Filter ensemble by Boltzmann population threshold.

Computes Boltzmann populations at given temperature and retains conformers accounting for specified cumulative population threshold.

pthr¶: Cumulative population threshold (0-1).

gsolv¶: SelectDriver for solvation corrections.

gtrv¶: SelectDriver for thermal corrections.

__init__(driver: BaseDriver, pthr: float, gsolv_component: SelectDriver | None = None, gtrv_component: SelectDriver | None = None, aux_driver: BaseDriver = None, label: str = 'E')¶

Initialize a BoltzmannFilter.

Parameters:

driver – Primary BaseDriver for energy calculations.
pthr – Cumulative population threshold (e.g., 0.95 for 95%).
gsolv_component – Which driver provides solvation energy. Defaults to None.
gtrv_component – Which driver provides thermal energy. Defaults to None.
aux_driver – Optional auxiliary BaseDriver. Defaults to None.
label – Label for reporting. Defaults to ‘E’.

filter(ensemble: Ensemble, output: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, T: float = 298.15) → Ensemble¶

Filter ensemble by a criterion implemented in subclasses.

Parameters:

ensemble – Input Ensemble to filter.
output – File object for driver output. Defaults to sys.stdout.
T – Temperature in Kelvin. Defaults to 298.15.

Returns:

Filtered Ensemble with retained geometries.

Raises:

NotImplementedError – Must be implemented by subclasses.

class pymerk.scripts.filter.EnergyFilter(driver: BaseDriver, ethr: float, gsolv_component: SelectDriver = SelectDriver.NONE, gtrv_component: SelectDriver = SelectDriver.NONE, aux_driver=None, label='E')¶

Bases: BaseFilter

Filter ensemble by energy threshold using single-point calculations.

Evaluates all geometries with specified drivers and removes those above energy threshold relative to the minimum.

ethr¶: Energy threshold in Hartree.

gsolv¶: SelectDriver for solvation corrections.

gtrv¶: SelectDriver for thermal corrections.

__init__(driver: BaseDriver, ethr: float, gsolv_component: SelectDriver = SelectDriver.NONE, gtrv_component: SelectDriver = SelectDriver.NONE, aux_driver=None, label='E')¶

Initialize an EnergyFilter.

Parameters:

driver – Primary BaseDriver for energy calculations.
ethr – Energy threshold in Hartree above minimum.
gsolv_component – Which driver provides solvation energy. Defaults to SelectDriver.NONE.
gtrv_component – Which driver provides thermal energy. Defaults to SelectDriver.NONE.
aux_driver – Optional auxiliary BaseDriver for correction terms. Defaults to None.
label – Label for reporting. Defaults to ‘E’.

filter(ensemble: Ensemble, output: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, T: float = 298.15) → Ensemble¶

Filter ensemble by a criterion implemented in subclasses.

Parameters:

ensemble – Input Ensemble to filter.
output – File object for driver output. Defaults to sys.stdout.
T – Temperature in Kelvin. Defaults to 298.15.

Returns:

Filtered Ensemble with retained geometries.

Raises:

NotImplementedError – Must be implemented by subclasses.

class pymerk.scripts.filter.MacroOptFilter(driver: BaseDriver, ethr: float, use_solvent: bool = True, gtrv_component: SelectDriver = SelectDriver.NONE, aux_driver=None, maxcycles: int = -1, optcycles: int = 10, gradthr: float = 0.01, optlevel: str = 'normal', label: str = 'E')¶

Bases: BaseFilter

Filter ensemble by iterative macro-optimization.

Performs multiple optimization cycles per structure with early discard logic. Useful for difficult optimizations or exhaustive refinement.

ethr¶: Energy threshold in Hartree for discard.

use_solvent¶: If True, optimize with solvation.

gtrv¶: SelectDriver for thermal corrections.

maxcycles¶: Maximum total optimization iterations.

optcycles¶: Optimization steps per macro-cycle.

gradthr¶: Gradient threshold for early discard in Hartree/Bohr.

optlevel¶: Optimization level.

__init__(driver: BaseDriver, ethr: float, use_solvent: bool = True, gtrv_component: SelectDriver = SelectDriver.NONE, aux_driver=None, maxcycles: int = -1, optcycles: int = 10, gradthr: float = 0.01, optlevel: str = 'normal', label: str = 'E')¶

Initialize a MacroOptFilter.

Parameters:

driver – Primary BaseDriver for optimization.
ethr – Energy threshold in Hartree.
use_solvent – If True, optimize with solvation. Defaults to True.
gtrv_component – Which driver provides thermal corrections. Defaults to SelectDriver.NONE.
aux_driver – Optional auxiliary BaseDriver. Defaults to None.
maxcycles – Maximum total optimization cycles (-1 = unlimited). Defaults to -1.
optcycles – Optimization steps per macro-cycle. Defaults to 10.
gradthr – Gradient norm threshold for early discard in Hartree/Bohr. Defaults to 1e-2.
optlevel – Optimization level. Defaults to ‘normal’.
label – Label for reporting. Defaults to ‘E’.

filter(ensemble: Ensemble, output: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, T: float = 298.15) → Ensemble¶

Filter ensemble by a criterion implemented in subclasses.

Parameters:

ensemble – Input Ensemble to filter.
output – File object for driver output. Defaults to sys.stdout.
T – Temperature in Kelvin. Defaults to 298.15.

Returns:

Filtered Ensemble with retained geometries.

Raises:

NotImplementedError – Must be implemented by subclasses.

class pymerk.scripts.filter.OptFilter(driver: BaseDriver, ethr: float, use_solvent: bool = True, gtrv_component: SelectDriver = SelectDriver.NONE, aux_driver=None, maxcycles: int = -1, optlevel: str = 'normal', label='E')¶

Bases: BaseFilter

Filter ensemble by geometry optimization and energy threshold.

Optimizes all geometries and retains only those that converged and are below energy threshold.

ethr¶: Energy threshold in Hartree.

use_solvent¶: If True, optimize with solvation model.

gtrv¶: SelectDriver for thermal corrections.

maxcycles¶: Maximum optimization cycles.

optlevel¶: Optimization level (‘loose’, ‘normal’, ‘tight’).

Initialize an OptFilter.

Parameters:

driver – Primary BaseDriver for optimization and energy.
ethr – Energy threshold in Hartree.
use_solvent – If True, optimize with solvation. Defaults to True.
gtrv_component – Which driver provides thermal corrections. Defaults to SelectDriver.NONE.
aux_driver – Optional auxiliary BaseDriver. Defaults to None.
maxcycles – Maximum optimization cycles (-1 = default). Defaults to -1.
optlevel – Optimization level. Defaults to ‘normal’.
label – Label for reporting. Defaults to ‘E’.

filter(ensemble: Ensemble, output: TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, T: float = 298.15) → Ensemble¶

Filter ensemble by a criterion implemented in subclasses.

Parameters:

ensemble – Input Ensemble to filter.
output – File object for driver output. Defaults to sys.stdout.
T – Temperature in Kelvin. Defaults to 298.15.

Returns:

Filtered Ensemble with retained geometries.

Raises:

NotImplementedError – Must be implemented by subclasses.

class pymerk.scripts.filter.SelectDriver(*values)¶

Bases: Enum

Enumeration for selecting which driver computes a correction term.

Used to route solvation and thermal corrections to main or auxiliary driver.

NONE¶: No correction is included.

MAIN¶: Correction computed by main driver.

AUX¶: Correction computed by auxiliary driver.

AUX = 3¶

MAIN = 2¶

NONE = 1¶

Workflow¶

class pymerk.scripts.run.BaseWorkflow(workdir: str | Path, config: Any)¶: Bases: object

class pymerk.scripts.run.DefaultWorkflow(workdir: str | Path, config: Any)¶

Bases: BaseWorkflow

filter(ensemble: Ensemble) → Ensemble¶

pymerk.scripts.run.main()¶