`sillonpy` — logging API

The client you import inside a simulation script. See Logging runs for worked examples.

import sillonpy as sp

Opening a run

`sillonpy.api`

The API exposes the main tracking functions to the user.

These functions are loaded through the simplypy import. The user should not have access to the underlying data logging and server transmission logic. To achieve this, a unique Tracker object for each simulation run is maintained using a ContextVar. This shared context allows the API functions to access the tracker from anywhere in the user's codebase without passing it explicitly.

`track_run(**kwargs)`

Context manager that opens a run and finalizes it on exit.

Initializes the tracker on entry and flushes/closes it on exit (success or error), so multi-run scripts don't have to call force_dump() by hand:

with sp.track_run(run_name="sweep-1"):
    sp.log_param("lr", 0.01)
    ...
# run is sealed here

Parameters:

Name	Type	Description	Default
`**kwargs`		Forwarded to `init` (run_name, project_name, project_path, ...).	`{}`

Yields:

Name	Type	Description
`Tracker`		The active tracker for the run.

`init(run_name=None, organisation=None, author=None, project_name=None, project_path=None, inherit=None)`

Initializes the Tracker for the current script.

Instantiates a background tracker linked to a specific project and run name. If a context already exists, this function will safely do nothing.

Parameters:

Name	Type	Description	Default
`run_name`	`str`	The name of the specific simulation run. Defaults to None.	`None`
`organisation`	`str`	The name of the organization. Defaults to None.	`None`
`author`	`str`	The name of the person running the simulation. Defaults to None.	`None`
`project_name`	`str`	The project grouping this simulation belongs to. Defaults to None.	`None`
`project_path`	`str \| Path`	The absolute or relative path to the project root. Defaults to None.	`None`
`inherit`	`Run \| str`	A previous run this run derives from — a `sillonlab.Run` (loaded via `sillonlab`) or a run name/uuid in the same project. Only a lineage link is recorded (nothing is copied); walk back to the parent later via `run.parents` to read its parameters. The parent must already exist in the project.	`None`

`force_dump()`

Forces the immediate synchronization and closing of the current tracker.

This explicitly calls the close method on the context to flush all data to the background server and database, and resets the local ContextVar to None.

`track(func=None, *, save_result=False, run_name=None, organisation=None, author=None, project_name=None, project_path=None, inherit=None)`

Decorator to log function execution and optionally initialize the Tracker.

Automatically logs the function's arguments, keyword arguments, execution duration, and return value. It can be used with or without arguments (e.g., @track or @track(save_result=True)).

Parameters:

Name	Type	Description	Default
`func`	`callable`	The function being decorated.	`None`
`save_result`	`bool`	Whether to explicitly save the function's return value to the HDF5 glob. Defaults to False.	`False`
`run_name`	`str`	Optional initialization parameter.	`None`
`organisation`	`str`	Optional initialization parameter.	`None`
`author`	`str`	Optional initialization parameter.	`None`
`project_name`	`str`	Optional initialization parameter.	`None`
`project_path`	`str \| Path`	Optional initialization parameter.	`None`

Returns:

Name	Type	Description
`callable`		The wrapped function.

Logging values

`sillonpy.api`

The API exposes the main tracking functions to the user.

These functions are loaded through the simplypy import. The user should not have access to the underlying data logging and server transmission logic. To achieve this, a unique Tracker object for each simulation run is maintained using a ContextVar. This shared context allows the API functions to access the tracker from anywhere in the user's codebase without passing it explicitly.

`log_metadata = add_metadata` `module-attribute`

`log_param(key_or_dict=None, value=None, **kwargs)`

Logs parameters to the current simulation context.

Provides a highly flexible interface allowing users to pass parameters as a single key/value pair, a dictionary, or direct keyword arguments.

Parameters:

Name	Type	Description	Default
`key_or_dict`	`str \| dict`	The parameter key string, or a dictionary of parameters. Defaults to None.	`None`
`value`	`Any`	The parameter value if `key_or_dict` is a string. Defaults to None.	`None`
`**kwargs`		Additional parameters passed as keyword arguments.	`{}`

Raises:

Type	Description
`ValueError`	If a string key is provided without a value, or if no valid data is provided at all.

`log_result(id=None, value=None, path=None, save_result=True, **kwargs)`

Logs an output result, metric dictionary, or physical file artifact.

If save_result is True and a path is given, it copies the file to the artifact storage. If save_result is True for a dict or key/value pair, it adds the heavy data to the HDF5 glob. Both cases log a pointer in the database.

Parameters:

Name	Type	Description	Default
`id`	`str \| dict`	The identifier string, or a dictionary of results. Defaults to None.	`None`
`value`	`Any`	The data value to store. Defaults to None.	`None`
`path`	`str \| Path`	The file path to an artifact. Defaults to None.	`None`
`save_result`	`bool`	Whether to physically save the artifact/data or just log the pointer. Defaults to True.	`True`
`**kwargs`		Additional results passed as keyword arguments.	`{}`

Raises:

Type	Description
`ValueError`	If both a `value` and a `path` are provided simultaneously.
`ValueError`	If neither a value, path, dictionary, nor kwargs are provided.
`ValueError`	If the `id` format is inherently invalid.

`log_figure(figure=None, name=None, path=None, used=None, caption=None, **info)`

Logs a figure produced during the run, with its data provenance.

The figure is stored alongside the run (hashed, like an artifact) in a dedicated figure table. The used argument is the provenance link: list there the names of the parameters and results the figure was built from, so anyone exploring the run later can see exactly what data was used for what figure.

Example

fig, ax = plt.subplots()
ax.plot(super_param, coef)
sl.log_figure(fig, name="fit", used=["super_param", "coef"],
              caption="Linear fit of the polynomial")

Parameters:

Name	Type	Description	Default
`figure`	`Any`	A live figure object exposing `savefig` (matplotlib Figure) or `get_figure` (matplotlib Axes). Rendered to png automatically. Defaults to None.	`None`
`name`	`str`	The figure name. Defaults to the figure label, the file name, or an auto-numbered name.	`None`
`path`	`str \| Path`	The path of an already rendered figure file, as an alternative to `figure`. Defaults to None.	`None`
`used`	`str \| list`	The parameter/result names the figure was built from. Defaults to None.	`None`
`caption`	`str`	A short description of the figure.	`None`
`**info`		Any extra metadata to attach to the figure.	`{}`

Raises:

Type	Description
`ValueError`	If neither or both of `figure` and `path` are provided.

`add_metadata(key_or_dict=None, metadata=None)`

Logs custom user metadata to the simulation context.

Automatically prefixes all keys with sillon.user_metadata. so they can be cleanly segregated and retrieved later without overlapping with system keys.

Parameters:

Name	Type	Description	Default
`key_or_dict`	`str \| dict`	The metadata key string, or a dictionary of metadata. Defaults to None.	`None`
`metadata`	`Any`	The metadata value if `key_or_dict` is a string. Defaults to None.	`None`

Raises:

Type	Description
`ValueError`	If a string key is provided without a corresponding value.

`add_note(note)`

Appends a textual note (or list of notes) to the current simulation.

Parameters:

Name	Type	Description	Default
`note`	`str \| list[str]`	A single string note or a list of string notes.	required

Raises:

Type	Description
`ValueError`	If the provided note is not a string or a list of strings.

`add_tag(*tags)`

Append one or more tags to the current simulation.

sillonpy — logging API

Opening a run

sillonpy.api

track_run(**kwargs)

init(run_name=None, organisation=None, author=None, project_name=None, project_path=None, inherit=None)

force_dump()

track(func=None, *, save_result=False, run_name=None, organisation=None, author=None, project_name=None, project_path=None, inherit=None)

Logging values

sillonpy.api

log_metadata = add_metadata module-attribute

log_param(key_or_dict=None, value=None, **kwargs)

log_result(id=None, value=None, path=None, save_result=True, **kwargs)

log_figure(figure=None, name=None, path=None, used=None, caption=None, **info)

add_metadata(key_or_dict=None, metadata=None)

add_note(note)

add_tag(*tags)

`sillonpy` — logging API

`sillonpy.api`

`track_run(**kwargs)`

`init(run_name=None, organisation=None, author=None, project_name=None, project_path=None, inherit=None)`

`force_dump()`

`track(func=None, *, save_result=False, run_name=None, organisation=None, author=None, project_name=None, project_path=None, inherit=None)`

`sillonpy.api`

`log_metadata = add_metadata` `module-attribute`

`log_param(key_or_dict=None, value=None, **kwargs)`

`log_result(id=None, value=None, path=None, save_result=True, **kwargs)`

`log_figure(figure=None, name=None, path=None, used=None, caption=None, **info)`

`add_metadata(key_or_dict=None, metadata=None)`

`add_note(note)`

`add_tag(*tags)`