gradient-free-optimizer

Short instructions for running the test suite.

Running tests

It's recommended to use a virtual environment. For macOS / zsh:

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install pytest

From the project root, run the full test suite with:

pytest -q

Or run a single test file or test case, for example:

pytest tests/test_molecule.py -q
pytest tests/test_molecule.py::test_write_coord_from_xyz -q

Notes

• The tests do not require Open Babel (obabel) to be installed; the z-matrix conversion tests mock subprocess.run to simulate a missing obabel. If you want to enable real z-matrix conversions, install Open Babel (macOS/Homebrew):

brew install open-babel

• The repository includes molecule.py which provides utilities for reading XYZ files, writing Turbomole coord files (coordinates are converted to Bohr), and inserting XYZ content into templates.

CI / GitHub Actions

A GitHub Actions workflow is included at .github/workflows/python-pytest.yml. It runs the project's pytest suite on pushes and pull-requests against Python 3.9, 3.10 and 3.11. The workflow installs dependencies from requirements.txt if present; otherwise it installs pytest and numpy before running the tests.

If you'd like to test the same configuration locally, follow the "Running tests" steps above and ensure pytest and numpy are installed in your virtual environment.

SciPy optimizer wrapper

This project includes a small wrapper that lets you call SciPy optimization methods from the Optimizer.minimize CLI by passing --optimizer scipy-<method>. For example, to invoke SciPy's L-BFGS-B implementation call:

python main.py --pes muller-brown --initial-coords -0.5 1.0 --optimizer scipy-l-bfgs-b --maxiter 200

The SciPy wrapper will:

• Import SciPy lazily and raise a helpful error if it's not installed.
• Use the project's Optimizer history recording so every function/gradient evaluation is recorded and available via opt.get_history().
• Print progress updates at each callback invocation (when supported by the method).

A demo shell script is provided at scripts/demo_scipy_l_bfgs_b.sh that shows a copy-pastable command line. Ensure you have SciPy installed in your environment:

pip install scipy

ORCA integration and examples

This project includes helpers for preparing and parsing ORCA inputs/outputs. The ORCA evaluator supports a dry-run (surrogate) mode and a real-run mode that invokes the orca executable. To help debugging real ORCA runs the helpers and evaluator accept verbose=True and an optional logger object so ORCA stdout/stderr and progress messages are logged.

Examples

Dry-run (surrogate) — prepare input but don't run ORCA:

python main.py --pes orca-casscf --geometry water.xyz --orca-template orca.G.inp

Real ORCA run (requires orca on PATH):

python main.py --pes orca-mrci --geometry water.xyz --orca-template orca.G.inp --orca-run

Enable verbose ORCA helper logging in Python code when building the evaluator:

from energy_functor import build_orca_evaluator
from molecule import Molecule
mol = Molecule('water.xyz')
# verbose=True will cause detailed logging from the ORCA helper
evaluator = build_orca_evaluator(input_template='orca.G.inp', molecule=mol, run=True, use='casscf', verbose=True)
energy = evaluator(mol.get_xyz_coordinates_flat())

Notes

• When running ORCA for real add --orca-run to the main.py CLI; without that flag the evaluator operates in a safe dry-run surrogate mode so the test-suite and CI do not require ORCA to be installed.
• You can pass a logging.Logger instance to build_orca_evaluator(..., logger=...) to integrate ORCA helper logs into your application's logging configuration.

License: MIT