# gradexp > Like wandb, but for tensors. ## Install ``` pip install gradexp ``` ## Authenticate ``` gradexp login ``` This opens your browser to generate an API key. ## Log tensors ```python import gradexp gradexp.init(project_name="my_project", run_name="run_1", precision="bf16") for step in range(10): gradexp.log(tensor, name="activations/layer_0", step=step) ``` `log()` is non-blocking — it queues data for background upload so your training loop isn't slowed down. Visit your run URL (printed by `init`) to visualize tensors in real time. --- ## API Reference ### init() ```python gradexp.init(project_name=None, run_name=None, precision="fp32") ``` Start a new run session. If no names are provided, defaults to "default". | Param | Type | Default | Description | |-------|------|---------|-------------| | project_name | str | "default" | Project to log under | | run_name | str | "default-run" | Name for this run | | precision | str | "fp32" | Storage precision: fp32, fp16, or bf16 | Automatically detects an active wandb run and pulls project/run names from it if available. ### log() ```python gradexp.log(tensor, name="default", dimension_labels=None, step=None) ``` Log a tensor. Accepts numpy arrays, PyTorch tensors, or array-like objects. Non-blocking. | Param | Type | Default | Description | |-------|------|---------|-------------| | tensor | array-like | — | The tensor data to log | | name | str | "default" | Tensor name (used for grouping) | | dimension_labels | list | None | Labels for each dimension | | step | int | None | Explicit step index. If omitted, auto-increments per tensor name. | ### finish() ```python gradexp.finish(status="complete") ``` End the session and flush all pending uploads. Blocks until uploads complete. | Param | Type | Default | Description | |-------|------|---------|-------------| | status | str | "complete" | Final run status | ### log_gradient_stats() ```python gradexp.log_gradient_stats(model, step=None, level="default", stats=None) ``` Log per-layer gradient and parameter statistics for a PyTorch model. Call after `loss.backward()`. | Param | Type | Default | Description | |-------|------|---------|-------------| | model | nn.Module | — | PyTorch model with gradients computed | | step | int | None | Explicit step index. If omitted, auto-increments per stat tensor. | | level | str | "default" | min, default, or full | | stats | list | None | Explicit list of stat names (overrides level) | #### Levels | Level | Stats logged | |-------|-------------| | min | grad_l2, l2_grad_param_ratio | | default | grad_l2, grad_max, grad_std, avg_abs_grad, param_l2, l2_grad_param_ratio | | full | All of default + param_std, avg_grad_std_ratio | ```python # after loss.backward() gradexp.log_gradient_stats(model, step=step) # lightweight — just norms and ratio gradexp.log_gradient_stats(model, step=step, level="min") # pick exactly what you need gradexp.log_gradient_stats(model, step=step, stats=["grad_l2", "grad_max"]) ``` ### log_model_tensors() ```python gradexp.log_model_tensors(model, step=None) ``` Special-case debugging API that logs every parameter tensor under `weights/*` and every populated gradient tensor under `updates/*`. **Do not use this for normal runs.** This is only for tiny toy models or targeted debugging. Each logged weight or update tensor must stay at or below 67,108,864 flattened elements (1024x1024x64), and larger tensors are rejected before upload. Most users should use `log_gradient_stats()` instead. | Param | Type | Default | Description | |-------|------|---------|-------------| | model | nn.Module | — | PyTorch model whose parameters should be logged | | step | int | None | Explicit step index. If omitted, auto-increments per weight/update tensor name. | Call after `loss.backward()` and before `opt.step()`. Only parameters with a populated `param.grad` produce `updates/*` tensors. --- ## CLI Reference ### Authentication ``` gradexp login ``` Opens your browser to authenticate and saves your API key locally. ### Local Instance ``` gradexp local start [--app-port 3000] [--api-port 3001] [--data-dir PATH] gradexp local status gradexp local stop ``` `start` launches a local Gradient Explorer backend. `status` checks if it's running. `stop` shuts it down. When a local instance is running, `gradexp.init()` automatically detects it and routes data locally. No code changes needed. ### Options | Flag | Description | |------|-------------| | --version | Print gradexp version | | --debug | Enable debug logging | --- ## Configuration All configuration is via environment variables. Defaults work well for most use cases. ### Batching | Variable | Default | Description | |----------|---------|-------------| | GRADEXP_BATCH_SIZE | 1000 | Max items per batch | | GRADEXP_MAX_BATCH_BYTES | 5 MB | Max bytes per batch | | GRADEXP_BATCH_IDLE_FLUSH_S | 2.0 | Seconds idle before flush | | GRADEXP_BATCH_MAX_AGE_S | 15.0 | Max batch age before flush | | GRADEXP_BATCH_MIN_FLUSH_STEPS | 8 | Min steps to trigger flush | | GRADEXP_BATCH_MIN_FLUSH_BYTES | 64 KB | Min bytes to trigger flush | ### Uploads | Variable | Default | Description | |----------|---------|-------------| | GRADEXP_UPLOAD_WORKERS | 1 | Parallel upload threads | | GRADEXP_GZIP_UPLOAD | false | Compress uploads with gzip | | GRADEXP_GZIP_LEVEL | 1 | Gzip compression level | | GRADEXP_DEBUG_UPLOAD | false | Log upload timing | ### Authentication | Variable | Description | |----------|-------------| | GRADEXP_API_KEY | Override saved API key (useful in CI/containers) |