Attribute Templates and Bounds

An AttributeTemplate defines a domain concept by giving it a canonical name and bounds, which describes the values that are acceptable for an Attribute.

For example, an attribute template could define a real value bounded between -3 and +17, or it could define a Categorical with the following allowed categories: "salt", "not salt". The values of attributes with Attribute Templates must conform to the bounds specified by the templates. If the value is not compatible with the template (e.g., if the template specifies that the value must be in the range [0, 1] but the value is 2), then the data are invalid.

attribute templates Figure1: How Attribute Templates help relate Attributes between Specs and Runs, and provide Bounds for Values.

Each AttributeTemplate is primarily defined by a name, bounds. AttributeTemplates can also be described with tags, description, and scope.

Field name Value type Default Description
type String Req. One of: property_template, condition_template, parameter_template
name String Req. The name of the template
bounds Bounds Req. Description of values that are valid according to the template (see below)
uids Map[String, String] Empty A collection of Unique Identifiers
description String None Some text describing what this template is
tags Set[String] Empty set Tags

Attribute Templates are critical in defining which quantities are comparable or equivalent. When Attributes are added to core objects (Runs or Specs), they should be associated with an appropriate Attribute Template. This association is meant to inform how Values are collected and aggregated in downstream consumers of GEMD data.

Constraints
Field name Relationship Field Name
len(name) <= 128, UTF-8 Encoded
len(description) <= 32,768 (32KB), UTF-8 Encoded
Examples
{
    "type" : "property_template",
    "uids" : {
        "id" : "2e1bec7e-bda4-441d-bebb-1215bfa6ee0f"
    },
    "tags" : [
        "hardness::indentation::vickers",
        "Newage MT91 Tester::004",
        "astm_hardness::ASTM E-384"],
    "name" : "Vickers Hardness on Machine 4",
    "description" : "A Vickers indentation hardness test on the Newage MT91 Tester with machine id #4. Conforms to ASTM standard E-384.",
    "bounds" : {
        "type" : "real_bounds",
        "default_units" : "HV30/15",
        "lower_bound" : 0.0,
        "upper_bound" : 10000.0
    }
}
{
    "type": "property_template",
    "id" : "2e1bec7e-bda4-441d-bebb-1215bfa6ee0f",
    "uids" : {},
    "tags" : [
        "#noindigo::newtonwaswrong",
        "taste::therainbow",
        "things_they_are_after::my_lucky_charms",
        "marketing::commercials::candy::skittles",
        "marketing::characters::cereal::leprechaun"
    ],
    "name" : "Rainbow Colors",
    "description" : "Colors in the rainbow",
    "bounds" : {
      "type" : "categorical_bounds",
      "categories" : [
        "red",
        "orange",
        "yellow",
        "green",
        "blue",
        "violet"
      ]
    }
}

Real Bounds

Real bounds are defined by a range of finite real values and a unit.

For example:

  • The band gap is defined from zero to 20 eV
  • The lowest unoccupied molecular orbital (LUMO) is defined from negative 100 to zero eV
  • The volume fraction in the austenite phase is defined from 0.0 to 1.0 and is dimensionless

Real bounds can validate distributions over the real numbers.

A real-valued distribution may be non-zero for points outside of the associated real bounds and still be valid. This is because common distributions such as a Gaussian are non-zero everywhere. If a Real Value is allowed to be non-zero outside the associated bounds, the conditions for validation are documented in the description of that type.

Field name Value type Description
type String always real_bounds
default_units String Unit used to express the bounds
lower_bound Number the lower bound
upper_bound Number the upper bound
Constraints
Field name Relationship Field Name
lower_bound <= upper_bound
Example
{
    "type" : "real_bounds",
    "default_units" : "meters",
    "lower_bound" : 0.0,
    "upper_bound" : 10.0
}

Integer Bounds

Integer bounds are defined by a range of integer values.

For example:

  • The number of power-cycles in a battery lifetime test is between 1 and 1,000,000
  • The position of a digital knob is between 1 and 10
  • The charge on an ion is between -128 and 128
Field name Value type Description
type String always integer_bounds
lower_bound Integer the inclusive lower bound
upper_bound Integer the inclusive upper bound
Constraints
Field name Relationship Field Name
lower_bound <= upper_bound
Example
{
    "type" : "integer_bounds",
    "lower_bound" : -128,
    "upper_bound" : 128
}

Categorical Bounds

Categorical bounds are defined by a set of valid category names. For example:

  • Colors are one of: "Red", "Orange", "Yellow", "Green", "Blue", "Purple"
  • Answers are one of: "Animal", "Vegetable", "Mineral"
  • Fats are one of: "Saturated", "Mono-unsaturated", "Poly-unsaturated"
Field name Value type Description
type String always categorical_bounds
categories Set[String] A set of valid categorical values
Example
{
    "type" : "categorical_bounds",
    "categories" : [
        "red",
        "orange",
        "yellow",
        "green",
        "blue",
        "violet"
    ]
}

Composition Bounds

Composition bounds are defined by a set of valid component names. For example:

  • Steel phase is a mixture of Austentite, Allotriomorphic ferrite, Idiomorphic ferrite, Pearlite, ... (there are 10)
  • Elemental composition is a mixture of the elements
  • Vodka is a mixture of water, ethanol, and contaminants
Field name Value type Description
type String always composition_bounds
components Set[String] A set of valid component names
Example
{
    "type" : "composition_bounds",
    "components" : [
        "water",
        "ethanol",
        "contaminants"
    ]
}

For users of the gemd-python library, the Empirical Formula value type has an all_elements method to easily include the entire periodic table: CompositionBounds(components=EmpiricalFormula.all_elements()).


Molecular Structure Bounds

Molecular structure bounds are used to describe an attribute template that expects a molecular structure type, but do not have any further parameterization. For example:

  • Ligand structure is molecular structure
  • Monomer is a molecular structure
Field name Value type Description
type String always molecular_structure_bounds
Example
{
    "type" : "molecular_structure_bounds"
}