Skip to content

getting_started.md

Latest commit

 

History

History
172 lines (130 loc) · 5.5 KB

getting_started.md

File metadata and controls

172 lines (130 loc) · 5.5 KB
Raw

Getting Started

Installation

From source (recommended for development)

git clone https://github.com/Yuma-Ichikawa/StatPhysMLSimPlayground.git
cd StatPhysMLSimPlayground
pip install -e ".[dev]"

Using uv (faster)

uv pip install -e ".[dev]"

Core requirements: Python ≥ 3.10, PyTorch ≥ 2.0, NumPy ≥ 1.24, SciPy ≥ 1.10, Matplotlib ≥ 3.7, pandas ≥ 2.0.

One-liner API

The fastest way to run a complete experiment (simulation + theory + plots):

import statphys

# Online SGD vs exact ODE theory (linear regression)
result = statphys.quick_online(d=400, lr=0.5, t_max=10)

# Ridge regression at several alpha = n/d vs replica theory
result = statphys.quick_replica(d=200, reg_param=0.1)

# Theory-free teacher-student experiment (works for any architecture)
result = statphys.quick_experiment("random_mlp", alphas=[1, 2, 4, 8])

Every helper returns the underlying result object, so the quick API also serves as an entry point into the full framework below.

New to statistical mechanics of learning? See the glossary first — every physics term below (order parameter, replica, phase transition, ...) is translated into plain ML language there.

The single most rewarding first command

If you only run one thing, run this — it trains several independent students, measures every physics order parameter automatically, checks generalization error, and renders a 4-panel dashboard:

import statphys
statphys.quick_order_parameters("random_mlp", alphas=[0.5, 1, 2, 4, 8, 16], show=True)

Or, without writing any Python:

statphys order-params random_mlp --alphas 0.5 1 2 4 8 16

Guided workflow and visual evidence report

For a reusable study with a validated configuration, start with the guided interface instead of constructing objects directly:

statphys catalog
statphys new --kind order_parameters --output study.toml
statphys validate study.toml
statphys run study.toml --output results
statphys report results/result.json --output results/report.html

The resulting report is a self-contained HTML file. Its phase explorer shows condition-level means and recorded uncertainty intervals; its evidence panel shows the theory status, independent seed count, and the strength of wording permitted by the study's evidence tier. Use statphys inspect to examine an artifact, statphys compare for condition-level comparisons, statphys resume to deterministically rerun the immutable study in a result directory, and statphys doctor to check optional dependencies. See guided_workflow.md for the full command reference.

Full workflow: Replica simulation vs theory

import statphys
from statphys.dataset import GaussianDataset
from statphys.model import LinearRegression
from statphys.loss import RidgeLoss
from statphys.simulation import ReplicaSimulation, SimulationConfig
from statphys.theory.replica import SaddlePointSolver, GaussianLinearRidgeEquations
from statphys.vis import ComparisonPlotter

statphys.fix_seed(42)

# Dataset with linear teacher: y = w0.x/sqrt(d) + noise
dataset = GaussianDataset(d=500, rho=1.0, eta=0.1)

# Simulation configuration
config = SimulationConfig.for_replica(
    alpha_range=(0.1, 5.0),   # sample ratio alpha = n/d
    alpha_steps=20,
    n_seeds=5,
    reg_param=0.01,
    use_theory=True,
)

# Theory: RS saddle-point equations for ridge regression
theory_solver = SaddlePointSolver(
    equations=GaussianLinearRidgeEquations(rho=1.0, eta=0.1, reg_param=0.01),
    order_params=["m", "q"],
)

sim = ReplicaSimulation(config)
results = sim.run(
    dataset=dataset,
    model_class=LinearRegression,
    loss_fn=RidgeLoss(0.01),
    theory_solver=theory_solver,
)

ComparisonPlotter().plot_theory_vs_experiment(results)

To run without theory, set use_theory=False and omit theory_solver; the experiment results remain accessible via results.experiment_results.

Full workflow: Online SGD dynamics vs ODE theory

from statphys.simulation import OnlineSimulation, SimulationConfig
from statphys.theory.online import ODESolver, GaussianLinearMseEquations

config = SimulationConfig.for_online(
    t_max=10.0,    # normalized time t = #samples / d
    t_steps=100,
    n_seeds=5,
    lr=0.5,        # equals the ODE learning rate eta (see concepts.md)
)

theory_solver = ODESolver(
    equations=GaussianLinearMseEquations(rho=1.0, lr=0.5),
    order_params=["m", "q"],
)

sim = OnlineSimulation(config)
results = sim.run(
    dataset=dataset,
    model_class=LinearRegression,
    loss_fn=RidgeLoss(0.01),
    theory_solver=theory_solver,
)

The theory ODE automatically starts from the experiment's measured initial condition; pass theory_init_values=... to run() to override.

Running tests

pytest tests/              # all tests
pytest tests/ --cov=statphys
pytest tests/test_theory.py

Next steps