mathxlab.exp.io

Filesystem and serialization helpers 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

Create standard output paths

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

Public API

Name	Kind	Summary
JsonDict	data	Type alias for JSON-serializable dictionaries.
RunPaths	class	Standard output paths for an experiment run.
prepare_out_dir	function	Prepare the output directory structure.
save_figure	function	Save a Matplotlib figure to disk.
json_default	function	Default JSON encoder for math objects.
write_json	function	Write a dictionary to a JSON file with stable formatting.
write_text	function	Write text to a file.

Reference

Classes

class mathxlab.exp.io.RunPaths(root, figures_dir, report_path, params_path)

Bases: object

Standard output paths for an experiment run.

Examples

>>> from mathxlab.exp.io import RunPaths
>>> RunPaths

Functions

mathxlab.exp.io.prepare_out_dir(*, out_dir)

Prepare the output directory structure.

Parameters:

out_dir – The root output directory for the experiment.

Returns:

A RunPaths object containing the paths to standard artifacts.

Examples

>>> from pathlib import Path
>>> from mathxlab.exp.io import prepare_out_dir
>>> paths = prepare_out_dir(out_dir=Path("out/e001"))

mathxlab.exp.io.save_figure(*, out_dir, name, fig, dpi=160, finalize=True)

Save a Matplotlib figure to disk.

Parameters:

• out_dir – Directory to save the figure in.

• name – Filename (without extension).

• fig – The figure object to save.

• dpi – Dots per inch for the output image.

• finalize – If True, apply standard formatting via finalize_figure() before saving.

Returns:

The path where the figure was saved.

Notes

When finalize=True, the function applies shared layout and math-text configuration before saving.

Examples

>>> import matplotlib.pyplot as plt
>>> from mathxlab.exp.io import save_figure
>>> fig = plt.figure(); _ = save_figure(out_dir=Path("out/e001/figures"), name="demo", fig=fig)

mathxlab.exp.io.json_default(obj)

Default JSON encoder for math objects.

Parameters:

obj – Object to encode.

Returns:

A JSON-serializable representation of the object.

Raises:

TypeError – If the object type is not supported.

Examples

>>> from mathxlab.exp.io import json_default
>>> json_default

mathxlab.exp.io.write_json(path, data)

Write a dictionary to a JSON file with stable formatting.

Parameters:

• path – Path to the JSON file.

• data – Dictionary to write.

Notes

The parent directory is not created automatically. Use prepare_out_dir() first, or create the directory yourself.

Examples

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

mathxlab.exp.io.write_text(path, text, encoding='utf-8')

Write text to a file.

Parameters:

• path – Path to the file.

• text – Text to write.

• encoding – Text encoding.

Examples

>>> from pathlib import Path
>>> from mathxlab.exp.io import write_text
>>> # write_text(Path("out/e001/report.md"), "# Report")

Data

mathxlab.exp.io.JsonDict = JsonDict

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.