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.

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.

resume

bool

optional

default: False

If False, creates a new run.

To continue an existing run, set to True and pass the ID of an existing run to the run_id argument.

To fork a run, use fork_run_id and fork_step instead.

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.

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.

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 an experiment.

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:
    ...

To resume a run, pass its ID and set resume to True:

with Run(
    run_id="likable-barracuda",  # a Neptune run with this ID already exists
    resume=True,
) as run:
    ...

Create a detached run:

with Run(run_id="likable-barracuda") 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.