Units

Units

In SAMSON, physical quantities are strongly typed. All physical quantities have associated unit types.
The full list of these units can be seen in the documentation: SBDQuantity.
These units should be used as input data for functions from SAMSON API whenever it is necessary.

We expose these units as Quantity sub-module in such a way, that you can operate with these units, do most of the arithmetic operations with them, and pass them into functions.

We also expose several types based on Units – as the Type sub-module.

Content:

Quantity sub-module

Quantity is a sub-module which contains Python bindings for SBQuantity from SAMSON API.
It allows you to operate with all the possible SBQuantity from SAMSON API, create your own quantities, and do arithmetic operations.
The next unit systems are available: SI units (International System of Units), atomic units, dalton, electronvolt, kilocaloriePerMole.
Please, check the documentation on SBDQuantity for the comprehensive list of available physical units.

Unit systems

See documentation on SBDQuantity

SI units (International System of Units)

List of defined quantity types:

  1. dimensionless
    • dimensionless
    • radian (rad)
    • degree (deg)
    • steradian (sr)
  2. length
    • kilometer (km)
    • hectometer (hm)
    • decameter (dam)
    • meter (m)
    • decimeter (dm)
    • centimeter (cm)
    • millimeter (mm)
    • micrometer (um, micron)
    • nanometer (nm)
    • angstrom
    • picometer (pm)
    • femtometer (fm, fermi)
    • attometer (am)
    • zeptometer(zm)
    • yoctometer (ym)
    • zeptometer(zm)
    • yoctometer (ym)

    There are also defined auxilliary physical quantities for inverse, square, inverse square, cubic, and inverse cubic length, e.g.: inversePicometer (inversePm), squarePicometer (squarePm), inverseSquarePicometer (inverseSquarePm), cubicPicometer (cubicPm), inverseCubicPicometer (inverseCubicPm).

  3. mass
    • kilogram (kg)
    • hectogram (hg)
    • decagram (dag)
    • gram (g)
    • decigram (dg)
    • centigram (cg)
    • milligram (mg)
    • microgram (ug)
    • nanogram (ng)
    • picogram (pg)
    • femtogram (fg)
    • attogram (ag)
    • zeptogram (zg)
    • yoctogram (yg)

    There are also defined auxilliary physical quantities for inverse mass, e.g.: inverseKilogram (inverseKg).

  4. time
    • second (s)
    • decisecond (ds)
    • centisecond (cs)
    • millisecond (ms)
    • microsecond (us)
    • nanosecond (ns)
    • picosecond (ps)
    • femtosecond (fs)
    • attosecond
    • zeptosecond (zs)
    • yoctosecond (ys)

    There are also defined auxilliary physical quantities for inverse time, e.g.: inverseFemtosecond (inverseFs).

  5. electric current
    • kiloampere (kA)
    • hectoampere (hA)
    • decaampere (daA)
    • ampere (A)
    • deciampere (dA)
    • centiampere (cA)
    • milliampere (mA)
    • microampere (uA)
    • nanoampere (nA)
    • picoampere (pA)
    • femtoampere (fA)
    • attoampere (aA)
    • zeptoampere (zA)
    • yoctoampere (yA)
  6. temperature
    • kilokelvin (kK)
    • hectokelvin (hK)
    • decakelvin (daK)
    • kelvin (K)
    • decikelvin (dK)
    • centikelvin (cK)
    • millikelvin (mK)
    • microkelvin (uK)
    • nanokelvin (nK)
    • picokelvin (pK)
    • femtokelvin (fK)
    • attokelvin (aK)
    • zeptokelvin (zK)
    • yoctokelvin (yK)
  7. amount of substance
    • kilomole (kmol)
    • hectomole (hmol)
    • decamole (damol)
    • mole (mol)
    • decimole (dmol)
    • centimole (cmol)
    • millimole (mmol)
    • micromole (umol)
    • nanomole (nmol)
    • picomole (pmol)
    • femtomole (fmol)
    • attomole (amol)
    • zeptomole (zmol)
    • yoctomole (ymol)
  8. luminous intensity
    • kilocandela (kcd)
    • hectocandela (hcd)
    • decacandela (dacd)
    • candela (cd)
    • decicandela (dcd)
    • centicandela (ccd)
    • millicandela (mcd)
    • microcandela (ucd)
    • nanocandela (ncd)
    • picocandela (pcd)
    • femtocandela (fcd)
    • attocandela (acd)
    • zeptocandela (zcd)
    • yoctocandela (ycd)
  9. derived units
    • gigahertz (GHz)
    • megahertz (MHz)
    • kilohertz (KHz)
    • hertz (Hz)
    • piconewton (pN)
    • nanonewton (nN)
    • newton (N)
    • Pascal (Pa)
    • zeptojoule (zJ)
    • kilojoule (kJ)
    • joule (J)
    • joulePerKelvin (jPerK)
    • joulePerMole (jPerMol)
    • kilojoulePerMole (kjPerMol)
    • jouleSecond (jS)
    • watt (W)
    • coulomb (C)
    • zeptocoulomb (zC)
    • coulombPerMeter (CPerM)
    • coulombPerSquareMeter (CPerM2)
    • volt (V)
    • farad (F)
    • ohm (O)
    • siemens (S)
    • weber (Wb)
    • tesla (T)
    • gigatesla (GT)
    • henry (H)
    • lumen
    • lux (lx)
    • becquerel (Bq)
    • gray (Gy)
    • sievert (Sv)
    • katal (Kat)
    • picometerPerSecond (pmPerS)
    • picometerPerFemtosecond (pmPerFs)
    • perSecond (perS)
    • radianPerSecond (radPerS)
    • degreePerSecond (degPerS)
    • picometerPerSquareFemtosecond (pmPerSquareFs)
    • yoctogramPicometerPerFemtosecond (ygPmPerFs)
    • yoctogramSquarePicometer (ygSquarePm)
    • perYoctogramPerSquarePicometer (perYgPerSquarePm)
    • nanonewtonPerPicometer (nNPerPm)
  10. default types
    • length (== picometer)
    • squareLength
    • cubicLength
    • inverseLength
    • inverseSquareLength
    • inverseCubicLength
    • distance (== length)
    • squareDistance
    • cubicDistance
    • inverseDistance
    • inverseSquareDistance
    • inverseCubicDistance
    • mass (== yoctogram)
    • squareMass
    • inverseMass
    • inverseSquareMass
    • time (== femtosecond)
    • squareTime
    • inverseTime
    • inverseSquareTime
    • intensity (== nanoampere)
    • squareIntensity
    • inverseIntensity
    • inverseSquareIntensity
    • temperature (== kelvin)
    • squareTemperature
    • inverseTemperature
    • inverseSquareTemperature
    • amountOfSubstance (== mole)
    • squareAmountOfSubstance
    • inverseAmountOfSubstance
    • inverseSquareAmountOfSubstance
    • luminousIntensity (== candela)
    • squareLuminousIntensity
    • inverseLuminousIntensity
    • inverseSquareLuminousIntensity
    • electricCharge (== squareTime)
    • voltage (== mass x squareLength)
    • electricField (== voltage / time)
    • magneticDensity (== mass x inverseIntensity x inverseSquareTime)
    • angularVelocity (== inverseTime)
    • angularAcceleration (== inverseSquareTime)
    • pressure (== inverseMass x length x inverseSquareTime)
    • lengthMass (== length x mass)
    • inverseLengthInverseMass (== 1 / lengthMass)
    • area (== squareLength)
    • inverseArea (== inverseSquareLength)
    • volume (==cubicLength)
    • inverseVolume (== inverseCubicLength)
    • position (== length)
    • velocity (== length / time)
    • acceleration (== length / squareTime)
    • force (== mass x length x inverseSquareTime)
    • energy (== mass x squareLength x inverseSquareTime)
    • inverseForce (== 1 / force)
    • lengthPerForce (== length / force)
    • forcePerLength (== force / length)
    • energyPerSquareLength (== energy / squareLength)
    • momentum (== mass x length x inverseTime)
    • inverseMomentum (== 1 / momentum)
    • momentOfInertia (== mass x squareLength)
    • inverseMomentOfInertia (== 1 / momentOfIntertia)
    • electronDensity (== inverseVolume)

atomic units

List of defined quantity types:

  1. electronMass (auMass, me)
  2. electronCharge (auCharge, e)
  3. auAction (hBar)
  4. auCoulombConstant (ec)
  5. auTime
  6. bohr (a0)
  7. hartree (Eh)

dalton

List of defined quantity types:

  1. unifiedAtomicMassUnit (u)
    • unifiedAtomicMassUnit (u)
    • dalton (Da)
    • kilodalton (KDa)
    • megadalton (MDa)
    • gigadalton (GDa)

electronvolt

List of defined quantity types:

  1. electronvolt (eV)

kilocaloriePerMole

List of defined quantity types:

  1. kilocaloriePerMole (kcalPerMol)

Quantity sub-module. Examples: working with physical quantities

To initialize a physical quantity you can use either the full name of the quantity or its short-name. For example, the next two definitions are the equivalent:

Quantity.picometer(1.23)
Quantity.pm(1.23)

It is possible to initialize quantities based on quantites of the same type, e.g.:

Quantity.angstrom(Quantity.nm(1)) # = Quantity.angstrom(10)

You can get a floating-point value of quantities in the next way:

l = Quantity.nanometer(1.2)
t = Quantity.femtosecond(0.5)
# the same using short-names:
# l = Quantity.nm(1.2)
# t = Quantity.fs(0.5)
l.value
t.value
Quantity.momentOfInertia(3.5).value

or, convert them to the necessary quantity, like this:

l.picometer
t.second
# the same using short-names
l.pm
t.s

Arithmetic operations can be used with quantities to produce defined and not-defined quantities, e.g.:

Quantity.nanometer(1.2) / Quantity.femtosecond(0.5) # = Quantity.picometerPerSecond(0.6)
# using short-names:
Quantity.nm(1.2) / Quantity.fs(0.5) # = Quantity.pmPerS(0.6)

Conversion between different unit systems

It is possible to convert physical quantities from one unit system to another (if this conversion makes physical sense).
The next conversions are defined:

  • mass ↔ dalton
  • mass ↔ electronMass
  • dalton ↔ kilogram
  • dalton ↔ gram
  • dalton ↔ yoctogram
  • electronMass ↔ dalton
  • electronMass ↔ kilogram
  • electronMass ↔ gram
  • electronMass ↔ yoctogram
  • bohr ↔ length
  • bohr ↔ meter
  • bohr ↔ nanometer
  • bohr ↔ picometer
  • coulomb ↔ electronCharge
  • auTime ↔ time
  • auTime ↔ second
  • auTime ↔ femtosecond
  • joule ↔ joulePerMole
  • joule ↔ hartree
  • joulePerMole ↔ hartree
  • joule ↔ electronvolt
  • electronvolt ↔ kilojoule
  • electronvolt ↔ zeptojoule
  • joulePerMole ↔ electronvolt
  • joule ↔ kilocaloriePerMole
  • joulePerMole ↔ kilocaloriePerMole
  • hartree ↔ electronvolt
  • hartree ↔ kilocaloriePerMole
  • electronvolt ↔ kilocaloriePerMole

Quantity sub-module. Examples: conversion between different unit systems

mass = Quantity.yoctogram(12) # = Quantity.yg(12)
# from yoctogram to dalton
mass_in_dalton = mass.dalton # = mass.Da
# from yoctogram to auMass
mass_in_au = mass.auMass
 
energy = Quantity.kilojoule(13) # = Quantity.kJ(13)
# from joule to joulePerMole
energy_in_JPerMol = energy.joulePerMole # = energy.JPerMol
# from joule to electronvolt
energy_in_eV = energy.electronvolt # = energy.eV
# from joule to kilocaloriePerMole
energy_in_kcalPerMol = energy.kilocaloriePerMole # = energy.kcalPerMol
# from joule to hartree
energy_in_hartree = energy.hartree # = energy.Eh

Type sub-module

Type sub-module contains a representation of the following types whose components are physical quantities:

  • vector3 – a three-dimensional physical vector. All vector components have the same unit.
  • vector6 – a spatial vector, a six-dimensional vector used to describe rigid-body dynamics and articulated-body dynamics. A spatial vector has an angular part and a linear part, which may have different units.
  • interval – a physical interval. Both components have the same unit.
  • intervalVector3 – a three-dimensional physical interval vector, whose components are physical intervals. All interval components have the same unit.
  • matrix33 – a 3×3 physical matrix. All components have the same unit.
  • matrix66 – a spatial matrix. For example, 6×6 matrices typically used to describe rigid or articulated inertias and inverse inertias. In a spatial matrix the 3×3 blocks may have different units.
  • spatialTransform – a spatial transform, containing an orientation matrix and a position vector.

These types can be used directly or through predefined types.

Predefined types for vector3 that constructs three-dimensional physical vectors in according units:

  • dimensionless3
  • radian3
  • position3
  • length3
  • inverseLength3
  • squareLength3
  • velocity3
  • acceleration3
  • picometerPerSecond3
  • radianPerSecond3
  • angularVelocity3
  • angularAcceleration3
  • energy3
  • torque3
  • force3
  • momentum3
  • inverseMomentum3

Predefined types for vector6 that constructs spatial vectors in according units:

  • dimensionless6
  • force6 – consist of energy and force units
  • velocity6 – consist of inverseTime and velocity units
  • acceleration6 – consist of inverseSquareTime and acceleration units

Predefined types for interval that constructs physical intervals in according units:

  • dimensionlessInterval
  • lengthInterval
  • squareLengthInterval
  • positionInterval
  • velocityInterval
  • accelerationInterval
  • energyInterval
  • forceInterval
  • momentumInterval

Predefined types for intervalVector3 that constructs three-dimensional physical interval vectors in according units:

  • dimensionlessInterval3
  • radianInterval3
  • radianPerSecondInterval3
  • lengthInterval3
  • positionInterval3
  • velocityInterval3
  • accelerationInterval3
  • forceInterval3
  • momentumInterval3

Predefined types for matrix33 that constructs 3×3 matrices in according units:

  • mass33
  • inverseMass33
  • momentOfInertia33
  • inverseMomentOfInertia33

Predefined types for matrix66 that constructs 6×6 matrix containing four 3×3 blocks in according units:

  • dimensionless66
  • inertia66
  • inverseInertia66

Also Type sub-module contains a set of useful constants: Pi, DegToRad, RadToDeg, avogadroConstant (shortname: NA), boltzmannConstant (shortname: kB), coulombConstant, protonMass, speedOfLight (shortname: c). They can be accessed in the following way:

Type.constant.Pi
Type.constant.Pi * Type.constant.RadToDeg
Type.constant.kB

To create a vector based on some SI units, you can use Type.vector3, e.g.:

Type.vector3()                          # creates a dimensionless zero vector
Type.vector3(1, 2, 3)                   # creates a dimensionless vector
Type.vector3([1, 2, 3])                 # creates a dimensionless vector
Type.vector3(Quantity.position(1))      # creates a vector with the same components
Type.vector3(Quantity.squareTime(1))
Type.vector3(Quantity.position(1.14), Quantity.position(3.14), Quantity.position(2.7))
Type.force3(0.0)                # creates a vector with the same components in force units
Type.position3(0.0, 1.0, 2.0)   # creates a position vector in length units

Type sub-module. Examples: working with physical quantities

pos = Type.position3(0.0, 1.0, 2.0)           # creates a position vector in length units
 
# accessing components
pos.x                                         # x-component of the vector (read-only attribute)
pos.y                                         # y-component of the vector (read-only attribute)
pos.z                                         # z-component of the vector (read-only attribute)
pos[0]                                        # x-component of the vector (read-only)
pos.value                                     # components of the vector (read-only)
 
# operations with vectors
pos.norm()                                    # returns norm of a vector
pos.norm2().angstrom                          # returns squared norm of a vector in Angstroms
pos_normalized = pos.normalizedVersion()      # get normalized version of the vector
pos_norm_u = pos.normalizedVersionWithUnits() # get normalized version of the vector with units
pos.swap(1,2)                                 # swaps 2 components
pos.setZero()                                 # sets all components to zero
 
pos = Type.vector3(Quantity.position(1.2))    # creates a vector in length units
# arithmetic operations with numbers, units, and vectors
pos /= 2.0
pos * 1.5
 
pos += Type.vector3(Quantity.angstrom(1))
time = Quantity.femtosecond(1)
velocity = pos / time
 
pos2 = Type.vector3(Quantity.angstrom(1.14), Quantity.angstrom(3.14), Quantity.angstrom(2.7))
pos | pos2                                    # returns the dot product of vectors
pos ^ pos2                                    # returns the cross product of vectors
pos + pos2                                    # returns the sum of vectors
pos == pos2                                   # lexicographic comparison
pos < pos2                                    # lexicographic comparison
 
# In case of an operation with vectors of different units (e.g. nanometers and angstrom) 
# the units of the first vector in the operation will be used for the resulting vector
pos_nm = Type.vector3(Quantity.nanometer(1.1), Quantity.nanometer(2.2), Quantity.nanometer(3.3))
pos_a  = Type.vector3(Quantity.angstrom(1.14), Quantity.angstrom(3.14), Quantity.angstrom(2.72))
pos_a + pos_nm                                # the result is in angstroms
pos_nm - pos_a                                # the result is in nanometers

Comments are closed.