Units#

In SAMSON, physical quantities are strongly typed. Every physical quantity has associated Units.

Use SAMSON quantities whenever a Python API expects a physical value, such as a distance, position, velocity, energy, force, or time. This keeps scripts explicit about units and avoids mixing plain numbers with physical values.

Note

The full list of these units can be seen in the SAMSON SDK: SBDQuantity.

Use these units whenever a function from the SAMSON API expects a quantity with physical units.

These units are exposed in the samson.SBQuantity sub-module so that you can create quantities, perform arithmetic with them, and pass them directly into SAMSON functions.

Create common physical quantities#
distance = SBQuantity.angstrom(1.20)
SBQuantity.picometer(1.20)
SBQuantity.pm(1.20)
time = SBQuantity.femtosecond(100.0)
energy = SBQuantity.kilojoulePerMole(1.0)
velocity = SBQuantity.picometerPerSecond(10.0)

The samson.SBQuantity sub-module contains Python bindings for SBDQuantity from SAMSON SDK - it allows you to operate with them, create your own quantities, and do arithmetic operations.

Please refer to the SBQuantity section for more information and the list of available classes.

Python scripting exposes a number of classes that define basic types used in SAMSON, in particular for mathematical operations.

# create a position vector in length units
pos = SBPosition3(0.0, 1.0, 2.0)
# this is the same as
pos = SBPhysicalVector3(SBQuantity.position(0.0), SBQuantity.position(1.0), SBQuantity.position(2.0))

# arithmetic operations with numbers, units, and vectors
pos /= 2.0
pos * 1.5

# accessing components
pos.x             # x-component of the vector
pos.x = 2 * pos.y
pos[0]            # x-component of the vector
pos.value         # components of the vector (read-only)

# operations with vectors
pos.norm()            # returns norm of a vector

pos += SBPhysicalVector3(SBQuantity.angstrom(1))

time = SBQuantity.femtosecond(1)
# this will create a velocity vector in proper length/time units
velocity = pos / time

# position in angstroms
pos2 = SBPhysicalVector3(
    SBQuantity.angstrom(1.14),
    SBQuantity.angstrom(3.14),
    SBQuantity.angstrom(2.7))

Please refer to the Type section for more information and the list of available classes.

Do / Don’t#

Do

Don’t

Use samson.SBQuantity constructors for physical quantities.

Pass raw floats where the SAMSON API expects typed physical values.

Use physical vector types such as SBPosition3 for positions.

Mix incompatible physical meanings in the same vector or calculation.

Access explicit unit conversions, such as quantity.nm or quantity.angstrom, when you need numeric values.

Assume a displayed number has the unit you need without converting it.