Metadata-Version: 2.4
Name: selene-core
Version: 0.3.0a2
Summary: The core interop library for Selene python interfaces
Project-URL: homepage, https://github.com/quantinuum/selene/selene-core
Project-URL: repository, https://github.com/quantinuum/selene/selene-core
License-Expression: Apache-2.0
Requires-Python: >=3.10
Requires-Dist: hugr>=0.13.0
Requires-Dist: lief>=0.16.5
Requires-Dist: llvmlite==0.45.1; sys_platform == 'darwin' and platform_machine == 'x86_64'
Requires-Dist: llvmlite~=0.47; sys_platform != 'darwin' or platform_machine != 'x86_64'
Requires-Dist: networkx<4,>=2.6
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pydot>=4.0.0
Requires-Dist: pyyaml~=6.0
Requires-Dist: typing-extensions>=4
Requires-Dist: ziglang~=0.13
Description-Content-Type: text/markdown

# Selene-Core

Selene is designed to be extensible through the use of plugins, in the form
of compiled libraries and lightweight python interfaces that provide configuration
for the selene-sim frontend. We achieve this through this selene-core crate and
python module.

Each plugin should comprise a python component and a compiled library component.
The compiled library implements the Selene plugin API, and the python component
provides configuration, link information and the path to the compiled library to
the selene frontend.

The selene-core python module provides interfaces for plugins to adhere to. It also
provides a bundled include directory, containing C headers for the Selene plugin API
for each type of component.

To access the C headers in the build stage of a python package, depend on selene-core
as a build dependency and call `selene_core.get_include_directory()`. The resulting
path can be provided to a build system for C or C++ and the plugin APIs can be included
through:
```c
#include <selene/simulator.h>   # for the simulator API
#include <selene/error_model.h> # for the error model API
#include <selene/runtime.h>     # for the runtime API
```

Each header defines a descriptor structure and a packed current-version constant:

- `SELENE_SIMULATOR_CURRENT_API_VERSION`
- `SELENE_ERROR_MODEL_CURRENT_API_VERSION`
- `SELENE_RUNTIME_CURRENT_API_VERSION`

Populate `struct_size` with `sizeof` the descriptor, use the corresponding version
constant for `api_version`, and populate every function pointer that is not documented
as optional. A plugin must export either the descriptor symbol documented in its header
or, preferably, the accessor function. For example, a simulator plugin should export:

```c
static const SeleneSimulatorPluginDescriptorV1 descriptor = {
    .struct_size = sizeof(SeleneSimulatorPluginDescriptorV1),
    .api_version = SELENE_SIMULATOR_CURRENT_API_VERSION,
    /* function pointers */
};

const SeleneSimulatorPluginDescriptorV1 *
selene_simulator_get_plugin_descriptor_v1(void) {
    return &descriptor;
}
```

The equivalent runtime and error-model accessor names are declared in their respective
headers.
