Project directory structure

Description

The CASM project directory structure standardizes the location of various files used by multiple CASM methods.

Path variable convention

In the descriptions that follow, some paths include codes of the form <variable> to indicate that there are multiple files or directory paths with varying names but following the same pattern.

This is used to (i) store data by supercell name (<supercellname>) or configuration name (<configname>) or (ii) organize data in parallel directories so users can work on multiple tasks in the same project or compare the results of using different parameters.

In particular, a CASM project allows storing multiple choices of:

  • <property>: the property being expanded
  • <bset>: the choice of basis set
  • <calctype>: the choice of property calculation method and parameters
  • <ref>: the choice of reference states (for formation energy calculations)
  • <eci>: the choice of fitting coefficients (effective cluster interactions)

Additional <variable> descriptions include:

  • <root>: indicates the CASM project root directory
  • <title>: a CASM project is given a title in the prim.json file used to initialize it
  • <dof_key>: a name of degrees of freedom (DoF) listed in prim.json

Controlling what data is used by default

When a CASM project is initialized with casm init, default directories are created with names such as bset.default, calctype.default, etc.

Either manually or by using casm settings, the user may create new directories with custom names such as bset.occupation, bset.chebychev, calctype.gga, calctype.lda, etc. to store different choices of basis set, calculation type, etc.

These directory names must be given the appropriate prefix (i.e. "bset.", "calctype.", etc.) for CASM to recognize them. This is taken care of when they are created using the casm settings command. The expected prefixes and default values for new CASM projects are:

Variable Prefix Default
<property> clex. clex.formation_energy
<bset> bset. bset.default
<calctype> calctype. calctype.default
<ref> ref. ref.default
<eci> eci. eci.default

The CASM project settings (which can be inspected and modified by casm settings) store a list of named cluster expansions specifying which choice of <property>, <bset>, <calctype>, <ref>, and <eci> are used.

A default cluster expansion can be configured which indicates which data from which directories to query by default.


CASM project directories

CASM project root directory

Location: <root>/

Contents:

Name Description Format
.casm/ Stores CASM project settings and data goto
basis_sets/ Stores basis set input, results, and generated code goto
cluster_expansions/ Stores cluster expansion fitting coefficients goto
reports/ Stores reports generated by casm import and casm update  
symmetry/ Stores symmetry analysis results goto
training_data/ Stores calculation settings and results goto
LOG Logs all casm API commands run for the project  

Project settings and data directory

Location: <root>/.casm/

Contents:

Name Description Format
jsonDB/ Directory containing enumerated supercells and configurations goto
query/ Directory containing query plugins code goto
prim.json Primitive crystal structure and allowed degrees of freedom (DoF) Prim
composition_axes.json Stores the selected and possible composition axes Composition Axes
project_settings.json Stores CASM project settings Project Settings

JSON database directory

Location: <root>/.casm/jsonDB

Contents:

Name Description Format
config_list.json File containing enumerated configurations  
scel_list.json File containing enumerated supercells  
<calctype>/config_props.json File containing calculated properties for a particular calculation type  

Query plugins directory

Location: <root>/.casm/query

Contents:

Name Description Format
Configuration/ Directory for placing configuration query plugin source code  
Supercell/ Directory for placing supercell query plugin source code  

Basis sets directory

Location: <root>/basis_sets/<bset>

Contents:

Name Description Format
basis.json Basis function orbit information Basis Set
bspecs.json Basis set specifications (input file) Basis Set Specs
clust.json Cluster orbit information Cluster Orbits
<title>_Clexulator.cc Generated source code for evaluating basis functions  
<title>_Clexulator.o Compiled object file for evaluating basis functions  
<title>_Clexulator.so Compiled shared object file for evaluating basis functions  

Cluster expansion ECI directories

Location: <root>/cluster_expansions/<property>/<bset>/<calctype>/<ref>/<eci>/

Contents:

Name Description Format
eci.json Basis function orbit information, with effective cluster interaction (ECI) values included Basis Set

Symmetry analysis directory

Location: <root>/symmetry/

Contents:

Name Description Format
analysis/<configname>/ Stores DoFSpace analysis results for enumerated configurations goto
lattice_point_group.json The point group of the prim lattice Symmetry Group
factor_group.json The prim factor group (a finite description of the crystal space group) Symmetry Group
crystal_point_group.json The group formed by excluding translations from the prim factor group operations Symmetry Group

DoFSpace analysis directories

Location: <root>/symmetry/analysis/<configname>/

Contents:

Name Description Format
lattice_point_group.json The point group of the configuration’s superlattice Symmetry Group
factor_group.json The configuration’s factor group (a finite description of the crystal space group) Symmetry Group
crystal_point_group.json The group formed by excluding translations from the configuration’s factor group operations Symmetry Group
dof_space_<dof_key>.json A description of the DoF vector space, by specified DoF type DoF Space

Configuration directories

Location: <root>/training_data/<configname>/

Description:

The configuration directories are used to store data associated with a particular configuration including its definition and calculated properties.

Contents:

Name Description Format
Calculation results directories goto
settings/ Configuration specific calculation settings goto
POS VASP POSCAR file corresponding to the configuration POSCAR
config.json JSON file containing the values degrees of freedom (DoF) defining the configuration Configuration
structure.json The crystal structure corresponding the configuration Structure

Calculation settings directories

Location:

One of:

  • For configuration specific settings: <root>/training_data/<configname>/settings/<calctype>/
  • For supercell specific settings: <root>/training_data/<supercellname>/settings/<calctype>/
  • For default settings: <root>/training_data/settings/<calctype>/

Description:

Calculation wrappers for CASM (ex. casm.vaspwrapper for running VASP calculations, casm.qewrapper for running Quantum Espresso calculations) check for input settings files in the calculation settings directories, using the most local settings for a particular configuration. In most cases, the default settings files are stored in <root>/training_data/settings/<calctype>/ and used for all configurations. Sometimes it is necessary to provide configuration specific settings to overcome an issue that arises when calculating properties. Rarely, the superell specific settings may be used to set default settings for all configurations in a particular supercell. The implementation is controlled by the wrapper code, but by convention, settings files should be searched on a file-by-file basis, so to set supercell or configuration specific settings it is sufficient to only include the particular files necessary in the supercell or configuration level settings folder.

Contents:

Name Description Format
calc.json JSON file containing calculation settings and parameters used to control job submission management software  
… others … Calculation type dependent files necessary for input file setup and job execution. See casm.wrapper documentation.  

Calculation results directories

Location: <root>/training_data/<configname>/<calctype>/

Contents:

Name Description Format
properties.calc.json CASM structure JSON file containing the calculated lattice, coordinates, and any properties for configuration <configname>. This file is read by casm update to update the calculated properties Structure
… others … Calculation type dependent input and output files. See casm.wrapper documentation.  

Chemical reference directories

Location: <root>/training_data/<configname>/<calctype>/<ref>/

Contents:

Name Description Format
chemical_reference.json Chemical reference states Chemical Reference