docs: update README for 0.2.0

[nikitafedik]

ALCHEMI Toolkit Pull Request

Description

Brings README.md up to date for the 0.2.0 release. Adds the subsystems
that landed during this cycle, training (nvalchemi.training) and spatial
domain decomposition (nvalchemi.distributed), along with the UMA wrapper
and MultiDataset composition. Key Features is restructured so the
list leads with what the toolkit does.

Also fixes three example snippets that do not run against the current API.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Performance improvement
• Documentation update
• Refactoring (no functional changes)
• CI/CD or infrastructure change

Related Issues

None.

Coordination note: does not overlap with #146 ("Exp docs 0.2.0 preview"),
which touches 100 files under docs/ but neither README.md nor
CHANGELOG.md.

Changes Made

• Restructured Key Features to lead with capabilities rather than
  architecture, with batched GPU simulation first.
• Added coverage for 0.2 features: training and fine-tuning, multi-GPU spatial
  domain decomposition, the UMA wrapper, and MultiDataset /
  InMemoryDataset and transforms.
• Split model listings into Interatomic potentials (MACE, AIMNet2, UMA,
  bring-your-own) and Interaction terms (Ewald/PME, DFT-D3, Lennard-Jones),
  since Ewald and PME read charges an MLIP predicts and cannot stand in for a
  potential.
• Clarified the | operator as stage-parallel, so it reads distinctly from the
  new intra-system spatial decomposition.
• Added a Roadmap section following the format used in
  nvalchemi-toolkit-ops.
• Replaced the inline breaking-changes paragraph with a pointer to
  CHANGELOG.md, which already carried all five items.
• Added two example snippets: training with validation and checkpointing, and
  splitting one system across GPUs with DomainParallel.
• Fixed three example snippets that do not run against the current API:
  • LoggingHook(frequency=100) raised TypeError; backend is a required
    positional argument ("csv" also needs log_path).
  • DemoDynamics.run(batch) raised AttributeError: 'Batch' has no attribute 'forces'. Dynamics needs forces, energy and velocities pre-allocated
    on AtomicData, as examples/basic/02_geometry_optimization.py does.
  • DemoDynamics(model=model, dt=0.5) raised TypeError; n_steps is
    required. Affected two snippets.

Testing

• Unit tests pass locally (make pytest)
• Linting passes (make lint)
• New tests added for new functionality meets coverage expectations?

make lint exits 0, and the repo's markdownlint pre-commit hook passes on
README.md.

make pytest was not run: this PR changes no source under nvalchemi/, so
there is no behavior to regress.

Example snippets were verified by execution rather than inspection, in a
uv sync --extra cu13 environment on an RTX 4000 SFF Ada (CUDA 13.2):

• Snippets 1-3 (forward pass, geometry optimization, + fused stage) were
  extracted verbatim from README.md and run to completion. Snippet 1 printed
  torch.Size([2, 1]) and torch.Size([7, 3]), matching its comments; snippet
  2 wrote a CSV with step,graph_idx,status,energy,fmax,temperature rows.
• Snippets 4-6 (| pipeline, training, domain decomposition) need two ranks
  and a single GPU was available, so their API calls were confirmed instead:
  | builds a DistributedPipeline, the loss expression yields a
  ComposedLossFunction, and TrainingStrategy, ValidationConfig,
  NVTLangevin, DomainConfig and DomainParallel all bind their keyword
  arguments. These three have not been executed end to end.

Checklist

• I have read and understand the Contributing Guidelines
• I have updated the CHANGELOG.md
• I have performed a self-review of my code
• I have added docstrings to new functions/classes
• I have updated the documentation (if applicable)

CHANGELOG.md is deliberately untouched. It does need attention before
release, but as separate commits rather than folded into a README change:

• No Added entry for nvalchemi.distributed, the largest feature in the
  release (~30.8k lines across 70 files). It currently appears only under
  Fixed.
• The Unreleased heading needs to become 0.2.0 with a date.
• Unlisted: slab correction in electrostatics wrappers (Expose Slab Correction in Electrostatics Wrappers #103), trainable
  PipelineModelWrapper (make PipelineModelWrapper trainable #99), MACE wrapper training support (update mace wrapper to enable training #97),
  the torch>=2.8 floor (Bumping torch minimum version to 2.8 #85), and the toolkit-ops 0.4.0 pin (Pin Toolkit-Ops version to 0.4.0 #120).
• The isotropic MTK NPT barostat mass change (W 3x smaller) is filed under
  Fixed. It silently changes existing NPT runs, so it may belong under
  Breaking Changes.

Additional Notes

Two items worth a reviewer's judgement:

1. The Roadmap section is new. Its format follows
   nvalchemi-toolkit-ops, and it carries no dates. Whether a public roadmap
   is wanted here at all is a maintainer call.
2. README snippets are not currently exercised by CI. A doctest-style
   check over fenced python blocks would catch this class of drift early.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[greptile-apps]

Greptile Summary

Updates the README for the 0.2.0 feature set.

• Restructures the feature overview around simulation, training, distributed execution, models, and data.
• Adds training and domain-decomposition examples while repairing existing dynamics snippets.
• Adds release-upgrade guidance, a roadmap, and optional-dependency compatibility notes.

Important Files Changed

Filename	Overview
README.md	Broadly updates release documentation and examples; the new training example advertises checkpointing without configuring it.

_{Reviews (1): Last reviewed commit: "docs: update README for 0.2.0" | Re-trigger Greptile}

[greptile-apps]

Checkpointing is not demonstrated

The example configures validation but does not install a CheckpointHook or call a checkpoint-saving API, so its current title incorrectly tells readers that running it will produce restartable checkpoints.

Suggested change

	<summary>Train a model with validation and checkpointing</summary>
	<summary>Train a model with validation</summary>

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!