Mkphuthi/intercalation calc [WIP]

[mkphuthi]

Summary

Major changes:

• feature 1: Added _mc.py, a driver for Monte-Carlo simulations (only canonical simulations implemented thus far)
• feature 2: Added _ineracalation.py, used to predict energies as a function of concentration of an intercalating ion given a disordered or fully occupied structure thus topotactic transformations. This allows computing the free energy or just taking the lowest energy structure at each concentration
• NOTE: This is built to support any MLIP and is actually rather slow, when using MatGL's TensorNet potentials, it is recommended to use the mc_intercalation implementation in pymacy (TBD) that takes full advantage of nvalchemi and batched simulations. I decided against implementing that in MatCalc as it goes against the ethos of benchmarking multiple potentials.

Todos

• Document theory behind features and perform benchmarks on real system

Checklist

• Run simulations on example systems e.g. LFP, LCO, DRX

[rul048]

Thanks for the contribution! I have resolved the conflicts and please check the output from the lint and pytest.

[shyuep]

🤖 Automated PR review by Claude (posted via @shyuep). Based on static analysis of the diff; no code was executed locally.

Substantial and well-documented addition — IntercalationCalc/MCCalc with clear docstrings on the move types, and the canonical vs. fixed-concentration sampling distinction is nicely explained.

Blocking: the lint job is failing (ruff check src):

• I001 import block un-sorted in src/matcalc/__init__.py — the new _intercalation / _mc imports are out of alphabetical order. Run ruff check --fix src && ruff format src.
• A second ruff error at src/matcalc/_intercalation.py:306.

The test suite (including fp-loaders) passes. Marked [WIP], so flagging these for when you're ready to finalize rather than as a merge gate.

[shyuep]

Automated PR review generated by Claude (on behalf of @shyuep)

Re-review of commits since 2026-06-30 (main merge, __init__ export, datetime/UTC cleanup, mypy signature fixes). CI green (5/5). Comments on the current state:

1. Module-level warnings.filterwarnings("ignore", message="logm result may be inaccurate") in _intercalation.py mutates global warning state for any process that merely imports matcalc. Scope it with warnings.catch_warnings() around the relax/score call instead.
2. MCCalc(ensemble="grand_canonical") is accepted but unimplemented — raise NotImplementedError in __init__ rather than at first use.
3. Default trajfile="mc.traj" silently writes into the CWD; suggest None default meaning "don't write".
4. _SwapSites (composition-conserving MCMC) vs _RemoveKSites + transform_initial=True (independent resampling, not a Markov chain): the docstrings distinguish these well, but MCCalc reports acceptance_ratio in both modes — for the resampling mode it's not a standard Metropolis acceptance ratio; a note would prevent misinterpretation.

Still [WIP] per title (benchmarks/theory docs pending), so not flagging for merge yet. Structure and test coverage look good.

[shyuep]

Automated PR review generated by Claude (scheduled routine, posted on behalf of @shyuep) — re-review after new commits since the 2026-06-30 automated review.

The architecture has firmed up nicely: MCCalc as a generic Metropolis driver with IntercalationCalc composing it via _RemoveKSites (independent fixed-concentration sampling) and _SwapSites (composition-conserving canonical MCMC) is a clean separation, and the species↔vacancy vs binary species↔species handling in _SwapSites with tolerance-based sublattice matching is well done. CI is green.

Notes for before this leaves WIP: (1) the module-level warnings.filterwarnings("ignore", message="logm result may be inaccurate") mutates global warning state at import time — scope it with catch_warnings around the relaxation calls instead; (2) docstrings use reST :param: style while the repo standard (and the PR checklist) is Google format; (3) _RemoveKSites + transform_initial=True is independent sampling rather than a Markov chain — the docstring says so, but the class docs for IntercalationCalc should make the statistical implications explicit for users comparing against the _SwapSites canonical chain; (4) the stated todos (theory docs, LFP/LCO/DRX benchmarks) remain the main gap.