> ## Documentation Index
> Fetch the complete documentation index at: https://wb-21fd5541-weave-otel-prioritization.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Use a dictionary-like object to save your experiment configuration
# Configure experiments
export const ColabLink = ({url}) =>
Try in Colab
;
Use the `config` property of a run to save your training configuration:
* hyperparameter
* input settings such as the dataset name or model type
* any other independent variables for your experiments.
The `wandb.Run.config` property makes it easy to analyze your experiments and reproduce your work in the future. You can group by configuration values in the W\&B App, compare the configurations of different W\&B runs, and evaluate how each training configuration affects the output. The `config` property is a dictionary-like object that can be composed from multiple dictionary-like objects.
To save output metrics or dependent variables like loss and accuracy, use `wandb.Run.log()` instead of `wandb.Run.config`.
## Set up an experiment configuration
Configurations are typically defined in the beginning of a training script. Machine learning workflows may vary, however, so you are not required to define a configuration at the beginning of your training script.
Use dashes (`-`) or underscores (`_`) instead of periods (`.`) in your config variable names.
Use the dictionary access syntax `["key"]["value"]` instead of the attribute access syntax `config.key.value` if your script accesses `wandb.Run.config` keys below the root.
The following sections outline different common scenarios of how to define your experiments configuration.
### Set the configuration at initialization
Pass a dictionary at the beginning of your script when you call the `wandb.init()` API to generate a background process to sync and log data as a W\&B Run.
The following code snippet demonstrates how to define a Python dictionary with configuration values and how to pass that dictionary as an argument when you initialize a W\&B Run.
```python theme={null}
import wandb
# Define a config dictionary object
config = {
"hidden_layer_sizes": [32, 64],
"kernel_sizes": [3],
"activation": "ReLU",
"pool_sizes": [2],
"dropout": 0.5,
"num_classes": 10,
}
# Pass the config dictionary when you initialize W&B
with wandb.init(project="config_example", config=config) as run:
...
```
If you pass a nested dictionary as the `config`, W\&B flattens the names using dots.
Access the values from the dictionary similarly to how you access other dictionaries in Python:
```python theme={null}
# Access values with the key as the index value
hidden_layer_sizes = run.config["hidden_layer_sizes"]
kernel_sizes = run.config["kernel_sizes"]
activation = run.config["activation"]
# Python dictionary get() method
hidden_layer_sizes = run.config.get("hidden_layer_sizes")
kernel_sizes = run.config.get("kernel_sizes")
activation = run.config.get("activation")
```
Throughout the Developer Guide and examples we copy the configuration values into separate variables. This step is optional. It is done for readability.
### Set the configuration with argparse
You can set your configuration with an argparse object. [argparse](https://docs.python.org/3/library/argparse.html), short for argument parser, is a standard library module in Python 3.2 and above that makes it easy to write scripts that take advantage of all the flexibility and power of command line arguments.
This is useful for tracking results from scripts that are launched from the command line.
The following Python script demonstrates how to define a parser object to define and set your experiment config. The functions `train_one_epoch` and `evaluate_one_epoch` are provided to simulate a training loop for the purpose of this demonstration:
```python theme={null}
# config_experiment.py
import argparse
import random
import numpy as np
import wandb
# Training and evaluation demo code
def train_one_epoch(epoch, lr, bs):
acc = 0.25 + ((epoch / 30) + (random.random() / 10))
loss = 0.2 + (1 - ((epoch - 1) / 10 + random.random() / 5))
return acc, loss
def evaluate_one_epoch(epoch):
acc = 0.1 + ((epoch / 20) + (random.random() / 10))
loss = 0.25 + (1 - ((epoch - 1) / 10 + random.random() / 6))
return acc, loss
def main(args):
# Start a W&B Run
with wandb.init(project="config_example", config=args) as run:
# Access values from config dictionary and store them
# into variables for readability
lr = run.config["learning_rate"]
bs = run.config["batch_size"]
epochs = run.config["epochs"]
# Simulate training and logging values to W&B
for epoch in np.arange(1, epochs):
train_acc, train_loss = train_one_epoch(epoch, lr, bs)
val_acc, val_loss = evaluate_one_epoch(epoch)
run.log(
{
"epoch": epoch,
"train_acc": train_acc,
"train_loss": train_loss,
"val_acc": val_acc,
"val_loss": val_loss,
}
)
if __name__ == "__main__":
parser = argparse.ArgumentParser(
formatter_class=argparse.ArgumentDefaultsHelpFormatter
)
parser.add_argument("-b", "--batch_size", type=int, default=32, help="Batch size")
parser.add_argument(
"-e", "--epochs", type=int, default=50, help="Number of training epochs"
)
parser.add_argument(
"-lr", "--learning_rate", type=float, default=0.001, help="Learning rate"
)
args = parser.parse_args()
main(args)
```
### Set the configuration throughout your script
You can add more parameters to your config object throughout your script.
The following code snippet demonstrates how to add new key-value pairs to an existing config object:
```python theme={null}
import wandb
# Define a config dictionary object
config = {
"hidden_layer_sizes": [32, 64],
"kernel_sizes": [3],
"activation": "ReLU",
"pool_sizes": [2],
"dropout": 0.5,
"num_classes": 10,
}
# Pass the config dictionary when you initialize W&B
with wandb.init(project="config_example", config=config) as run:
# Update config after you initialize W&B
run.config["epochs"] = 4
run.config["batch_size"] = 32
```
You can add multiple values at a time. The following code snippet shows how to update multiple key-value pairs in an existing config object:
```python theme={null}
# Define a config dictionary object
config = {
"channels": 24,
"lr": 1.0,
}
with wandb.init(project="config_example", config=config) as run:
run.config.update(
{
"lr": 0.1,
"channels": 16,
},
allow_val_change=True,
)
```
Make sure you set `allow_val_change=True` if you want to update the value of an existing key. If you do not set this parameter, W\&B will raise an error if you try to update the value of an existing key.
### Set the configuration after your run finishes
Use the [W\&B Public API](/models/ref/python/public-api/) to update a completed run's config.
You must provide the API with your entity, project name and the run's ID. You can find these details in the Run object or in the [W\&B App](/models/track/workspaces/):
```python theme={null}
with wandb.init() as run:
...
# Find the following values from the Run object if it was initiated from the
# current script or notebook, or you can copy them from the W&B App UI.
username = run.entity
project = run.project
run_id = run.id
# Note that api.run() returns a different type of object than wandb.init().
api = wandb.Api()
api_run = api.run(f"{username}/{project}/{run_id}")
api_run.config["bar"] = 32
api_run.update()
```
## Highlight config values
Pin config keys to the **References** section at the top of a run's overview page.
Use [`wandb.Run.pin_config_keys`](/models/ref/python/experiments/run#method-run-pin_config_keys) to pin one or more config keys with the Python SDK.
For example, if you use a Grafana dashboard to monitor training runs, add the dashboard URL to your config and pin the `grafana_url` key:
```python theme={null}
config = {
"hidden_layer_sizes": [32, 64],
"kernel_sizes": [3],
"activation": "ReLU",
"pool_sizes": [2],
"dropout": 0.5,
"num_classes": 10,
"grafana_url": "[Grafana dashboard](https://my-grafana-instance.com/)"
}
with wandb.init(config=config) as run:
# Add the "grafana_url" config key to the References section.
run.pin_config_keys(["grafana_url"])
```
## View config values
Access your config values in the W\&B App, during a run, or from existing runs. You can also access config values from your local filesystem.
View a run configuration in the W\&B App:
1. Navigate to your project in the W\&B App.
2. Select the run you want to view.
3. Select the **Overview** tab.
4. Scroll to the **Config** section.
5. Optional: Click **View raw data** to view the configuration as JSON.
The raw JSON format is useful when you write expressions to create or transform line plots from config values, logged metrics, or summary values. See [Expressions](/models/app/features/panels/line-plot/reference#expressions) for more details.
Use the [`wandb.Run.config`](/models/ref/python/experiments/run#property-config) property to access a run's configuration values during a run. `wandb.Run.config` returns a dictionary object that contains the configuration key-value pairs.
The following example shows how to access a run's configuration values during a run. Replace the values in the config dictionary with your own hyperparameters, model architecture, dataset name, and other settings. Replace `""` with your W\&B project name:
```python theme={null}
import wandb
config = {
"epochs": 100,
"learning_rate": 0.001,
"model_type": "CNN",
"dataset_id": "cats-0192"
}
with wandb.init(project="", config=config) as run:
print(dict(run.config))
```
The following snippet shows an example of what your terminal output might look like when you run the code above:
```shell theme={null}
{'_runtime': 0.0970615, '_step': 97, 'accuracy': 0.9746484067793967, 'loss': 0.025044765547545846, '_timestamp': 1785255343.65151}
```
Use the W\&B Public API to access the configuration of a previously logged run. Pass the entity, project name, and run ID to `wandb.Api.run()`, and then access the run’s configuration with the wandb.Api.Run.config property.
Replace `""`, `""`, and `""` in the following example with your W\&B entity, project name, and run ID.
```python theme={null}
import wandb
api = wandb.Api()
run = api.run("//")
print(run.name)
print(run.config)
```
To access configuration values for multiple runs in a project, use `wandb.Api.runs()` to retrieve the runs, and then iterate over the returned Run objects:
```python theme={null}
import wandb
api = wandb.Api()
runs = api.runs("/")
for run in runs:
print(f"Run name: {run.name}")
print(f"Run ID: {run.id}")
print(f"Run config: {run.config}")
print("----------")
```
The following snippet shows an example of what your terminal output might look like when you run the code above:
```shell theme={null}
Run name: clean-oath-11
Run ID: mt2dasoz
Run config: {'epochs': 1000, 'learning_rate': 0.1, 'model_type': 'Multivariate_neural_network_classifier'}
----------
Run name: zesty-snowball-7
Run ID: qne08r7u
Run config: {'epochs': 1000, 'learning_rate': 0.1, 'model_type': 'Multivariate_neural_network_classifier'}
----------
```
W\&B stores run configuration values in the `config.yaml` file in the run directory. To read the config values locally, open the `config.yaml` file.
By default, the run directory is located at `./wandb/run--`.
## File-Based Configs
If you place a file named `config-defaults.yaml` in the same directory as your run script, the run automatically picks up the key-value pairs defined in the file and passes them to `wandb.Run.config`.
The following code snippet shows a sample `config-defaults.yaml` YAML file:
```yaml theme={null}
batch_size:
desc: Size of each mini-batch
value: 32
```
You can override the default values automatically loaded from `config-defaults.yaml` by setting updated values in the `config` argument of `wandb.init()`. For example:
```python theme={null}
import wandb
# Override config-defaults.yaml by passing custom values
with wandb.init(config={"epochs": 200, "batch_size": 64}) as run:
...
```
To load a configuration file other than `config-defaults.yaml`, use the `--configs command-line` argument and specify the path to the file:
```bash theme={null}
python train.py --configs other-config.yaml
```
### Example use case for file-based configs
Suppose you have a YAML file with some metadata for the run, and then a dictionary of hyperparameters in your Python script. You can save both in the nested `config` object:
```python theme={null}
hyperparameter_defaults = dict(
dropout=0.5,
batch_size=100,
learning_rate=0.001,
)
config_dictionary = dict(
yaml=my_yaml_file,
params=hyperparameter_defaults,
)
with wandb.init(config=config_dictionary) as run:
...
```
## TensorFlow v1 flags
You can pass TensorFlow flags into the `wandb.Run.config` object directly.
```python theme={null}
with wandb.init() as run:
run.config.epochs = 4
flags = tf.app.flags
flags.DEFINE_string("data_dir", "/tmp/data")
flags.DEFINE_integer("batch_size", 128, "Batch size.")
run.config.update(flags.FLAGS) # add tensorflow flags as config
```