Getting Started
===============

Installation
------------

Install the package in your environment:

.. code-block:: bash

   pip install scuq

Command Line
------------

The package installs a small diagnostic command:

.. code-block:: bash

   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.

Quick Example
-------------

.. code-block:: python

   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.

.. code-block:: python

   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:

.. code-block:: python

   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.