Experiments
Experiments are the foundation of ML-Dash. Each experiment represents a single experiment run, containing all your logs, parameters, metrics, and files.
Prefix Format
The prefix is a universal key that identifies your experiment:
- owner: First segment (e.g., your username)
- project: Second segment (e.g., project name)
- path: Remaining segments form the folder structure
- name: Derived from the last segment
Three Usage Styles
Context Manager (recommended for most cases):
Decorator (clean for training functions):
Direct (manual control):
Automatic Path Detection with RUN.entry
Use RUN.entry = __file__ to automatically detect the script path and generate a meaningful experiment prefix:
This is useful when:
- Running multiple scripts in the same project
- You want the prefix to automatically reflect the file structure
- Organizing experiments by script location
Local, Hybrid, and Remote Mode
Where an experiment writes depends on dash_url and dash_root:
| Mode | How to get it | Writes to |
|---|---|---|
| Local (default) | no dash_url | .dash/ on disk. No server, no login |
| Hybrid | dash_url=... | the server and .dash/ |
| Remote | dash_url=..., dash_root=None | the server only |
Any mode that uses the server needs a login first. See
Authentication. Runs recorded in local mode can
be uploaded later with ml-dash upload.
Experiment Metadata
Add a description (readme), tags, and bindrs for organization:
Metadata fields:
readme: Human-readable experiment description (shown as the description on the server). Note that the argument isreadme, notdescription. Unknown keyword arguments are silently ignored.tags: List of tags for categorization (e.g., ["baseline", "production"])bindrs: List of bindrs for resource/team association (e.g., ["gpu-1", "team-ml"])
Experiment Status Lifecycle
Experiments automatically track their status through the lifecycle:
- RUNNING: Automatically set when experiment opens
- COMPLETED: Set when experiment closes normally
- FAILED: Set when exception occurs during experiment
- CANCELLED: Can be set manually
Automatic status management (recommended):
Manual status control:
Note: Status updates only work in remote mode. Local mode doesn't track status.
Resuming Experiments
Experiments use upsert behavior - reopen by using the same prefix:
Report an application lifecycle to DreamLake Jobs
This optional integration requires ml-dash 0.9.0+ and a DreamLake API that supports the job lifecycle endpoint described below. Dash experiment status and DreamLake job execution status are separate records. To report application start, success, failure or cancellation, bind the reporter to the exact existing DreamLake job and its accepted execution receipt:
The caller supplies MY_JOB_ID and MY_EXECUTION_RECEIPT_ID from the existing
authenticated Jobs response (id and attemptId). These example environment
variables are not automatically injected by Nymph. Do not substitute a Dash
experiment ID, prefix, scheduler ID or worker ID. Use a DreamLake credential
authorized for this job; the Dash credential is separate. No credentials are
written to the journal.
The explicit run.start(), run.complete(), run.fail() and run.cancel()
contract drives reporting. Normal context-manager exit requests success; an
exception requests failure. Existing buffer-flush failures still downgrade a
requested completion to failure. A return value such as False or None does
not by itself mean failure. Reporting does not inspect program outputs or turn
a process exit into application success.
Each event is saved durably before transmission, with a stable event ID and the
exact API origin, namespace, job and attempt binding. Keep the private journal
on persistent storage. After a lost acknowledgment or process restart, construct
the reporter with the same binding and journal, then call lifecycle.flush()
to resend pending events. This sends only previously saved evidence. An API
restart returns the same accepted receipt on replay. A stale attempt or
conflicting terminal report is rejected; do not generate a replacement event
or change the attempt to make it pass. Credential renewal may retry the same
journal under the currently authorized actor.
DreamLake list/summary/detail responses expose applicationStatus and accepted
applicationLifecycle receipts. With no accepted event, the application status
is unknown. No terminal event is invented after a crash or forced termination.
The legacy status and its explicit executionStatus alias retain script-exit
compatibility; use applicationStatus to determine application lifecycle success.
An experiment timeout or stale dashboard status is not a job lifecycle receipt.
Available Operations
Once an experiment is open, you can use all ML-Dash features:
Storage Structure
Local mode creates a directory structure:
Files are stored under files/{prefix}/{snowflake_id}/{filename} where:
prefix: Logical path (e.g., "models", "configs")snowflake_id: Unique identifier for the filefilename: Original filename
Remote mode stores data in MongoDB + S3 on your server.
Next: Learn about Logging to track events and progress.