Structural Bioinformatics Library
Template C++ / Python API for developping structural bioinformatics applications.

Authors: F. Cazals and T. Dreyfus
The UnitSystemTraits package provides two things, namely a concept to represent a units system, together with accompanying models. It is in particular meant to ensure the compile time coherence of the dimensions of the manipulated quantities.
The International System of Units is a coherent system of units based on seven base units–represented on the package logo. This kind of system ensures the coherence of calculations relying on different data types.
For example, in biomolecular modeling, computing the potential energy of a protein uses input files describing atomic positions expressed in Angstroms, while force fields may express distances in nanometers.
To foster the coherence of such calculations, this package provides models to represent unit systems with easy interconversions based on the Boost Units Library
The main unit systems used in biophysics are summarized in the following table (see also Parmed documentation for an overview of these unit systems) :
Unit system  Length unit  Mass unit  Time unit  Charge unit  Temperature unit  Amount unit  Energy unit 

SI  meters  kilograms  second  Ampere  kelvin  mole  joule 
CGS  centimeters  gram  second  Ampere  kelvin  mole  1e7 joule 
MD  nanometers  gram  second  q electron  kelvin  mole  kilojoule 
Planck  Planck length  Planck mass  Planck time  Planck charge  Planck temperature  item  Planck energy 
AKMA  angstroms  daltons  AKMA time  q electron  kelvin  mole  kilocalorie 
The SBL provides the two unit systems classically used in molecular dynamics : AKMA and MD.
When the data used do not comply with the units required for the calculations undertaken, a conversion is in order. For example, if the distance between two atoms expressed in MD is printed, the expression 1 nm is printed, even if the atomic coordinates are specified in Angstrom.
We first introduce the Boost Units Library and discuss its usage in this package. Then we describe the different models provided in this package.
The Boost Units Library offers a full mechanism to represent existing and custom unit systems in C++. There are five important notions :
This framework allows defining the traits class for the unit system, which contains :
The primary goal of this package is to ensure compile time coherence of calculations involving units. To this end, the following two classes are offered:
The simplest way to use these models is to replace number types by the quantities these models define. For example, a classical dimensionless calculation of the Euclidean squared distance between two 2D points is done as follows :
double x1 = 0; double y1 = 0; double x2 = 1; double y2 = 0; double d = (x2  x1)*(x2  x1) + (y2  y1)*(y2  y1);
If we know that the coordinates are in angstroms, we can replace the double type by the Length_quantity type :
UnitSystemTraits::Length_quantity x1 = 0*UnitSystemTraits::angstrom; UnitSystemTraits::Length_quantity y1 = 0*UnitSystemTraits::angstrom; UnitSystemTraits::Length_quantity x2 = 1*UnitSystemTraits::angstrom; UnitSystemTraits::Length_quantity y2 = 0*UnitSystemTraits::angstrom; UnitSystemTraits::Length_quantity d = (x2  x1)*(x2  x1) + (y2  y1)*(y2  y1);
Note that the type UnitSystemTraits can be replaced by any model of the concept, even if the Angstrom is not a base unit of the unit system : the unit constant angstrom is defined in all models of UnitSystemTraits
Note also that it is possible to use nameless units when values are independent from the unit system to be used. For exemple, a molar energy value that has to be initialized to 1 whatever the underlying system cannot explicitly use AKMA or MD units, and will use these systemindependent units :
UnitSystemTraits::Molar_energy_quantity E = 1*UnitSystemTraits::energy_unit/UnitSystemTraits::amount_unit;
The value of E will be always 1, whatever the underlaying unit system.
There are two limitations of this approach when using a third party library :
To overcome these difficulties, one can use the static method value() of the concept UnitSystemTraits that returns the dimensionless value of the quantity. This package also provides dimensionless versions of AKMA and MD :
The main difference is that units and quantities are represented by a simple number type (double for example). This means also that there is no compile time check for the coherence of the dimensions. For example, one can check the coherence of dimensions of examples within Molecular_potential_energy using SBL::Models::T_Unit_system_traits_AKMA . However, the energy minimization provided in the package Real_value_function_minimizer may use libraries which are not generic w.r.t the number type .
Finally, the class SBL::Models::T_Unit_system_traits_for_potential_energy< UnitSystemTraitsBase > specializes the parameter UnitSystemTraitsBase and defines supplemental units and quantities used in the package Molecular_potential_energy
A model of UnitSystemTraits has to define the following types :
Length_unit Mass_unit Time_unit Temperature_unit Angle_unit Amount_unit Charge_unit Energy_unit Molar_energy_unit Length_quantity Mass_quantity Time_quantity Temperature_quantity Angle_quantity Amount_quantity Charge_quantity Energy_quantity Molar_energy_quantity
It also has to define the following static constants :
length_unit; angstrom; angstroms; nanometer; nanometers; mass_unit; dalton; daltons; time_unit; T; picosecond; picoseconds; temperature_unit; kelvin; kelvins; angle_unit; radian; radians; degree; degrees; amount_unit; mole; moles; charge_unit; q_electron; coulomb; coulombs; energy_unit; kilocalorie; kilocalories; kilojoule; kilojoules;
Note that these constants can be either of a unit type either of a quantity type indifferenty.
Finally, a model of UnitSystemTraits has to define the static method value(const Quantity& q) that returns the dimensionless value of the input quantity.