A Python dictionary template for storing serializable computational-materials-science
metadata. The schema and controlled vocabularies are kept in lock-step with
atomRDF, so YAML/JSON files produced with
conceptual_dictionary can be parsed directly by atomRDF's WorkflowParser.
- Strongly-typed templates for samples, workflows, properties, operations, defects, datasets and math operations.
- Controlled vocabularies mirrored from atomRDF (methods, ensembles, potentials, XC functionals, …) with optional runtime validation.
- A
dictsubclass (ConceptualDict) with YAML/JSON I/O that automatically cleans numpy types and is round-trip safe.
pip install conceptual-dictionaryFrom source:
pip install -e .importcopyfromconceptual_dictionaryimport (
ConceptualDict, sample_template, workflow_template,
property_template, dataset_template,
)
cd=ConceptualDict()
# Samplesample=copy.deepcopy(sample_template)
sample["id"] ="Al_fcc"sample["material"]["element_ratio"] = {"Al": 1.0}
sample["material"]["crystal_structure"]["spacegroup_symbol"] ="Fm-3m"sample["material"]["crystal_structure"]["spacegroup_number"] =225sample["material"]["crystal_structure"]["unit_cell"]["lattice_parameter"] = [4.05, 4.05, 4.05]
sample["material"]["crystal_structure"]["unit_cell"]["angle"] = [90.0, 90.0, 90.0]
cd["computational_sample"].append(sample)
# Workflowwf=copy.deepcopy(workflow_template)
wf["method"] ="MolecularStatics"wf["interatomic_potential"] = {"potential_type": "eam/alloy",
"uri": "https://doi.org/10.1103/physrevb.59.3393"}
wf["input_sample"] = ["Al_fcc"]
wf["output_sample"] = ["Al_fcc"]
energy=copy.deepcopy(property_template)
energy.update({"label": "EquilibriumEnergy", "value": -3.36, "unit": "EV",
"associate_to_sample": ["Al_fcc"]})
wf["calculated_property"] = [energy]
cd["workflow"].append(wf)
# Optional dataset provenanceds=copy.deepcopy(dataset_template)
ds["title"] ="Al FCC reference"ds["samples"] = ["Al_fcc"]
cd["dataset"] =dscd.validate(strict=True) # raises on first vocab violationcd.to_yaml("metadata.yaml")
cd.to_json("metadata.json", indent=2)Every template is a plain dict. Use copy.deepcopy before mutating, then
populate only the fields that apply (everything is optional unless marked
Required).
| Import | Purpose |
|---|---|
sample_template | A computational sample (material + simulation cell + atoms) |
property_template | A single calculated/input/output property |
workflow_template | A simulation/calculation step |
dataset_template | DCAT dataset provenance (creators, publication, sample IDs) |
operation_template | Atomic-scale transform (DeleteAtom, Rotate, Translate, Shear, …) |
math_operation_template | Arithmetic activity (Subtraction, Addition, Multiplication, Division, Exponentiation) |
vacancy_template, substitutional_template, interstitial_template | Point defects |
stacking_fault_template | Stacking fault |
grain_boundary_template | Grain boundary (5 YAML key variants) |
dislocation_template | Dislocation (4 YAML key variants) |
defect_complex_template | Multi-defect complex |
full_sample_template, full_yaml_template | Reference templates with every supported field |
A dict subclass pre-populated with the four top-level sections atomRDF reads:
ConceptualDict() == {
"computational_sample": [],
"workflow": [],
"operation": [],
"math_operation": [],
}Add an optional "dataset" key (or anything else) at any time.
| Method | Notes |
|---|---|
to_yaml(filepath, sort_keys=False) | numpy → native conversion, preserves insertion order by default |
from_yaml(filepath)(classmethod) | Loads any partial YAML (missing top-level keys keep their default empty lists) |
to_json(filepath, sort_keys=False, indent=2) | Same numpy cleanup as YAML |
from_json(filepath)(classmethod) | Symmetric counterpart |
validate(strict=False) | Returns a list of violation dicts {section, index, field, value, allowed}. With strict=True raises ValueError on the first violation |
generate_id(length=7) | Collision-resistant random ID using os.urandom (safe against third-party random.seed()) |
Both to_yaml and to_json recursively convert np.ndarray, np.floating,
np.integer, np.bool_ and any unknown object (via str(obj)) to JSON/YAML
native types — so values coming from ASE / pyiron / LAMMPS need no
pre-processing.
The full top-level YAML/JSON shape consumed by atomRDF:
dataset: # optional, dcat:Dataset provenanceidentifier: ...title: ...creators: [{id, name}, ...]publication: {id, identifier, title}samples: [<sample id>, ...]computational_sample: # list of sample dicts
- id: ...material: {...}simulation_cell: {...}atom_attribute: {...}calculated_property: [...]# optional defect blocks (see Defects below)workflow: # list of workflow steps
- method: ...algorithm: ......operation: # list of atomic-scale transforms (legacy alias: 'activity')
- method: ...input_sample: ...output_sample: ...math_operation: # list of arithmetic activities
- type: ...result: {...}The following sections enumerate every string atomRDF accepts for each
field. Aliases are marked → canonical. Anything outside these sets is rejected
by ConceptualDict.validate() (and silently ignored or errored by atomRDF
depending on the field).
The frozen sets are also importable and useful for building UIs:
fromconceptual_dictionaryimport (
METHOD, ALGORITHM, DEGREES_OF_FREEDOM, THERMODYNAMIC_ENSEMBLE,
POTENTIAL_TYPE, XC_FUNCTIONAL, OPERATION_METHOD,
MATH_OPERATION_TYPE, GRAIN_BOUNDARY_TYPE, YAML_TOP_LEVEL_KEYS,
CONTROLLED_VALUES,
)| Field | Accepted values | atomRDF source |
|---|---|---|
workflow.method | MolecularDynamics, MolecularStatics, DensityFunctionalTheory | atomrdf/datamodels/workflow/method.py (method_map) |
workflow.algorithm | EquationOfStateFit, QuasiHarmonicApproximation, ThermodynamicIntegration, ANNNIModel, TensileTest, CompressionTest; alias UniaxialTension → TensileTest | atomrdf/datamodels/workflow/algorithm.py (algorithm_map) |
workflow.degrees_of_freedom(list) | AtomicPositionRelaxation, CellVolumeRelaxation, CellShapeRelaxation | atomrdf/datamodels/workflow/dof.py (dof_map) |
workflow.thermodynamic_ensemble | CanonicalEnsemble (NVT), MicrocanonicalEnsemble (NVE), IsothermalIsobaricEnsemble (NPT), IsoenthalpicIsobaricEnsemble (NPH), GrandCanonicalEnsemble (μVT) | atomrdf/datamodels/workflow/ensemble.py (ensemble_map) |
workflow.xc_functional | LDA, GGA, PBE (→ GGA), LocalDensityApproximation, GeneralizedGradientApproximation, PerdewBurkeErnzerhof (→ GGA), HybridFunctional, HybridGeneralizedGradientApproximation, HybridMetaGeneralizedGradientApproximation, MetaGeneralizedGradientApproximation | atomrdf/datamodels/workflow/xcfunctional.py (xc_map) |
workflow.interatomic_potential.potential_type accepts the canonical class
name or any short alias atomRDF understands:
| Family | Canonical | Aliases |
|---|---|---|
| Generic | InteratomicPotential | — |
| EAM | EmbeddedAtomModel | EAM, eam, eam/alloy, eam/fs |
| MEAM | ModifiedEmbeddedAtomModel | MEAM, meam |
| Lennard–Jones | LennardJonesPotential | LJ, lj |
| Machine learning | MachineLearningPotential | ACE, pace, HDNNP, hdnnp, GRACE, grace |
Source: atomrdf/datamodels/workflow/potential.py (potential_map).
operation.method (legacy top-level key activity is also accepted):
DeleteAtom, SubstituteAtom, AddAtom, Rotate (alias Rotation),
Translate (alias Translation), Shear.
Source: atomrdf/io/workflow_parser.py (OPERATION_MAP).
math_operation.type: Subtraction, Addition, Multiplication, Division,
Exponentiation. Operands are either a scalar or a property id string
referencing a previously declared calculated_property / input_parameter /
output_parameter:
type | Operand fields |
|---|---|
Subtraction | minuend, subtrahend |
Addition | addend(list) |
Multiplication | factor(list) |
Division | dividend, divisor |
Exponentiation | base, exponent |
Source: atomrdf/datamodels/workflow/math_operations.py.
label and basename on a property are not validated as a closed enum,
but at RDF generation time atomRDF resolves basename against the
ASMO
ontology via getattr(ASMO, basename), so the value should match an ASMO
class. The following terms appear in atomRDF's source / parsers / visualizer
and are known to round-trip correctly:
| Category | Recognised terms |
|---|---|
| Energies | TotalEnergy, Energy, EquilibriumEnergy, CohesiveEnergy, FormationEnergy, VacancyFormationEnergy, GrainBoundaryEnergy, SurfaceEnergy, StackingFaultEnergy, SegregationEnergy, WorkOfSeparation, MigrationEnergy |
| Mechanical | BulkModulus, ElasticConstant, C11, C12, C44, Stress, Pressure |
| Geometric | Volume, EquilibriumVolume, LatticeConstant |
| Thermo / state | Temperature |
| Generic wrappers | CalculatedProperty, Property, AtomAttribute |
Custom strings outside this list will still be written to the YAML/JSON
verbatim — they just won't resolve to a known ASMO class when loaded into an
RDF graph. Sources: atomrdf/datamodels/workflow/property.py,
atomrdf/visualize.py, atomrdf/io/reconstruct.py,
atomrdf/parsers/pyiron.py.
The unit string is suffixed onto http://qudt.org/vocab/unit/{unit} and
stored as a QUDT URI — there is no closed enum
in atomRDF, so any valid QUDT unit code is accepted. Examples that appear in
atomRDF or its examples:
| Quantity | Common QUDT codes |
|---|---|
| Energy | EV, J, KiloCAL |
| Length | ANGSTROM, M, NanoM |
| Volume | ANGSTROM3, M3 |
| Temperature | K, DEG_C |
| Pressure / stress | PA, GigaPA, BAR |
| Force | N, EV-PER-ANGSTROM |
| Angle | RAD, DEG |
Source: atomrdf/datamodels/workflow/property.py line 93.
Place at most one of these as a key inside a sample dict.
| Family | YAML keys | Template | Fields |
|---|---|---|---|
| Point defect | vacancy, substitutional, interstitial | vacancy_template, substitutional_template, interstitial_template | concentration (atomic fraction), number |
| Stacking fault | stacking_fault | stacking_fault_template | plane (Miller indices), displacement (3-vector) |
| Grain boundary | grain_boundary, tilt_grain_boundary, twist_grain_boundary, symmetric_tilt_grain_boundary, mixed_grain_boundary | grain_boundary_template | sigma, plane, misorientation_angle, rotation_axis |
| Dislocation | dislocation, edge_dislocation, screw_dislocation, mixed_dislocation | dislocation_template | line_direction, burgers_vector, slip_system.{slip_direction, slip_plane.normal}, plus character_angle for mixed_dislocation |
| Defect complex | defect_complex | defect_complex_template | ids (list of defect key names), relative_distance |
Source: atomrdf/datamodels/structure.py,
atomrdf/datamodels/defects/{pointdefects,grainboundary,dislocation,stackingfault,complex}.py.
The frozen set GRAIN_BOUNDARY_TYPE enumerates the five GB key variants.
| Field | Notes |
|---|---|
material.element_ratio | {symbol: fraction}, e.g. {"Fe": 0.8, "Cr": 0.2} |
material.crystal_structure.spacegroup_symbol | Hermann–Mauguin (e.g. "Fm-3m") — no validation |
material.crystal_structure.spacegroup_number | 1–230 — no validation |
material.crystal_structure.unit_cell.bravais_lattice | URI string. Common values used in atomRDF: https://www.wikidata.org/wiki/Q851536 (bcc), Q3006714 (fcc), Q663314 (hcp), Q2242450 (sc), Q503601 (tetragonal), Q648961 (orthorhombic), Q624543 (monoclinic), Q13362463 (rhombohedral) |
material.crystal_structure.unit_cell.lattice_parameter | [a, b, c] in Å |
material.crystal_structure.unit_cell.angle | [α, β, γ] in degrees |
| Field | Notes |
|---|---|
position | List of [x, y, z] (Å) — for inline small systems |
species | List of element symbols, parallel to position |
file_path | Path to a structure file (resolved relative to the YAML file). Preferred for large MD snapshots |
file_format | ASE format string (e.g. "lammps-data", "lammps-dump-text", "vasp", "aims"); auto-detected when None |
file_species | Species order for LAMMPS numeric atom types (e.g. ["Al"]) |
Source: atomrdf/io/workflow_parser.py_resolve_atom_attribute_from_file.
software:
- uri: https://doi.org/10.1016/j.cpc.2021.108171label: LAMMPSversion: "29Sep2021"workflow_manager:
uri: ...label: ...version: ...Source: atomrdf/datamodels/workflow/software.py.
YAML_TOP_LEVEL_KEYS = {computational_sample, workflow, operation, activity (legacy), math_operation}.
Plus dataset (DCAT provenance, parsed by atomRDF if present).
A property may carry an id; later math operations reference it by string:
e_def=copy.deepcopy(property_template)
e_def.update({"id": "E_def", "label": "TotalEnergy", "value": -3.20, "unit": "EV"})
e_perf=copy.deepcopy(property_template)
e_perf.update({"id": "E_perf", "label": "TotalEnergy", "value": -3.36, "unit": "EV"})
cd["workflow"][0]["calculated_property"] = [e_def, e_perf]
cd["math_operation"].append({
"type": "Subtraction",
"minuend": "E_def",
"subtrahend": "E_perf",
"result": {"id": "E_form", "label": "FormationEnergy", "unit": "EV",
"associate_to_sample": ["Al_fcc_with_vacancy"]},
})violations=cd.validate() # warns on each violation, returns the listcd.validate(strict=True) # raises ValueError on the first violationvalidate() currently checks workflow.method, workflow.algorithm,
workflow.degrees_of_freedom, workflow.thermodynamic_ensemble,
workflow.xc_functional, workflow.interatomic_potential.potential_type,
operation.method and math_operation.type. Each violation dict has keys
section, index, field, value, allowed.
Working YAML/JSON examples live in examples/:
single_structure_with_workflow.yaml/.jsongrain_boundary.yaml/.jsonexamples.ipynb— end-to-end notebook
If you use conceptual_dictionary in your research, please cite the
associated paper:
A. Azocar Guzman, S. Menon, T. Hickel, S. Sandfeld. Ontology-based knowledge graph infrastructure for interoperable atomistic simulation data. arXiv:2604.06230 (2026). https://arxiv.org/abs/2604.06230
BibTeX:
@misc{guzman2026ontologybasedknowledgegraphinfrastructure,
title={Ontology-based knowledge graph infrastructure for interoperable atomistic simulation data},
author={Abril Azocar Guzman and Sarath Menon and Tilmann Hickel and Stefan Sandfeld},
year={2026},
eprint={2604.06230},
archivePrefix={arXiv},
primaryClass={cs.DB},
url={https://arxiv.org/abs/2604.06230},
}MIT License — see LICENSE.