Skip to content

Utils API Reference

quicksum

Efficiently sum an iterable of expressions, variables, and floats.

This function provides an optimized way to sum multiple expressions or variables, which is more efficient than using repeated addition.

Parameters:

  • iterable (Iterable) –

    An iterable containing Expression, Variable, and/or float objects.

  • start (Expression or Variable, default: None ) –

    Optional starting value for the sum.

Returns:

  • Expression –

    An expression representing the sum.

Examples:

Sum a list of variables:

>>> from luna_model import Environment, Variable
>>> from luna_model.utils import quicksum
>>> with Environment():
...     vars = [Variable(f"x{i}") for i in range(10)]
>>> expr = quicksum(vars)
>>> print(expr)
x0 + x1 + x2 + x3 + x4 + x5 + x6 + x7 + x8 + x9

Sum with coefficients:

>>> coeffs = [1, 2, 3, 4, 5]
>>> terms = [c * v for c, v in zip(coeffs, vars[:5])]
>>> expr = quicksum(terms)
>>> print(expr)
x0 + 2 x1 + 3 x2 + 4 x3 + 5 x4
Notes

This is significantly faster than using sum() or repeated + operations for large numbers of terms.

Timer

Timer for measuring execution time, with named sub-intervals.

Examples:

>>> from luna_model.timer import Timer
>>> t = Timer.start()
>>> preprocessing = t.record("preprocessing")
>>> # ... perform preprocessing ...
>>> _ = preprocessing.stop()
>>> qpu = t.record("qpu")
>>> # ... call the QPU ...
>>> _ = qpu.stop()
>>> timing = t.stop()
>>> print(f"Elapsed: {timing.total} seconds")
Elapsed: ... seconds

start() -> Timer classmethod

Start a new timer.

Returns:

  • Timer –

    A running timer instance.

record(timing: str) -> SubTimer

Start a named sub-timer.

Parameters:

  • timing (str) –

    The name under which the elapsed time will be recorded once the returned sub-timer is stopped.

Returns:

  • SubTimer –

    A running sub-timer; call .stop() on it to record it.

stop() -> Timing

Stop the timer and return timing information.

Returns:

  • Timing –

    The timing information for the measured interval, including any named sub-timings recorded along the way.

Timing

Timing information recorded by a Timer.

Holds the overall elapsed time plus any named sub-timings recorded via Timer.record().

start: datetime | None property

Get the start time.

end: datetime | None property

Get the end time.

total: float property

Get the overall elapsed time in seconds.

total_seconds: float property

Get the overall elapsed time in seconds.

__init__(total: float | None = None) -> None

Create a Timing.

Parameters:

  • total (float, default: None ) –

    The overall elapsed time in seconds. Defaults to 0.0.

from_dict(timings: dict[str, float | list[float]] | dict[str, float] | dict[str, list[float]], total: float | None = None) -> Timing classmethod

Create a Timing from a dict of named sub-timings.

Parameters:

  • timings (dict[str, float | list[float]]) –

    Sub-timing values keyed by name. Each value is either a single elapsed time in seconds or a list of elapsed times (e.g. from repeated calls to Timer.record() under the same name).

  • total (float, default: None ) –

    The overall elapsed time in seconds. Defaults to the sum of all values in timings.

__getattr__(name: str) -> float | None

Get the total elapsed time for a named sub-timing, pandas-column-style.

Falls back to total_for(name) for any attribute not otherwise defined on Timing, so e.g. timing.qpu is equivalent to timing.total_for("qpu"). Only invoked when normal attribute lookup fails, so it never shadows total, get, etc.

__setattr__(name: str, value: float) -> None

Set a named sub-timing via attribute access, pandas-column-style.

Falls back to self[name] = value for any attribute not already defined on Timing (e.g. _t, total, get), so e.g. timing.qpu = 1.0 is equivalent to timing["qpu"] = 1.0.

get(key: str) -> list[float]

Get the recorded values for a named sub-timing.

Parameters:

  • key (str) –

    The sub-timing name.

Returns:

  • list[float] –

    The recorded elapsed times, in seconds. Empty if key was never recorded.

total_for(key: str) -> float | None

Get the total elapsed time for a named sub-timing.

Parameters:

  • key (str) –

    The sub-timing name.

Returns:

  • float or None –

    The sum of the recorded values for key, in seconds, or None if key was never recorded.

__setitem__(key: str, value: float) -> None

Overwrite the recorded values for a named sub-timing.

Parameters:

  • key (str) –

    The sub-timing name.

  • value (float) –

    The single value to record for key, replacing any previously recorded values.

__getitem__(key: str) -> float

Get the total elapsed time for a named sub-timing.

Equivalent to total_for(key), but returns 0.0 instead of None when key was never recorded, so timing[key] += value works directly.

Parameters:

  • key (str) –

    The sub-timing name.

Returns:

  • float –

    The sum of the recorded values for key, in seconds, or 0.0 if key was never recorded.

__eq__(other: object) -> bool

Check equality with another Timing by total and recorded values.

__str__() -> str

Return a human-readable string representation.

__repr__() -> str

Return a string representation for debugging.