CoMoDInO

Continuum electrochemical interface model. Development continues at roncofaber/comodino, preserving the history of electrolyte-machine/continuum_electrolyte. The Python distribution is comodino; existing imports remain continuum_electrolyte.

For MD setup and agent-assisted workflows, start with the recipe index. The staged bulk equilibration recipe generates separate heating, NPT preparation and fixed-volume NVT stages from a validated mdinterface-built structure. The old 50 ps pilot remains a short diagnostic, not the full preparation protocol.

The surface-PMF recipe builds mdinterface Metal111 z-sandwiches and outermost-plane Colvars coordinates for water, ions and supplied molecular species. Ordinary PPPM is the baseline, with explicit background compensation available for a single ion. Structure/CV generation is implemented; interface equilibration, bias configuration and physical validation remain separate gates.

CoMoDInO is licensed under the MIT license. The GitHub repository remains private; licensing does not change repository visibility. develop is the default development branch; reviewed development is merged into main, and the RF_PhD_thesis tag preserves the historical baseline. Merging does not publish a release or alter scientific defaults. See the release procedure for gated PyPI automation. The manuscript and its continuation plan live separately in comodino-paper. Local development uses GitHub as origin and retains GitLab as upstream.

Version 0.1.0a1 is the first alpha: APIs and workflow contracts may change. Numerical tests do not establish physical validity for a new electrolyte or replace target-engine MD validation.

Start with the current-model consolidation audit for supported components, validation limits, a confirmed reference-initialization defect and the prioritized consolidation work. New feature development is paused while these foundations are checked.

The reference defect is now corrected. See the follow-up convergence and workflow checks for current numerical evidence, continuation requirements, profile versus Cd resolution, and remaining validation gates.

The PiperION frozen-input transfer check now includes unchanged-density baselines. The provisional parameterization fails quantitative transfer to biased MD states despite converged reference recovery; this is documented separately from numerical implementation checks.

The Jacobian assembly optimization gives a measured median 1.36x speedup in paired benchmarks, with unchanged numerical results and no change to physics or solver defaults.

See thermodynamic conventions for units, model assumptions, and known limits. Every code change must be recorded in the change log, including its rationale and verification. Published-method provenance, manuscript integration tasks and reusable BibTeX are tracked in the literature register.

The multicomponent bulk MSA module now supports coupled unequal-size/charge mixtures and neutral composition derivatives. It remains distinct from an interface closure; the restricted model is retained as an analytical benchmark.

MSA reaction equilibrium is available for pressure-controlled bulk and fixed-volume bulk, with explicit source-compatible reference matching. Spatial MSA remains disabled under the strict functional-selection decision; bulk results are not interface reservoirs.

MSA uses the spherical packing-volume diameter when Specie.correlation_diameter_A is omitted, with explicit overrides and per-species provenance. See the reservoir/nonlocal integration plan for the remaining implementation steps and physical-consistency conditions.

For the current continuum development, start with the complete model specification and rebuild guide. It defines explicit water versus vacancies, hydration, dipolar response, free energies, solver conventions, limitations and self-contained examples. develop contains ongoing development; main receives reviewed changes. The tested direct dependency versions are in requirements-piperion.txt.

For model integration and the named reservoir/inventory API, see component integration. Run python examples/ensemble_pair.py for explicit water and a counterion using the same material model in reservoir and closed-cell calculations. Multispecies and reacting systems now use the same population formulation; see reactive interfaces and run python examples/reactive_ensembles.py for water-consuming hydration with conserved chemical components. The guides distinguish supported combinations from remaining limitations.

Explicit geometry and voltage references are available through PlanarGeometry, TwoElectrodeCell and ElectrodeBulk. Interface.solve returns a dictionary-compatible result with unit-explicit accessors and a consistent fixed-voltage energy report. See boundaries and results and run python examples/boundaries_and_energy.py.

Use Interface.prepare_reservoir(component_densities) to equilibrate fixed-volume bulk composition before a half-cell solve. See reservoir preparation for units and assumptions.

Run examples/benchmark_solvers.py to measure half/full-cell grid scaling and continuation costs. See solver benchmarks for the reproducible baseline and profiling conclusions.

An optional model.solve(..., solver="sparse") uses a sparse-LU-preconditioned SciPy Krylov solver with a native sparse least-squares fallback. Dense remains the default. See sparse solver for verification, numerical controls and limitations.

Use examples/stress_solvers.py and examples/report_solver_stress.py for voltage-window, mesh and differential-capacitance checks. The stress-test record distinguishes solver agreement from grid convergence and includes reproduction commands.

For a proposed new-system workflow, see the MD-to-continuum recipe, residual interactions and Imat design, and draft parameterization manifest. These define scientific extraction/validation steps and a future automation interface; they do not launch MD or enable legacy nonzero Imat.

The first selectable correlation closure is DebyeHuckelLDA(), a local dilute-limit benchmark for implicit solvent with molecular mixing and constant linear dielectric. It consistently contributes to bulk preparation, reacting half/full cells and reported free energies. correlations=None preserves the existing model. Run python examples/correlation_comparison.py for illustrative profiles and capacitance. A separate finite-size MSA bulk benchmark, with explicit species contact diameters, provides neutral-salt electrostatic thermodynamics; run python examples/msa_bulk_comparison.py. It is not yet an interface closure. BSK is not included.

For the first executable parameterization step, see bulk reaction calibration and run python examples/bulk_parameterization.py --output output/bulk_pilot. This maps equilibrium densities to model-specific reaction energies and tests held-out transfer using a clearly labelled synthetic hydration/association control, not a validated MD extraction.

The single-Na PMF qualification adds real-data basin/history sensitivity and an unchanged-population baseline. It distinguishes finite-box counting hypotheses from macroscopic calibration and documents what still prevents physical parameter transfer.

The coordination-state mapping audit compares the saved smooth CV against actual periodic Na-O neighbour counts using MDAnalysis. It tests the geometric state definitions without treating biased trajectory counts as equilibrium populations.

For the current working decision and a numerical explanation, start with the worked Na PMF recipe. It retains the PMF basin states, shows exactly which mixing contribution is subtracted, and distinguishes finite-box candidate offsets from continuum reaction-energy calibration.

The executable Na bulk bridge now converts those offsets to reference-matched continuum dGx, verifies forward recovery and predicts the other boxes and a homogeneous hydration-density sweep without refitting. It adds no fictitious counterion and is not a neutral-salt reservoir or an electrostatic interface calculation.

Requirements

Python 3.11 or newer is required. Runtime dependencies are declared in pyproject.toml and installed automatically by pip. Use Python 3.12 with requirements-piperion.txt to reproduce the direct dependency versions used for the ionomer benchmarks. See installation and verification for the tested environments and optional MD tools.

Installation

git clone --branch develop https://github.com/roncofaber/comodino.git
cd comodino
git switch develop
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install .
python -m pip check
python -m examples.ensemble_pair
python -m examples.reactive_ensembles

The current general model is developed on develop and merged into main for release preparation. The private repository requires GitHub access. For an existing clone, start at git switch develop. Conda users can instead create a Python 3.12 environment and run the same pip commands inside it. requirements.txt is now a pip convenience file pointing to the project, not a conda dependency list.

Install directly without a checkout, including structure-building dependencies:

python -m pip install 'comodino[workflow] @ git+https://github.com/roncofaber/comodino.git@develop'
comodino resources ./comodino-recipes

Documentation, examples and a portable agent skill ship in the wheel. comodino skill PATH_TO_NEW_SKILL_DIRECTORY exports the skill explicitly; pip does not modify agent settings. See installation for migration, skill discovery and external MD requirements. This is a Git installation, not a PyPI release; plain pip install comodino is not yet the documented installation route.

For development and tests, use python -m pip install -e '.[test,md]' followed by python -m pytest -q. The md extra installs MDAnalysis for MD trajectory utilities; it is not required by the continuum solvers. The two examples check matched half/full-cell profiles with illustrative parameters, not production grid convergence or experimental agreement.

Usage - tutorial

Self-contained current examples are examples/piperion_hydration.py, examples/piperion_explicit_water.py, and examples/audit_ionomer_md.py. Run with --help; the model specification gives complete reproduction commands. The explicit-water demonstration uses synthetic surface energies unless a water free-energy file is supplied and is not an MD-calibrated prediction.

Mixing entropy is selectable with Interface(..., entropy_model="molecular") or ConstantPressure(..., entropy_model="molecular"). The default remains "site". Both retain lambda-dependent molecular volumes and packing; selecting a model does not recalibrate reaction energies or adsorption profiles. See entropy formulations and verification.

Jupyter Notebooks - Open on demand:

To use the Continuum Model functionalities within a jupyter notebook and the lrc-ondemand service, follow those steps:

0. If needed: create a conda environment (same as before):

module load anaconda3/2024.02-1-11.4 

git clone --branch develop https://github.com/roncofaber/comodino.git
cd comodino
git switch develop
conda create -n cont_mod python=3.12
conda activate cont_mod
python -m pip install . ipykernel

1. Install the IPython kernels:

python -m ipykernel install --user --name=cont_mod

3. Connect to a Jupyter Notebook through: https://lrc-ondemand.lbl.gov/ → interactive apps → Jupyter Notebook → compute mode .....

4. Open a new notebook, make sure to select the cont_mod kernel.