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 atitlein theprim.jsonfile used to initialize it<dof_key>: a name of degrees of freedom (DoF) listed inprim.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 |