Run

Python package: neptune-scale

Representation of experiment tracking run logged with Neptune.

By default, Neptune periodically synchronizes the data with the server in the background. The connection to Neptune remains open until the run is stopped or the script finishes executing.

Initialization

Initialize with the class constructor:

from neptune_scale import Run


if __name__ == "__main__":
    run = Run(...)

Or with a context manager:

from neptune_scale import Run


if __name__ == "__main__":
    with Run(...) as run:
        ...

The line if __name__ == "__main__": ensures safe importing of the main module. For details, see the Python documentation.

Parameters

run_id

str

optional

default: None

Identifier of the run. Max length: 128 bytes.

The custom run ID provided to the run_id argument must be unique within the project. It can't contain the / character.

If not provided, a random, human-readable ID is generated.

If a run with the provided ID already exists, Neptune resumes logging to that run.

What's the difference between sys/id and sys/custom_run_id?

• sys/custom_run_id is the run identifier you set manually via the run_id argument of the Run constructor. It's auto-generated if not provided.
• sys/id is a legacy run identifier based on the project key. It will be removed in a future release and can be ignored.

project

str

optional

default: None

Name of a project in the form workspace-name/project-name. If None, the value of the NEPTUNE_PROJECT environment variable is used.

api_token

str

required

default: None

Your Neptune API token or a service account's API token. If None, the value of the NEPTUNE_API_TOKEN environment variable is used. To keep your token secure, don't place it in source code. Instead, save it as an environment variable.

mode

"async" | "disabled" | "offline"

required

default: "async"

Mode of operation.

• If "disabled", the run doesn't log any metadata.
• If "offline", the run is only stored locally. For details, see Offline logging.
• If this parameter and the NEPTUNE_MODE environment variable are not set, the default is "async".

experiment_name

str

optional

default: None

Name of the experiment to associate the run with.

Can't be used together with the resume parameter.

The name can contain any Unicode character, including /, , ., :, ;, &, and |.

creation_time

datetime

optional

default: datetime.now()

Custom creation time of the run. If not provided, the current time is used. If provided, and timestamp.tzinfo is not set, the time is assumed to be in the local timezone.

fork_run_id

str

optional

default: None

The ID of the run to fork from.

fork_step

int

optional

default: None

The step number to fork from.

log_directory

str | Path

optional

default: .neptune

The base directory where experiment and run metadata is stored:

• If the path is absolute, it's used as provided.
• If the path is relative, it's treated as relative to the current working directory.
• If set to None and the NEPTUNE_LOG_DIRECTORY environment variable isn't set, the default is .neptune in the current working directory.

caution

Because Neptune uses SQLite database files to store metadata and logs, it's not recommended to point the log directory to an NFS filesystem. For details, see the SQLite documentation.

max_queue_size

int

optional

default: None

Deprecated.

on_queue_full_callback

Callable[[BaseException, Optional[float]], None]

optional

default: None

Callback function triggered when the queue is full. The function must take as an argument the exception that made the queue full and, as an optional argument, a timestamp of when the exception was last raised.

on_network_error_callback

Callable[[BaseException, Optional[float]], None]

optional

default: None

Callback function triggered when a network error occurs.

on_error_callback

Callable[[BaseException, Optional[float]], None]

optional

default: None

The default callback function triggered when an unrecoverable error occurs. Applies if an error wasn't caught by other callbacks. In this callback you can choose to perform your cleanup operations and close the training script. For how to end the run in this case, use terminate().

on_warning_callback

Callable[[BaseException, Optional[float]], None]

optional

Callback function triggered when a warning occurs.

enable_console_log_capture

bool

optional

default: True

Log the standard streams stdout and stderr to the run.

• By default, they're stored under the paths runtime/stdout and runtime/stderr, respectively. To change the namespace, use the runtime_namespace parameter.
• If False, no console logs are captured.

runtime_namespace

str

optional

default: runtime

Custom path of the namespace where console logs are stored.

source_tracking_config

SourceTrackingConfig

optional

default: SourceTrackingConfig()

Change or disable the logging of source code and Git information.

• To specify what information to log and define the destination path in the run structure, pass a SourceTrackingConfig object.
• To disable logging, set to None.

Examples

Create a run:

from neptune_scale import Run

with Run(experiment_name="swim-further") as run:
    ...

Create a run and pass Neptune credentials as arguments:

from neptune_scale import Run

with Run(
    project="team-alpha/project-x",
    api_token="h0dHBzOi8aHR0cHM6...Y2MifQ==",
    experiment_name="swim-further",
) as run:
    ...

For help, see Create a run.

To restart (fork) an experiment, create a forked run:

with Run(
    experiment_name="swim-further",
    fork_run_id="likable-barracuda",
    fork_step=102,
) as run:
    ...

Create a detached run:

with Run(
    run_id="likable-barracuda",  # optional
) as run:
    ...

note

Forking and history is only supported for experiment runs.

To take advantage of these and other features that concern analysis of multiple related runs, create experiments rather than stand-alone runs.

Methods

Method	Description
log_configs()	Logs the specified metadata to a Neptune run.
log_metrics()	Logs the specified metrics to a Neptune run.
log_string_series()	Logs the specified strings as a sequence.
log_histograms()	Logs the specified histograms to a step in a Neptune run.
add_tags()	Adds the list of tags to the run.
remove_tags()	Removes the specified tags from the run.
assign_files()	Logs the specified files to Neptune.
log_files()	Logs the specified files as a sequence.
get_run_url()	Returns a URL for viewing the run in the Neptune web app.
get_experiment_url()	Returns a URL for viewing the experiment in the Neptune web app.
wait_for_submission()	Waits until all metadata is submitted to Neptune for processing.
wait_for_processing()	Waits until all metadata is processed by Neptune.
close()	Waits for all locally queued data to be processed by Neptune and closes the run.
terminate()	Terminates the failed run in the error callback.