Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ShipSoft/FairShip/llms.txt
Use this file to discover all available pages before exploring further.
The shipunit module defines the physical unit system used throughout FairShip. It is derived from CLHEP’s SystemOfUnits.h and adapted for use with FairROOT. All quantities in FairShip geometry, energy, time, and momentum are expressed in these units. The two fundamental base units are centimeter (1.0, for length) and GeV (1.0, for energy); all other units are defined as dimensionless scale factors relative to those bases. To convert a value stored internally to a desired unit, divide by the unit constant — for example, length_cm = pos / u.cm.
import shipunit as u
# Construct physical quantities
mass = 1.0 * u.GeV # 1 GeV (internal: 1.0)
length = 50.0 * u.cm # 50 cm (internal: 50.0)
time = 100.0 * u.ns # 100 ns (internal: 100.0)
angle = 30.0 * u.degree # 30° in radians
# Convert back to human units by dividing
print(f"Mass in MeV: {mass / u.MeV:.1f}") # 1000.0
print(f"Length in mm: {length / u.mm:.1f}") # 500.0
print(f"Time in μs: {time / u.microsecond:.4f}")
print(f"Angle in mrad: {angle / u.mrad:.2f}")
# Speed of light and particle β·γ kinematics
p = 10.0 * u.GeV
m0 = 0.938 * u.GeV
E = (p**2 + m0**2) ** 0.5
print(f"c_light = {u.c_light / (u.m / u.s):.6e} m/s")
Length units
All length units are defined relative to the millimeter (millimeter = 0.1), making the centimeter the true internal base unit (centimeter = 1.0).
| Symbol | Full name | Value in internal units (cm) |
|---|
mm | millimeter | 0.1 |
cm | centimeter | 1.0 |
m | meter | 1 000 |
km | kilometer | 100 000 |
um | micrometer | 1 × 10⁻⁴ |
nm | nanometer | 1 × 10⁻⁷ |
angstrom | angstrom | 1 × 10⁻⁸ |
fermi | fermi | 1 × 10⁻¹³ |
pc | parsec | 3.0856775807 × 10¹⁸ |
mm2, mm3, cm2, cm3, m2, m3, km2, km3.
Cross-section units (area):
| Symbol | Full name | Value |
|---|
barn | barn | 1 × 10⁻²⁴ cm² |
millibarn | millibarn | 1 × 10⁻²⁷ cm² |
microbarn | microbarn | 1 × 10⁻³⁰ cm² |
nanobarn | nanobarn | 1 × 10⁻³³ cm² |
picobarn | picobarn | 1 × 10⁻³⁶ cm² |
Energy units
The base energy unit is the gigaelectronvolt (GeV = 1.0). The megaelectronvolt is defined as MeV = 1/1000.
| Symbol | Full name | Value in internal units (GeV) |
|---|
eV | electronvolt | 1 × 10⁻⁹ |
keV | kiloelectronvolt | 1 × 10⁻⁶ |
MeV | megaelectronvolt | 1 × 10⁻³ |
GeV | gigaelectronvolt | 1.0 |
TeV | teraelectronvolt | 1 × 10³ |
PeV | petaelectronvolt | 1 × 10⁶ |
joule | joule | eV / e_SI ≈ 6.2415 × 10¹² MeV |
Time units
The base time unit is the nanosecond (nanosecond = 1.0).
| Symbol | Full name | Value in internal units (ns) |
|---|
ns | nanosecond | 1.0 |
ms | millisecond | 1 × 10⁶ |
s | second | 1 × 10⁹ |
microsecond | microsecond | 1 × 10³ |
picosecond | picosecond | 1 × 10⁻³ |
hertz | hertz | 1 / second |
kilohertz | kilohertz | 1 × 10³ Hz |
megahertz | megahertz | 1 × 10⁶ Hz |
Angle units
| Symbol | Full name | Value |
|---|
rad | radian | 1.0 |
mrad | milliradian | 1 × 10⁻³ |
deg | degree | π / 180 |
sr | steradian | 1.0 |
Mass units
Mass is a derived unit: kilogram = joule · s² / m².
| Symbol | Full name | Value |
|---|
kg | kilogram | joule * second² / meter² |
g | gram | 1 × 10⁻³ kg |
mg | milligram | 1 × 10⁻⁶ kg |
Magnetic field units
FairROOT and Geant3 use kilogauss as the internal field unit (kilogauss = 1.0).
| Symbol | Full name | Value in internal units (kG) |
|---|
kilogauss | kilogauss | 1.0 |
tesla | tesla | 10.0 |
gauss | gauss | 1 × 10⁻⁴ |
Electric charge and potential
| Symbol | Full name | Notes |
|---|
eplus | positron charge | 1.0 (internal) |
e_SI | positron charge in Coulombs | 1.60217733 × 10⁻¹⁹ C |
coulomb | coulomb | eplus / e_SI |
volt | volt | 1 × 10⁻⁶ MV |
kilovolt | kilovolt | 1 × 10⁻³ MV |
megavolt | megavolt | MeV / eplus |
Pressure units
| Symbol | Full name | Notes |
|---|
pascal | pascal | newton / m² |
bar | bar | 1 × 10⁵ Pa |
atmosphere | atmosphere | 101 325 Pa |
Physical constants
The module also exports fundamental constants derived from the unit system.
| Constant | Description | Value |
|---|
pi | π | 3.14159265358979 |
twopi | 2π | 6.28318… |
halfpi | π/2 | 1.5707… |
c_light | Speed of light | 2.99792458 × 10⁸ m/s |
c_squared | c² | c_light² |
h_Planck | Planck constant | 6.6260755 × 10⁻³⁴ J·s |
hbar_Planck | ℏ | h_Planck / 2π |
hbarc | ℏ·c | 197.32705 × 10⁻¹² MeV·mm |
electron_mass_c2 | Electron mass | 0.51099906 MeV |
proton_mass_c2 | Proton mass | 938.27231 MeV |
neutron_mass_c2 | Neutron mass | 939.56563 MeV |
amu_c2 | Atomic mass unit | 931.49432 MeV |
Avogadro | Avogadro number | 6.0221367 × 10²³ /mol |
k_Boltzmann | Boltzmann constant | 8.617385 × 10⁻¹¹ MeV/K |
fine_structure_const | Fine structure constant α | elm_coupling / hbarc |
classic_electr_radius | Classical electron radius | elm_coupling / electron_mass_c2 |
speedOfLight | Speed of light (alias) | 299792458 m/s |
STP_Temperature | Standard temperature | 273.15 K |
STP_Pressure | Standard pressure | 1 atm |
universe_mean_density | Mean cosmic density | 1 × 10⁻²⁵ g/cm³ |
Miscellaneous fractional constants
import shipunit as u
u.perCent # 0.01
u.perThousand # 0.001
u.perMillion # 0.000001
Common patterns
import shipunit as u
# Detector geometry: magnet aperture
aperture = 2.5 * u.m # store in cm internally
# Momentum threshold cut
p_min = 1.0 * u.GeV # store in GeV internally
# Cross-section: express in pb
xs = 3.7e-8 * u.picobarn
# Density threshold for gas volumes
kGasThreshold = 10.0 * u.mg / u.cm3
# Convert: divide by the target unit
print(f"aperture = {aperture / u.cm:.1f} cm")
print(f"p_min = {p_min / u.MeV:.0f} MeV")