# Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
#
# NOTICE TO USER:
#
# This source code and/or documentation (the "Licensed Materials") is
# the confidential and proprietary information of Karana Dynamics Inc.
# Use of these Licensed Materials is governed by the terms and conditions
# of a separate software license agreement between Karana Dynamics and the
# Licensee ("License Agreement"). Unless expressly permitted under that
# agreement, any reproduction, modification, distribution, or disclosure
# of the Licensed Materials, in whole or in part, to any third party
# without the prior written consent of Karana Dynamics is strictly prohibited.
#
# THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
# KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
# BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
# FITNESS FOR A PARTICULAR PURPOSE.
#
# IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
# INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
# ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
# OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
#
# U.S. Government End Users: The Licensed Materials are a "commercial item"
# as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
# only as a commercial end item under the terms of this license.
#
# Any use of the Licensed Materials in individual or commercial software must
# include, in the user documentation and internal source code comments,
# this Notice, Disclaimer, and U.S. Government Use Provision.
"""Simulation quantities and unit conversion tools.
This module contains common quantities used throughout simulations. It also contains
helper functions to convert a given quantity to the simulation's units. In addition,
it contains functions to define and set a units system. The default is SI.
"""
import numpy as np
import quantities as pq
from typing import Optional, Literal, overload
import numpy as np
from numpy.typing import NDArray
# This variables define the known quantities. If you add a new one, you must also add it to the
# _recalculateQuantities function so its value actually gets set.
length: pq.Quantity
mass: pq.Quantity
time: pq.Quantity
velocity: pq.Quantity
angular_velocity: pq.Quantity
acceleration: pq.Quantity
force: pq.Quantity
torque: pq.Quantity
inertia: pq.Quantity
gravitational_parameter: pq.Quantity
# Used internally to re-calculate quantities
def _recalculateQuantities():
global length, mass, time, velocity, angular_velocity, acceleration, force, torque, inertia, gravitational_parameter
length = pq.m.simplified.units
mass = pq.kg.simplified.units
time = pq.s.simplified.units
velocity = (pq.m / pq.s).simplified.units
angular_velocity = (pq.rad / pq.s).simplified.units
acceleration = (pq.m / pq.s**2).simplified.units
force = pq.N.simplified.units
torque = (pq.N * pq.m).simplified.units
inertia = (pq.kg * pq.m**2).simplified.units
gravitational_parameter = (pq.m**3 / pq.s**2).simplified.units
# Call this once to set the module variables
_recalculateQuantities()
[docs]
def setDefaultUnits(
system: Optional[Literal["si", "cgs"]] = None,
currency: Optional[pq.Quantity] = None,
current: Optional[pq.Quantity] = None,
information: Optional[pq.Quantity] = None,
length: Optional[pq.Quantity] = None,
luminous_intensity: Optional[pq.Quantity] = None,
mass: Optional[pq.Quantity] = None,
substance: Optional[pq.Quantity] = None,
temperature: Optional[pq.Quantity] = None,
time: Optional[pq.Quantity] = None,
):
"""Set the default units / units system.
Parameters
----------
system : Literal["si","cgs"]
Set the default units system. Other parameters will modify this system. If None, then si is used.
currency : Optional[Quantity]
Set the currency unit.
current : Optional[Quantity]
Set the current unit.
information : Optional[Quantity]
Set the information unit.
length : Optional[Quantity]
Set the length unit.
luminous_intensity : Optional[Quantity]
Set the luminous_intensity unit.
mass : Optional[Quantity]
Set the mass unit.
substance : Optional[Quantity]
Set the substance unit.
temperature : Optional[Quantity]
Set the temperature unit.
time : Optional[Quantity]
Set the time unit.
"""
pq.set_default_units(
system=system,
currency=currency,
current=current,
information=information,
length=length,
luminous_intensity=luminous_intensity,
mass=mass,
substance=substance,
temperature=temperature,
time=time,
)
# Recalculate the quantities in the new units system.
_recalculateQuantities()
[docs]
def isQuantity(v: pq.Quantity | NDArray, quantity: pq.Quantity):
"""Determine if the given value is one of the known quantities."""
if not isinstance(v, pq.Quantity):
raise ValueError("isQuantity got a non-quantity type.")
return np.all(v.simplified.units == quantity)
@overload
def convert(v: float) -> float: ...
@overload
def convert(v: NDArray) -> NDArray: ...
@overload
def convert(v: pq.Quantity) -> pq.Quantity: ...
[docs]
def convert(v: object) -> object:
"""Convert this quantity to the current units system."""
# If v is not a quantity, i.e., has no units, then there
# is no need to convert it.
if not isinstance(v, pq.Quantity):
return v
return v.simplified
