macer 0.3.4

Machine-learning accelerated Atomic Computational Environment for automated Research workflows

macer

macer: Machine-learning accelerated Atomic Computational Environment for Research workflows

The macer package provides a command-line workflow for crystal structure relaxation, molecular dynamics simulations, and lattice dynamics calculations, using a variety of Machine-Learned Force Fields (MLFFs). It integrates universal Machine Learning Interatomic Potentials (uMLIP) calculators like MACE, MatterSim, SevenNet, CHGNet, M3GNet, Allegro, Orb, and FairChem with libraries like ASE (Atomic Simulation Environment), Phonopy, Phono3py, DynaPhoPy, and symfc.

The self-consistent harmonic approximation workflow is implemented through the qSCAILD engine (qscaild).

---

Key Features

• MLFF Integration: Utilizes various MLFFs as interatomic potential calculators for all supported workflows with same cli commands.
• Structure Relaxation: Employs ASE optimizers (FIRE, BFGS, etc.) with VASP-compatible ISIF modes. Results are saved directly in the input directory by default (VASP-style).
• Molecular Dynamics: Performs NPT, NVT, and NVE ensemble simulations with Physics-based Auto-parameterization:
• Path Integral Molecular Dynamics (PIMD): Provides PIMD simulations by wrapping the external PIMD_python core with macer MLFF and post-processing workflows.
• Phonon Calculations: Uses Phonopy to calculate phonon band structure, density of states (DOS), irreducible representations (irreps), and Grüneisen parameters.
• Quasiharmonic Approximation (QHA): Automates the calculation of thermodynamic properties like thermal expansion and heat capacity. Includes options for volume sampling and custom output directory control.
• qSCAILD / SSCHA Workflow: A workflow to compute temperature-dependent effective force constants, following the qscaild package. The implementation features:
• Anharmonic Phonon Analysis (DynaPhoPy): Calculates finite-temperature phonon properties by analyzing MD trajectories using DynaPhoPy. This workflow:
• Lattice Thermal Conductivity: Calculates lattice thermal conductivity by solving the linearized Boltzmann transport equation (LBTE) using phono3py. Supports RTA and LBTE modes with MLFF-calculated forces.
• Point Defect Analysis: Automates point defect calculations (Chemical Potential Diagram, Defect Formation Energies) using pydefect and vise, integrating MLFF relaxation via macer.

---

Installation & Setup

Macer now supports a Unified MLFF Environment, allowing all force fields (MACE, SevenNet, MatterSim, etc.) to coexist in a single Python environment. This is achieved by "vendorizing" MACE and its legacy dependencies.

1. Create a Virtual Environment

We recommend using uv (fastest) or conda. Use macer_env as your environment name.

Option A: Using uv (Recommended)

# 1. Create environment
uv venv macer_env

# 2. Activate environment
source macer_env/bin/activate

# 3. Install Macer and all dependencies
uv pip install -e .

Option B: Using Conda

# 1. Create environment
conda create -n macer_env python=3.11
conda activate macer_env

# 2. Install Macer and all dependencies
pip install -e .

2. Custom Configuration (~/.macer.yaml)

Macer uses a configuration file named .macer.yaml in your home directory (~/.macer.yaml) to manage global default settings (e.g., default force field, compute device, and model paths).

• Automatic Setup: On its first run, Macer automatically creates a ~/.macer.yaml file populated with global defaults if it doesn't already exist.
• Easy Editing: You can easily edit these settings visually using the Interactive Mode (macer -i) by selecting the [ Default setting editor (~/.macer.yaml) ] menu.

Configuration Format

# ~/.macer.yaml
default_mlff: mattersim  # Options: mattersim, mace, sevennet, chgnet, m3gnet, allegro, orb, fairchem
device: cpu              # Options: cpu, mps, cuda

# Custom directory to search for MLFF model files before checking project defaults.
mlff_directory: /path/to/your/models

models:
  # Specify filenames (searched in mlff_directory or package default) or absolute paths.
  mace: mace-omat-0-small.model
  sevennet: checkpoint_sevennet_0.pth

3. Verify Installation

After installation, the macer command will be available globally in your environment.

macer --help

4. Installation on HPC Systems (GPU & Compiler Issues)

On High Performance Computing (HPC) systems (especially with ARM/aarch64 CPUs and NVIDIA GPUs), standard installation often fails due to:

1. Compiler Conflicts: System default compilers (like nvc) failing to build Python packages. Macer's setup script now automatically detects nvc and prevents broken installations.
2. PyTorch Version Mismatch: pip tends to reinstall the CPU-only version of PyTorch during dependency resolution, overwriting any pre-installed CUDA version.

To resolve this, we provide a robust helper script (scripts/install_hpc_cuda.sh) that:

1. Enforces GCC: Sets CC=gcc, CXX=g++, etc., to avoid nvc compatibility issues.
2. Auto-detects CUDA: Uses nvcc to find the system CUDA version and selects the matching PyTorch wheel (e.g., cu118, cu121, cu124).
3. Safe Installation: Installs Macer first, then forces the re-installation of the correct CUDA-enabled PyTorch package at the very end to ensure GPU support.

Recommended Installation Command for HPC:

# This script handles compiler setup and ensures CUDA PyTorch is used
bash scripts/install_hpc_cuda.sh

# Optional: You can override the CUDA version if auto-detection fails
bash scripts/install_hpc_cuda.sh cu118

Or manually configure your environment (Advanced Users):

module load gcc       # Load GCC module
export CC=gcc         # Force C compiler to GCC
export CXX=g++        # Force C++ compiler to G++
export FC=gfortran    # Force Fortran compiler

# 1. Install Macer (Let pip resolve deps, ignoring potential torch downgrade)
pip install -e . --no-build-isolation

# 2. FORCE reinstall PyTorch with CUDA (Critical Step!)
pip uninstall torch torchvision torchaudio -y
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

5. Pre-trained Model Management (macer util gm)

Macer provides a centralized utility to manage and download pre-trained Machine Learning Force Field (MLFF) models. Downloaded models are stored in the mlff-model/ directory.

Basic Usage

# 1. List all supported models and their installation status
macer util gm

# 2. Download ALL available models
macer util gm --model all

# 3. Download all models for a specific force field (e.g., MACE)
macer util gm --model all --ff mace

# 4. Download a specific model by its keyword
macer util gm --model sevennet-omni

Auto-Provisioning

If you run a simulation (e.g., macer relax) and the required model is missing from your local directory, macer will attempt to download it automatically using the same mechanism.

---

Usage

The macer CLI is the unified entry point for all workflows. It supports relax and md directly, and integrates other tools as subcommands: phonopy, pydefect, and util.

Interactive TUI Mode

For a more user-friendly experience, use the Interactive Mode. This provides a menu-driven interface to configure and run all macer workflows, manage your global configuration, and explore files with an advanced vi-style browser.

# Launch the interactive TUI
macer -i

You can access help for each command and its subcommands directly from the terminal:

macer --help
macer relax -h
macer md -h
macer phonopy [sr, pb, qha, qscaild, sscha, ft, tc] -h
macer pydefect [cpd, defect, full] -h
macer util [dynaphopy, md, phonon, model, struct] -h

Relaxation Examples (macer relax)

By default, relaxation results (CONTCAR-*, OUTCAR-*, etc.) are saved directly in the same directory as the input structure file. Use --subdir if you prefer a dedicated RELAX-* directory.

# Full cell relaxation (atoms + lattice) using the default force field
macer relax --poscar POSCAR --isif 3

# Batch relaxation for multiple structures using MACE
macer relax --poscar POSCAR-* --isif 2 --ff mace

# Use a specific Orb model (auto-downloaded by name)
macer relax --poscar POSCAR --isif 3 --ff orb --model orb_v3_conservative_inf_omat

# Generate outputs for PyDefect (single-point calculation)
macer relax --poscar POSCAR --isif 0 --pydefect

# Relaxation with a fixed c-axis
macer relax --poscar POSCAR --isif 3 --fix-axis c

# Calculate bulk modulus for multiple files
macer relax -p POSCAR-001 POSCAR-002 --bulk-modulus

Molecular Dynamics Examples (macer md)

# 1. NPT Auto-setting (Default): Automatic barostat (via Bulk Modulus) and thermostat (40 * dt)
macer md -p POSCAR --ensemble npt --temp 300 --press 0.0 --ff mattersim

# 2. NVT Auto-setting: Automatic thermostat coupling (ttau = 40 * tstep)
macer md -p POSCAR --ensemble nvt --temp 600 --nsteps 10000

# 3. Temperature Ramping (mimicking VASP TEBEG -> TEEND)
# Gradually increase temperature from 300K to 1000K over 20000 steps
macer md -p POSCAR --ensemble nvt --temp 300 --temp-end 1000 --nsteps 20000

# 4. Restart with Velocities: macer automatically detects and loads velocity block from CONTCAR/POSCAR
macer md -p CONTCAR --ensemble npt --temp 300 --ff mace

# 5. Manual NPT: Explicitly set coupling constants (ttau=100fs, ptau=1000fs)
macer md --ensemble npt --temp 600 --press 1.0 --ttau 100 --ptau 1000 --nsteps 20000

# 6. Langevin MD: Using explicit friction coefficient (ps^-1) for NVT
macer md -p POSCAR --ensemble nvt --temp 300 --thermostat langevin --friction 10.0

# 7. MD simulation with atomic mass override
macer md --ensemble npt --temp 300 --mass H 2.014 --output-dir D_MD

Path Integral Molecular Dynamics Examples (macer pimd)

macer pimd wraps the external PIMD core from PIMD_python and integrates it with macer I/O, MLFF bridging, and post-processing.

# Basic NVT run
macer pimd -p POSCAR --ff mattersim --temp 300 --nbead 4 --tstep 0.25 --nsteps 2000

# NVE run (temperature still used for initialization)
macer pimd -p POSCAR --ensemble nve --ff mattersim --temp 300 --nbead 8 --tstep 0.25 --nsteps 2000

# Restart from pimd snapshot
macer pimd --ff mattersim --temp 300 --nbead 4 --tstep 0.25 --nsteps 200 --restart ./pimd-run/restart.npz

# Multi-replica run (production fan-out; `--n-replica >= 2` enables replica mode)
macer pimd -p POSCAR --ff mattersim --temp 300 --n-replica 4 --nsteps 2000

# Replica with equilibration handoff
macer pimd -p POSCAR --ff mattersim --temp 300 --equil-steps 500 --n-replica 4 --nsteps 2000

# Fixed replica-count run (auto-tuner removed)
macer pimd -p POSCAR --ff mattersim --temp 300 --n-replica 8 --nsteps 2000

Notes:

• Replica mode safety default: if --n-replica >= 2 and --batch-size is omitted, force evaluation runs in sequential mode.
• Set --batch-size to enable native batch force evaluation in replica runs.
• Runtime logs include replica startup metadata (init_mode, per-replica seed) in pimd_replica_run.log and each replica-*/pimd.log.

Phonon & Lattice Dynamics Examples (macer phonopy)

Unit Cell Symmetrization (macer phonopy sr)

This is a first step for any lattice dynamics calculation to ensure a high-symmetry structure.

# Iteratively relax and symmetrize a unit cell
macer phonopy sr --poscar POSCAR --tolerance 1e-3

Phonon Bands & Grüneisen Parameter (macer phonopy pb)

Calculates and plots the phonon band structure.

# Calculate phonon bands using an automatically determined supercell size
macer phonopy pb -p ./example/POSCAR

# Explicitly set the supercell dimension
macer phonopy pb -p ./example/POSCAR --dim 2 2 2

# Calculate and plot the Grüneisen parameter, with automatic strain estimation.
# This automatically generates interactive 3D plots (HTML).
macer phonopy pb -p ./example/POSCAR --dim 2 2 2 --plot-gruneisen

# Calculate irreducible representations and generate VESTA visualization for the Gamma point
macer phonopy pb -p ./example/POSCAR --irreps
...
# Calculate and plot Phonon DOS (Total + Projected).
macer phonopy pb -p POSCAR --dos --mesh 20 20 20

Interactive 3D Grüneisen Visualization: When using --plot-gruneisen (-pg), Macer generates interactive 3D visualizations (.html) of Grüneisen parameters over the Brillouin Zone. The plot includes the 1st Brillouin zone wireframe, special q-points (seekpath), and reciprocal basis vectors (b1/b2/b3) drawn as arrows with labels.

Quasiharmonic Approximation (macer phonopy qha)

Automates the full QHA workflow to compute thermodynamic properties.

# Run a full QHA workflow, automatically estimating the volume range
macer phonopy qha --poscar POSCAR --num-volumes 7 --tmax 1200

# Run QHA with a specific supercell dimension and a manually specified volume range
macer phonopy qha --poscar POSCAR --dim 2 2 2 --length-factor-min 0.98 --length-factor-max 1.02

# Run QHA using a local polynomial fit for the equation of state
macer phonopy qha --poscar POSCAR --eos local_poly

NAC (BORN) for pb / qha / sscha / tc

Use a VASP-derived BORN file to enable LO-TO non-analytic correction.

# Prepare BORN from VASP (LEPSILON=.TRUE. single-point)
phonopy-vasp-born > BORN

# Case 1: Basic NAC (default method)
macer phonopy pb -p POSCAR --born ./BORN
macer phonopy qha -p POSCAR --born ./BORN
macer phonopy sscha -p POSCAR -T 300 --born ./BORN

# Case 2: Explicit NAC method + q->0 direction
macer phonopy pb -p POSCAR --born ./BORN --nac-method wang --nac-q-direction 1 1 0
macer phonopy qha -p POSCAR --born ./BORN --nac-method wang --nac-q-direction 1 1 0
macer phonopy sscha -p POSCAR -T 300 --born ./BORN --nac-method wang --nac-q-direction 1 1 0
macer phonopy tc -p POSCAR --born ./BORN --nac-method wang --nac-q-direction 1 1 0

Notes:

• --nac-method and --nac-q-direction require --born.
• For macer phonopy ft, NAC is enabled by --born and current DynaPhoPy bridge supports --nac-method gonze.

qSCAILD (macer phonopy qscaild, alias: macer phonopy sscha)

Performs a qSCAILD workflow to find temperature-dependent effective force constants.

# Basic qSCAILD run at 300K with auto-sized supercell
macer phonopy qscaild -p POSCAR -T 300 --nsteps 20

# Continue from an existing initial FC and fixed supercell
macer phonopy qscaild -p POSCAR -T 500 --read-initial-fc FORCE_CONSTANTS --dim 2 2 2 --nconf 20 --nsteps 30

# Pressure-coupled run
macer phonopy qscaild -p POSCAR -T 500 --use-pressure cubic --pressure-diag 0 0 0 --pdiff 2.0 --nconf 10 --nsteps 30

# Include 3rd order force constants in the fitting process
macer phonopy qscaild -p POSCAR -T 300 --include-third-order --nconf 20 --nsteps 50 --save-every 5

Anharmonic Phonon Analysis (macer phonopy finite-temperature, aliased to ft)

Calculates finite-temperature renormalized phonon dispersion and quasiparticle properties (linewidths, shifts) using MD and DynaPhoPy.

# Standard workflow: Auto-supercell, harmonic reference, and renormalization at 800K
# (Default algorithm: FFT/Direct, -psm 2)
macer phonopy ft -p POSCAR -T 800 --ff mattersim

# Run with specific supercell and MD settings (recommended for production)
macer phonopy ft -p POSCAR -T 800 --dim 2 2 2 --md-steps 10000 --md-equil 2000

# Multi-temperature run with comparison plot (e.g., 300K vs 800K)
macer phonopy ft -p POSCAR -T 300 800 --dim 2 2 2

# High-resolution analysis: Project onto specific q-point and save quasiparticle data
macer phonopy ft -p POSCAR -T 300 --dim 3 3 3 --resolution 0.01 --projection-qpoint 0.5 0.0 0.0 --save-quasiparticles

# Direct MD: Use a large input supercell as-is (no expansion)
macer phonopy ft -p POSCAR_SUPERCELL -T 300 --no-supercell

Lattice Thermal Conductivity (macer phonopy thermal-conductivity, aliased to tc)

Calculates lattice thermal conductivity by solving the linearized Boltzmann transport equation (LBTE) using phono3py. This workflow automates structure relaxation, dual supercell generation (FC3/FC2), force calculation with MLFFs, and post-processing.

# Basic run with auto-configured dual supercell (FC3~12A, FC2~25A) and relaxation
macer phonopy tc -p POSCAR --mesh 11 11 11

# Run with specific supercell dimensions and temperature range
macer phonopy tc -p POSCAR --dim 2 2 2 --dim-fc2 4 4 4 --mesh 11 11 11 --tmin 0 --tmax 1000

# Run for a specific temperature and save heavy HDF5 files for advanced post-processing
macer phonopy tc -p POSCAR --mesh 11 11 11 --temp 300 --save-hdf5

# Run using LBTE mode for higher accuracy (accurate for high-k materials)
macer phonopy tc -p POSCAR --lbte

Native Batch Evaluation (Common Controls)

Macer uses native batch inference first, then safely falls back to sequential evaluation when needed.

Applied workflows (current):

• macer phonopy pb
• macer phonopy qha
• macer phonopy qscaild / macer phonopy sscha
• macer phonopy tc
• macer util eval
• macer pimd (bead force bridge path)

Common options:

• --batch-size N: explicit mini-batch size (N >= 1).
  • Omit to use backend auto batching.
  • Effective meaning: number of structures evaluated per batch job call.
• --sequential (alias: --seq): force per-structure sequential mode.

Common behavior:

• Default: batch-first mode.
• If batch path fails at runtime: automatic sequential fallback with warning logs.

Examples:

# Auto batching (default)
macer phonopy tc -p POSCAR --temp 300

# Explicit mini-batch size
macer phonopy qha -p POSCAR --batch-size 8

# Force sequential mode
macer phonopy sscha -p POSCAR -T 300 --seq

Gibbs Free Energy Examples (macer gibbs)

Calculates the Gibbs Free Energy ($G(T)$) by integrating enthalpy from NPT MD simulations (Gibbs-Helmholtz integration).

# Calculate Gibbs energy from 100K to 1000K (default step 50K) using NPT MD
macer gibbs -p POSCAR --temp-start 100 --temp-end 1000

# Hybrid approach: Use QHA result as a low-T reference for absolute G(T)
# First, run QHA to get thermodynamic properties (e.g., at 300K)
# Then, use the free energy from QHA as the reference point
macer gibbs -p POSCAR --temp-start 300 --temp-end 1500 --qha-ref qha_results/thermal_properties.yaml

# Customize MD settings for integration
macer gibbs -p POSCAR --temp-start 100 --temp-end 500 --nsteps 50000 --ensemble npt --ff mace

Defect Analysis Examples (macer pydefect)

The macer pydefect command automates the point defect calculation workflow, integrating pydefect and vise for analysis and macer for MLFF-based structure relaxation. It is verified to work with pydefect v0.9.11 and vise v0.9.5.

Chemical Potential Diagram (macer pydefect cpd)

Generates the Chemical Potential Diagram (CPD) and determines the target chemical potential vertices.

# Generate CPD for a formula (retrieved from Materials Project)
macer pydefect cpd -f MgAl2O4

# Generate CPD for a specific MPID with dopants
macer pydefect cpd -m mp-1234 -d Ca Ti

Defect Formation Energy (macer pydefect defect)

Calculates defect formation energies for a set of defects given the CPD info.

# Run defect calculations (requires standard_energies.yaml and target_vertices.yaml from CPD step)
macer pydefect defect -p POSCAR -s standard_energies.yaml -t target_vertices.yaml --matrix 2 2 2

Full Workflow (macer pydefect full)

Runs the entire pipeline: CPD generation -> Supercell generation -> Defect Calculation -> Analysis.

# Run full workflow for a POSCAR file
macer pydefect full -p POSCAR --matrix 2 2 2 --min_atoms 100 --max_atoms 300

# Batch run for multiple POSCAR files using a glob pattern
macer pydefect full -p POSCAR-mp-* --matrix 2 2 2 -d Cl

Utility Suite (macer util)

The macer util command provides various post-processing and analysis tools, integrated into categories like md, model, and struct.

MD Post-processing (macer util md)

# Calculate ionic conductivity
# Automatically detects MD interval from XDATCAR/md.csv and charges from pydefect
macer util md conductivity -i ./md.traj -t 500 --dt 2

# Plot MD trajectory data (T, E, P from md.csv)
macer util md plot -i md.csv

# Calculate and plot Radial Distribution Function (RDF)
macer util md rdf -i md.traj

# Convert ASE .traj to VASP XDATCAR with a specific interval
macer util md traj2xdatcar -i md.traj --interval 50

# Print statistical summary of MD results
macer util md summary -i md.csv

DynaPhoPy Wrapper (macer util dynaphopy)

A direct wrapper for the dynaphopy CLI that benefits from Macer's runtime compatibility patches. Use this for manual, low-level trajectory analysis exactly as you would use the original dynaphopy command.

# Standard DynaPhoPy usage (arguments are passed through directly)
# Macer handles NumPy 2.x and Phonopy 2.x compatibility automatically.
macer util dynaphopy input_file XDATCAR -ts 0.001 --normalize_dos -i -psm 2

Phonon & Grüneisen Post-processing (macer util phonon)

# Plot phonon dispersion from .dat or .yaml file
macer util phonon band -i band.dat -y band.yaml

# Plot Grüneisen parameters with custom ranges and symmetric visual scaling
macer util phonon gruneisen -i gruneisen.dat -y band.yaml --gmin -50 --gmax 5

# Generate interactive 3D BZ plot of Grüneisen parameters from a full mesh data file
macer util phonon gruneisen-3d -i gruneisen_full.dat
> The 3D plot includes the 1st BZ wireframe, special q-points, and reciprocal basis arrows (`b1/b2/b3`). It outputs HTML/PDF/CSV and annotates Formula, SpaceGroup, and Path.

Model & Structure Utilities (macer util model/struct)

# Convert a model to float32 precision
macer util model fp32 -i model.pth

# Convert VASP4 POSCAR to VASP5 (adds element symbols to the header)
macer util struct vasp4to5 -i POSCAR

# Plot 1BZ wireframe + special q-points (HTML)
macer util struct bz-3d -p POSCAR
macer util struct bz-3d -f MgAl2O4
macer util struct bz-3d -m mp-3536

> `bz-3d` draws the 1st Brillouin zone wireframe, special q-points, and reciprocal basis arrows (`b1/b2/b3`).

---

Command Line Options

macer relax Options

Option	Description	Default
-p, --poscar	Input POSCAR file(s) or glob pattern(s).	POSCAR
--model	Path or name of the MLFF model.	(from default.yaml)
--ff	Force field to use.	(dynamic)
--isif	VASP ISIF mode (0–8) for relaxation.	3
--no-pdf	Do not generate the relaxation log PDF.	False
--output-dir	Directory to save output files.	None
--subdir	Create a RELAX-* subdirectory for outputs.	False
--fmax	Force convergence threshold (eV/Å).	0.01
--smax	Stress convergence threshold (eV/ų).	0.001
--press, --pressure	Target external pressure [GPa] for volume-changing ISIF modes (3, 6, 7, 8).	0.0
--bulk-modulus	Perform bulk modulus calculation instead of relaxation.	False
--strain	Max strain for E-V curve (e.g., 0.05 for ±5%).	0.05
--eos	Equation of state for bulk modulus (birchmurnaghan or murnaghan).	birchmurnaghan

POSCAR/CIF and MP download priority: When both -p and -f/-m are provided, -p takes precedence. The -p option accepts POSCAR or CIF; the format is detected automatically. For VASP4 POSCARs (no element symbols line), Macer will stop and ask you to convert to VASP5 format (e.g., macer util struct vasp4to5).

Materials Project access: -f/--formula and -m/--mpid require a Materials Project API key. Set it via export MP_API_KEY="your_api_key" in your shell config (.bashrc or .zshrc).

macer md Options

Option	Description	Default
-p, --poscar	Input POSCAR/CONTCAR file. Supports velocity loading.	POSCAR
--ensemble	MD ensemble: npt, nvt (or nte), or nve.	npt
--temp, --tebeg	Target or starting temperature [K] (VASP TEBEG).	300.0
--temp-end, --teend	Final temperature [K] for linear ramping (VASP TEEND).	None
--press	Target pressure [GPa] (NPT only).	0.0
--tstep	MD time step [fs].	2.0
--ttau	Thermostat time constant [fs].	0 (auto: 40*dt)
--ptau	Barostat time constant [fs] (NPT only).	0 (auto: from B)
--pfactor	Directly set ASE NPT pfactor (overrides ptau).	None
--nsteps	Number of MD steps.	20000
--output-dir	Directory to save MD output files.	.
--mass	Specify atomic masses (e.g., H 2.014).	None
--initial-relax	Perform a full structural relaxation before the MD run.	False

Replica extensions (macer md):

• --replica, --n-replica: Enable multi-replica production fan-out.
• --equil-steps, --equil-ps: Equilibration handoff before production fan-out.

macer phonopy Options

macer phonopy pb Options

Option	Description	Default
-p, --poscar	Input POSCAR or CIF file(s).	Required
-f, --formula	Chemical formula to retrieve from Materials Project (e.g., MgAl2O4).	None
-m, --mpid	Materials Project ID (e.g., mp-3536).	None
-l, --length	Minimum supercell lattice vector length in Å.	20.0
--dim	Set supercell dimension explicitly (e.g., 2 2 2). Overrides -l.	None
-pg, --plot-gruneisen	Calculate and plot Grüneisen parameter.	False
--strain	Strain for Grüneisen calculation. If not set, estimated from bulk modulus.	None
--irreps	Calculate irreducible representations.	False
--qpoint	Q-point for irreps calculation (3 floats).	0 0 0
--write-arrow	Write VESTA and MCIF files for phonon mode visualization.	False
--arrow-length	Max arrow length in Å for VESTA visualization.	1.7
--arrow-qpoint-gamma	Generate arrows only for the Gamma point.	False
--arrow-qpoint	Generate arrows for a specific q-point vector (3 floats).	None
--dos	Calculate and plot Phonon DOS (Total + Projected).	False
--mesh	Q-point mesh for DOS calculation (3 ints).	20 20 20
--mass	Specify atomic masses (e.g., H 2.014).	None
--output-dir	Directory to save output files.	None

macer phonopy qha Options

Option	Description	Default
--dim	Set supercell dimension explicitly (e.g., 2 2 2). Overrides --min-length.	None
--num-volumes	Number of volume points to sample for the E-V curve.	5
--length-scale	Symmetric strain range for volume sampling (e.g., 0.05 for ±5%). Auto-estimated if not set.	None
--length-factor-min/max	Explicitly define the min/max length scaling factors for the volume range.	None
--eos	Equation of state for fitting (vinet, birch_murnaghan, murnaghan, local_poly).	vinet
--tmax	Maximum temperature for thermal property calculation.	1300 K
--mass	Specify atomic masses (e.g., H 2.014).	None
--output-dir	Directory to save all output files.	(auto)

macer phonopy qscaild Options

The qSCAILD workflow is divided into several stages, each with its own set of options.

Group	Option	Description	Default
General	-p, --poscar	Input crystal structure file (e.g., POSCAR).	Required
	--ff	Force field to use.	(dynamic)
	--model	Path or name of the MLFF model.	(from default.yaml)
	--device	Compute device (cpu, mps, cuda).	cpu
	--modal	Modal for SevenNet model, if required.	None
	--seed	Random seed for reproducibility.	None
Initial FC	--initial-fmax	Force convergence for initial relaxation (eV/Å).	5e-3
	--dim	Supercell dimension (e.g., 2 2 2). Overrides --min-length.	(auto)
	-l, --min-length	Minimum supercell length if --dim is not set (Å).	15.0
	--amplitude	Displacement amplitude for 0K FC calculation (Å).	0.03
	--pm	Use plus/minus displacements for initial FC generation.	False
	--nodiag	Do not use diagonal displacements for initial FC generation.	False
	--symprec	Symmetry tolerance for phonopy (Å).	1e-5
	--read-initial-fc	Path to FORCE_CONSTANTS to skip initial calculation.	None
	--initial-symmetry-off	Disable FixSymmetry in the initial structure relaxation.	False
Ensemble	--reference-method	Reference method (currently random is supported in qSCAILD mode).	random
qSCAILD	-T, --temperature	Target temperature in Kelvin.	Required
	--nconf	Number of displaced configurations per cycle.	10
	--nsteps	Maximum number of qSCAILD cycles.	100
	--memory	History fraction used for multi-cycle reweighting fit.	0.3
	--mixing	Linear mixing factor for IFC update.	0.0
	--tolerance	IFC convergence tolerance.	1e-2
	--pdiff	Pressure convergence tolerance (kbar).	1.0
	--grid	q-grid size for covariance construction.	9
	--use-smalldisp	Use small-displacement mode.	False
	--imaginary-freq	Imaginary-frequency handling parameter (THz).	1.0
	--use-pressure	Pressure-driven cell update mode (False, cubic, tetragonal, orthorhombic).	False
	--pressure-diag	Target diagonal pressure components (kbar).	0 0 0
	--mesh	Q-point mesh for free energy calculation (e.g., 7 7 7).	7 7 7
	--include-third-order	Enable simultaneous fitting of 3rd order force constants.	False
Compatibility	--optimize-volume	Compatibility flag (currently ignored in qSCAILD mode).	False
Output	--output-dir	Directory to save all output files.	qscaild_{poscar_stem}-mlff={ff}
	--save-every	Save intermediate FORCE_CONSTANTS every N steps.	5
	--no-plot-bands	Disable plotting of band structures.	(Plotting is on)
	--gamma-label	Label for the Gamma point in plots.	GM

macer phonopy thermal-conductivity (aliased to tc) Options

Option	Description	Default
--mesh	Q-point mesh for thermal conductivity calculation (e.g., 11 11 11).	11 11 11
-l, --length	Min length for auto-determining FC3 dim (Å).	12.0
-l2, --length-fc2	Min length for auto-determining FC2 dim (Å).	25.0
--dim	FC3 supercell dimension (e.g., 2 2 2). Overrides -l.	(auto)
--dim-fc2	FC2 supercell dimension (e.g., 4 4 4). Overrides -l2.	(auto)
--temp, --ts	Specific temperatures to calculate (e.g., 300 400).	None
-f, --formula	Chemical formula to retrieve from Materials Project (e.g., MgAl2O4).	None
-m, --mpid	Materials Project ID (e.g., mp-3536).	None
--save-hdf5	Save heavy HDF5 files (kappa, fc2, fc3) for post-processing.	False
--tmin/tmax/tstep	Temperature range settings if --temp not set.	0/1000/10
--amplitude	Displacement amplitude (Å).	0.03
--isif	ISIF mode for initial relaxation (0 to skip).	3

macer phonopy finite-temperature (aliased to ft) Options

Option	Description	Default
-p, --poscar	Input crystal structure file.	Required
-T, --temp	List of temperatures to calculate (K).	Required
--ensemble	MD ensemble for renormalization: nvt or npt.	nvt
--dim	Supercell dimension (e.g., 2 2 2).	(auto)
-l, --min-length	Min supercell length if --dim is not set (Å).	15.0
--md-steps	MD production steps.	8000
--md-equil	MD equilibration steps.	2000
--tstep	MD time step in fs.	1.0
--ttau	Thermostat time constant [fs].	0 (auto)
--ptau	Barostat time constant [fs] (NPT only).	0 (auto)
--pfactor	Directly set ASE NPT pfactor.	None
--thermostat	MD thermostat (nose-hoover, langevin).	nose-hoover
--psm	Power spectrum algorithm (1: MEM, 2: FFT/Direct).	2
--mem	Number of MEM coefficients (only for --psm 1).	1000
`--resolution"	Power spectrum resolution (THz).	0.05
--projection-qpoint	Reduced q-vector for projection (e.g., 0.5 0.0 0.0).	None
--save-quasiparticles	Save frequency shift/linewidth data to YAML.	False
--thermal-properties	Calculate thermal properties (Free energy, Entropy).	True
--no-thermal-properties	Disable thermal properties calculation.	False
--power-spectrum	Calculate and save power spectrum data.	True
--no-power-spectrum	Disable power spectrum calculation.	False
--no-fcsymm	Disable force constant symmetrization.	False

macer gibbs Options

Option	Description	Default
-p, --poscar	Input crystal structure file.	POSCAR
--temp-start	Starting temperature (K).	100
--temp-end	Ending temperature (K).	1000
--temp-step	Temperature step size (K).	50
--nsteps	Number of MD production steps per temperature.	50000
--equil-steps	Number of MD equilibration steps.	10000
--ensemble	MD ensemble (npt, nvt).	npt
--pressure	Target pressure for NPT (GPa).	0.0
--qha-ref	Path to QHA result YAML for absolute G(T) reference.	None
--output-dir	Directory to save results.	(auto)

macer pydefect Options

macer pydefect cpd Options

Option	Description	Default
-f, --formula	Chemical formula to retrieve from Materials Project (e.g., MgAl2O4).	None
-m, --mpid	Materials Project ID (e.g., mp-3536).	None
-d, --doping	List of dopant elements (e.g., Ca Ti).	None
-p, --poscar	Input POSCAR file(s) or glob pattern(s).	None
--energy-shift-target	Manually shift target energy in eV/atom (e.g., 0.05 to lower energy by 0.05 eV).	0.0

macer pydefect defect Options

Option	Description	Default
-p, --poscar	Input unit cell POSCAR file(s) or glob pattern(s).	Required
-d, --doping	List of dopant elements (e.g., Ca Ti).	None
-s, --std_energies	Path to standard_energies.yaml from CPD step.	Required
-t, --target_vertices	Path to target_vertices.yaml from CPD step.	Required
--matrix	Supercell matrix (e.g., 2 2 2).	None
--min_atoms	Minimum number of atoms for supercell.	50
--max_atoms	Maximum number of atoms for supercell.	300
--no_symmetry_analysis	Disable symmetry analysis (requires sites_yaml).	False
--sites_yaml	Path to sites.yaml file (if symmetry analysis is disabled).	None

macer pydefect full Options

Option	Description	Default
-p, --poscar	Input unit cell POSCAR file(s) or glob pattern(s).	Required
-d, --doping	List of dopant elements (e.g., Ca Ti).	None
--matrix	Supercell matrix (e.g., 2 2 2).	None
--min_atoms	Minimum number of atoms for supercell.	50
--max_atoms	Maximum number of atoms for supercell.	300
--no_symmetry_analysis	Disable symmetry analysis (requires sites_yaml).	False
--sites_yaml	Path to sites.yaml file (if symmetry analysis is disabled).	None
--energy-shift-target	Manually shift target energy in eV/atom.	0.0

---

Dependencies

Core Dependencies

• Python ≥ 3.10
• ASE (Atomic Simulation Environment)
• Phonopy & Phono3py
• Pymatgen & Monti
• seekpath
• pydefect & vise (for defect analysis)

MLFF Support (Unified Environment)

Macer supports multiple MLFFs in a single environment.

• MACE: Bundled internally (legacy e3nn conflict is handled via shimming).
• SevenNet / FairChem: Uses global e3nn >= 0.5.1.
• MatterSim, CHGNet, M3GNet (matgl), Orb, Allegro (nequip): Integrated and ready to use after pip install -e ..

---

Related packages

• phonopy https://github.com/phonopy/phonopy
• phono3py https://github.com/phonopy/phono3py
• DynaPhoPy https://github.com/abelcarreras/DynaPhoPy
• symfc https://github.com/symfc/symfc
• pydefect https://github.com/kumagai-group/pydefect
• SeeK-path https://github.com/giovannipizzi/seekpath

---

Model & Structure Utilities (macer util model/struct)

# Convert a model to float32 precision
macer util model fp32 -i model.pth

# Convert VASP4 POSCAR to VASP5 (adds element symbols to the header)
macer util struct vasp4to5 -i POSCAR

---

Mattersim Fine-tuning (macer util ft)

Specialized workflow for fine-tuning Mattersim pre-trained models. It refines pre-trained models using your own DFT data (e.g., extended xyz format or VASP ML_AB file) and performs automatic evaluation.

# Standard fine-tuning with auto-splitting (8:1:1) and auto-evaluation
macer util ft -d dataset.xyz --epochs 100

# Use 100% of data for training (no test set) with a specific base model
macer util ft -d dataset.xyz --full-train --model ./base_model.pth

# Custom validation data and differential learning rates (Head vs Backbone)
# Recommended: Higher Head LR for adapting to new chemical species
macer util ft -d train.xyz --valid-data valid.xyz --head-lr 1e-3 --backbone-lr 1e-5

# Fine-tuning without stress training (e.g., if using ISIF=0 data)
macer util ft -d dataset.xyz --epochs 10 --no-stresses

# SELECT-aware split from VASP logs:
# train = selected, valid/test = unselected
macer util ft -d ML_ABN --ml-logfile ML_LOGFILE

# Or use stdout.log only
macer util ft -d ML_ABN --stdout-log stdout.log

In SELECT-aware mode, --ratio a b c uses b:c as validation:test ratio. Default --ratio 0.8 0.1 0.1 means validation:test = 1:1.

---

Fine-tuning Data Convert (macer util ft-convert, ftc)

# Basic conversion: ML_AB -> extxyz
macer util ft-convert -i ML_AB -o dataset.mattersim.xyz

# SELECT-mode extraction from ML_ABN + log
# (at least one of --ml-logfile or --stdout-log is required;
#  --select is auto-enabled when either is provided)
macer util ft-convert -i ML_ABN --ml-logfile ML_LOGFILE
macer util ft-convert -i ML_ABN --stdout-log stdout.log

# Optional cross-check with both logs
macer util ft-convert -i ML_ABN --ml-logfile ML_LOGFILE --stdout-log stdout.log

# Output files:
#   ML_ABN-total.xyz
#   ML_ABN-selected-ml-mode.xyz
#   ML_ABN-unselected.xyz
#   POSCAR-SELECTED-CONFIG-001..N (sequential by generation order)

For VASP SELECT-mode extraction, attach ML_LOGFILE generated with:

ML_LMLFF   = .TRUE.
ML_MODE    = SELECT
ML_EPS_LOW = 1E-9

--poscar-dir default is <input>-selected-poscars. If the directory already exists, -NEW### is appended automatically to avoid collisions.

Manual delta dataset generation (dataset.xyz -> dataset-delta.xyz) is also supported:

# Build delta labels using default configured MatterSim model (~/.macer.yaml -> models.mattersim)
macer util ft-convert -i dataset.xyz --delta-dataset

# Explicit base model + metadata sidecar
macer util ft-convert -i dataset.xyz --delta-dataset \
  --delta-base-model mattersim-v1.0.0-1M.pth \
  --delta-write-metadata dataset-delta-metadata.json

# Custom output path
macer util ft-convert -i dataset.xyz --delta-dataset --delta-out dataset-delta.xyz

--delta-base-model has alias --model.
Delta label construction reuses the same prediction stack as macer util evaluate: calculator factory routing, batch-first inference (evaluate_batch), sequential fallback, and stress-unit handling.

Practical guidance:

• Delta learning is most useful when your target labels are systematically different from foundation-PBE behavior (e.g., higher-level corrections with small expensive datasets).
• If selected/unselected are already close to foundation distribution, direct fine-tuning can outperform delta.

---

Standalone Scripts

The scripts/ directory contains standalone versions of some key workflows, which can be run directly with python.

---

MLFF Model Attribution

This project integrates various Machine-Learned Force Fields (MLFFs). For more information, please refer to the official repositories:

• MACE: https://github.com/ACEsuit/mace-foundations
• SevenNet: https://github.com/MDIL-SNU/SevenNet
• CHGNet: https://github.com/CederGroupHub/chgnet
• M3GNet: https://github.com/materialsvirtuallab/m3gnet
• Allegro: https://github.com/mir-group/nequip
• MatterSim: https://github.com/microsoft/mattersim
• Orb: https://github.com/orbital-materials/orb-models
• FairChem: https://github.com/facebookresearch/fairchem (Models available at Hugging Face)

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Contributors

• Soungmin Bae — [e-mail], Tohoku University
• Yasuhide Mochizuki — [e-mail], Institute of Science Tokyo
• Kuwahata Kazuaki — [e-mail], Graduate School of Nanobioscience, Yokohama City University, Yokohama, Japan