Getting Started

Installation

scuq requires Python 3.8 or newer. Install the package from PyPI in an activated virtual environment:

python -m pip install scuq

Alternatively, install directly from GitLab:

python -m pip install git+https://gitlab.hrz.tu-chemnitz.de/chair-of-electromagnetic-theory-and-compatibility-at-tu-dresden/mpylab/scuq.git

This requires git to be installed. A branch or tag can be selected by appending it to the URL, for example @main or @v1.0.5.

Command Line

The package installs a small diagnostic command:

scuq-info

It prints the installed scuq version, Python and NumPy versions, the package path, the current strict-mode setting, and a few quick smoke-check results. Use scuq-info --json for machine-readable output and scuq-info --help for usage and available options. Save a report with:

scuq-info --json > scuq-info.json

Quick Example

from scuq.quantities import Quantity
from scuq.si import VOLT

u = Quantity(VOLT, 2)
print(u)  # 2 V

Strict Mode

scuq has a global strict mode for operations that require comparable units, such as addition, subtraction, comparisons, and get_value(unit). Strict mode is enabled by default. In strict mode, units must be exactly equal; compatible units such as volt and millivolt are not converted automatically.

from scuq.quantities import Quantity, set_strict
from scuq.si import VOLT
from scuq.units import AlternateUnit

mV = AlternateUnit("mV", VOLT / 1000)

set_strict(True)
Quantity(VOLT, 2) + Quantity(VOLT, 3)   # ok
Quantity(VOLT, 2) + Quantity(mV, 500)   # raises ConversionException

Disable strict mode when automatic conversion between compatible units is desired:

set_strict(False)

result = Quantity(VOLT, 2) + Quantity(mV, 500)
print(result)  # 2.5 V

The result is expressed in the unit of the left operand. reduce_to() always performs a requested compatible conversion, independently of strict mode.

Interactive Cheat Sheet

The repository contains a Marimo cheat sheet with executable examples of strict mode, correlations, probability distributions, and export into tabular value/uncertainty/unit columns. In a virtual environment using Python 3.10 or newer, clone the repository and install its optional notebook dependencies:

git clone https://gitlab.hrz.tu-chemnitz.de/chair-of-electromagnetic-theory-and-compatibility-at-tu-dresden/mpylab/scuq.git
cd scuq
python -m pip install ".[notebook]"
marimo run marimo/cheat-sheet.py

The notebook extra requires Python 3.10 or newer because its Marimo dependency no longer supports older interpreters. It remains separate from scuq’s runtime dependencies and does not change the package’s Python 3.8 minimum.

A Jupyter version is available in notebook/cheat-sheet.ipynb. Additional scripts live in Examples/. See Examples for worked calculations and API Reference for the complete reference.