Adding Custom Input Arguments

Adding Custom Input Arguments#

When running parameter sweep experiments, some settings or configurations may not logically belong to the parameter grid but still need to vary between experiments. For example, you might want to specify unique filenames for saving outputs, paths for logging, or experiment-specific metadata. Adding these as custom arguments allows you to manage such variations without unnecessarily inflating the parameter grid.

How to Use Custom Arguments#

With sweepexp, you can add custom arguments that apply to the experiment’s function alongside the parameters in the grid. These custom arguments are added with add_custom_argument() and have a default value (shared across all experiments). After adding the custom argument, you can modify its values in the data attribute to assign unique values for each parameter combination.

Here’s how you can use this feature:

1: Add the Custom Argument: Use add_custom_argument() to introduce the new argument and define a default value.

2: Customize the Argument for Each Experiment Modify the argument values in the data attribute to assign unique values for each grid point.

3: Run the Experiment: The custom argument will automatically be passed to the function for each parameter combination.

Example#

In the following example, a unique filename is passed to a function that writes two parameters to a file. The filename is set as a custom argument and modified for each experiment:

from sweepexp import sweepexp

# Create a function that writes two parameters to a file
def write_to_file(param1: int, param2: int, filename: str):
    with open(filename, "w") as f:
        f.write(f"param1: {param1}, param2: {param2}")
    return {}

# Create a SweepExp object around the function
sweep = sweepexp(
    func = write_to_file,
    parameters = { "param1": [1, 4], "param2": [1, 2] },
)

# Create an additional argument for the filename
sweep.add_custom_argument("filename", default_value="output.txt")
# Change the filenames for the experiments
sweep.data["filename"].values = [["output1.txt", "output2.txt"],
                                 ["output3.txt", "output4.txt"]]
# Run the experiments
sweep.run()

Unique UUIDs for Filenames#

You can also use a built-in feature in sweepexp to automatically generate a unique UUID for each experiment, which can be useful for creating unique filenames without manually specifying them. This is particularly helpful when running a large number of experiments where manually assigning filenames might not be feasible.

Here’s the same example as above, but using the UUID feature to generate unique filenames:

from sweepexp import sweepexp

# Create a function that writes two parameters to a file
def write_to_file(param1: int, param2: int, uuid: str):
    filename = f"output_{uuid}.txt"
    print(f"Writing to: {filename}")
    with open(filename, "w") as f:
        f.write(f"param1: {param1}, param2: {param2}")
    return {}

# Create a SweepExp object around the function
sweep = sweepexp(
    func = write_to_file,
    parameters = { "param1": [1, 4], "param2": [1, 2] },
    pass_uuid=True,  # Enable UUID passing
)

sweep.run()

The UUIDs are generated automatically for each experiment, and the filenames are created accordingly. You can access the UUID of each experiment in the data attribute under the “uuid” key.

Tip

The UUID feature is not limited to filenames. You can use it in any possible case where you need a unique identifier for each experiment.

Contents