sillonlab — analysis API

Load projects and explore their runs from a script or a notebook. See Querying and analysis for worked examples.

import sillonlab as sl

Finding and loading projects

sillonlab.projects

Machine-wide project discovery — the notebook counterpart of sillon projects.

project.py is about one loaded project; this module is about finding which projects exist on this machine in the first place, so you can open one without remembering where you put it.

Both this and the CLI read the same records from silloncore.projects, so they never disagree.

list_projects(with_stats=True, include_missing=True)

Every sillon project registered on this machine.

Example

import sillonlab as sl

for p in sl.list_projects():
    print(p["project_name"], p["run_count"], p["project_path"])

Parameters:

Name	Type	Description	Default
with_stats	bool	Include run_count and last_activity, which means opening each project's database. False for a fast listing.	True
include_missing	bool	Keep projects whose directory is gone, flagged exists=False, rather than hiding them — an unmounted drive should look different from a project you never had.	True

Returns:

Type	Description
list	list[dict]: project_name, project_path, project_storage, exists, and when with_stats, run_count, last_activity, readable.

open_project(name_or_path)

Load a project by its registered name instead of by path.

Accepts a project name (case-insensitive; a unique prefix is enough) or a path, so the output of list_projects can be used directly.

Example

project = sl.open_project("Shaking Lattice")

Parameters:

Name	Type	Description	Default
name_or_path	str	A registered project name, or a path.	required

Raises:

Type	Description
LookupError	If nothing matches, or if a name prefix is ambiguous.

Returns:

Name	Type	Description
Project	Project	The loaded project.

sillonlab

sillonlab: the analysis library of the sillon toolchain.

Load a sillon project from a python script or a jupyter notebook and explore its logged runs, the same way silloncli does from the shell.

Example

import sillonlab as sl

project = sl.load_project("path/to/project")
print(project.runs().list())

run = project.get("my_run")
print(run.parameters)
data = run.load_result("coef")

load_project(project_path=None)

Loads a sillon project from a path (defaults to the current directory).

Parameters:

Name	Type	Description	Default
project_path	str | Path	The project root containing the .sillon directory.	None

Returns:

Name	Type	Description
Project	Project	The loaded project.

Project

sillonlab

sillonlab: the analysis library of the sillon toolchain.

Load a sillon project from a python script or a jupyter notebook and explore its logged runs, the same way silloncli does from the shell.

Example

import sillonlab as sl

project = sl.load_project("path/to/project")
print(project.runs().list())

run = project.get("my_run")
print(run.parameters)
data = run.load_result("coef")

Project

The entry point of sillonlab: a loaded sillon project.

Wraps the silloncore engine so logged runs can be explored from a python script or a jupyter notebook, the same way silloncli does from the shell.

Example

import sillonlab as sl

project = sl.load_project("path/to/project")
runs = project.runs()                # RunCollection of all runs
run = project.get("integration_alpha")
run.parameters                       # {"learning_rate": 0.01, ...}
run.load_result("final_loss")        # read back from the HDF5 glob

Attributes:

Name	Type	Description
path	Path	The root path of the project.
storage_root	Path	The folder holding the database, glob and artifact storage (the .sillon folder by default).
engine	Engine	The SQLAlchemy engine connected to the project database.

context(*run_names)

Fetches the context summary of the project or of specific runs.

Parameters:

Name	Type	Description	Default
*run_names	str	Optional run names to target. If omitted, the project-wide overview is returned.	()

Returns:

Name	Type	Description
dict	dict	The engine context payload (mode and runs keys).

show(*run_names)

Pretty-prints the project context, like sillon context does.

With no argument, an overview table of all runs is displayed. With run names, a detail card is displayed for each targeted run. Works in a terminal and in a jupyter notebook.

Parameters:

Name	Type	Description	Default
*run_names	str	Optional run names to target.	()

runs()

Loads all the runs of the project.

Returns:

Name	Type	Description
RunCollection	RunCollection	Lazy Run handles, sorted by timestamp.

query(has_parameter=None, has_metadata=None, has_result=None, has_analysis=None, has_artifact=None, has_tag=None, tags=None, parameters=None, metadata=None, results=None, analyses=None, fields=None, before=None, after=None, **param_conditions)

Finds the runs matching value/predicate and presence criteria.

Value conditions map a name to a plain value (equality) or a callable predicate, and can target parameters, metadata, results, or analyses. Bare keyword arguments are a shorthand for parameter conditions. fields filters on top-level columns (status, author, git hash, ...). before/after filter on the run date. Presence filters (has_*, tags) keep only runs that have the named item.

Cheap criteria (parameters, metadata, tags, date, fields, presence) are resolved entirely from the database; result/analysis value conditions read the glob, but only for runs that already passed the cheap filters.

Example

project.query(optimizer="adam")                       # param equality
project.query(learning_rate=lambda lr: lr < 0.1)      # param predicate
project.query(metadata={"sillon.language": "python"})
project.query(tags="baseline", after="2026-06-01")
project.query(fields={"status": "SUCCESS"})
project.query(results={"final_loss": lambda v: v < 0.05})
project.query(tags="prod", results={"loss": lambda v: v < 0.1})

Parameters:

Name	Type	Description	Default
has_parameter	str | list	Parameter name(s) that must exist.	None
has_metadata	str | list	Metadata name(s) that must exist.	None
has_result	str | list	Result/artifact name(s) that must exist.	None
has_analysis	str | list	Analysis name(s) that must exist.	None
has_artifact	str | list	Artifact name(s) that must exist.	None
has_tag	str | list	Tag(s) the run must have.	None
tags	str | list	Alias for has_tag.	None
parameters	dict	Parameter value/predicate conditions.	None
metadata	dict	Metadata value/predicate conditions.	None
results	dict	Result value/predicate conditions.	None
analyses	dict	Analysis value/predicate conditions.	None
fields	dict	Conditions on top-level columns (e.g. {"status": "SUCCESS", "author": "doph"}).	None
before	datetime | str	Keep runs created before this date.	None
after	datetime | str	Keep runs created after this date.	None
**param_conditions		Shorthand parameter value/predicate conditions.	{}

Returns:

Name	Type	Description
RunCollection	RunCollection	The matching runs.

get(run_name)

Loads a single run by name or uuid.

Parameters:

Name	Type	Description	Default
run_name	str	The name or uuid of the run.	required

Raises:

Type	Description
LookupError	If the run does not exist in the project database.

Returns:

Name	Type	Description
Run	Run	The loaded run handle.

details(run_names=None, parameters=None, metadata=None, results=None)

Queries run details exactly like sillon show does.

Each category accepts a list of keys, a single key, or True to fetch everything in that category.

Parameters:

Name	Type	Description	Default
run_names	str | list	Run name(s) to target.	None
parameters	str | list | bool	Parameter keys to fetch.	None
metadata	str | list | bool	Metadata keys to fetch.	None
results	str | list | bool	Result keys to fetch.	None

Returns:

Name	Type	Description
dict	dict	The engine payload with parameter, metadata, result and artifacts keys, present only if requested.

add(run_names, notes=None, tags=None)

Appends notes or tags to existing runs, like sillon add.

Parameters:

Name	Type	Description	Default
run_names	str | list	The run name(s) to annotate.	required
notes	str | list	Note(s) to append.	None
tags	str | list	Tag(s) to append.	None

Returns:

Name	Type	Description
dict	dict	The engine status payload of the operation.

delete_run(run)

Permanently deletes a run (its stored data and database row).

Parameters:

Name	Type	Description	Default
run	Run | str	A Run handle, or the run name/uuid to delete.	required

Returns:

Name	Type	Description
dict	dict	{"status": "success", "deleted": str, "freed_bytes": int}, or an error status if the run does not exist.

rename(run, new_name)

Renames a run, rejecting the rename if new_name is already taken.

Parameters:

Name	Type	Description	Default
run	Run | str	A Run handle, or the run name/uuid to rename.	required
new_name	str	The new run name.	required

Returns:

Name	Type	Description
dict	dict	{"status": "success", "old": ..., "new": ...} or an error status.

find_by_hash(file_or_hash)

Finds which run(s) own a file, by its content hash.

Pass a file path (it gets hashed) or a hash string. Useful to trace a stray figure/artifact back to the run that produced it.

Parameters:

Name	Type	Description	Default
file_or_hash	str | Path	A file path or a SHA-256 hash.	required

Returns:

Type	Description
list	list[dict]: One {run_name, run_uuid, kind, name} per match.

compare(run_name1, run_name2)

Diffs two runs (parameters, context, source), like sillon compare.

Parameters:

Name	Type	Description	Default
run_name1	str	The baseline run name.	required
run_name2	str	The target run name.	required

Returns:

Name	Type	Description
dict	dict	The engine diff payload (diff_param, diff_status, diff_runtime, diff_source).

Run and RunCollection

sillonlab

sillonlab: the analysis library of the sillon toolchain.

Load a sillon project from a python script or a jupyter notebook and explore its logged runs, the same way silloncli does from the shell.

Example

import sillonlab as sl

project = sl.load_project("path/to/project")
print(project.runs().list())

run = project.get("my_run")
print(run.parameters)
data = run.load_result("coef")

Run

A lazy handle on a single logged simulation run.

The object is cheap to create: it only holds the run name and the project pointers. All the data is fetched through the silloncore engine on first access and cached, so a notebook can hold hundreds of handles for free.

Attributes:

Name	Type	Description
name	str	The human-readable name of the run.
uuid	str	The unique identifier of the run (available after the first data access).
timestamp	str	The creation date of the run.
status	str	The final execution status of the run.

parameters property

All logged parameters of the run as a dictionary.

results property

The names of all logged results and artifacts of the run.

metadata property

All logged metadata of the run as a dictionary.

tags property

The tags attached to the run.

notes property

The notes attached to the run.

runtime property

The execution duration of the run.

figures property

The figures logged during the run, with their provenance metadata.

Each entry maps the figure name to its metadata: the used key lists the parameters/results the figure was built from.

analyses property

The post-processed analyses attached to the run, with their context.

parents()

Runs this run derives from (lineage) — as walkable Run handles.

Inheritance copies nothing; it only records the link. Walk back to read a parent's parameters, e.g. run.parents()[0].load_parameter("lr").

parent_links()

The raw parent edges ([{"uuid", "name"}, ...]).

children()

Runs that derive from this run (reverse lineage), as Run handles.

load_parameter(*names)

Loads one or more parameter values by name.

Parameters:

Name	Type	Description	Default
*names	str	The parameter name(s) to load.	()

Returns:

Name	Type	Description
Any	Any	The value if one name is given, otherwise a list of values.

load_result(*names)

Loads one or more results by name, through the engine.

Heavy results saved to the HDF5 glob are read back from disk. Results logged as artifacts return the path to the stored copy. Plain values or external paths are returned as stored in the database.

Parameters:

Name	Type	Description	Default
*names	str	The result name(s) to load.	()

Returns:

Name	Type	Description
Any	Any	The value if one name is given, otherwise a list of values.

load_metadata(*names)

Loads one or more metadata values by name, or all of them.

Parameters:

Name	Type	Description	Default
*names	str	The metadata name(s) to load. If omitted, the whole metadata dictionary is returned.	()

Returns:

Name	Type	Description
Any	Any	The full dictionary, a single value, or a list of values.

load_artifact(name)

Resolves the on-disk location of a saved artifact.

Parameters:

Name	Type	Description	Default
name	str	The result name the artifact was logged under.	required

Returns:

Name	Type	Description
Path	Path	The path to the artifact file, or to its folder if the artifact holds several files.

load_source()

Loads the main script source code recorded for the run.

load_figure(name)

Resolves the on-disk location of a figure logged during the run.

Parameters:

Name	Type	Description	Default
name	str	The name the figure was logged under.	required

Returns:

Name	Type	Description
Path	Path	The path to the figure file (e.g., to open or display in a notebook with IPython.display.Image).

fetch_result(name, dest=None)

Fetches a result, artifact, or figure as a file on disk.

Artifacts and figures are copied as-is; glob results are saved as .npy (or .txt for strings). Use load_result instead to get the value directly in memory.

Parameters:

Name	Type	Description	Default
name	str	The result, artifact, or figure name to fetch.	required
dest	str | Path	The destination directory. Defaults to the current working directory.	None

Returns:

Name	Type	Description
Path	Path	The path of the fetched copy.

sizes()

Measures the storage footprint of every stored item of the run.

Returns:

Name	Type	Description
dict	dict	Mapping of item names to {"kind": str, "bytes": int}.

export(dest=None, format='npz')

Exports the stored data of the run into a portable file.

Parameters:

Name	Type	Description	Default
dest	str | Path	Output file (or folder for "npy"). Defaults to <run_name>_export.<ext> in the current directory.	None
format	str	One of "npz", "npy", "hdf5". The hdf5 export also embeds the parameters and run identity. Defaults to "npz".	'npz'

Returns:

Name	Type	Description
dict	dict	{"path": Path, "exported": [names], "skipped": [names]}.

report(dest=None, with_data=False)

Exports a self-contained context bundle (zip) describing the run.

The bundle answers "what did this run use and do": a JSON manifest, a readable report.md, the recorded entry script, and optionally the run's data as HDF5. Ideal to archive a run or drop it in a thesis appendix.

Parameters:

Name	Type	Description	Default
dest	str | Path	Output zip path. Defaults to <run_name>_report.zip in the current directory.	None
with_data	bool	Also embed results/analyses as HDF5. Defaults to False.	False

Returns:

Name	Type	Description
Path	Path	The path of the written zip bundle.

manifest()

Returns the structured run report as a dictionary (no file written).

add_note(note)

Appends one or more notes to the run.

Parameters:

Name	Type	Description	Default
note	str | list	The note(s) to append.	required

add_tag(tag)

Appends one or more tags to the run.

Parameters:

Name	Type	Description	Default
tag	str | list	The tag(s) to append.	required

add_metadata(key_or_dict, value=None)

Merges metadata into the run.

Parameters:

Name	Type	Description	Default
key_or_dict	str | dict	A metadata key, or a dictionary of metadata key/value pairs.	required
value	Any	The value when a single key is given.	None

add_analysis(name, data, **info)

Attaches post-processed data to the run for later reuse.

Use this when you derive new data from the run after the fact: for example, if the simulation fitted a function, store f(x) evaluated on your grid of interest and reload it later with load_analysis.

Parameters:

Name	Type	Description	Default
name	str	The analysis name.	required
data	Any	The processed data to store (array-like).	required
**info		Free-form context saved with the analysis (e.g., inputs=["coef"], comment="evaluated on fine grid").	{}

Returns:

Name	Type	Description
dict	dict	The stored analysis row (name, hash, date...).

load_analysis(name)

Loads back a post-processed analysis attached to the run.

Parameters:

Name	Type	Description	Default
name	str	The analysis name to load.	required

Returns:

Name	Type	Description
Any	Any	The stored analysis data.

to_dataframe(metadata=False, results=False)

Builds a single-row pandas DataFrame of the run.

Parameters:

Name	Type	Description	Default
metadata	bool	If True, metadata keys are added as columns.	False
results	bool	If True, results are loaded and added as columns.	False

Returns:

Type	Description
	pandas.DataFrame: A one-row summary of the run.

delete()

Permanently deletes this run — its stored data and database row.

This is irreversible: the run's glob, artifacts and figures are removed from disk and its database entry (with linked artifacts/figures/ analyses) is dropped. After this call the handle is stale.

Returns:

Name	Type	Description
dict	dict	{"status": "success", "deleted": str, "freed_bytes": int}, or an error status if the run no longer exists.

rename(new_name)

Renames the run, rejecting the rename if new_name is already taken.

Parameters:

Name	Type	Description	Default
new_name	str	The new run name.	required

Returns:

Name	Type	Description
dict	dict	{"status": "success", "old": ..., "new": ...} or an error status (e.g. the name clashes with an existing run).

show()

Pretty-prints the run as a detail card (terminal or notebook).

RunCollection

A list-like container of Run objects with analysis helpers.

list()

Returns the names of all runs in the collection.

filter(predicate)

Returns a new collection of the runs matching the predicate.

Parameters:

Name	Type	Description	Default
predicate	Callable[[Run], bool]	A function tested on each run.	required

sort_by(key, reverse=False)

Returns a new collection ordered by key.

key is either a callable taking a Run, or the name of a parameter or result to order on -- so the common question ("my five best runs") is one call:

best = project.query(status="SUCCESS").sort_by("final_loss")[:5]
worst_first = runs.sort_by(lambda r: r.runtime, reverse=True)

Runs missing the named key sort last, whatever the direction, so a partially-logged run never displaces a real result.

Parameters:

Name	Type	Description	Default
key	Callable[[Run], Any] | str	A key function, or a parameter or result name.	required
reverse	bool	Descending order. Defaults to False.	False

Returns:

Name	Type	Description
RunCollection	RunCollection	A new collection; the original is left untouched.

where(has_parameter=None, has_metadata=None, has_result=None, has_analysis=None, has_artifact=None, has_tag=None, tags=None, parameters=None, metadata=None, results=None, analyses=None, fields=None, before=None, after=None, **param_conditions)

Filters the collection on value/predicate and presence criteria.

Same criteria as Project.query (parameters, metadata, results, analyses, fields, tags, date, and has_* presence), but applied to the runs already in this collection. Cheap criteria are checked before any glob is read.

Example

runs.where(optimizer="adam", learning_rate=lambda v: v < 0.1)
runs.where(metadata={"sillon.language": "python"})
runs.where(tags="baseline", after="2026-06-01")
runs.where(results={"final_loss": lambda v: v < 0.05})

Parameters:

Name	Type	Description	Default
has_parameter	str | list	Parameter name(s) that must exist.	None
has_metadata	str | list	Metadata name(s) that must exist.	None
has_result	str | list	Result/artifact name(s) that must exist.	None
has_analysis	str | list	Analysis name(s) that must exist.	None
has_artifact	str | list	Artifact name(s) that must exist.	None
has_tag	str | list	Tag(s) the run must have.	None
tags	str | list	Alias for has_tag.	None
parameters	dict	Parameter value/predicate conditions.	None
metadata	dict	Metadata value/predicate conditions.	None
results	dict	Result value/predicate conditions.	None
analyses	dict	Analysis value/predicate conditions.	None
fields	dict	Conditions on top-level columns.	None
before	datetime | str	Keep runs created before this date.	None
after	datetime | str	Keep runs created after this date.	None
**param_conditions		Shorthand parameter value/predicate conditions.	{}

Returns:

Name	Type	Description
RunCollection	RunCollection	The matching runs.

show()

Pretty-prints the collection as a summary table.

to_dataframe(metadata=False, results=False)

Builds a pandas DataFrame summarizing the collection.

Each row is a run with its name, timestamp, status, runtime and one column per logged parameter.

Parameters:

Name	Type	Description	Default
metadata	bool	If True, metadata keys are added as columns. Defaults to False.	False
results	bool	If True, results are loaded (glob reads included) and added as columns. Defaults to False.	False

Returns:

Type	Description
	pandas.DataFrame: The summary table, one row per run.

delete_run(run)

Permanently deletes a run (its stored data and database row).

Convenience wrapper around Run.delete().

Parameters:

Name	Type	Description	Default
run	Run	The run handle to delete.	required

Returns:

Name	Type	Description
dict	dict	{"status": "success", "deleted": str, "freed_bytes": int}, or an error status if the run no longer exists.