Object Construction and Property Validation for Files of Synthesis (FOS)

Introduction

During construction of a parsed FOS into a Synthesis object, or when reassigning a property of an exising object, most classes have properties that should be expected in a certain format, or might contain nested objects with their own properties. The parsed properties are passed as either strings or (in the case of nested objects) a list or dict structure to the validation routine mapped to them in FoSpy.parsing.validation.py. In the case of nested objects, the validation routine is usually the constructor of the required object.

Classes can have required properties, which must be present at read time, or optional properties, which have validation routines but might not be expected for all syntheses.

During attribute assignment, expected properties are built up in order of parent classes. Any subclass inherits all the expected properties of its parent classes, but they may be overwritten to other validators.

Dispatching Subclasses

Properties marked with (dispatched) are used to identify and delegate construction to the respective subclass. A class with a dispatch key is rarely constructed as itself, but may be used to inherit methods or required/optional properties.

ListBlock and Simple Lists

ListBlock subclasses do not have required properties. Instead, they are a rich list of objects with a certain required SingleBlock subclass. Some ListBlock subclasses have their own methods and unique attributes. If a ListBlock is required for a given SingleBlock subclass but it doesn't need any method or attribute overrides, it can be instantiated with the class method ListBlock.Simple(SingleBlockSubclass) (referred to below as a "simple list").

TemplateLists

TemplateList is a unique subclass of ListBlock used for storing TemplateBlock subclass objects. TemplateList has a class method Simple() similar to ListBlock's method, but instead of full objects (e.g. Material), it generates hybridized templates with fields for any field-marked or missing properties. Some syntax for TemplateList entries can be found in the code example walkthrough.

Modifying Property Validation at Runtime

The intent of the FOS is to be as flexible as possible while still enforcing standards for fully capturing a synthetic method. However, it may be necessary for private or niche applications to modify standards to match your own synthesis. This can be done by mutating the dictionaries in FoSpy.parsing.validation at the start of your script. The example below creates a new block type with its own expected properties, and then adds it as an optional top-level block for a synthesis file.

These modifications should be reserved for very unique and isolated cases. If you are modifying standards in a significant way, or such that may be applicable for other researchers, consider reaching out to FoSpy developers or creating a fork of the GitHub.

Python

import FoSpy.parsing.validation as vd
from FoSpy.blocks import (
    blocks.SingleBlock as SingleBlock
    synthesis.Synthesis as Synthesis
)


class MySpecialBlock(SingleBlock):
    pass

vd.required_keys[MySpecialBlock] = {
    "special_prop1": str
    "special_prop2": float
}

vd.optional_keys[Synthesis]["special"] = MySpecialBlock

New FOS Block

[Special]
special_prop1: foobar
special_prop2: 6.022

---

Expected Property Tables

AnnealSection

Class Documentation

Subclass of SingleBlock

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
type	Examples: "dwell", "ramp", "quench"	Any text entry

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

Annealing

Class Documentation

Subclass of Treatment

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
type	What type of treatment was performed.	Any text entry
repeats	How many times the treatment was performed in succession uninterrupted. If other treatments are performed between repeats, add a different treatment block after the interrupting treatments.	Any integer (positive or negative)
program	The temperatures and gradients used during annealing.	A specialized ListBlock of AnnealSection objects.
start_temp	Initial temperature at start of program.	Positive decimal value Requires that start_temp_unit also be present
start_temp_unit	Units for initial temperature.	Validator is a subclass of pint's Unit class With more flexibility for recognizing temperature units. Must be a recognizable unit for temperature.

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.
observations	General observations during the treatment	Any text entry
recovered_amount	How much material was recovered after treatment.	Positive decimal value Requires that recovered_amount_unit also be present
recovered_amount_unit	Units for treatment recovered amount.	Validator is a subclass of pint's Unit class With additional rules enforcing the correct dimensionality of the unit. Allowed dimensions: [mass] [length]^3
start_time	What time the treatment was started	Any text entry
end_time	What time the treatment was finished	Any text entry
gas_flow	Consistent gas flow conditions applied during annealing.	A simple ListBlock of GasFlow objects.

---

Attachment

Class Documentation

Subclass of SingleBlock

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
file_name	The name of the attached file (with extension)	A valid filename (no path, no separators, allowed characters only). Must include a valid extension. Allowed characters: letters, digits, '_', '-', '.' Commas are allowed, but may lead to unexpected behavior for some OS or software. Paths to nonexistent files will be validated, but may raise errors when the parent FileBlock attempts to track the file.

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.
path	The directory containing the attached file, relative to the directory containing the parent FileBlock.	Mutually exclusive with embedded property. A valid relative filepath to a directory. Path is relative to the directory containing the parent FileBlock. "." should be used to indicate the same directory as the parent FileBlock. ".." can be used to walk up the directory tree. Paths to nonexistent directories will be validated, but may raise errors when the parent FileBlock attempts to track the file. Examples for a FileBlock at /home/user/synthesis.fos: "." is /home/user ".." is /home "../foo" is /home/foo "./bar" is /home/user/bar
embedded	Attachment content embedded as a raw utf-8 string.	Mutually exclusive with path property. Attachment content as a raw utf-8 string.

Additional Requirements

In addition to the required properties above, all Attachment objects must be constructed with one of the following optional properties:

• embedded
• path

The first matching property found will be used and the remainder will be discarded. The presence of one of these properties is used to identify what form of file attachment it is. Refer to the attachments guide for more information

Attachment Types

• EmbeddedFile (Embedded text content)
• PathFile (Referenced by relative path)

File Types

• CIFFile (Crystallographic Information File)

Attachment Method Subclasses

Attachment Subclasses are hybridized between an attachment type and a file type. Attachment types share most method names to be called by file type methods, but method source code differs on the basis of how the file was attached. For example, _get_filepath() for PathFile simply returns an absolute filepath resolved from the value in its path attribute, whereas EmbeddedFile objects create a temporary file to print their embedded lines to before returning its filepath.

Attachment types are dispatched based on which optional properties they have. File types are dispatched based on extension. Unrecognized extensions simply don't add any special file type methods.

---

CIFFile

Class Documentation

Subclass of Attachment

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
file_name	The name of the attached file (with extension)	A valid filename (no path, no separators, allowed characters only). Must include a valid extension. Allowed characters: letters, digits, '_', '-', '.' Commas are allowed, but may lead to unexpected behavior for some OS or software. Paths to nonexistent files will be validated, but may raise errors when the parent FileBlock attempts to track the file.

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.
path	The directory containing the attached file, relative to the directory containing the parent FileBlock.	Mutually exclusive with embedded property. A valid relative filepath to a directory. Path is relative to the directory containing the parent FileBlock. "." should be used to indicate the same directory as the parent FileBlock. ".." can be used to walk up the directory tree. Paths to nonexistent directories will be validated, but may raise errors when the parent FileBlock attempts to track the file. Examples for a FileBlock at /home/user/synthesis.fos: "." is /home/user ".." is /home "../foo" is /home/foo "./bar" is /home/user/bar
embedded	Attachment content embedded as a raw utf-8 string.	Mutually exclusive with path property. Attachment content as a raw utf-8 string.

Additional Requirements

CIFFiles also have additional requirements to follow according to their attachment type designation. Refer to the Attachment class.

---

ChemChange

Class Documentation

Subclass of Chemical

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
formula	Molecular composition.	A chemical formula recognized by the chemformula package.
amount	The sign-sensitive amount of this chemical that was added (positive) or removed (negative).	Positive decimal value
amount_unit	Units for comp change amount.	Any text entry

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

Chemical

Class Documentation

Subclass of SingleBlock

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
formula	Molecular composition.	A chemical formula recognized by the chemformula package.

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

CompChange

Class Documentation

Subclass of Treatment

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
type	What type of treatment was performed.	Any text entry
changes	A list of chemicals that were added or removed from the active reaction in this step.	A simple ListBlock of ChemChange objects.

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.
observations	General observations during the treatment	Any text entry
recovered_amount	How much material was recovered after treatment.	Positive decimal value Requires that recovered_amount_unit also be present
recovered_amount_unit	Units for treatment recovered amount.	Validator is a subclass of pint's Unit class With additional rules enforcing the correct dimensionality of the unit. Allowed dimensions: [mass] [length]^3
start_time	What time the treatment was started	Any text entry
end_time	What time the treatment was finished	Any text entry

---

Dwell

Class Documentation

Subclass of AnnealSection

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
type	Examples: "dwell", "ramp", "quench"	Any text entry
time	How long the temperature was kept constant in this section.	Positive decimal value Requires that time_unit also be present
time_unit	Units for dwell time.	Validator is a subclass of pint's Unit class With additional rules enforcing the correct dimensionality of the unit. Allowed dimensions: [time]

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

EmbeddedFile

Class Documentation

Subclass of Attachment

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
file_name	The name of the attached file (with extension)	A valid filename (no path, no separators, allowed characters only). Must include a valid extension. Allowed characters: letters, digits, '_', '-', '.' Commas are allowed, but may lead to unexpected behavior for some OS or software. Paths to nonexistent files will be validated, but may raise errors when the parent FileBlock attempts to track the file.
embedded		Mutually exclusive with path property. Attachment content as a raw utf-8 string.

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

Equipment

Class Documentation

Subclass of SingleBlock

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

Experimenter

Class Documentation

Subclass of SingleBlock

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
name	Name of the experimenter	Any text entry
affiliation	Lab/University/Research Group/etc.	Any text entry

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.
orcid	The experimenter's ORCID	Any text entry

---

FileBlock

Class Documentation

Subclass of SingleBlock

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
metadata	General information about the file.	A MetaData object.

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

GasFlow

Class Documentation

Subclass of SingleBlock

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

LabConditions

Class Documentation

Subclass of SingleBlock

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

Material

Class Documentation

Subclass of Chemical

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
name	A unique name for the material.	Any text entry
type	How it was used in the synthesis (e.g., reagent, flux, solvent)	Any text entry
formula	Molecular composition.	A chemical formula recognized by the chemformula package.
supplier	Source of purchase/synthesis	Any text entry
cas	CAS ID	Any text entry
form	Physical shape or state of the material at time of acquisition (e.g., powder, shot, wire, lump). If the material was modified after aquiring but before use in the synthesis (e.g., grinding into powder, drying, etc.), these actions should be specified in the material's treatments property (not the synthesis treatments).	Any text entry
env	What atmospheric environment the material is stored in. (e.g., ambient, Ar(g))	Any text entry
amount	Amount of the material that was used.	Positive decimal value
amount_unit	Units for material amount.	Any text entry

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.
purity	0 < purity <= 1	Decimal value within range: 0 < val <= 1
treatments	Treatments that were applied to the material before use in the synthesis.	A simple ListBlock of Treatment objects.

---

MetaData

Class Documentation

Subclass of SingleBlock

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
fos_id	A reaction ID unique within the scope of the applicable context. (e.g., a synthesis ID, template ID, etc.)	Any text entry
fos_type	What type of FileBlock subclass the file should be interpreted as.	Any text entry
description	A brief description of the intent for the file (characteristic methods, target products, template category, etc.).	Any text entry

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

PathFile

Class Documentation

Subclass of Attachment

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
file_name	The name of the attached file (with extension)	A valid filename (no path, no separators, allowed characters only). Must include a valid extension. Allowed characters: letters, digits, '_', '-', '.' Commas are allowed, but may lead to unexpected behavior for some OS or software. Paths to nonexistent files will be validated, but may raise errors when the parent FileBlock attempts to track the file.
path		Mutually exclusive with embedded property. A valid relative filepath to a directory. Path is relative to the directory containing the parent FileBlock. "." should be used to indicate the same directory as the parent FileBlock. ".." can be used to walk up the directory tree. Paths to nonexistent directories will be validated, but may raise errors when the parent FileBlock attempts to track the file. Examples for a FileBlock at /home/user/synthesis.fos: "." is /home/user ".." is /home "../foo" is /home/foo "./bar" is /home/user/bar

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

Product

Class Documentation

Subclass of Chemical

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
formula	Molecular composition.	A chemical formula recognized by the chemformula package.
name	A unique name for the product.	Any text entry
expected	Whether or not the product was expected from the synthesis.	A boolen value (True or False) Acceptable 'True' values (not case sensitive): true t yes y 1 on Acceptable 'False' values (not case sensitive): false f no n 0 off
obtained	Whether or not the product obtained from the synthesis.	A boolen value (True or False) Acceptable 'True' values (not case sensitive): true t yes y 1 on Acceptable 'False' values (not case sensitive): false f no n 0 off
observations	General observations about the product.	Any text entry

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.
expected_amount	How much of the product was nominally expected to be obtained from the synthesis	Positive decimal value Requires that expected_amount_unit also be present
expected_amount_unit	Units for product expected amount.	Validator is a subclass of pint's Unit class With additional rules enforcing the correct dimensionality of the unit. Allowed dimensions: [mass] [length]^3
obtained_amount	How much of the product was actually obtained from the synthesis..	Positive decimal value Requires that obtained_amount_unit also be present
obtained_amount_unit	Units for product obtained amount	Validator is a subclass of pint's Unit class With additional rules enforcing the correct dimensionality of the unit. Allowed dimensions: [mass] [length]^3
characterizations	Description of characterization methods used to determine/quantitate the product.	Any text entry
structure_comments	General description of the structure of the product.	Any text entry

---

Quench

Class Documentation

Subclass of AnnealSection

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
type	Examples: "dwell", "ramp", "quench"	Any text entry
medium	What medium the reaction vessel was quenched in (e.g., water, air).	Any text entry

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

Ramp

Class Documentation

Subclass of AnnealSection

Required properties

During construction of a Ramp object, it is required to have at least 2 of the following optional properties, with their respective units:

• temp
• time
• rate

If all three are provided, the last one found during reading will be discarded as redundant data, and the object is dispatched to a Ramp subclass with a "retrieval" method for calculating the missing property (e.g., get_temp(), get_time(), or get_rate()) When working with Ramp objects in the FoSpy framework, it is best practice to always use the "retrieval" methods. For subclasses that do have the desired property, retrieval methods default to returning it directly.

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
type	Examples: "dwell", "ramp", "quench"	Any text entry

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.
temp	The next temperature in the program.	Positive decimal value Requires that temp_unit also be present
time	Length of time from the previous temperature to the new temperature.	Positive decimal value Requires that time_unit also be present
rate	The sign-sensitive rate at which temperature was changed to get to the new temperature. (Increase -> positive, Decrease -> negative).	Any decimal value (positive or negative) Requires that rate_unit also be present
temp_unit	Units for ramp temperature.	Validator is a subclass of pint's Unit class With more flexibility for recognizing temperature units. Must be a recognizable unit for temperature.
time_unit	Units for ramp time.	Validator is a subclass of pint's Unit class With additional rules enforcing the correct dimensionality of the unit. Allowed dimensions: [time]
rate_unit	Units for ramp rate.	Validator is a subclass of pint's Unit class with more flexibility for recognizing temperature units. Must be a recognizable unit for temperature over time.

Ramp Method Subclasses

The following subclasses are dispatched based on the redundant parameter (see Required Properties above) and override the retrieval method to calculate the missing parameter instead of getting it from attributes:

• RampNoRate: overrides get_rate()
• RampNoTemp: overrides get_temp()
• RampNoTime: overrides get_time()

---

RampNoRate

Class Documentation

Subclass of Ramp

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
type	Examples: "dwell", "ramp", "quench"	Any text entry

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.
temp	The next temperature in the program.	Positive decimal value Requires that temp_unit also be present
time	Length of time from the previous temperature to the new temperature.	Positive decimal value Requires that time_unit also be present
rate	The sign-sensitive rate at which temperature was changed to get to the new temperature. (Increase -> positive, Decrease -> negative).	Any decimal value (positive or negative) Requires that rate_unit also be present
temp_unit	Units for ramp temperature.	Validator is a subclass of pint's Unit class With more flexibility for recognizing temperature units. Must be a recognizable unit for temperature.
time_unit	Units for ramp time.	Validator is a subclass of pint's Unit class With additional rules enforcing the correct dimensionality of the unit. Allowed dimensions: [time]
rate_unit	Units for ramp rate.	Validator is a subclass of pint's Unit class with more flexibility for recognizing temperature units. Must be a recognizable unit for temperature over time.

---

RampNoTemp

Class Documentation

Subclass of Ramp

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
type	Examples: "dwell", "ramp", "quench"	Any text entry

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.
temp	The next temperature in the program.	Positive decimal value Requires that temp_unit also be present
time	Length of time from the previous temperature to the new temperature.	Positive decimal value Requires that time_unit also be present
rate	The sign-sensitive rate at which temperature was changed to get to the new temperature. (Increase -> positive, Decrease -> negative).	Any decimal value (positive or negative) Requires that rate_unit also be present
temp_unit	Units for ramp temperature.	Validator is a subclass of pint's Unit class With more flexibility for recognizing temperature units. Must be a recognizable unit for temperature.
time_unit	Units for ramp time.	Validator is a subclass of pint's Unit class With additional rules enforcing the correct dimensionality of the unit. Allowed dimensions: [time]
rate_unit	Units for ramp rate.	Validator is a subclass of pint's Unit class with more flexibility for recognizing temperature units. Must be a recognizable unit for temperature over time.

---

RampNoTime

Class Documentation

Subclass of Ramp

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
type	Examples: "dwell", "ramp", "quench"	Any text entry

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.
temp	The next temperature in the program.	Positive decimal value Requires that temp_unit also be present
time	Length of time from the previous temperature to the new temperature.	Positive decimal value Requires that time_unit also be present
rate	The sign-sensitive rate at which temperature was changed to get to the new temperature. (Increase -> positive, Decrease -> negative).	Any decimal value (positive or negative) Requires that rate_unit also be present
temp_unit	Units for ramp temperature.	Validator is a subclass of pint's Unit class With more flexibility for recognizing temperature units. Must be a recognizable unit for temperature.
time_unit	Units for ramp time.	Validator is a subclass of pint's Unit class With additional rules enforcing the correct dimensionality of the unit. Allowed dimensions: [time]
rate_unit	Units for ramp rate.	Validator is a subclass of pint's Unit class with more flexibility for recognizing temperature units. Must be a recognizable unit for temperature over time.

---

Reaction

Class Documentation

Subclass of SingleBlock

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
nominal_formula	Total expected chemical composition from all final products.	A chemical formula recognized by the chemformula package.
nominal_amount	Total amount expected to be recovered from all final products.	Positive decimal value
nominal_amount_unit	Units for reaction nominal amount.	Validator is a subclass of pint's Unit class With additional rules enforcing the correct dimensionality of the unit. Allowed dimensions: [mass] [length]^3

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

Rename

Class Documentation

Subclass of SingleBlock

Any SingleBlock object can have rename as one of its properties, which contains an instance of a Rename block. These can be used to alter the expected (required or optional) property names to custom names instead. This is useful for when expected properties are present and matching descriptions, but the default name doesn't align with the niche context. (e.g., \"experimenters\" might be mapped to the more generic \"collaborators\" for computational or meta-contexted FOS files.)

Rename blocks are available as a "stop-gap" for scientists who are trying to make use of the FoS format, but whose areas of expertise are significantly deviated from the context FoS was designed for. Renaming is not intended as a long-term solution.

• If the descriptions/validation routines for the renamed property are still appropriate, but the property name itself is inaccurate: Consider reaching out to developers about altering the FoS standards to better reflect the growing community.
• If you are working with a very niche application that requires fundamental alteration of the FoS standards: Consider modifying validation at runtime or creating a fork of the GitHub to make changes to the sourcecode.

Note that renaming a property will keep all relevant validation rules attached to the new custom name (e.g., for the aforementioned example, the same rules that apply to the \"experimenters\" property now apply to the new \"collaborators\" property instead.). This allows researchers to make modifications for clarity purposes only, without bypassing any FoS standards.

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	Each property of a Rename object renames its parent's expected property of the same name to the provided value. Renaming properties starting with "_" is not allowed. Properties must be expected property names for the parent block. For unexpected (custom) keys, adding a rename mapping is not necessary. (There is no required/optional validator to redirect to.) You cannot rename a property to a different expected property. (Unexpected names only.) The following reserved properties cannot be renamed: rename metadata

---

SingleBlock

Class Documentation

Subclass of Block

SingleBlock is the parent class of all block classes representing a single entity. SingleBlocks are rarely constructed without subclassing, but may be used if you want to take advantage of the rigorous attribute assignment and methods that all other block classes inherit, without defining any expected properties.

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

Synthesis

Class Documentation

Subclass of FileBlock

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
metadata	General information about the file.	A SynthesisMeta object.
experimenters	Experimenters who participated in any treatments described in the synthesis.	A simple ListBlock of Experimenter objects.
reaction	General information applying to the entire synthetic reaction.	A Reaction object.
products	Products expected or obtained from the synthesis.	A simple ListBlock of Product objects.
materials	Starting chemicals and materials used in the synthesis.	A specialized ListBlock of Material objects.
treatments	Sequence of individual actions performed on the materials or active reaction to carry out the synthesis.	A simple ListBlock of Treatment objects.

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.
attachments	A list of files either attached by relative path or with embedded text.	A simple ListBlock of Attachment objects.
laboratory_conditions	General conditions of the laboratory during the synthesis.	A LabConditions object.
equipment	Specialized equipment or apparatuses used during the synthesis.	A simple ListBlock of Equipment objects.

---

SynthesisMeta

Class Documentation

Subclass of MetaData

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
fos_id	A reaction ID unique within the scope of the applicable context. (e.g., a synthesis ID, template ID, etc.)	Any text entry
fos_type	What type of FileBlock subclass the file should be interpreted as.	Any text entry
description	A brief description of the intent for the file (characteristic methods, target products, template category, etc.).	Any text entry
group_id	The unique identifier for the generating research group or organization.	Any text entry
project_id	Describes the context or purpose of the synthesis within the scope of the group_id and/or lead experimenter.	Any text entry

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

TemplateBlock

Class Documentation

Subclass of SingleBlock

The TemplateBlock class is not normally used alone to construct objects. Instead, it is used to make hybridized subclasses of other SingleBlock subclasses. Template subclasses override required properties of the original class with template fields that can be later filled in and passed to their validators with the fill() method. Refer to the code example walkthrough for some uses of templates.

Instances of the base TemplateBlock class are usually constructed by calling the TemplateClass class method on an existing block, but some template classes can dynamically determine which fields are missing and redirect to the appropriate template class.

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
template_name	An unique name for the template.	Any text entry

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

TemplateSet

Class Documentation

Subclass of FileBlock

In contrast with a Synthesis file, most top-level properties for a TemplateSet are expected to contain lists of templates of a given type. The TemplateList.Simple() class method uses a flexible subclass of the TemplateBlock class to dynamically determine what fields are missing/empty and delegate to the correct template for each object in the list.

TemplateSets do not have many expected properties by default, but you can add a list of templates for any block to a TemplateSet using an alias. Aliases are ways of signaling to a block that you are creating an unexpected property, but you want it to be a certain block type anyway. You do this by adding "$", followed by the name of the block type in all lowercase, to the end of the property name.

For example:

[[Experimenters]]
name: Travis Errthum
affiliation: Kovnir Group - Iowa State University
orcid: 0009-0006-1937-5672
colleague$experimenter: [
    name: Joseph Race
    affiliation: Graham's Dad
    orcid: 0000-0002-8551-3627
]

Here, the experimenter has the normal expected properties, but it also has an unexpected property, colleague, aliased with experimenter. This signals that the contents should be interpreted as an experimenter.

Unlike most blocks, for TemplateSets, all top-level property aliases are intepreted to mean a list of items, not just a single item. So if I add this to my templates file:

[[experimenter_templates$experimenter]]
name: Travis Errthum
affiliation: Kovnir Group - Iowa State University
-orcid: <!TEMPLATE-FIELD>

name: Joseph Race
-affiliation: <!TEMPLATE-FIELD>
orcid: 0000-0002-8551-3627

The experimenters property will be correctly interpreted as a list of Experimenter objects. Putting the same block (with filled templates) into a Synthesis file would result in an error, because syntheses expect the $experimenter alias to mean only one experimenter (use $experimenterlist to contain multiple).

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
metadata	General information about the file.	A MetaData object.

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.

---

Treatment

Class Documentation

Subclass of SingleBlock

Required properties

Property	Description	Validation Rules
Universal	Rules that apply to all properties of this block.	No Universal Rules
type	What type of treatment was performed.	Any text entry
repeats	How many times the treatment was performed in succession uninterrupted. If other treatments are performed between repeats, add a different treatment block after the interrupting treatments.	Any integer (positive or negative)

Optional properties

Property	Description	Validation Rules
rename	See Rename documentation	A Rename object.
observations	General observations during the treatment	Any text entry
recovered_amount	How much material was recovered after treatment.	Positive decimal value Requires that recovered_amount_unit also be present
recovered_amount_unit	Units for treatment recovered amount.	Validator is a subclass of pint's Unit class With additional rules enforcing the correct dimensionality of the unit. Allowed dimensions: [mass] [length]^3
start_time	What time the treatment was started	Any text entry
end_time	What time the treatment was finished	Any text entry

---