User guide

This guide is for people who use a library that has been built with Coheriq and want to turn on an acceleration engine for it. You do not need to understand how the framework works internally to follow it.

Note

Activating an engine is done through Coheriq’s own enable_engine() function, passing the library itself and the engine you want. You do not need the library to expose anything special for this — the same call works for every Coheriq library. Consult your library’s documentation for the engine names available to it.

Install an engine

An acceleration engine is typically a separate Python package from the library it accelerates. Install it the same way you install any other dependency, for example:

pip install mylib-fast-engine

Installing the engine does not change the library’s behavior on its own. Nothing is accelerated until you explicitly enable the engine (or set the environment variable described below).

Query the available engines

Which engine names are available depends on what you have installed. available_engines() lists the ones you can pass to enable_engine():

>>> import coheriq
>>> import mylib
>>> coheriq.available_engines(mylib)
('reference', 'mylib-fast')

Every library has at least one entry: 'reference', its own implementation. In the current version of Coheriq it comes first and is the one you get if you enable nothing. Any other names are acceleration engines you have installed.

Asking this question does not activate anything, and it does not import the engine packages it names. An engine can advertise itself without having been imported yet, so a listed name means enable_engine() will try it, not that it is guaranteed to load.

Activate an engine

There are two ways to activate an engine. You must do so before the first use of any accelerated functionality; otherwise, the library’s reference implementation is used.

In Python code

Call enable_engine() once, at program startup, before calling anything else in the library. Pass the library itself and the engine name:

import coheriq
import mylib

coheriq.enable_engine(mylib, "fast-engine")

# From here on, all accelerated functions dispatch to the engine.
result = mylib.some_function(...)

Why pass the module?

A library’s domain is registered as a side effect of importing it, so Coheriq can only look up a library it has already seen. Passing the module makes that ordering impossible to get wrong: you cannot name mylib before importing it.

The library’s domain name is also accepted, and is equivalent as long as the import has already happened:

import mylib   # required first: this is what registers the domain

coheriq.enable_engine("mylib", "fast-engine")

Reach for the string form only where the module form is unavailable — for instance in a single file that defines a domain and enables an engine for it, since such a file cannot import itself.

Via an environment variable

If the library author has opted into it, you can select an engine without touching the code, by setting an environment variable. The exact variable name is chosen by the library (it is derived from a prefix the author configures); consult the library’s documentation for the precise name. For a library that uses the prefix MYLIB, the variable would be MYLIB_ENGINE:

MYLIB_ENGINE=fast-engine python my_script.py

This is convenient for switching engines between runs, or for enabling an engine on an HPC cluster without editing the program.

Precedence

If an engine is enabled explicitly in Python and an environment variable is also set, the explicit call wins. This lets a script pin a specific engine regardless of the surrounding environment.

Activation rules

Engine activation follows a small, strict contract. Keeping to it guarantees predictable behavior:

  • Enable before first use. Activation must happen before any accelerated function or class is used. Once the library has been used, the choice of implementation is locked in and can no longer be changed.

  • One engine at a time. A library can have at most one engine enabled.

  • Activation is one-way. You cannot switch to a different engine, nor disable an engine, later in the same process. To use a different engine, start a new process.

  • Re-enabling the same engine is fine. Calling enable_engine again with the engine that is already active does nothing and is not an error.

If you enable an engine name that does not exist, Coheriq raises CoheriqEngineNotFoundError.

Reporting issues

Because the accelerated code and the library are typically maintained separately, it is encouraged to report problems to the most appropriate place:

  • If a problem occurs with no engine enabled, it is a library issue — report it to the library’s issue tracker.

  • If a problem occurs only when a particular engine is enabled, report it to that engine’s issue tracker.