mathxlab.exp.cli

Command-line helpers for experiments.

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

Parse standard CLI arguments

from mathxlab.exp.cli import parse_experiment_args
args = parse_experiment_args(argv=["--out", "out/e001", "--seed", "1"])
print(args.out_dir)

Public API

Name

Kind

Summary

ExperimentArgs

class

Parsed command-line arguments for an experiment run.

ExperimentArgsWithSize

class

Parsed command-line arguments for an experiment run with a size parameter.

ExperimentArgsWithNMax

class

Parsed command-line arguments for an experiment run with an n_max parameter.

parse_experiment_args_with_size

function

Parse standard experiment CLI arguments plus a --size option.

parse_experiment_args_with_n_max

function

Parse standard experiment CLI arguments plus a --n-max option.

parse_experiment_args

function

Parse standard experiment CLI arguments.

Reference

Classes

class mathxlab.exp.cli.ExperimentArgs(out_dir, seed, verbose)[source]

Bases: object

Parsed command-line arguments for an experiment run.

out_dir

Output directory where all artifacts will be written.

seed

Deterministic seed for randomness.

verbose

Enable verbose logging.

Examples

>>> from mathxlab.exp.cli import ExperimentArgs
>>> ExperimentArgs
class mathxlab.exp.cli.ExperimentArgsWithSize(out_dir, seed, verbose, size)[source]

Bases: object

Parsed command-line arguments for an experiment run with a size parameter.

out_dir

Output directory where all artifacts will be written.

seed

Deterministic seed for reproducibility.

verbose

Enable verbose logging.

size

Grid size parameter (meaning depends on experiment).

Examples

>>> from mathxlab.exp.cli import ExperimentArgsWithSize
>>> ExperimentArgsWithSize
class mathxlab.exp.cli.ExperimentArgsWithNMax(out_dir, seed, verbose, n_max)[source]

Bases: object

Parsed command-line arguments for an experiment run with an n_max parameter.

out_dir

Output directory where all artifacts will be written.

seed

Deterministic seed for reproducibility.

verbose

Enable verbose logging.

n_max

Inclusive upper bound for computations (must be >= 2).

Examples

>>> from mathxlab.exp.cli import ExperimentArgsWithNMax
>>> ExperimentArgsWithNMax

Functions

mathxlab.exp.cli.parse_experiment_args_with_size(*args, experiment_id=None, description=None, argv=None, size_default=301, size_help='Grid size parameter (must be positive and odd).')[source]

Parse standard experiment CLI arguments plus a –size option.

This helper keeps new experiments consistent with the standard template while allowing a common –size knob for grid-based visualizations.

Parameters:

  • experiment_id – Optional program name for help.

  • description – Optional description for help.

  • argv – Optional argv list (without a program name). If None, argparse reads from sys.argv.

  • size_default – Default size value.

  • size_help – Help text for the –size option.

Returns:

Parsed ExperimentArgsWithSize.

Raises:

  • TypeError – If argv is passed both positionally and as a keyword, or if the positional argv is invalid.

  • SystemExit – If size is non-positive or even.

Examples

>>> from mathxlab.exp.cli import parse_experiment_args_with_size
>>> args = parse_experiment_args_with_size(argv=["--out", "out/e124", "--size", "401"])
>>> args.size
401
mathxlab.exp.cli.parse_experiment_args_with_n_max(*args, experiment_id=None, description=None, argv=None, n_max_default=2000000, n_max_help='Inclusive upper bound N for computations (>= 2).')[source]

Parse standard experiment CLI arguments plus a –n-max option.

Compatibility note: Some experiments call parse_experiment_args_with_n_max(argv) positionally, where argv may be None. The preferred style is parse_experiment_args_with_n_max(argv=argv). Both are supported.

Parameters:

  • experiment_id – Optional program name for help.

  • description – Optional description for help.

  • argv – Optional argv list (without a program name). If None, argparse reads from sys.argv.

  • n_max_default – Default n_max value.

  • n_max_help – Help text for the –n-max option.

Returns:

Parsed ExperimentArgsWithNMax.

Raises:

  • TypeError – If argv is passed both positionally and as a keyword, or if the positional argv is invalid.

  • SystemExit – If n_max is < 2.

mathxlab.exp.cli.parse_experiment_args(*args, experiment_id=None, description=None, argv=None)[source]

Parse standard experiment CLI arguments.

Parameters:

  • experiment_id – Optional program name for help.

  • description – Optional description for help.

  • argv – Optional argv list (without a program name). If None, argparse reads from sys.argv.

Returns:

Parsed ExperimentArgs.

Examples

>>> from mathxlab.exp.cli import parse_experiment_args
>>> args = parse_experiment_args(argv=["--out", "out/e001", "--seed", "7"])
>>> args.out_dir.name
'e001'