fram-core 0.0.0__py3-none-any.whl → 0.1.0__py3-none-any.whl

framcore/expressions/queries.py

@@ -0,0 +1,416 @@
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+import numpy as np
+from numpy.typing import NDArray
+
+from framcore import check_type
+from framcore.curves import Curve
+from framcore.expressions import Expr
+from framcore.expressions._get_constant_from_expr import _get_constant_from_expr
+from framcore.expressions._utils import _load_model_and_create_model_db
+from framcore.expressions.units import get_unit_conversion_factor
+from framcore.querydbs import QueryDB
+from framcore.timeindexes import FixedFrequencyTimeIndex, SinglePeriodTimeIndex, TimeIndex
+from framcore.timevectors import TimeVector
+
+if TYPE_CHECKING:
+    from framcore import Model
+
+
+def get_level_value(
+    expr: Expr,
+    db: QueryDB | Model,
+    unit: str | None,
+    data_dim: SinglePeriodTimeIndex,
+    scen_dim: FixedFrequencyTimeIndex,
+    is_max: bool,
+) -> float:
+    """
+    Evaluate Expr representing a (possibly aggregated) level.
+
+    The follwing will be automatically handled for you:
+    - fetching from different data objecs (from db)
+    - conversion to requested unit
+    - query at requested TimeIndex for data and scenario dimension, and with requested reference period
+    - conversion to requested level type (is_max or is_avg)
+
+    Supports all expressions. Will evaluate level Exprs at data_dim (with reference period of scen_dim),
+    and profile Exprs as an average over scen_dim (both as constants). Has optimized fastpath methods for sums, products and aggregations.
+    The rest uses a fallback method with SymPy.
+
+    """
+    check_type(expr, Expr)  # check expr here since _get_level_value is not recursively called.
+    check_type(unit, (str, type(None)))
+    check_type(data_dim, SinglePeriodTimeIndex)
+    check_type(scen_dim, FixedFrequencyTimeIndex)
+    check_type(is_max, bool)
+    db = _load_model_and_create_model_db(db)
+
+    return _get_level_value(expr, db, unit, data_dim, scen_dim, is_max)
+
+
+def get_profile_vector(
+    expr: Expr,
+    db: QueryDB | Model,
+    data_dim: SinglePeriodTimeIndex,
+    scen_dim: FixedFrequencyTimeIndex,
+    is_zero_one: bool,
+    is_float32: bool = True,
+) -> NDArray:
+    """
+    Evaluate expr representing a (possibly aggregated) profile.
+
+    expr = sum(weight[i] * profile[i]) where
+
+        weight[i] >= 0 and is unitless, and will be evaluated as a constant
+        profile[i] is a unitless profile expr
+
+        profile[i] is either "zero_one" or "mean_one" type of profile
+
+        "zero_one" and "mean_one" profile type must be converted to the
+        same standard to be added correctly.
+
+        The query parameters data_dim and scen_dim are used to evaluate the values
+        requested TimeIndex for data and scenario dimension, and with requested reference period
+
+        weight[i] will be evaluated level Exprs at data_dim (with reference period of scen_dim),
+        and profile Exprs as an average over scen_dim (both as constants)
+
+        profile[i] will be evaluated as profile vectors over scen_dim
+
+        The query parameter is_zero_one tells which profile type the output
+        vector should be converted to.
+    """
+    # Argument expr checked in _get_profile_vector since it can be recursively called.
+    check_type(data_dim, SinglePeriodTimeIndex)
+    check_type(scen_dim, FixedFrequencyTimeIndex)
+    check_type(is_zero_one, bool)
+    check_type(is_float32, bool)
+    db = _load_model_and_create_model_db(db)
+
+    return _get_profile_vector(expr, db, data_dim, scen_dim, is_zero_one, is_float32)
+
+
+def get_units_from_expr(db: QueryDB | Model, expr: Expr) -> set[str]:
+    """Find all units behind an expression. Useful for queries involving conversion factors."""
+    db = _load_model_and_create_model_db(db)
+
+    units: set[str] = set()
+
+    _recursively_update_units(units, db, expr)
+
+    return units
+
+
+def get_timeindexes_from_expr(db: QueryDB | Model, expr: Expr) -> set[TimeIndex]:
+    """
+    Find all timeindexes behind an expression.
+
+    Useful for optimized queries (not asking for more data than necessary).
+    """
+    db = _load_model_and_create_model_db(db)
+
+    timeindexes: set[TimeIndex] = set()
+
+    _recursively_update_timeindexes(timeindexes, db, expr)
+
+    return timeindexes
+
+
+def _get_level_value(
+    expr: Expr,
+    db: QueryDB,
+    unit: str | None,
+    data_dim: SinglePeriodTimeIndex,
+    scen_dim: FixedFrequencyTimeIndex,
+    is_max: bool,
+) -> float:
+    cache_key = ("_get_constant_from_expr", expr, unit, data_dim, scen_dim, is_max)
+    if db.has_key(cache_key):
+        return db.get(cache_key)
+    t0 = time.perf_counter()
+    output_value = _get_constant_from_expr(expr, db, unit, data_dim, scen_dim, is_max)
+    t1 = time.perf_counter()
+    db.put(cache_key, output_value, elapsed_seconds=t1 - t0)
+
+    return output_value
+
+
+def _get_profile_vector(
+    expr: Expr,
+    db: QueryDB,
+    data_dim: SinglePeriodTimeIndex,
+    scen_dim: FixedFrequencyTimeIndex,
+    is_zero_one: bool,
+    is_float32: bool = True,
+) -> NDArray:
+    check_type(expr, Expr)
+
+    if expr.is_leaf():
+        return _get_profile_vector_from_leaf_expr(expr, db, data_dim, scen_dim, is_zero_one, is_float32)
+
+    ops, args = expr.get_operations(expect_ops=True, copy_list=False)
+    tmp = np.zeros(scen_dim.get_num_periods(), dtype=np.float32 if is_float32 else np.float64)
+
+    if "+" in ops:
+        out = _get_profile_vector(args[0], db, data_dim, scen_dim, is_zero_one, is_float32)
+        for op, arg in zip(ops, args[1:], strict=True):
+            assert op == "+", f"{ops}  {args}"
+            tmp = _get_profile_vector(arg, db, data_dim, scen_dim, is_zero_one, is_float32)
+            np.add(out, tmp, out=out)
+        return out
+
+    if not all(op == "*" for op in ops):
+        message = f"Expected w1*w2*..*wn*profile. Got operations {ops} for expr {expr}"
+        raise ValueError(message)
+
+    profiles = [arg for arg in args if arg.is_profile()]
+    weights = [arg for arg in args if not arg.is_profile()]
+
+    if len(profiles) != 1:
+        message = f"Got {len(profiles)} profiles in expr {expr}"
+        raise ValueError(message)
+
+    total_weight = 0.0
+    is_max = False  # use avg-values to calculate weights
+
+    for weight_expr in weights:
+        total_weight += _get_constant_from_expr(weight_expr, db, None, data_dim, scen_dim, is_max)
+
+    out = _get_profile_vector(profiles[0], db, data_dim, scen_dim, is_zero_one, is_float32)
+    np.multiply(out, total_weight, out=out)
+    return out
+
+
+def _get_profile_vector_from_leaf_expr(
+    expr: Expr,
+    db: QueryDB,
+    data_dim: SinglePeriodTimeIndex,
+    scen_dim: FixedFrequencyTimeIndex,
+    is_zero_one: bool,
+    is_float32: bool,
+) -> NDArray:
+    src = expr.get_src()
+
+    if isinstance(src, str):
+        obj = db.get(src)
+    else:
+        obj = src
+
+    if isinstance(obj, Expr):
+        if not obj.is_profile():
+            msg = f"Expected {obj} to be is_profile=True."  # User may be getting this from setting wrong metadata in time vector files?
+            raise ValueError(msg)
+        return _get_profile_vector(obj, db, data_dim, scen_dim, is_zero_one, is_float32)
+
+    assert isinstance(obj, (TimeVector, Curve))
+
+    cache_key = ("_get_profile_vector_from_timevector", obj, data_dim, scen_dim, is_zero_one, is_float32)
+    if db.has_key(cache_key):
+        vector: NDArray = db.get(cache_key)
+        return vector.copy()
+    t0 = time.perf_counter()
+    vector = _get_profile_vector_from_timevector(obj, scen_dim, is_zero_one, is_float32)
+    t1 = time.perf_counter()
+    db.put(cache_key, vector, elapsed_seconds=t1 - t0)
+    return vector
+
+
+def _get_profile_vector_from_timevector(
+    timevector: TimeVector,
+    scen_dim: FixedFrequencyTimeIndex,
+    target_is_zero_one: bool,
+    is_float32: bool,
+) -> NDArray:
+    out = np.zeros(scen_dim.get_num_periods(), dtype=np.float32 if is_float32 else np.float64)
+
+    tv_is_zero_one = timevector.is_zero_one_profile()  # OPPGAVE endrer TimeVector-API
+    assert isinstance(tv_is_zero_one, bool)
+    assert isinstance(timevector.get_unit(), type(None))
+    values = timevector.get_vector(is_float32)
+    timeindex = timevector.get_timeindex()
+    timeindex.write_into_fixed_frequency(out, scen_dim, values)
+
+    # CASE HANDLED:
+    # Both profiles are mean one within their respective reference periods.
+    # We convert timevector ref period to target reference period by
+    # making sure the mean value of 'out' is 1 within the target reference period.
+    if not target_is_zero_one and not tv_is_zero_one:
+        target_ref_period = scen_dim.get_reference_period()
+        tv_ref_period = timevector.get_reference_period()
+        if target_ref_period != tv_ref_period:
+            tv_target_ref_period_mean = timeindex.get_period_average(
+                vector=values,
+                start_time=scen_dim.get_start_time(),
+                duration=scen_dim.get_period_duration() * scen_dim.get_num_periods(),
+                is_52_week_years=scen_dim.is_52_week_years(),
+            )
+
+            if tv_target_ref_period_mean == 0.0:
+                message = f"TimeVector {timevector} has invalid mean value of 0.0 for target reference period {target_ref_period}."
+                raise ValueError(message)
+
+            np.multiply(out, 1 / tv_target_ref_period_mean, out=out)
+
+    # TODO: Bør heller "ikke stole på"
+    if target_is_zero_one != tv_is_zero_one:
+        if target_is_zero_one:
+            np.multiply(out, 1 / out.max(), out=out)  # convert to zero one profile standard
+        elif not np.all(out == 0):
+            np.multiply(out, 1 / out.mean(), out=out)  # convert to mean one profile standard")
+
+    # TODO: handle different ref periods if is_avg
+    return out
+
+
+def _recursively_update_units(units: set[str], db: QueryDB, expr: Expr) -> None:
+    if expr.is_leaf():
+        src = expr.get_src()
+        obj = src if isinstance(src, TimeVector) else db.get(key=src)
+
+        if isinstance(obj, Expr):
+            _recursively_update_units(units, db, obj)
+        elif isinstance(obj, Curve):
+            message = "Not yet implemented for Curve objects."
+            raise NotImplementedError(message)
+        elif isinstance(obj, TimeVector):
+            unit = obj.get_unit()
+            if unit is not None:
+                units.add(unit)
+        else:
+            message = f"Got unexpected object {obj}."
+            raise RuntimeError(message)
+    __, args = expr.get_operations(expect_ops=False, copy_list=False)
+    for arg in args:
+        _recursively_update_units(units, db, arg)
+
+
+def _recursively_update_timeindexes(timeindexes: set[TimeIndex], db: QueryDB, expr: Expr) -> None:
+    if expr.is_leaf():
+        src = expr.get_src()
+        obj = src if isinstance(src, TimeVector) else db.get(key=src)
+        if isinstance(obj, Expr):
+            _recursively_update_timeindexes(timeindexes, db, obj)
+        elif isinstance(obj, Curve):
+            pass
+        elif isinstance(obj, TimeVector):
+            timeindex = obj.get_timeindex()
+            if timeindex is not None:
+                timeindexes.add(timeindex)
+        else:
+            message = f"Got unexpected object {obj}."
+            raise RuntimeError(message)
+    __, args = expr.get_operations(expect_ops=False, copy_list=False)
+    for arg in args:
+        _recursively_update_timeindexes(timeindexes, db, arg)
+
+
+def _get_level_value_from_timevector(  # noqa: C901
+    timevector: TimeVector,
+    db: QueryDB,
+    target_unit: str | None,
+    data_dim: SinglePeriodTimeIndex,
+    scen_dim: FixedFrequencyTimeIndex,
+    target_is_max: bool,
+    profile_expr: Expr | None,
+) -> float:
+    tv_is_max = timevector.is_max_level()  # OPPGAVE endrer TimeVector-API
+
+    is_float32 = True
+
+    values = timevector.get_vector(is_float32)  # OPPGAVE endrer TimeVector-API
+
+    # if DEFENSIVE_MODE:  # global i data-mng-modul
+    # assert isinstance(values, np.ndarray)
+    # assert len(values.shape) == 1
+
+    timeindex = timevector.get_timeindex()
+    from_unit = timevector.get_unit()
+
+    starttime = data_dim.get_start_time()  # OPPGAVE endrer ConstantTimeIndex-API?
+    timedelta = data_dim.get_period_duration()  # OPPGAVE endrer ConstantTimeIndex-API?
+    scalar = timeindex.get_period_average(values, starttime, timedelta, data_dim.is_52_week_years())
+
+    if from_unit is not None and target_unit is not None:
+        scalar *= get_unit_conversion_factor(from_unit, target_unit)
+    elif from_unit is None and target_unit is None:
+        pass
+    else:
+        message = "Mismatch between 'target_unit' 'from_unit'. One is None while the other is not."  # more descriptive?
+        raise ValueError(message)
+
+    if not target_is_max:
+        if not tv_is_max:  # from avg to avg
+            avg_level = scalar
+            tv_ref_period = timevector.get_reference_period()  # Vi lar ReferencePeriod være tidsindex som en lang periode
+            if tv_ref_period is None:
+                assert profile_expr is None, f"Timevector {timevector} has no reference period, profile_expr must therefore be None."
+                return avg_level  # avg level fra timevector uten ref periode
+            target_ref_period = scen_dim.get_reference_period()
+            if target_ref_period is None:
+                message = f"No reference period for scen_dim {scen_dim}"
+                raise ValueError(message)
+            if tv_ref_period != target_ref_period:
+                # if DEFENSIVE_MODE:
+                # tv_ref_period_mean = get_profile_vector(profile_expr, db, data_dim, tv_ref_period, is_float32, is_zero_one=False)
+                # assert tv_ref_period_mean.size == 1
+                # assert tv_ref_period_mean[0] == 1
+                assert profile_expr, f"Profile Expr is None for TimeVector {timevector} when it should exist"
+                tv_target_ref_period_mean = get_profile_vector(
+                    profile_expr,
+                    db,
+                    data_dim,
+                    scen_dim.copy_as_reference_period(target_ref_period),
+                    is_zero_one=False,
+                    is_float32=is_float32,
+                )
+                assert tv_target_ref_period_mean.size == 1
+                avg_level = tv_target_ref_period_mean[0] * avg_level
+            return avg_level
+        # timevector fra max til avg
+        max_level = scalar
+        assert timevector.get_reference_period() is None
+
+        zero_one_profile_vector_mean = 1
+        if profile_expr is not None:  # only try to get profile if the level is actually associated with one.
+            zero_one_profile_vector_mean = get_profile_vector(
+                profile_expr,
+                db,
+                data_dim,
+                scen_dim,
+                is_zero_one=True,
+                is_float32=is_float32,
+            ).mean()
+        return zero_one_profile_vector_mean * max_level
+
+    assert target_is_max  # vi skal ha max level
+
+    if not tv_is_max:
+        avg_level = scalar
+        tv_ref_period = timevector.get_reference_period()  # Vi lar ReferencePeriod være tidsindex som en lang periode
+        if tv_ref_period is None:
+            assert profile_expr is None, f"Timevector {timevector} has no reference period, profile_expr must therefore be None."
+            return avg_level
+        target_ref_period = scen_dim.get_reference_period()
+        if target_ref_period is None:
+            message = f"No reference period for scen_dim {scen_dim}"
+            raise ValueError(message)
+        if tv_ref_period != target_ref_period:
+            tv_target_ref_period_mean = get_profile_vector(
+                profile_expr,
+                db,
+                data_dim,
+                scen_dim.copy_as_reference_period(target_ref_period),
+                is_zero_one=False,
+                is_float32=is_float32,
+            )
+            assert tv_target_ref_period_mean.size == 1
+            avg_level = tv_target_ref_period_mean[0] * avg_level
+        # avg_level med korrekt ref periode
+        mean_one_profile_vector = get_profile_vector(profile_expr, db, data_dim, scen_dim, is_zero_one=False, is_float32=is_float32)
+        return mean_one_profile_vector.max() * avg_level
+
+    return scalar  # all good

framcore/expressions/units.py

@@ -0,0 +1,227 @@
+"""
+Define units used in the system, their handling and conversion rules.
+
+We use SymPy to support unit conversions. Already computed unit conversion factors are cached to minimize redundant calculations.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import re
+
+import sympy
+from sympy import Expr as SymPyExpr
+from sympy.core.power import Pow
+from sympy.core.symbol import Symbol
+from sympy.physics.units import Quantity, giga, gram, hour, kilo, mega, meter, second, tera, tonne, watt, year
+from sympy.physics.units.prefixes import Prefix
+
+EUR = Quantity("EUR", abbrev="€")
+
+_SUPPORTED_UNITS = {
+    "second": second,
+    "s": second,
+    "hour": hour,
+    "h": hour,
+    "year": year,
+    "y": year,
+    "watt": watt,
+    "g": gram,
+    "gram": gram,
+    "kg": kilo * gram,
+    "t": tonne,
+    "tonne": tonne,
+    "meter": meter,
+    "m": meter,
+    "m3": meter**3,
+    "Mm3": mega * meter**3,
+    "m3/s": meter**3 / second,
+    "kilo": kilo,
+    "mega": mega,
+    "giga": giga,
+    "tera": tera,
+    "kWh": kilo * watt * hour,
+    "MWh": mega * watt * hour,
+    "GWh": giga * watt * hour,
+    "TWh": tera * watt * hour,
+    "kW": kilo * watt,
+    "MW": mega * watt,
+    "GW": giga * watt,
+    "TW": tera * watt,
+    "EUR": EUR,
+    "€": EUR,
+}
+
+_FASTPATH_CONVERSION_FACTORS = {
+    ("MW", "GW"): 0.001,
+    ("MWh", "TWh"): 1e-6,
+    ("m3", "Mm3"): 1e-6,
+    ("kWh/m3", "GWh/Mm3"): 1.0,
+    ("EUR/MWh", "EUR/GWh"): 1000.0,
+    ("GWh/year", "MW"): 0.11407955544967756,
+    ("Mm3/year", "m3/s"): 0.03168876540268821,
+    ("t/MWh", "t/GWh"): 1000.0,
+}
+
+_FASTPATH_INCOMPATIBLE_CONVERSIONS = {
+    ("MW", "m3/s"),
+    ("m3/s", "MW"),
+    ("GWh", "Mm3"),
+    ("Mm3", "GWh"),
+}
+
+_DEBUG = False
+
+_COLLECT_FASTPATH_DATA = False
+_OBSERVED_UNIT_CONVERSIONS = set()
+
+
+def get_unit_conversion_factor(from_unit: str | None, to_unit: str | None) -> float:  # noqa C901
+    """Get the conversion factor from one unit to another."""
+    if from_unit == to_unit:
+        return 1.0
+
+    if from_unit is None or to_unit is None:
+        return _get_unit_conversion_factor_with_none(from_unit, to_unit)
+
+    fastpath = _fastpath_get_unit_conversion_factor(from_unit, to_unit)
+
+    if _DEBUG is False and fastpath is not None:
+        return fastpath
+
+    if fastpath is None:
+        has_multiplier = False
+        with contextlib.suppress(Exception):
+            ix = from_unit.index("*")
+            multiplier = float(from_unit[:ix])
+            base_from_unit = from_unit[ix + 1 :].strip()
+            has_multiplier = True
+
+        if has_multiplier:
+            fastpath = _fastpath_get_unit_conversion_factor(base_from_unit, to_unit)
+            fastpath = fastpath if fastpath is None else fastpath * multiplier
+            if _DEBUG is False and fastpath is not None:
+                return fastpath
+
+    if _COLLECT_FASTPATH_DATA and fastpath is None:
+        if has_multiplier:
+            _OBSERVED_UNIT_CONVERSIONS.add((base_from_unit, to_unit))
+        else:
+            _OBSERVED_UNIT_CONVERSIONS.add((from_unit, to_unit))
+
+    fallback = _fallback_get_unit_conversion_factor(from_unit, to_unit)
+
+    if _DEBUG and fastpath is not None and fallback != fastpath:
+        message = f"Different results!\nfrom_unit {from_unit} to_unit {to_unit}\nfastpath {fastpath} fallback {fallback}"
+        raise RuntimeError(message)
+
+    if _unit_has_no_floats(from_unit) and _unit_has_no_floats(to_unit):
+        _FASTPATH_CONVERSION_FACTORS[(from_unit, to_unit)] = fallback
+
+    return fallback
+
+
+def _get_unit_conversion_factor_with_none(from_unit: str | None, to_unit: str | None) -> float:
+    if from_unit:
+        try:
+            return get_unit_conversion_factor(from_unit, "1")
+        except Exception:
+            pass
+    if to_unit:
+        try:
+            return get_unit_conversion_factor("1", to_unit)
+        except Exception:
+            pass
+    message = f"Incompatible units: from_unit {from_unit} to_unit {to_unit}"
+    raise ValueError(message)
+
+
+def _unit_has_no_floats(unit: str) -> bool:
+    if not unit:
+        return True
+    floats_in_str = re.findall(r"[-+]?(?:\d*\.*\d+)", unit)
+    if not floats_in_str:
+        return True
+    floats_in_str: list[float] = [float(x) for x in floats_in_str]
+    return all(x.is_integer() for x in floats_in_str)
+
+
+def validate_unit_conversion_fastpaths() -> bool:
+    """Run-Time validation of fastpaths."""
+    errors = []
+    for (from_unit, to_unit), result in _FASTPATH_CONVERSION_FACTORS.items():
+        sympy_result = None
+        with contextlib.suppress(Exception):
+            sympy_result = _fallback_get_unit_conversion_factor(from_unit, to_unit)
+        if result != sympy_result:
+            message = f"'{from_unit}' to '{to_unit}' failed. Fastpath: {result}, SymPy: {sympy_result}"
+            errors.append(message)
+    for from_unit, to_unit in _FASTPATH_INCOMPATIBLE_CONVERSIONS:
+        with contextlib.suppress(Exception):
+            sympy_result = _fallback_get_unit_conversion_factor(from_unit, to_unit)
+            message = f"'{from_unit}' to '{to_unit}'. Fastpath claim incompatible units, but SymPy fallback returned {sympy_result}"
+            errors.append(message)
+    if errors:
+        message = "\n".join(errors)
+        raise RuntimeError(message)
+
+
+def _fastpath_get_unit_conversion_factor(from_unit: str, to_unit: str) -> float | None:
+    """Try to look up the result."""
+    key = (from_unit, to_unit)
+    if key in _FASTPATH_CONVERSION_FACTORS:
+        return _FASTPATH_CONVERSION_FACTORS[key]
+    if key in _FASTPATH_INCOMPATIBLE_CONVERSIONS:
+        message = f"Cannot convert from '{from_unit}' to '{to_unit}'"
+        raise ValueError(message)
+    return None
+
+
+def _fallback_get_unit_conversion_factor(from_unit: str, to_unit: str) -> float | str:
+    """Calculate conversion factor using sympy."""
+    from_unit_sym = _unit_str_to_sym(from_unit)
+    to_unit_sym = _unit_str_to_sym(to_unit)
+
+    conversion_expr = from_unit_sym / to_unit_sym
+
+    value = _get_scalar_from_expr(conversion_expr)
+
+    if not isinstance(value, float):
+        s = f"Incompatible units in expression: {conversion_expr}\nSimplified: {value}"
+        message = f"Cannot convert from '{from_unit}' to '{to_unit}':\n{s}"
+        raise ValueError(message)
+
+    return value
+
+
+def _unit_str_to_sym(unit: str) -> SymPyExpr:
+    """Convert str unit to valid sympy representation or error."""
+    unit = unit.strip()
+    x = sympy.sympify(unit, locals=_SUPPORTED_UNITS)
+    unsupported_args = [arg for arg in x.args if not (isinstance(arg, Prefix | Quantity | Pow | Symbol) or arg.is_number)]
+    if unsupported_args:
+        message = f"Unit string '{unit}' not valid. Unsupported args: {unsupported_args}"
+        raise ValueError(message)
+    return x
+
+
+def _get_scalar_from_expr(expr_sym: SymPyExpr) -> float | str:
+    """Get scalar value from a sympy expression."""
+    simplified_expr = expr_sym.simplify()
+    if not simplified_expr.is_number:
+        for prefix in _SUPPORTED_UNITS.values():
+            if isinstance(prefix, Prefix):
+                expr_sym = expr_sym.subs(prefix, prefix.scale_factor)
+        simplified_expr = expr_sym.simplify()
+    try:
+        return float(simplified_expr)
+    except Exception:
+        return str(simplified_expr)
+
+
+def is_convertable(unit_from: str, unit_to: str) -> bool:
+    """Return True if from_unit can be converted to to_unit else False."""
+    with contextlib.suppress(Exception):
+        get_unit_conversion_factor(unit_from, unit_to)
+        return True
+    return False

framcore/fingerprints/__init__.py

@@ -0,0 +1,11 @@
+# framcore/fingerprints/__init__.py
+
+from framcore.fingerprints.fingerprint import Fingerprint, FingerprintDiff, FingerprintDiffType, FingerprintRef
+
+__all__ = [
+    "Fingerprint",
+    "FingerprintDiff",
+    "FingerprintDiffType",
+    "FingerprintRef",
+]
+