chipsff 2024.11.30

CHIPSFF: A force field analysis toolkit

CHIPS-FF

Overview

The chipsff repository provides a comprehensive framework for performing materials simulations with machine learning force fields (MLFFs). Simulations include structural relaxation, vacancy and surface energy calculations, interface analysis, elastic properties, phonons and thermal properties. The code supports multiple universal MLFFs and integrates with the JARVIS database and the Atomic Simulation Environment (ASE) to facilitate various materials simulations and workflows.

Features

• Structural Relaxation: Optimize atomic structures using various MLFF calculators and optimization algorithms.
• Energy-Volume (E-V) Curve: Fit the E-V curve using an equation of state (EOS) to obtain bulk modulus and equilibrium energy and volume.
• Elastic Properties: Calculate elastic tensors.
• Vacancy and Surface Energy Calculations: Compute vacancy formation energies and surface energies for different types of vacancies and surface terminations.
• Phonon Analysis: Generate phonon band structures, density of states (DOS), and thermal properties using Phonopy.
• Thermal Conductivity: Calculate thermal conductivity using third order force constants from Phono3py.
• Thermal Expansion: Perform thermal expansion calculations using the Quasi-Harmonic Approximation (QHA).
• Molecular Dynamics (MD) Simulations: Conduct MD simulations to melt and quench structures, and calculate Radial Distribution Functions (RDFs).
• Support for Multiple Calculators: Seamlessly switch between different MLFF calculators such as alignn_ff, chgnet, sevenn, mace, matgl, custom, etc.
• Automatic Error Calculation: Direct comparison to density functional theory (DFT) calculations from JARVIS-DFT.

Installation

Clone the repository:

git clone https://github.com/usnistgov/chipsff

Set up a conda environment:

conda env create -f environment.yml -n chipsff
conda activate chipsff

Install the CHIPS-FF package:

cd chipsff
pip install -e .

Examples

Notebooks	Google Colab	Descriptions
Structure optimization		Examples for comparing errors in lattice parameter predictions, bulk modulus, elastic constants, etc.
Scaling/timing comparison		Examples of analyzing scaling and timing comparisons.

Requirements

The following libraries and tools are required:

• python >= 3.9
• numpy
• matplotlib
• pandas
• scikit-learn
• ase
• phonopy
• phono3py
• jarvis-tools
• intermat
• h5py
• plotly
• ruamel

Universal MLFFs Implemented

• alignn_ff
• chgnet
• sevenn
• mace
• matgl
• orb
• fairchem

Note: Some calculators may have additional dependencies or require specific versions of libraries. Please refer to their respective documentation for setup instructions. To install the intermat package, see here.

Input File Parameters

The input configuration file is a JSON file that specifies all required settings for performing materials simulations. Below is a detailed explanation of each parameter and its expected values.

Primary Parameters

• jid (string): The JARVIS ID of the material to analyze (e.g., "JVASP-1002"). This identifier is used to fetch structural data from the JARVIS database.

• jid_list (list of strings): A list of multiple JARVIS IDs for batch analysis (e.g., ["JVASP-1002", "JVASP-816", "JVASP-867"]). Only used if analyzing multiple materials.

• film_id and substrate_id (list of strings): Lists of JARVIS IDs for film and substrate materials, respectively, in an interface analysis (e.g., ["JVASP-1002"] and ["JVASP-816"]).

• calculator_type (string): Specifies the MLFF calculator to use for analysis. Each calculator corresponds to a different machine learning force field or calculation model.

• calculator_types (list of strings): A list of calculators to use for batch processing (e.g., ["alignn_ff", "chgnet"]). Only required if analyzing multiple calculators for batch processing.

• chemical_potentials_file (string): Path to the JSON file containing chemical potentials for elements (e.g., "chemical_potentials.json"). Required for formation energy and defect calculations. If an entry is missing for a particular element or MLFF calculator, it will be automatically calculated and stored in the chemical_potentials.json file.

Structural and Interface Settings

• film_index and substrate_index (string): Miller indices for the film and substrate in interface analysis, respectively. Example: "1_1_0" for both film and substrate.

• use_conventional_cell (boolean): Determines whether to use a conventional cell for the simulation. Set to true to use the conventional cell structure, or false for the primitive cell.

Properties to Calculate

• properties_to_calculate (list of strings): Specifies which properties to calculate during the workflow. Each string represents a calculation or analysis task. Options include:
  • "relax_structure": Perform initial structural relaxation.
  • "calculate_formation_energy": Calculate formation energy per atom.
  • "calculate_ev_curve": Fit the energy-volume (E-V) curve.
  • "calculate_elastic_tensor": Compute the elastic tensor.
  • "run_phonon_analysis": Run phonon band structure and thermal property calculations.
  • "analyze_defects": Calculate vacancy formation energies.
  • "analyze_surfaces": Calculate surface energies.
  • "analyze_interfaces": Perform interface analysis.
  • "run_phonon3_analysis": Run calculations for thermal conductivity.
  • "calculate_thermal_expansion": Calculate the thermal expansion coefficient.
  • "general_melter": Perform MD melting and quenching simulations.
  • "calculate_rdf": Calculate the Radial Distribution Function (RDF) for a quenched structure.

Relaxation and Analysis Settings

Bulk Relaxation Settings

• bulk_relaxation_settings (dictionary): Configures the relaxation process for bulk structures. Contains:
  • filter_type (string): Specifies the filter type in ASE. Options include "ExpCellFilter" (exponential cell filter) and other filters.
  • relaxation_settings (dictionary): Contains relaxation parameters:
    • constant_volume (boolean): If true, keeps the volume constant during relaxation.
    • fmax (float): Convergence criterion for force (e.g., 0.05).
    • steps (int): Maximum number of optimization steps (e.g., 200).

Phonon Settings

• phonon_settings (dictionary): Configures phonon calculation parameters. Contains:
  • dim (list of integers): Specifies the supercell dimensions for phonon calculations (e.g., [2, 2, 2]).
  • distance (float): Specifies the displacement distance for finite-displacement phonon calculations (e.g., 0.2).

Defect Settings

• defect_settings (dictionary): Configures defect analysis, including vacancy formation energy calculations. Contains:
  • generate_settings (dictionary): Contains parameters for defect generation:
    • on_conventional_cell (boolean): If true, generates defects on a conventional cell.
    • enforce_c_size (int): Minimum size constraint for the c-axis (e.g., 8).
    • extend (int): Extends the unit cell to create a supercell (e.g., 1).
  • filter_type (string): Specifies the filter type used during relaxation.
  • relaxation_settings (dictionary): Contains settings similar to bulk_relaxation_settings (e.g., constant_volume, fmax, steps).

Surface Settings

• surface_settings (dictionary): Configures surface energy calculations. Contains:
  • indices_list (list of lists of integers): Specifies Miller indices for surface orientations (e.g., [[1, 0, 0], [1, 1, 1]]).
  • layers (int): Number of atomic layers in the surface (e.g., 4).
  • vacuum (float): Vacuum thickness in Ångströms (e.g., 18).
  • filter_type (string): Specifies the filter type used during relaxation.
  • relaxation_settings (dictionary): Similar to bulk_relaxation_settings.

Phonon3 Settings

• phonon3_settings (dictionary): Configures third order force constant calculations for thermal conductivity. Contains:
  • dim (list of integers): Supercell dimensions (e.g., [2, 2, 2]).
  • distance (float): Displacement distance (e.g., 0.2).

MD Settings

• md_settings (dictionary): Configures parameters for MD simulations, specifically for melting and quenching. Contains:
  • dt (float): Time step in femtoseconds (e.g., 1).
  • temp0 (float): Initial temperature for melting (e.g., 3500 K).
  • nsteps0 (int): Number of steps for melting phase (e.g., 1000).
  • temp1 (float): Final temperature for quenching (e.g., 300 K).
  • nsteps1 (int): Number of steps for quenching phase (e.g., 2000).
  • taut (float): Temperature coupling parameter (e.g., 20).
  • min_size (float): Minimum cell size in Ångströms (e.g., 10.0).

Usage

The main script run_chipsff.py provides a command-line interface to perform various materials analyses.

1. Single Material Analysis To run an analysis on a single material by providing an input.json file:

python run_chipsff.py --input_file input.json

An example input.json file:

{
  "jid": "JVASP-1002",
  "calculator_type": "chgnet",
  "chemical_potentials_file": "chemical_potentials.json",
  "properties_to_calculate": [
    "relax_structure",
    "calculate_ev_curve",
    "calculate_formation_energy",
    "calculate_elastic_tensor",
    "run_phonon_analysis",
    "analyze_surfaces",
    "analyze_defects",
    "run_phonon3_analysis",
    "general_melter",
    "calculate_rdf"
  ],
"bulk_relaxation_settings": {
  "filter_type": "ExpCellFilter",
  "relaxation_settings": {
    "fmax": 0.05,
    "steps": 200,
    "constant_volume": false
  }
},
  "phonon_settings": {
    "dim": [2, 2, 2],
    "distance": 0.2
  },
  "use_conventional_cell": true,
  "surface_settings": {
    "indices_list": [
      [0, 1, 0],
      [0,0,1]
    ],
    "layers": 4,
    "vacuum": 18,
    "relaxation_settings": {
      "fmax": 0.05,
      "steps": 200,
      "constant_volume": true
    },
    "filter_type": "ExpCellFilter"
  },
  "defect_settings": {
    "generate_settings": {
      "on_conventional_cell": true,
      "enforce_c_size": 8,
      "extend": 1
    },
    "relaxation_settings": {
      "fmax": 0.05,
      "steps": 200,
      "constant_volume": true
    },
    "filter_type": "ExpCellFilter"
  },
  "phonon3_settings": {
    "dim": [2, 2, 2],
    "distance": 0.2
  },
  "md_settings": {
    "dt": 1,
    "temp0": 35,
    "nsteps0": 10,
    "temp1": 200,
    "nsteps1": 20,
    "taut": 20,
    "min_size": 10.0
  }
}

2. Interface Analysis To perform an interface analysis between a film and substrate:

python run_chipsff.py --input_file interface_input.json

An example interface_input.json file:

{
  "film_id": ["JVASP-1002"],
  "substrate_id": ["JVASP-816"],
  "calculator_type": "alignn_ff",
  "chemical_potentials_file": "chemical_potentials.json",
  "film_index": "1_1_0",
  "substrate_index": "1_1_0",
  "properties_to_calculate": [
    "analyze_interfaces"
  ]
}

Key Methods

• relax_structure(): Optimizes the atomic structure using the specified calculator and relaxation settings.
• calculate_formation_energy(relaxed_atoms): Computes the formation energy per atom based on the relaxed structure and chemical potentials.
• calculate_elastic_tensor(relaxed_atoms): Calculates the elastic tensor for the relaxed structure.
• calculate_ev_curve(relaxed_atoms): Fits the energy-volume curve using an equation of state to obtain bulk modulus, minimum energy and equilibrium volume.
• run_phonon_analysis(relaxed_atoms): Performs phonon band structure calculations, density of states, and thermal properties using Phonopy.
• analyze_defects(): Analyzes vacancy formation energies by generating defects, relaxing them, and calculating formation energies.
• analyze_surfaces(): Analyzes surface energies by generating surface structures, relaxing them, and calculating surface energies.
• run_phonon3_analysis(relaxed_atoms): Runs third order force constant calculations for thermal conductivity using Phono3py.
• calculate_thermal_expansion(relaxed_atoms): Calculates the thermal expansion coefficient using the Quasi-Harmonic Approximation.
• general_melter(relaxed_atoms): Performs MD simulations to melt and quench the structure, then calculates the Radial Distribution Function (RDF). Can be used to generate amorphous structures.
• analyze_interfaces(): Performs interface analysis between film and substrate materials using the intermat package.

How to contribute

For detailed instructions, please see Contribution instructions

Correspondence

Please report bugs as Github issues (https://github.com/usnistgov/chipsff/issues) or email to [e-mail] or [e-mail].

Funding support

This work was performed with funding from the CHIPS Metrology Program, part of CHIPS for America, National Institute of Standards and Technology, U.S. Department of Commerce.

Code of conduct

Please see Code of conduct