H2 MC Solvation

Run fixed-mode H2 Monte Carlo solvation with q2m3.solvation. Install the catalyst and solvation extras first.

Run The Script

uv run python examples/qmmm/h2_mc_solvation.py

The script builds a SolvationConfig, runs run_solvation(), and reports whether the Catalyst IR cache was a hit or miss.

Configuration Pattern

from q2m3.solvation import MoleculeConfig, QPEConfig, SolvationConfig, run_solvation

h2 = MoleculeConfig(
    name="H2",
    symbols=["H", "H"],
    coords=[[0.0, 0.0, 0.0], [0.0, 0.0, 0.74]],
    charge=0,
    active_electrons=2,
    active_orbitals=2,
    basis="sto-3g",
)

config = SolvationConfig(
    molecule=h2,
    qpe_config=QPEConfig(
        n_estimation_wires=4,
        n_trotter_steps=10,
        n_shots=50,
        qpe_interval=10,
        target_resolution=0.003,
        energy_range=0.2,
    ),
    hamiltonian_mode="fixed",
    n_waters=10,
    n_mc_steps=100,
    temperature=300.0,
    random_seed=42,
)

result = run_solvation(config, show_plots=False)

Fixed Mode

fixed mode uses a vacuum QPE Hamiltonian. It adds MM energy terms during the MC loop. Use this example to check Catalyst, JAX, PySCF, and the IR cache together.

The first run can compile Catalyst IR. Later runs can reuse cached IR if the circuit structure is unchanged.

Output Fields

The result dictionary includes energy trajectories, acceptance statistics, timing data, circuit metadata, and optional cache statistics. Diagnostics can add result keys. Code that reads results should use .get() for optional metadata.

Memory Notes

Use H2 fixed mode for the first MC run. H3O+ and dynamic mode increase Hamiltonian term count, circuit size, and Catalyst compile cost. Treat them as diagnostics until the H2 run passes its checks.