Metadata-Version: 2.5
Name: comodino
Version: 0.1.0a1
Summary: Continuum model package
Project-URL: Homepage, https://github.com/roncofaber/comodino
Project-URL: Repository, https://github.com/roncofaber/comodino
Project-URL: Upstream, https://gitlab.com/electrolyte-machine/continuum_electrolyte
Author-email: Ana Sanz Matias <asanzmatias@lbl.gov>, Fabrice Roncoroni <roncoroni@lbl.gov>, David Prendergast <dgprendergast@lbl.gov>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: ase
Requires-Dist: colorcet
Requires-Dist: dill
Requires-Dist: joblib
Requires-Dist: matplotlib
Requires-Dist: networkx
Requires-Dist: numpy>=2.0
Requires-Dist: pandas
Requires-Dist: psutil
Requires-Dist: scipy>=1.14
Requires-Dist: seaborn
Provides-Extra: md
Requires-Dist: mdanalysis>=2.7; extra == 'md'
Provides-Extra: test
Requires-Dist: packaging>=24; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Provides-Extra: workflow
Requires-Dist: mdanalysis>=2.7; extra == 'workflow'
Requires-Dist: mdinterface>=1.5.4; extra == 'workflow'
Description-Content-Type: text/markdown

# CoMoDInO

Continuum electrochemical interface model. Development continues at [roncofaber/comodino](https://github.com/roncofaber/comodino), preserving the history of [electrolyte-machine/continuum_electrolyte](https://gitlab.com/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](docs/workflows/README.md). The [staged bulk equilibration recipe](docs/workflows/bulk_equilibration.md) 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](docs/workflows/interface_pmf.md) 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](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](docs/releasing.md) for gated PyPI automation. The manuscript and its continuation plan live separately in [comodino-paper](https://github.com/roncofaber/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](docs/model_baseline_audit.md) 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](docs/consolidation_validation.md) for current numerical evidence, continuation requirements, profile versus Cd resolution, and remaining validation gates.

The [PiperION frozen-input transfer check](docs/md_transfer_validation.md) 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](docs/jacobian_optimization.md) 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](docs/thermodynamic_conventions.md) for units, model assumptions, and known limits. Every code change must be recorded in the [change log](CHANGELOG.md), including its rationale and verification. Published-method provenance, manuscript integration tasks and reusable BibTeX are tracked in the [literature register](docs/literature.md).

The [multicomponent bulk MSA module](docs/msa_mixture.md) 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](docs/msa_pressure_bulk.md) and [fixed-volume bulk](docs/msa_volume_bulk.md), with explicit source-compatible reference matching. Spatial MSA remains disabled under the [strict functional-selection decision](docs/msa_interface_decision.md); 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](docs/msa_integration_plan.md) for the remaining implementation steps and physical-consistency conditions.

For the current continuum development, start with the [complete model specification and rebuild guide](docs/model_specification.md). 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](requirements-piperion.txt).

For model integration and the named reservoir/inventory API, see [component integration](docs/component_integration.md). 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](docs/reactive_interfaces.md) 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](docs/boundaries_results.md) 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](docs/reservoir_preparation.md) for units and assumptions.

Run `examples/benchmark_solvers.py` to measure half/full-cell grid scaling and continuation costs. See [solver benchmarks](docs/solver_benchmarks.md) 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](docs/sparse_solver.md) 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](docs/solver_stress.md) distinguishes solver agreement from grid convergence and includes reproduction commands.

For a proposed new-system workflow, see the [MD-to-continuum recipe](docs/md_to_continuum_recipe.md), [residual interactions and Imat design](docs/residual_interactions.md), and [draft parameterization manifest](examples/parameterization/system_manifest.template.json). 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](docs/correlations.md) 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](docs/msa_bulk.md), 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](docs/bulk_calibration.md) 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](docs/na_pmf_qualification.md) 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](docs/na_coordination_mapping.md) 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](docs/na_pmf_worked_recipe.md). 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](docs/na_bulk_bridge.md) 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](pyproject.toml) and installed automatically by pip. Use Python 3.12 with [requirements-piperion.txt](requirements-piperion.txt) to reproduce the direct dependency versions used for the ionomer benchmarks. See [installation and verification](docs/installation.md) for the tested environments and optional MD tools.

## Installation


```bash
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](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:

```bash
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](docs/installation.md) 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](docs/entropy_models.md).

## 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/ &rarr; interactive apps &rarr; Jupyter Notebook &rarr; compute mode .....

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