mathxlab.exp.reporting

Reporting utilities for experiment runs.

Stability

Status: Experimental.

This project treats the documented names as the public surface, but details may still evolve. If you need strict API guarantees, add __all__ = [...] to each module and version releases accordingly.

Design notes

• Keep experiment scripts small: delegate I/O, seeding, and logging here.

• Aim for reproducible outputs (fixed seeds, stable file names).

Examples

Prepare artifacts for a run

from pathlib import Path
from mathxlab.exp.reporting import prepare_out_dir
artifacts = prepare_out_dir(out_dir=Path("out/e001"))

Public API

Name	Kind	Summary
JsonPayload	data	Type alias for JSON-serializable payloads.
RunArtifacts	class	Paths to standard artifacts produced by an experiment run.
prepare_out_dir	function	Create the output directory and return standard artifact paths.
save_figure	function	Save the current Matplotlib figure to disk.
write_json	function	Write a JSON file with stable formatting.

Reference

Classes

class mathxlab.exp.reporting.RunArtifacts(out_dir, report_md, params_json)

Bases: object

Paths to standard artifacts produced by an experiment run.

out_dir

Output directory.

report_md

Path to the Markdown report.

params_json

Path to parameters JSON file.

Examples

>>> from mathxlab.exp.reporting import RunArtifacts
>>> RunArtifacts

Functions

mathxlab.exp.reporting.prepare_out_dir(out_dir)

Create the output directory and return standard artifact paths.

Parameters:

out_dir – Output directory.

Returns:

RunArtifacts with paths for a report and params.

See also

• mathxlab.exp.io.prepare_out_dir: Preferred output layout helper for new experiments.

Examples

>>> from pathlib import Path
>>> from mathxlab.exp.reporting import prepare_out_dir
>>> arts = prepare_out_dir(Path("out/e001"))

mathxlab.exp.reporting.save_figure(path)

Save the current Matplotlib figure to disk.

Parameters:

path – Output image path.

See also

• mathxlab.exp.io.save_figure: Figure saving with optional finalization.

Examples

>>> from mathxlab.exp.reporting import save_figure
>>> save_figure

mathxlab.exp.reporting.write_json(path, payload)

Write a JSON file with stable formatting.

Parameters:

• path – Output path.

• payload – JSON-serializable payload.

See also

• mathxlab.exp.io.write_json: JSON writer with NumPy/Path support via json_default.

Examples

>>> from pathlib import Path
>>> from mathxlab.exp.reporting import write_json
>>> write_json(Path("out/e001/params.json"), {"seed": 1})

Data

mathxlab.exp.reporting.JsonPayload = JsonPayload

Type alias.

Type aliases are created through the type statement:

type Alias = int

In this example, Alias and int will be treated equivalently by static type checkers.

At runtime, Alias is an instance of TypeAliasType. The __name__ attribute holds the name of the type alias. The value of the type alias is stored in the __value__ attribute. It is evaluated lazily, so the value is computed only if the attribute is accessed.

Type aliases can also be generic:

type ListOrSet[T] = list[T] | set[T]

In this case, the type parameters of the alias are stored in the __type_params__ attribute.

See PEP 695 for more information.