Get started¶

Setup¶

Install the library using the pip command for the latest release:

pip install dccQuantities

Once installed, most common classes can be directly imported from the package.

from dcc_quantities import DccQuantityType

Quick Use¶

Working with single Quantities¶

For a quick use, this documentation considers only dccQuantities that have an array of one single value as the quantity data.

A quantity can be initialized as an DccQuantityType with the method .from_single_quantity_value().

from dcc_quantities import DccQuantityType

m = DccQuantityType.from_single_quantity_value(
    name="Distance", value=15.0, uncertainty=0.01, unit="\\metre", label="d"
)

Once the instance is initialized, mathematical operations can be performed to create new quantities.

from dcc_quantities import DccQuantityType

s = DccQuantityType.from_single_quantity_value(
    name="Time", value=2.3, uncertainty=0.01, unit="\\second", label="t"
)
velocity = m / s
velocity.set_label("V")
print(velocity)  # V: [6.521739130434783 ± 0.028686784296913147] \metre\per\second

See Math Operations for more information about performing math with quantities.

Extracting tables from XML files¶

The most common use for dccQuantities is to extract data from XML files. For this purpose, the library offers the function extract_dcc_elements, which returns all available tables in the XML.

from dcc_quantities import extract_dcc_elements

# Extracting all tables from the file:
listed_dcc_table_data: list[dict] = extract_dcc_elements("path/to/dcc_file.xml")

Now listed_dcc_table_data is a list where each item is a DccTable as a dictionary. Each item can be initialized into a DccQuantityTable with the from_dcc_data classmethod.

from dcc_quantities import DccQuantityTable

listed_dcc_table_data: list[dict]
table = DccQuantityTable.from_dcc_data(listed_dcc_table_data[0])

This classmethod will return either a DccFlatTable or a DccLongTable instance, depending on the refTypes and Attributes coded into the table data.

For more examples onto how to work over tables, see Operate with DccTables.

Math operations¶

Each DccQuantityType instance allows some basic math operations, returning a new instance with the new D-SI unit. These equations are:

• Addition a + b: Both quantities 'a' and 'b' must have the same D-SI unit.
• Subtraction a - b: Both quantities 'a' and 'b' must have the same D-SI unit.
• Multiplication a * b
• Division a / b
• Power operator a ** N: 'N' must be either a number or an adimensional quantity.

Additional math functions are available in the dcc_math module, importable also from the root package.

from dcc_quantities import dcc_math

This module allows more complex functions, as dcc_math.sqrt(), and trigonometric functions, as dcc_math.sin(), to be performed directly over DccQuantities.

Mathematical functions also consider the units and modify them if required. For example:

• Any direct trigonometric function (sin, cos, tan, etc.) will work only on angles¹ or adimensional units².
• Inverse trigonometric functions can be used only over adimensional units² and will return the result with \radian as D-SI unit.
• The function sqrt() will modify the units to the corresponding one, e.g. \metre\tothe{2} is converted to \metre.