solprop.backends.numba_cpu.pass_timers#

Opt-in wall-clock timers for the passes of a free-space evaluation (SEP 28 phase 0).

A measurement aid, not a profiler: the backend reads ENVIRONMENT once, at construction, and holds a PassTimers only when it is set to 1. Otherwise it holds None, and each instrumented pass costs one comparison with None – no clock read, no call, no allocation – so a run without the switch takes the same path as before it existed.

Each instrumented function keeps its own mark, a clock reading, and laps it after every pass:

mark = timers.now()
...  # the pass
mark = timers.lap("free.pack", mark)

so that timed functions nest: a caller’s lap around a timed callee includes the callee’s own laps. Every pass the backend times is synchronous on the host (FFTW’s threaded execution and Numba’s parallel loops return when their work is done), so a lap is that pass’s wall time. The names the backend records are listed in the SEP 28 phase 0 report.

Module Attributes

ENVIRONMENT

The environment variable that enables the timers: 1 on, unset or 0 off.

Functions

timers_from_environment([environ])

Return a PassTimers if ENVIRONMENT asks for one.

Classes

`PassTimers`([clock])	Accumulate wall time and call counts per named pass.
`PassTotal`(calls, seconds)	The accumulated wall time of one named pass.

solprop.backends.numba_cpu.pass_timers.ENVIRONMENT = 'SOLPROP_PASS_TIMERS'#: The environment variable that enables the timers: 1 on, unset or 0 off.

class solprop.backends.numba_cpu.pass_timers.PassTimers(clock=<built-in function perf_counter>)[source]#

Bases: object

Accumulate wall time and call counts per named pass.

Parameters:

clockcallable, optional: A monotonic clock in seconds; time.perf_counter() by default.

Examples

>>> ticks = iter([0.0, 0.5, 2.0])
>>> timers = PassTimers(clock=lambda: next(ticks))
>>> mark = timers.now()
>>> mark = timers.lap("pack", mark)
>>> mark = timers.lap("to_time", mark)
>>> timers.snapshot()["to_time"]
PassTotal(calls=1, seconds=1.5)

lap(name, mark)[source]#

Charge the time since mark to name, and return the new mark.

Parameters:

namestr: The pass, for example "free.to_time".
markfloat: The clock’s reading when the pass began, s.

Returns:

float: The clock’s reading now, s: the next pass’s mark.

now()[source]#

Return the clock’s reading, s, to start a sequence of laps.

Returns:

float: The clock’s reading, s.

reset()[source]#

Forget every pass recorded so far, to start a timed window.

snapshot()[source]#

Return the passes recorded since the last reset().

Returns:

dict of str to PassTotal: Each pass’s calls and total wall time, sorted by name.

class solprop.backends.numba_cpu.pass_timers.PassTotal(calls, seconds)[source]#

Bases: object

The accumulated wall time of one named pass.

Attributes:

callsint: How many times the pass ran.
secondsfloat: Its total wall time, s.

calls: int#

seconds: float#

solprop.backends.numba_cpu.pass_timers.timers_from_environment(environ=environ({'ASDF_CONFIG_FILE': '/home/docs/.asdfrc', 'ASDF_DATA_DIR': '/home/docs/.asdf', 'ASDF_DEFAULT_TOOL_VERSIONS_FILENAME': '.tool-versions', 'ASDF_DIR': '/home/docs/.asdf', 'DEBIAN_FRONTEND': 'noninteractive', 'HOME': '/home/docs', 'HOSTNAME': '3732187e1c14', 'LANG': 'C.UTF-8', 'NO_COLOR': '1', 'PATH': '/home/docs/checkouts/solprop/envs/24/bin:/home/docs/.asdf/installs/uv/0.13.5/bin:/home/docs/checkouts/solprop/envs/24/bin:/home/docs/.asdf/shims:/home/docs/.asdf/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', 'PWD': '/home/docs/checkouts/solprop/checkouts/24', 'READTHEDOCS': 'True', 'READTHEDOCS_CANONICAL_URL': 'https://solprop--24.org.readthedocs.build/en/24/', 'READTHEDOCS_GIT_CLONE_URL': 'https://github.com/LupoLab/solprop.git', 'READTHEDOCS_GIT_COMMIT_HASH': '938cb81bb3ad625dff99b2cd16cf1783b5024138', 'READTHEDOCS_GIT_IDENTIFIER': '24', 'READTHEDOCS_LANGUAGE': 'en', 'READTHEDOCS_OUTPUT': '/home/docs/checkouts/solprop/checkouts/24/_readthedocs/', 'READTHEDOCS_PRODUCTION_DOMAIN': 'app.readthedocs.org', 'READTHEDOCS_PROJECT': 'solprop', 'READTHEDOCS_REPOSITORY_PATH': '/home/docs/checkouts/solprop/checkouts/24', 'READTHEDOCS_VERSION': '24', 'READTHEDOCS_VERSION_NAME': '24', 'READTHEDOCS_VERSION_TYPE': 'external', 'READTHEDOCS_VIRTUALENV_PATH': '/home/docs/checkouts/solprop/envs/24', 'SHLVL': '0', 'UV': '/home/docs/.asdf/installs/uv/0.13.5/bin/uv', 'UV_PROJECT_ENVIRONMENT': '/home/docs/checkouts/solprop/envs/24', 'UV_RUN_RECURSION_DEPTH': '1', 'VIRTUAL_ENV': '/home/docs/checkouts/solprop/envs/24', 'DOCUTILSCONFIG': '/home/docs/checkouts/solprop/checkouts/24/docs/docutils.conf', 'MLX_ENABLE_TF32': '0', 'KMP_DUPLICATE_LIB_OK': 'True'}))[source]#

Return a PassTimers if ENVIRONMENT asks for one.

Parameters:

environmapping of str to str, optional: The environment, os.environ by default.

Returns:

PassTimers or None: Timers when the variable is 1; None when it is unset, empty or 0.

Raises:

BackendError: If the variable holds anything else.

Examples

>>> timers_from_environment({}) is None
True
>>> isinstance(timers_from_environment({ENVIRONMENT: "1"}), PassTimers)
True