How dogusariturk/materialsframework works
Purpose and public entry points
MaterialsFramework is a Python 3.12 materials-simulation library that normalizes access to 20+ ML interatomic potentials plus VASP. Its public package entry points are the domain subpackages: calculators, analysis, transformations, tools, and I/O under src/materialsframework/__init__.py, src/materialsframework/calculators/__init__.py, and src/materialsframework/analysis/__init__.py.
Calculator abstraction and backend adapters
The primary execution boundary is the shared calculator API: backend-specific adapters accept ASE structures and generally pymatgen structures/molecules, then expose consistent single-point calculation and relaxation behavior. Adapter implementations isolate optional MLIP dependencies and backend conventions in files such as src/materialsframework/calculators/chgnet.py, src/materialsframework/calculators/mace.py, and src/materialsframework/calculators/vasp.py. VASP is the external licensed backend; MLIP adapters depend on separately installed optional packages.
Dynamics and execution observation
MD-capable calculators extend the calculation layer with NVE and NVT/NPT execution. The MD orchestration and calculator-facing utility boundary live in src/materialsframework/tools/md.py and src/materialsframework/tools/calculator.py; trajectory capture is represented by src/materialsframework/tools/trajectory.py. This stage takes an initial structure plus ensemble/runtime settings and returns final structures and sampled calculation data.
Lazy registries and plugin selection
Registries allow lookup by name without importing every heavyweight backend, making them the main dependency-loading control point. The central and domain registries are src/materialsframework/_registry.py, src/materialsframework/calculators/registry.py, and src/materialsframework/analysis/registry.py. Equivalent registries exist for transformations and tools, supporting runtime substitution of calculators and workflows.
Transformation → calculation → analysis workflows
Property workflows are deliberately split into paired transformations and analyzers. A transformation generates strained, displaced, slab, defect, path, or other derived structures; the analyzer invokes a supplied calculator over those structures and reduces results into a physical property. This separation is represented by src/materialsframework/transformations/elastic_constants.py, src/materialsframework/analysis/elastic_constants.py, and src/materialsframework/analysis/base.py. Parallel pairs cover EOS, phonons, NEB, formation energy, surface energies, stacking faults, and related analyses.
Standalone materials tools
Tools implement higher-level generation, modeling, and postprocessing outside the analyzer pipeline: SQS generation, cluster expansion, Cahn–Hilliard phase fields, stability maps, and CALPHAD-oriented conversion. Architecturally central implementations include src/materialsframework/tools/sqsgen.py, src/materialsframework/tools/cluster_expansion.py, and src/materialsframework/tools/cahn_hilliard.py. These may produce structures or scientific datasets consumed by calculators or external workflows.
Data formats, dependencies, and delivery
ASE is the core atomistic execution representation, while pymatgen inputs are supported at the public boundary; parsing support is under src/materialsframework/io/file_parser.py. Python package metadata and optional MLIP extras are defined in pyproject.toml; the resolved environment is uv.lock. Documentation is built with MkDocs (mkdocs.yml) and published through GitHub Pages (.github/workflows/gh-pages.yml); CI tests, linting, and releases run in GitHub Actions.
Main entry points: calculators/__init__.py Calculator API · materialsframework/__init__.py MaterialsFramework package · calculators/registry.py Calculator registry · analysis/registry.py Analysis registry
Components 20
Public API
- MaterialsFramework package · Domain subpackages expose the public library API.
src/materialsframework/__init__.py - File parser · Parses supported materials input formats.
src/materialsframework/io/file_parser.py
Calculation & dynamics
- Calculator API · Normalizes single-point and relaxation operations across backends.
src/materialsframework/calculators/__init__.py - Calculator registry · Selects named backends without eagerly importing optional dependencies.
src/materialsframework/calculators/registry.py - Registry core
src/materialsframework/_registry.py - MLIP adapters · CHGNet, MACE, and related optional-potential integrations.
src/materialsframework/calculators/chgnet.py - VASP adapter · Integrates the licensed VASP execution backend.
src/materialsframework/calculators/vasp.py - MD orchestration · Runs NVE and NVT/NPT dynamics from structures and runtime settings.
src/materialsframework/tools/md.py - Trajectory capture · Collects sampled calculation data and final structures.
src/materialsframework/tools/trajectory.py
Property workflows
- Structure transformations · Generates derived strained, displaced, slab, defect, and path structures.
src/materialsframework/transformations/elastic_constants.py - Analyzer base · Runs supplied calculators over derived structures and reduces results.
src/materialsframework/analysis/base.py - Property analyzers · Elastic constants and parallel EOS, phonon, NEB, and surface-property analyses.
src/materialsframework/analysis/elastic_constants.py - Analysis registry · Provides runtime selection of analysis workflows.
src/materialsframework/analysis/registry.py
Scientific tools
- Materials modeling tools · SQS generation, cluster expansion, and Cahn–Hilliard modeling.
src/materialsframework/tools/sqsgen.py
Packaging & delivery
- Package extras · Defines Python metadata and optional MLIP dependency extras.
pyproject.toml - Documentation publishing
mkdocs.yml - GitHub Pages workflow
.github/workflows/gh-pages.yml
Other components
- ASE & pymatgen structures · ASE is the execution representation; pymatgen is accepted at the public boundary.
- Optional MLIP packages
- VASP
Connections 21
- MaterialsFramework package → Calculator API: exports
- MaterialsFramework package → Analysis registry: exports
- MaterialsFramework package → File parser: exports
- ASE & pymatgen structures → Calculator API: structures
- File parser → ASE & pymatgen structures: parses
- Calculator registry → Registry core: uses
- Analysis registry → Registry core: uses
- Calculator registry → MLIP adapters: lazily loads
- Calculator registry → VASP adapter: selects
- MLIP adapters → Optional MLIP packages: depends on
- VASP adapter → VASP: executes
- MD orchestration → Calculator API: drives
- MD orchestration → Trajectory capture: records
- Structure transformations → Analyzer base: derived structures
- Analyzer base → Calculator API: invokes
- Property analyzers → Analyzer base: implements
- Analysis registry → Property analyzers: selects
- Materials modeling tools → ASE & pymatgen structures: produces or consumes
- Materials modeling tools → Calculator API: can consume
- Package extras → Optional MLIP packages: declares extras
- Documentation publishing → GitHub Pages workflow: published by