Error Model API

Functions

uint64_t selene_error_model_get_api_version(void)

The API version comprises four unsigned 8-bit integers:

  • reserved: 8 bits (must be 0)

  • major: 8 bits

  • minor: 8 bits

  • patch: 8 bits

Selene maintains its own API version for the error model and is updated upon changes to the API depending on how breaking the changes are. Selene is also responsible for validating the API version of the plugin against its own version.

The plans for this validation are a work-in-progress, but currently selene will reject any plugin that has a different major or minor version than the current Selene version, or with a reserved field that is not 0.

SeleneErrno selene_error_model_init(SeleneErrorModelInstance *instance, uint64_t n_qubits, uint32_t error_model_argc, const char *const *error_model_argv, const char *simulator_plugin, uint32_t simulator_argc, const char *const *simulator_argv)

When Selene is initialised, it is provided with some default arguments (the maximum number of qubits, the path to a simulator plugin to use, etc) and some custom arguments for the error model and simulator. These arguments are provided to the error model through this initialization function, with the custom arguments passed in in an argc, argv format.

It is this function’s responsibility to parse and validate those user-provided arguments and initialise a plugin instance ready for a call to selene_error_model_shot_start(). The instance pointer is designed to be set by this function and hold all relevant state, such that subsequent calls to the corresponding instance will be able to access that state, and such that calls to other instances will not be impacted.

Error model plugins should provide customisation of parameter values within their python implementations. They should also define how those parameters are converted to an argv list to be passed to their compiled counterparts.

SeleneErrno selene_error_model_exit(SeleneErrorModelInstance instance)

This function is called when Selene is exiting, and it is responsible for cleaning up any resources that the error model plugin has allocated.

SeleneErrno selene_error_model_shot_start(SeleneErrorModelInstance instance, uint64_t shot_id, uint64_t error_model_seed, uint64_t simulator_seed)

This function is called at the start of a shot, and it is responsible for initialising the error model plugin for that shot. The error_model_seed is provided for RNG seeding, and it is highly recommended that all randomness used by the error model plugin is seeded with this value.

As the error model currently owns the simulator, the simulator_seed is also provided to allow the error model to seed the simulator’s RNG. This should result in a call to the simulator’s shot_start function.

SeleneErrno selene_error_model_shot_end(SeleneErrorModelInstance instance)

This function is called at the end of a shot, and it is responsible for finalising the error model plugin for that shot. For example, it may clean up any intra-shot state, such as accumulators or buffers. A call to this function will usually be followed either by a call to selene_error_model_shot_start to prepare for the following shot, or by a call to selene_error_model_exit to shut down the instance.

SeleneErrno selene_error_model_handle_operations(SeleneErrorModelInstance instance, SeleneRuntimeExtractOperationInstance extract_ops_instance, const SeleneRuntimeExtractOperationInterface *extract_ops_interface, SeleneErrorModelSetResultInstance result_instance, const SeleneErrorModelSetResultInterface *result_interface)

This function is called to handle a batch of operations extracted from the runtime. It is responsible for processing the operations and returning the results of any measurements provided in the operation list.

As a batch of operations takes the form of a container, we provide extraction through a RuntimeExtractOperationInterface (essentially a list of function pointers) and a corresponding RuntimeExtractOperationInstance that provides the underlying state. See the documentation for [RuntimeExtractOperationInterface] and [RuntimeExtractOperationInstance] for more details.

Likewise, as the results of the operations are also in the form of a container, we provide an ErrorModelSetResultInterface that allows the error model to set the results of the measurements in the runtime.

SeleneErrno selene_error_model_dump_simulator_state(SeleneErrorModelInstance instance, const char *filename, const uint64_t *qubits, uint64_t qubits_length)

This function is called to dump the current state of the simulator to a file. This is niche functionality and any error model that ‘wraps’ the simulator state in a non-trivial manner (such that the underlying simulator state is not reflective of the state itself, e.g. in the case of leakage) should return an error from this function, as the simulator state is not meaningful in that case.

SeleneErrno selene_error_model_get_simulator_metrics(SeleneErrorModelInstance instance, uint8_t nth_metric, char *tag_ptr, uint8_t *datatype_ptr, uint64_t *data_ptr)

This is a passthrough function to the simulator’s get_metric function. The error model should invoke the simulator’s metric function directly unless it has reason to modify the output in some way.