CascadesDB metadata

Each archive of simualtions comes with one metadata file describing it. An archive holds a set of simulations that share the same material, PKA (atomic number and energy), interatomic potential, simulation time and set-up; they differ only in PKA direction (or initial thermalisation). If any of those differ, separate archives will need to be submitted.

The metadata can be written in JSON or as plain text; the two carry exactly the same information and either can be converted to the other. CascadesDB stores the JSON.

• A blank text template to fill in: metadata.txt
• Complete examples: R005 as text and JSON, and R0d8 (extra XYZ columns, an initial defect) as text and JSON
• The JSON Schema, for checking JSON files with your own tools

Metadata is checked when it is uploaded, and any problems are reported (with line numbers, for the text form).

The text form

Contributor: Andrea Sand
PKA energy (keV): 10
Acknowledgements:
  This work was supported by ...

  A second paragraph.
Column: x | Å

• One field per line, Label: value. Labels are not case-sensitive, and A may be written for Å.
• A value can run over several lines: indent the following lines by two spaces. Blank lines between indented lines are kept and separate paragraphs.
• Lines starting with # are ignored. Fields left blank are ignored, so you can fill in the template and comment out what does not apply.
• Yes/no fields take yes or no. Three numbers (box lengths, lattice lengths) are separated by spaces or commas.
• Column and Simulation are given once per column or simulation, with their parts separated by |. Leave a part empty to skip it: Column: atom index | | Atom index.

Fields

Units are fixed; in the JSON they are part of the key name (e.g. the simulation time, simulation_time_ps is in picoseconds).

Text label	JSON key	Required	Meaning
Format	format	yes	Always cascadesdb-metadata/2.
Contributor	contributor.name	yes	The person to contact about the data.
Affiliation	contributor.affiliation
Country	contributor.country
Email	contributor.email		Shown publicly, as a contact address.
ORCID	contributor.orcid		e.g. 0000-0002-1825-0097
Publication DOI	publication_doi		The DOI only (10.1038/…), not a URL.
Acknowledgements	acknowledgements
Formula	material.formula	yes	e.g. W, Fe, Fe0.9Cr0.1
Structure	material.structure	yes	fcc, bcc, hcp, diamond, amorphous or other
Lattice lengths a, b, c (Å)	material.lattice.a_angstrom …		Three numbers. If given, the angles must be given too.
Lattice angles alpha, beta, gamma (deg)	material.lattice.alpha_deg …		Three numbers.
Surface	has_surface	yes	Does the simulation include a surface?
Initially perfect	initially_perfect	yes	Is the crystal free of defects at the start?
PKA atomic number	pka.atomic_number	yes	e.g. 74 for a tungsten PKA.
PKA energy (keV)	pka.energy_keV	yes
PKA by recoil	pka.recoil	yes	yes for a recoiling atom of the material, no for a projectile.
Number of simulations	number_of_simulations	yes	How many simulations the archive holds.
Simulation time (ps)	simulation_time_ps	yes	Note: picoseconds, not femtoseconds.
Initial temperature (K)	initial_temperature_K	yes
Box lengths (Å)	box.lengths_angstrom	yes	Three numbers: x, y, z.
Box orientation	box.orientation		Three Miller indices for x, y, z: 100 010 001 or [1 -1 0] [1 1 0] [0 0 1].
Electronic stopping	electronic_stopping.included	yes
Electronic stopping comment	electronic_stopping.comment		e.g. the threshold used.
Thermostat	thermostat.included	yes
Thermostat comment	thermostat.comment
Potential	potential	yes, or the next three	The identifier of a potential already in CascadesDB, e.g. P2.
Potential file / Potential DOI / Potential comment	potential.file, .doi, .comment		For a new potential: describe it here and send its file with the submission.
Code / Code version	code.name, code.version	name	e.g. LAMMPS, 22 Aug 2018.
Input files	input_files		Names or patterns of input files in the archive, e.g. md.in-*.
Initial configuration file / comments	initial_configuration.file, .comments		If the starting configuration is in the archive.
Column	xyz_columns	yes	Every column of an atom line in the XYZ files, in order: name \| units \| description. At least element, x, y, z.
Simulation	simulations		Optional, one per simulation: file \| PKA direction (3 numbers) \| comment.
Comments	comments		Anything else about the data set.

Set by CascadesDB

These are added when an archive is accepted; leave them out of what you upload.

Text label	JSON key	Meaning
Record	id	The record identifier, e.g. R141.
Archive	archive.name	The stored archive name: the identifier's number followed by your file name, e.g. 141-W-10keV.tar.bz2.
Archive size (bytes)	archive.size_bytes
Archive SHA-256	archive.sha256	Checksum of the archive, to check a download.

Changes from the previous format

For users with metadata files from the old site:

• Key names are all lower case with underscores (archive-name, PKA-energy, source_doi and so on are gone), and carry their units (energy_keV, simulation_time_ps).
• The JSON no longer repeats details of the person, institution and potential; the potential is referred to by its identifier.
• All XYZ columns are listed, not just the ones after x, y, z.
• XML (CDBML) is not produced for now; it may come back as a download converted from the JSON.
• 69 records are numbered differently: every record is now numbered after its archive (0d8-….tar.bz2 is R0d8), which was not always the case before.