Using Equivalents

New to XDL 1, equivalents ('eq', 'equivalents', 'equivs') can now be used as a unit for the addition of solids and liquids. This enables stoichiometric addition of reagents.

Defining Equivalent References and Equivalent Amounts

In order for equivalents to be used as a unit, a reference reagent (equiv_reference) and equivalent amount (equiv_amount) need to be defined when the XDL is compiled by calling the prepare_for_execution method (see Defining Equivalence References). equiv_reference is the reference reagent for all stoichiometric calculations.

The equiv_reference should be a reagent present in the Reagents section. The equiv_amount is the value that corresponds to one equivalent of that reagent (in ‘moles’, ‘g’ or ‘L’ etc.).

From these values, the number of moles per one equivalent of reference reagent is calculated. This enables stoichiometric addition of reagents via use of the equivalent ('eq') unit. When a stoichiometric reference reagent has been provided and the 'eq' unit is used for additions, the final volume / mass of reagents added are automatically scaled to this stoichiometric reference (see Equivalence Calculations).

Equivalent References in prepare_for_execution

Equivalent reference (equiv_reference) and equivalent amount (equiv_amount) can be defined during prepare for execution:

from xdl import XDL

x = XDL("example_xdl.xdl", platform)

    equiv_amount="1 g",

These values will be used as the equivalent reference for any step using eq that does not have a specific equivalent reference (i.e. no Blueprint-Specific Equivalent References)

Blueprint-Specific Equivalent References

Individual blueprints can have unique equivalent references. The (equiv_reference) must be a Reagent defined in the blueprint itself, not a global Reagent from the main Synthesis section.

For more information on how to use blueprints, please see XDL Blueprints.

   <Blueprint id="blueprint_1">
         <Component id="reactor" type="reactor"/>

         <Reagent id="solid"/>

         <Add reagent="solid" vessel="reactor" amount="1 eq"/>
         <Wait time="0.5 min"/>

         <Component id="reactor_1" type="reactor"/>

         <Reagent name="example_solid" solid="true" molecular_weight="155.155 g/mol"/>

            equiv_amount="0.5 g"/>

Defining a global equiv_reference and equiv_amount (in prepare_for_execution) will not overwrite blueprint-specific equivalents. However, if a blueprint does not have a unique equiv_reference and equiv_amount defined when the blueprint is used, it will use the global equiv_reference and equiv_amount values.

Using the Equivalents Unit

The steps that currently support the use of the ‘equivalence’ units are Add, Dissolve, Precipitate and Transfer. Adding a certain number of equivalents of a given reagent can be specified using the amount property of the above steps.

For example,


   <Add reagent="reagent_1" vessel="reactor" amount="1 eq"/>

      amount="100 eq"
      time="10 min"
      rinsing_volume="1 mL"


Equivalence Calculations

Depending on the scenario in which equivalents is used, certain combinations of Reagent properties are required to calculate the final amount.

Calculating Mass and Volume from ‘amount’

Depending on the scenario in which amount is used, certain combinations of Reagent properties are required to calculate the final amount.

Calculations For Liquid Reagents

Amount Unit Conversion




mass (g) to volume (mL)

moles (mmol) to volume (mL)

equivalents (eq) to volume (mL)

For example, to Add 5 g of a liquid reagent (convert to mL), you would need its density or both it’s molecular weight and concentration.

Calculations For Solid Reagents

Amount Unit Conversion




moles (mmol) to mass (g)

equivalents (eq) to mass (g)