Skip to content

deepmodeling/APEX

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

745 Commits
.github
.github
 
 
apex
apex
 
 
docs
docs
 
 
examples
examples
 
 
tests
tests
 
 
.gitignore
.gitignore
 
 
CHANGELOG-1.3.0.md
CHANGELOG-1.3.0.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
setup.py
setup.py
 
 

Repository files navigation

APEX: Alloy Property EXplorer

1.3.0 Changelog

APEX helps materials scientists build reliable alloy property workflows that run on local machines, on-premises clusters, or the Bohrium cloud. It refactors the DP-GEN auto_test module into a flexible, dflow-powered Python package that prepares tasks, dispatches calculations, monitors progress, and collects results for calculators such as LAMMPS, VASP, and ABACUS.

Fig1

The comprehensive architecture of APEX is demonstrated below:

Fig1

Figure 1. Schematic diagram of APEX

APEX currently offers calculation methods for the following alloy properties:

  • Equation of State (EOS)
  • Cohesive energy vs. lattice scaling (cohesive energy line)
  • Surface energy
  • Decohesive energy vs. separation (decohesive energy line)
  • Elastic constants
  • Vacancy formation energy
  • Interstitial formation energy
  • Generalized stacking fault energy (Gamma line/Gamma Surface)
  • Phonon spectra
  • Grüneisen parameters and thermal expansion
  • Finite-temperature lattice parameters (FiniteTlatt)
  • Finite-temperature Elastic Constant (FiniteTelastic)
  • Annealing with RDF, MSD, and volume-temperature analysis

What's Inside

1.Installation

1.1. Install APEX

There are two ways to install APEX:

Option 1: Install from PyPI (recommended for most users)

pip install apex-flow

Option 2: Install from Source (latest features / development)

git clone https://github.com/deepmodeling/APEX.git
cd APEX
pip install .

2. Quick Start

To submit an APEX workflow, you need to organize three essential components in your working directory:

  1. A work directory with initial structures and computational files
  2. Calculation parameter files specifying what to compute
  3. Global configuration files specifying where and how to compute

We present a quick example using a LAMMPS_example to compute the Equation of State (EOS) and elastic constants of molybdenum (Mo) metal in both Body-Centered Cubic (BCC) phase.

2.1. Work Directory Structure

Create your working directory with the following structure:

lammps_demo/
├── confs/
│   ├── std-bcc/
│       └── POSCAR
├── frozen_model.pb
├── global_bohrium.json
└── param_joint.json

Directory Organization:

  • confs/ subdirectory: Contains initial crystal structures in POSCAR format for different phases (BCC, FCC). These are the starting geometries for your calculations. To compute the properties of Mo in BCC/FCC phases, you can download the corresponding POSCAR files from Materials Project.

  • frozen_model.pb: The machine learning potential model file (or other force field files). This is the pre-trained model used to perform the calculations.

  • param_*.json files: Specify the computational requirements:

    • param_joint.json - Parameters for structure relaxation and property calculations

  • global_bohrium.json: Provides computing resource information for Bohrium cloud platform execution.

2.1.1 Random Solid Solution (RSS) Generation

APEX provides a pseudo Monte Carlo sampler to generate random solid solutions with user-defined Warren-Cowley short-range order (SRO) targets.

Run RSS generation with:

apex rss rss.json

Required input structure definition

In rss.json, provide one of the following:

  • parent_structure: path to an existing structure file (typically POSCAR)
  • parent_lattice: programmatic parent lattice definition

Example parent_lattice:

{
  "parent_lattice": {
    "type": "B2",
    "a": "auto",
    "supercell": "auto"
  },
  "composition_tolerance": 0.001,
  "supercell_shape": "near_cubic",
  "maxmium_nums_atoms": 128
}

Current supported parent_lattice.type: fcc, bcc, sc, hcp, diamond, B2, L12, L10.

Key RSS parameters

  • supercell (array[int, int, int]): expands the loaded/built parent structure. If you also set parent_lattice.supercell, both expansions are applied.
  • output_structure (string): output root directory for generated configurations. Default is RSS. Each generated structure is written to a separate conf_###/POSCAR directory, such as conf_001/POSCAR.
  • compositions (object): species fractions per sublattice. Fractions within each sublattice must sum to 1.0.

Commonly used controls:

  • sro_targets, shell_cutoffs, shell_weights
  • max_steps, temperature, tol, patience
  • num_configs, interval, seed, metadata, show_progress

For a complete key-by-key reference and runnable examples, see examples/rss/README.md.

2.2. Calculation Parameter Files

Calculation parameter files define what properties to compute and with what parameters.

Joint Parameter File

This file contains parameters for geometry optimization, structure relaxation and property calculations:

Important: The Json format does not support adding annotations. The annotations provided below are for reference only.

{
  "structures":            ["confs/std-*"],  # Input structure paths
  "interaction": {
    "type":           "deepmd",              # Interaction type
    "model":          "frozen_model.pb",     # Model file path
    "type_map":       {"Mo": 0}              # Element type mapping
  },
  "relaxation": {
    "cal_setting":   {
      "etol":       0,        # Energy tolerance
      "ftol":     1e-10,      # Force tolerance
      "maxiter":   5000,      # Maximum iterations
      "maximal":  500000      # Maximum evaluation steps
    }
  },
  "properties": [
    {
      "type":         "eos",                 # Property type: Equation of State
      "vol_start":    0.6,                   # Starting volume (relative)
      "vol_end":      1.4,                   # End volume (relative)
      "vol_step":     0.1,                   # Volume step
    },
    {
      "type":         "elastic",             # Property type: Elastic constants
    }
  ]
}

2.3. Global Configuration Files

Global configuration files specify where and how your workflows should be executed.

Configuration for Bohrium Cloud Platform

Create global_bohrium.json to submit workflows to the Bohrium cloud platform:

{
  "lammps_image_name": "registry.dp.tech/dptech/prod-11045/deepmdkit-phonolammps:2.1.1",
  "lammps_run_command":"lmp -in in.lammps",
  "scass_type":"c8_m31_1 * NVIDIA T4"
}

APEX now injects Bohrium defaults automatically (dflow_host, k8s_api_server, batch_type, context_type, apex_image_name).

Save your Bohrium account once in ~/.apex/account.json:

apex account

Or set it directly:

apex account --email YOUR_EMAIL --password YOUR_PASSWD --program-id 1234

When running apex submit -c global_bohrium.json, values in your json file still have highest priority and override the saved defaults.

2.4. Submit Your First Workflow

Once you have prepared all necessary files and configuration, submit your workflow using the Bohrium platform (as shown in the Quick Start example):

apex submit param_joint.json -c global_bohrium.json

Monitor the workflow progress at https://workflows.deepmodeling.com.

2.5. Check Your Results

After the job is finished, you can check your results by:

apex report

For other submission examples, please refer to Lammps_tutorial.

3. User menu

3.1. Execution Backends

APEX builds on dflow to orchestrate cloud-native workflows. Choose the backend that matches your infrastructure:

  • Local debug (apex submit -d): Run everything on your workstation without Docker or Argo. Good for quick validation and debugging scripts.
  • Local Argo on Minikube: Use docs/scripts/install-linux-cn.sh (Unix-like) to bootstrap Docker, Minikube, and Argo with the UI on 127.0.0.1:2746. See the dflow tutorials for Windows setup.
  • Remote HPC via DPDispatcher: Define SSH credentials, scheduler options, and resource requirements inside your global config. APEX hands off the run step to DPDispatcher to submit jobs to Slurm or other supported schedulers.
  • Bohrium cloud: Leverage the managed Argo service and curated container images on Bohrium. You only need valid account credentials and program ID.

3.2 Prepare Your Input Files

Every submission needs three pieces:

  • Global configuration (global*.json): dflow, container, and dispatcher settings.
  • Calculation parameters (param*.json): structures, calculator inputs, and target properties.
  • Work directory: structure files, potential files, and any resources referenced by the parameter JSON (paths are relative to this directory).

Example layout (examples/lammps_demo):

lammps_demo
├── confs
│   ├── std-bcc
│   │   └── POSCAR
│   └── std-fcc
│       └── POSCAR
├── frozen_model.pb
├── global_bohrium.json
├── global_hpc.json
├── machine_hpc.json
├── param_joint.json
├── param_props.json
└── param_relax.json

3.3 Calculation parameter file types

Type File format Required dictionaries Typical use
Relaxation (param_relax.json) JSON structures, interaction, relaxation Prepare equilibrium structures
Property (param_props.json) JSON structures, interaction, properties Evaluate selected properties
Joint (param_joint.json) JSON structures, interaction, relaxation, properties Run relaxation followed by properties

Paths in these files should be relative to the work directory. The examples above cover standard Deep Potential workflows; see docs/Hands_on_auto-test.pdf for a complete walk-through.

3.4 Submit and Monitor Workflows

APEX chooses the workflow type from the parameter files you provide:

apex submit [-h] [-c CONFIG] [-w WORK [WORK ...]] [-d] [-s] [-f {relax,props,joint}] parameter [parameter ...]
  • parameter: one or more calculation JSON files (joint workflows accept both relax and property files).
  • -c: path to the global config (./global.json by default).
  • -w: override work directories (defaults to current directory).
  • -d: run in local debug mode (no containers).
  • -s: submit only, skip auto result retrieval.
  • -f: force workflow type when inferring from parameters is not desired.

Common management commands:

Command Purpose
apex list List workflows visible to the configured dflow service.
apex get -i <id> Inspect workflow metadata.
apex getsteps -i <id> Inspect step-by-step status.
apex getkeys -i <id> List step keys.
apex delete -i <id> Remove a workflow.
apex resubmit -i <id> Resubmit a workflow with the same settings.
apex retry -i <id> Retry failed steps.
apex resume -i <id> Resume a suspended workflow.
apex stop -i <id> / apex suspend -i <id> / apex terminate -i <id> Control workflow execution.

3.5 Run Individual Steps

For fine-grained debugging you can execute single steps locally via apex do:

  1. Generate tasks: 
    apex do param_relax.json make_relax
  2. Dispatch tasks (specify machine settings in a separate JSON if needed): 
    apex do param_relax.json run_relax -c machine_hpc.json
  3. Post-process results: 
    apex do param_relax.json post_relax

The same pattern applies to property calculations (make_props, run_props, post_props).

3.6 After Submission

  • Manual retrieval

    apex retrieve [-h] [-i ID] [-w WORK] [-c CONFIG]

    Useful when automatic retrieval is disabled (-s) or fails.

  • Archive results

    apex archive [parameters ...]

    Sync the latest property data into all_result.json, or push to MongoDB / DynamoDB by setting database_type in your global config. Use apex archive -h for details.

  • Interactive reports

    apex report -w WORKDIR [WORKDIR ...]

    Launch a Dash app (http://127.0.0.1:8050/) to explore multiple result sets side-by-side.

3.7 Graphical Interface (GUI)

APEX also provides a web GUI for common CLI operations (submit, list/get/retry/resume, retrieve, etc.):

apex gui [-H HOST] [-p PORT] [--no-browser]
  • Default URL: http://127.0.0.1:8060/
  • The GUI has four tabs:
    • Submit: simplified generator for param.json + global.json, then launch background submit (internally driven by the GUI wrapper rather than a single raw nohup apex submit ... command) (supports fixed element slots plus an extra-element input for larger interaction.type_map) (the generated param.json is merged from profile-specific param_structure.json + param_relax.json + param_props.json, and property checkboxes follow the selected profile) (now also merges profile param_interaction/param_interaction.json; for VASP/ABACUS you can edit interaction rows in table form, and default INCAR/INPUT files are auto-created from template when needed) (interaction table now supports dynamic add/remove rows; ABACUS uses a third orb_file column) (VASP/ABACUS also provide an INCAR/INPUT text editor in GUI; its content is written to the target file on submit) (when dflow can run at most 100 calculations per workflow, the GUI now auto-counts matched confs, splits them into batches of at most 100 confs, submits those workflows in parallel, and stores batch metadata in .apex-submit-group.json) (the Workflow ID(s) field accepts multiple workflow ids separated by commas; the GUI can aggregate progress across the whole batch) (you can also prefill multiple workflow ids manually by following the example template apex/default_config/gui_submit_group.template.json)
    • Manage: tail and refresh apex.log for background submit status
    • Advanced: run custom command tails (except gui/report, which are blocked to avoid nested Dash servers)
    • Account: overwrite Bohrium account fields (email/program_id/password) backed by apex account storage; password is never displayed in GUI (only "set/unset" status)

For manually tracking an existing workflow group in the GUI, fill the Workflow ID(s) field with comma-separated ids, for example:

wf-aaaa1111, wf-bbbb2222, wf-cccc3333

The progress bar and the step/conf statistics panel will aggregate all listed workflows together. A reusable example payload is provided at apex/default_config/gui_submit_group.template.json.

3.8 Bohrium Account Defaults

Use apex account to store Bohrium credentials globally (default path: ~/.apex/account.json):

# interactive mode
apex account

# non-interactive mode
apex account --email YOUR_EMAIL --password YOUR_PASSWD --program-id 1234

Useful commands:

apex account --show
apex account --reset

When you run apex submit -c global_bohrium.json, APEX auto-fills these defaults if missing:

  • dflow_host: https://workflows.deepmodeling.com
  • k8s_api_server: https://workflows.deepmodeling.com
  • batch_type: Bohrium
  • context_type: Bohrium
  • apex_image_name: registry.dp.tech/dptech/prod-11045/apex-dependency:1.2.0

Priority rule: values in your -c json file override account defaults.

4. Detailed Parameter Reference

4.1 Global configuration (global*.json)

Basic config

Key Type Default Description
apex_image_name String zhuoyli/apex_amd64 Image for steps other than run. Build from docs/Dockerfile if customising.
run_image_name String None Calculator image for the run step. Overrides {calculator}_image_name if both present.
run_command String None Command executed in the run step. Use {calculator}_run_command for calculator-specific overrides.
group_size Integer 1 Number of tasks grouped per parallel run.
pool_size Integer 1 Multiprocessing pool size when multiple tasks run locally (set -1 for unlimited).
upload_python_package List[String] None Extra Python packages to upload into the container.
debug_pool_workers Integer 1 Pool size when executing in debug mode (-d).
flow_name String None Custom workflow name (defaults to work directory name).
submit_only Bool False Submit without auto retrieval. Combine with apex retrieve later.

dflow config

Key Type Default Description
dflow_host String https://127.0.0.1:2746 dflow service endpoint.
k8s_api_server String https://127.0.0.1:2746 Kubernetes API endpoint.
dflow_config Dict None Advanced dflow settings (see documentation).
dflow_s3_config Dict None S3 storage configuration passed directly to dflow.

Dispatcher config (via DPDispatcher)

Key Type Default Description
context_type String None Dispatcher context (e.g., SSHContext, Bohrium, Local).
batch_type String None Scheduler / batch system (e.g., Slurm, Shell).
local_root String ./ Local root directory.
remote_root String None Remote working directory.
remote_host String None Remote host (deprecated in favour of machine.remote_profile).
remote_username String None Remote username.
remote_password String None Remote password.
port Integer 22 SSH port.
machine Dict None Full machine specification (overrides top-level keys).
resources Dict None Resource specification (nodes, queue, modules, etc.).
task Dict None Task specification (command, working directory, environment variables).

Bohrium extras

Key Type Default Description
email String None Bohrium account email.
phone String None Bohrium account phone.
password String None Bohrium password.
program_id Integer None Bohrium program ID.
scass_type String None Bohrium node type.

Note: in Bohrium workflows, these fields can be stored in ~/.apex/account.json via apex account.

4.2. Calculation parameters (param*.json)

The JSON schema inherits from dpgen.autotest. Below are example snippets for each workflow type:

  • Relaxation

    {
  "structures": ["confs/std-*"],
  "interaction": {
    "type": "deepmd",
    "model": "frozen_model.pb",
    "type_map": {"Mo": 0}
  },
  "relaxation": {
    "req_calc": true,
    "cal_setting": {
      "etol": 0,
      "ftol": 1e-10,
      "maxiter": 5000,
      "maximal": 500000
    }
  }
}

  • Property

    {
  "structures": ["confs/std-*"],
  "interaction": {
    "type": "deepmd",
    "model": "frozen_model.pb",
    "type_map": {"Mo": 0}
  },
  "properties": [
    {
      "type": "eos",
      "req_calc": true,
      "vol_start": 0.6,
      "vol_end": 1.4,
      "vol_step": 0.1,
      "cal_setting": {"etol": 0, "ftol": 1e-10}
    },
    {
      "type": "elastic",
      "req_calc": true,
      "norm_deform": 1e-2,
      "shear_deform": 1e-2,
      "cal_setting": {"etol": 0, "ftol": 1e-10}
    }
  ]
}

  • Joint

    {
  "structures": ["confs/std-*"],
  "interaction": {
    "type": "deepmd",
    "model": "frozen_model.pb",
    "type_map": {"Mo": 0}
  },
  "relaxation": {
    "cal_setting": {
      "etol": 0,
      "ftol": 1e-10,
      "maxiter": 5000,
      "maximal": 500000
    }
  },
  "properties": [
    {
      "type": "eos",
      "req_calc": true,
      "vol_start": 0.6,
      "vol_end": 1.4,
      "vol_step": 0.1,
      "cal_setting": {"etol": 0, "ftol": 1e-10}
    },
    {
      "type": "elastic",
      "req_calc": true,
      "norm_deform": 1e-2,
      "shear_deform": 1e-2,
      "cal_setting": {"etol": 0, "ftol": 1e-10}
    }
  ]
}

Relaxation selection behavior:

  • If relaxation.req_calc is omitted, relaxation is calculated by default.
  • In a joint workflow, set "relaxation": {"req_calc": false} to skip relaxation and submit properties from each structure directory's POSCAR.
  • When relaxation is skipped, APEX exposes that POSCAR as the equilibrium structure consumed by property setup.
  • elastic/vacancy/interstitial/surface/gammaline/gamma_surface require relaxation step

Property selection behavior:

  • If a property block is not present in properties, it is not calculated.
  • If a property block is present and req_calc is omitted, it is calculated by default.
  • Set "req_calc": false to explicitly disable that property.

4.3 EOS

Key Type Example Description
vol_start Float 0.9 Starting volume relative to the relaxed structure.
vol_end Float 1.1 Ending volume relative to the relaxed structure.
vol_step Float 0.01 Increment between volume points.
vol_abs Bool false Treat vol_start and vol_end as absolute volumes when true.

4.4 Cohesive energy line

Key Type Example Description
latt_start Float 0.9 Starting lattice size relative to the relaxed structure.
latt_end Float 1.1 Ending lattice size relative to the relaxed structure.
latt_step Float 0.01 Increment between lattice points.
latt_abs Bool false Treat latt_start and latt_end as absolute lattice sizes when true.

4.5 Decohesive energy line

Key Type Example Description
min_slab_size Integer 10 Minimum slab thickness.
max_vacuum_size Integer 11 Maximum vacuum width.
pert_xz Float 0.01 Perturbation along xz plane for surface energy.
miller_miller List[Int] [1, 1, 0] Miller indices of the target plane.

4.6 Elastic

Key Type Example Description
norm_deform Float 0.01 Normal strain applied in xx/yy/zz.
shear_deform Float 0.01 Shear strain applied to off-diagonal components.
conventional Bool false Use the conventional cell for deformation.
ieee Bool false Rotate relaxed structure into IEEE standard orientation.
modulus_type String "voigt" Bulk/shear modulus averaging method (voigt, reuss, vrh).

4.7 Surface

Key Type Example Description
min_slab_size Integer 10 Minimum slab thickness.
min_vacuum_size Integer 11 Minimum vacuum width.
pert_xz Float 0.01 Perturbation along xz plane for surface energy.
max_miller Integer 2 Maximum Miller index considered.

4.8 Vacancy

Key Type Example Description
supercell List[Int] [3, 3, 3] Supercell size built around the defect.

4.9 Interstitial

Key Type Example Description
insert_ele List[String] ["Al"] Elements to insert.
supercell List[Int] [3, 3, 3] Supercell size.
conf_filters Dict {"min_dist": 1.5} Filters to drop invalid configurations.
Fig3

4.10 Gamma line/surface (generalized stacking fault)

Fig2

Schematic of the Gamma line calculation

APEX generates displaced slab structures from the specified Miller plane and slip directions. The slip vector always follows the primary direction. Use predefined slip systems for FCC, BCC, and HCP crystals when possible to avoid invalid structures.

Crystal Plane Miller Slip direction Secondary direction Default slip length
FCC $(001)$ $[100]$ $[010]$ $a$
$(110)$ $[\bar{1}10]$ $[001]$ $\sqrt{2}a$
$(111)$ $[11\bar{2}]$ $[\bar{1}10]$ $\sqrt{6}a$
$(111)$ $[\bar{1}\bar{1}2]$ $[1\bar{1}0]$ $\sqrt{6}a$
$(111)$ $[\bar{1}10]$ $[\bar{1}\bar{1}2]$ $\sqrt{2}a$
$(111)$ $[1\bar{1}0]$ $[11\bar{2}]$ $\sqrt{2}a$
BCC $(001)$ $[100]$ $[010]$ $a$
$(111)$ $[\bar{1}10]$ $[\bar{1}\bar{1}2]$ $\frac{\sqrt{2}}{2}a$
$(110)$ $[\bar{1}11]$ $[00\bar{1}]$ $\frac{\sqrt{3}}{2}a$
$(110)$ $[1\bar{1}\bar{1}]$ $[001]$ $\frac{\sqrt{3}}{2}a$
$(112)$ $[11\bar{1}]$ $[\bar{1}10]$ $\frac{\sqrt{3}}{2}a$
$(112)$ $[\bar{1}\bar{1}1]$ $[1\bar{1}0]$ $\frac{\sqrt{3}}{2}a$
$(123)$ $[11\bar{1}]$ $[\bar{2}10]$ $\frac{\sqrt{3}}{2}a$
$(123)$ $[\bar{1}\bar{1}1]$ $[2\bar{1}0]$ $\frac{\sqrt{3}}{2}a$
HCP $(0001)$ $[2\bar{1}\bar{1}0]$ $[01\bar{1}0]$ $a$
$(0001)$ $[1\bar{1}00]$ $[01\bar{1}0]$ $\sqrt{3}a$
$(0001)$ $[10\bar{1}0]$ $[01\bar{1}0]$ $\sqrt{3}a$
$(01\bar{1}0)$ $[\bar{2}110]$ $[000\bar{1}]$ $a$
$(01\bar{1}0)$ $[0001]$ $[\bar{2}110]$ $c$
$(01\bar{1}0)$ $[\bar{2}113]$ $[000\bar{1}]$ $\sqrt{a^2+c^2}$
$(\bar{1}2\bar{1}0)$ $[\bar{1}010]$ $[000\bar{1}]$ $\sqrt{3}a$
$(\bar{1}2\bar{1}0)$ $[0001]$ $[\bar{1}010]$ $c$
$(01\bar{1}1)$ $[\bar{2}110]$ $[\bar{1}2\bar{1}\bar{3}]$ $a$
$(01\bar{1}1)$ $[\bar{1}2\bar{1}\bar{3}]$ $[2\bar{1}\bar{1}0]$ $\sqrt{a^2+c^2}$
$(01\bar{1}1)$ $[0\bar{1}12]$ $[\bar{1}2\bar{1}\bar{3}]$ $\sqrt{3a^2+4c^2}$
$(\bar{1}2\bar{1}2)$ $[10\bar{1}0]$ $[1\bar{2}13]$ $\sqrt{3}a$
$(\bar{1}2\bar{1}2)$ $[1\bar{2}13]$ $[\bar{1}010]$ $\sqrt{a^2+c^2}$

Key parameters:

Key Type Default Description
plane_miller Sequence[Int] None Miller indices of the target plane.
slip_direction Sequence[Int] None Primary slip direction.
slip_length Float or Sequence 1 Slip magnitude (vector format [x, y, z] means $\sqrt{(xa)^2 + (yb)^2 + (zc)^2}$).
plane_shift Float 0 Shift of the displacement plane in units of lattice parameter c.
n_steps Integer 10 Number of sampling points along the slip.
vacuum_size Float 0 Added vacuum layer thickness (Å).
supercell_size Sequence[Int] [1, 1, 5] Slab supercell size.
add_fix Sequence[String] ["true","true","false"] Position constraints along x/y/z.

Example:

{
  "type": "gamma",
  "req_calc": false,
  "plane_miller": [0, 0, 1],
  "slip_direction": [1, 0, 0],
  "hcp": {
    "plane_miller": [0, 1, -1, 1],
    "slip_direction": [-2, 1, 1, 0],
    "slip_length": [1, 0, 1],
    "plane_shift": 0.25
  },
  "supercell_size": [1, 1, 6],
  "vacuum_size": 10,
  "add_fix": ["true", "true", "false"],
  "n_steps": 10
}

To preview structure behave as expected before brusting computational resource, you can use preview to generate a gif file to visulize it.

apex preview gammaline.json

Nested dictionaries (fcc, bcc, hcp, etc.) override the top-level parameters for the corresponding lattice type.

Similarly, to investigate Gamma Surface, change the type to gamma_surface, and adjust steps accordingly. gamma_surface keeps the same crystallographic interface: plane_miller and slip_direction define the in-plane fault basis, vacuum_size = 0 gives a bulk-like periodic generalized stacking-fault calculation, and vacuum_size > 0 adds vacuum along the selected fault normal for slab/free-surface calculations.

"properties": [
        {
            "type": "gamma_surface",
            "req_calc": true,
            "plane_miller": [1, 1, 0],
            "slip_direction": [1, -1, -1],
            "supercell_size": [1, 1, 20],
            "vacuum_size": 15,
            "add_fix": ["true", "true", "false"],
            "n_steps_x": 20,
            "n_steps_y": 20
        }
    ]

4.11 Phonon spectra

APEX integrates parts of dflow-phonon and wraps Phonopy / phonoLAMMPS. SeeK-path automatically generates high-symmetry k-paths.

Important: Ensure the run_image (or local environment in debug mode) contains phonoLAMMPS when running LAMMPS-based phonon workflows.

Key Type Default Description
primitive Bool false Reduce to primitive cell before phonon calculation.
approach String "linear" VASP phonon method: "linear" or "displacement".
supercell_size Sequence[Int] [2, 2, 2] Supercell dimensions.
MESH Sequence[Int] None Reciprocal-space mesh (e.g., [8, 8, 8]).
PRIMITIVE_AXES String None Custom primitive axes definition ("0.0 0.5 0.5 0.5 0.0 0.5 0.5 0.5 0.0").
BAND String None Band path definition (falls back to SeeK-path when omitted).
BAND_LABELS String None Labels for band segments.
BAND_POINTS Integer 51 Number of sampling points per segment.
BAND_CONNECTION Bool true Enable band connection estimation.
seekpath_from_original Bool false Use seekpath.get_path_orig_cell instead of seekpath.get_path.
seekpath_param Dict None Extra arguments passed to SeeK-path.

The linear-response method accelerates calculations for metallic systems, while the finite-displacement approach works with any calculator that can provide forces (e.g., ABACUS).

4.12 Grüneisen parameters and thermal expansion

APEX supports Grüneisen workflows based on phonon calculations at multiple strained volumes. The sign_only mode evaluates the heat-capacity-weighted Grüneisen sum and its sign, while the full mode additionally fits the bulk modulus from the volume-energy points and reports the volumetric thermal expansion coefficient.

Key Type Default Description
volume_strains Sequence[Float] Required Symmetric volume strains around 0.0, e.g. [-0.01, 0.0, 0.01].
temperatures Sequence[Float] Required Temperatures for heat-capacity weighting and thermal expansion output.
alpha_mode String "sign_only" Output mode: "sign_only" or "full".
bulk_modulus_source String "eos_fit" Bulk modulus source for full mode.
eos_model String "birch_murnaghan" EOS model used for the bulk-modulus fit.
primitive Bool false Reduce to primitive cell before phonon calculation.
approach String "linear" Phonon workflow approach; VASP Grüneisen currently uses linear response.
supercell_size Sequence[Int] [2, 2, 2] Phonon supercell dimensions.
MESH Sequence[Int] None Reciprocal-space mesh for mode summation.
PRIMITIVE_AXES String None Custom primitive axes definition.
BAND String None Band path definition (falls back to SeeK-path when omitted).
BAND_LABELS String None Labels for band segments.
BAND_POINTS Integer 51 Number of sampling points per segment.
BAND_CONNECTION Bool true Enable band connection estimation.

For full mode, use fixed-volume internal relaxation in cal_setting (relax_pos = true, relax_shape = false, relax_vol = false) so the phonon and energy points share the intended volume grid.

4.13 Finite-temperature lattice parameters

APEX supports lattice parameter calculations at finite temperatures using molecular dynamics in LAMMPS. This workflow performs NVT equilibration at target temperatures and averages lattice parameters over the equilibrated trajectory.

Key Type Default Description
supercell_size Sequence[Int] [2, 2, 2] Supercell dimensions for the simulation.

LAMMPS-specific calculation settings in cal_setting:

Key Type Default Description
temperature Sequence[Float] Required Target temperatures (K) for lattice parameter calculation, e.g., [200, 400, 600, 800].
equi_step Integer 80000 Number of equilibration steps before averaging.
ave_step Integer 40000 Number of steps for averaging lattice parameters.
timestep Float 0.001 MD timestep (ps).
tdamp Float 0.1 Thermostat damping parameter.
pdamp Float 1.0 Barostat damping parameter.
N_every Integer 100 Interval for computing averages.
N_repeat Integer 10 Number of average samples.
N_freq Integer 2000 Sample output frequency.

Example:

{
  "type": "finite_t_latt",
  "supercell_size": [2, 2, 2],
  "cal_setting": {
    "temperature": [200, 400, 600, 800],
    "equi_step": 80000,
    "ave_step": 40000,
    "timestep": 0.001,
    "tdamp": 0.1,
    "pdamp": 1.0,
    "N_every": 100,
    "N_repeat": 10,
    "N_freq": 2000
  }
}

4.14 Finite-temperature elastic constant

APEX supports elastic constant calculations at finite temperatures using molecular dynamics in LAMMPS. This implementation uses the noise-cancellation method (see DOI: 10.1103/sd49-wqd6) to compute temperature-dependent elastic constants from stress fluctuations.

Key Type Default Description
supercell_size Sequence[Int] [2, 2, 2] Supercell dimensions for the simulation.

LAMMPS-specific calculation settings in cal_setting:

Key Type Default Description
temperature Sequence[Float] Required Target temperatures (K) for elastic calculation, e.g., [300].
strain Float Required Small strain magnitude for fluctuation analysis.
strain_components Sequence[String] Required Strain components to compute: "xx", "yy", "zz", "yz", "xz", "xy".
equi_step Integer 16000 Number of equilibration steps before measurement.
response_step Integer 16000 Number of steps for collecting stress-strain data.
stress_output_every Integer 100 Stress output frequency (steps).
timestep Float 0.001 MD timestep (ps).
tdamp Float 0.1 Thermostat damping parameter.
pdamp Float 1.0 Barostat damping parameter.
seed Integer Required Random seed for reproducibility.
n_blocks Integer 10 Number of blocks for statistical analysis.
method String "paired_langevin" Thermostat method (now only support "paired_langevin").

Example:

{
  "type": "finite_t_elastic",
  "supercell_size": [2, 2, 2],
  "cal_setting": {
    "temperature": [300],
    "strain": 0.001,
    "strain_components": ["xx", "yy", "zz", "yz", "xz", "xy"],
    "equi_step": 16000,
    "response_step": 16000,
    "stress_output_every": 100,
    "timestep": 0.001,
    "tdamp": 0.1,
    "pdamp": 1.0,
    "seed": 12345,
    "n_blocks": 10,
    "method": "paired_langevin"
  }
}

4.15 Annealing

APEX supports annealing simulations using molecular dynamics in LAMMPS. This workflow equilibrates the structure at a starting temperature, ramps to a target temperature, cools to an ending temperature, and performs final equilibration. Post-processing extracts radial distribution functions (RDF), mean squared displacement (MSD), and volume-temperature data from the heating and cooling stages for report visualization.

Key Type Default Description
supercell_size Sequence[Int] [2, 2, 2] Supercell dimensions for the simulation.
supercell_length Float None Optional target supercell length. When provided, APEX derives a near-cubic replication from the relaxed structure.

LAMMPS-specific calculation settings in cal_setting:

Key Type Default Description
start_temp Float 4 Starting temperature (K).
target_temp Float or Sequence[Float] 300 Peak annealing temperature (K). A sequence creates one annealing task per target temperature.
end_temp Float 4 Final cooling temperature (K).
temp_ramp_rate Float 1000 Heating rate used to derive ramp_step when explicit step counts are not provided. Alias: ramp_rate.
cool_rate Float temp_ramp_rate Cooling rate used to derive cool_step when explicit step counts are not provided.
equi_step Integer 20000 Initial equilibration steps at start_temp.
ramp_step Integer rate-derived Heating steps from start_temp to target_temp. Alias: temp_ramp_step.
hold_step Integer 20000 Final equilibration steps.
cool_step Integer rate-derived Cooling steps from target_temp to end_temp. Alias: temp_decline_step.
thermostat String "nose_hoover" Thermostat method: "nose_hoover" or "langevin".
ensemble String "npt" Ensemble. For Nose-Hoover use "npt" or "nvt"; for Langevin use "nph" or "nve".
timestep Float 0.001 MD timestep (ps).
tdamp Float None Thermostat damping parameter. If omitted, derived from tdamp_factor * timestep.
pdamp Float None Barostat damping parameter. If omitted, derived from pdamp_factor * timestep.
tdamp_factor Float 100 Factor used to derive tdamp when tdamp is omitted.
pdamp_factor Float 1000 Factor used to derive pdamp when pdamp is omitted.
velocity_seed Integer 123457 Random seed for initial velocities. Alias: init_v_seed.
dump_step Integer 2000 Atom dump output interval. Alias: dump_interval.
thermo_interval Integer 2000 Interval for heating/cooling thermo averages used in volume-temperature extraction.
restart_interval Integer 20000 Restart output interval.
req_compute_rdf Bool true Enable RDF calculation and extraction.
rdf_bins Integer 100 Number of RDF bins.
rdf_cutoff Float 6.0 RDF cutoff distance (Å).
rdf_interval Integer 200 RDF output interval. Also used as fallback for rdf_nevery and rdf_nfreq.
req_compute_msd Bool true Enable MSD calculation and extraction.
msd_nevery Integer 100 MSD sampling interval for fix ave/time.
msd_nrepeat Integer 1 Number of MSD samples per average.
msd_nfreq Integer 200 MSD output frequency.

Example:

{
  "type": "annealing",
  "supercell_size": [4, 4, 4],
  "cal_setting": {
    "start_temp": 300,
    "target_temp": 1500,
    "end_temp": 300,
    "equi_step": 10000,
    "ramp_step": 20000,
    "hold_step": 10000,
    "cool_step": 20000,
    "thermostat": "nose_hoover",
    "ensemble": "npt",
    "tdamp": 0.1,
    "pdamp": 1.0,
    "velocity_seed": 12345,
    "dump_step": 1000,
    "thermo_interval": 1000,
    "timestep": 0.002,
    "rdf_bins": 200,
    "rdf_cutoff": 5.0,
    "rdf_interval": 100,
    "msd_nevery": 100,
    "msd_nrepeat": 1,
    "msd_nfreq": 200
  }
}

After post_props and archive, annealing results are written to result.json and all_result.json. The report page displays RDF, MSD, and volume per atom as a function of temperature for the available annealing stages.

More Resources

  • APEX Bohrium App – Launch workflows from your browser with minimal configuration (Bohrium account required).

  • Documentation & tutorials – Explore docs/Hands_on_auto-test.pdf, docs/scripts/, and the dflow tutorials for environment setup.

  • Hands-on Bohrium notebook – Interactive tutorial covering Bohrium submissions.

  • How to cite APEX –

    Li, Z., Wen, T., Zhang, Y. et al. APEX: an automated cloud-native material property explorer. npj Comput Mater 11, 88 (2025). https://doi.org/10.1038/s41524-025-01580-y

About

APEX: Alloy Properties EXplorer using simulations

Resources

Readme

License

LGPL-3.0 license
Activity
Custom properties

Stars

45 stars

Watchers

6 watching

Forks

36 forks
Report repository

Releases 5

v1.3.0 Latest
Jun 6, 2026
+ 4 releases

Packages

 
 
 

Contributors

Languages