Skip to main content

Experiments

The Experiments feature of the Strangeworks platform offers a powerful tool for running computational experiments in the cloud. By leveraging the Strangeworks SDK, you can easily define, submit, and manage your experiments, allowing you to focus on your research and analysis.

If you are interested in using Experiments, contact us or find us in Slack!

Getting Started​

Authenticate with your API key:

import strangeworks as sw
sw.authenticate("your_api_key")

Running an Experiment​

To run an experiment, you define a function within a .py file that encapsulates your computational task. You then use the @strangeworks.experiment decorator to mark it for execution on the Strangeworks platform. This decorator can be used with or without specifying an ExperimentConfiguration. Here are two examples to illustrate both approaches:

Simple Example​

Run an experiment with default settings:

import strangeworks as sw

@sw.experiment()
def my_experiment():
    return 42

my_experiment()

In this example, the @sw.experiment() decorator is used without any arguments, making it a quick and easy way to run an experiment with default settings.

With Configuration​

Customize experiment settings using ExperimentConfiguration to reference the requirements.txt file listing any dependencies required to run your script:

import strangeworks
from strangeworks.core.client.experiments import ExperimentConfiguration
@strangeworks.experiment(cfg=ExperimentConfiguration(requirements_path="./requirements.txt"))
def my_experiment():
    # Your experiment code here

my_experiment()

Managing Experiments​

Uploading Files​

Upload files to your experiment:

sw.experiment_upload("experiment_name", "trial_name", "./file_path")

Downloading Files​

Download the Last 3 Trials​

Download files from the last 3 trials of an experiment, excluding related jobs:

sw.experiment_download(
    "heavy_computation", 3, "user_program_stdout.txt", False
)

Download Specific Trials with Multiple Files​

Download specific files from named trials, including related jobs:

sw.experiment_download(
    "heavy_computation",
    ["siete_ocho", "siete_ocho_9"],
    ["result.pickle", "user_program_stdout.txt"],
    True,
)

This will return an Experiment object containing the specified trials with their requested files and any related jobs.

Accessing Experiment Results​

While downloading files provides raw data from your experiments, accessing experiment results allows you to directly retrieve and deserialize the outcome of your experiment for immediate use in your analysis:

result = strangeworks.experiment_get_result("experiment_name", "trial_name")