### Run a Sacred Hello World Experiment from CLI

Source: https://sacred.readthedocs.io/en/stable/index.html/quickstart

This shows the command-line execution and output of the minimal Sacred experiment. It demonstrates how Sacred logs information about the run, including start and completion times.

```CLI Output
> python h01_hello_world.py
INFO - 01_hello_world - Running command 'my_main'
INFO - 01_hello_world - Started
Hello world!
INFO - 01_hello_world - Completed after 0:00:00
```

--------------------------------

### Install Sacred via pip

Source: https://sacred.readthedocs.io/en/stable/index.html/quickstart

This command installs the Sacred library directly from PyPI using pip, the Python package installer. It's the simplest way to get started with Sacred.

```Shell
pip install sacred
```

--------------------------------

### Install Sacred from Git Repository

Source: https://sacred.readthedocs.io/en/stable/index.html/quickstart

These commands clone the Sacred project from its GitHub repository and then install it locally. This method is useful for developers or if you need a specific version not available on PyPI.

```Shell
git clone https://github.com/IDSIA/sacred.git
cd sacred
[sudo] python setup.py install
```

--------------------------------

### Run a Minimal Sacred Hello World Experiment

Source: https://sacred.readthedocs.io/en/stable/index.html/examples

This is a minimal example of a Sacred experiment. It demonstrates the basic setup and execution, printing 'Hello world!' along with some logging information. The log-level can be controlled using the `-l` argument.

```Shell
$ ./01_hello_world.py
WARNING - 01_hello_world - No observers have been added to this run
INFO - 01_hello_world - Running command 'main'
INFO - 01_hello_world - Started
Hello world!
INFO - 01_hello_world - Completed after 0:00:00
```

```Shell
$ ./01_hello_world.py -l WARNING
WARNING - 01_hello_world - No observers have been added to this run
Hello world!
```

--------------------------------

### Create a Minimal Sacred Experiment

Source: https://sacred.readthedocs.io/en/stable/index.html/quickstart

This Python code defines a basic Sacred experiment. It imports `Experiment`, creates an instance, and uses `@ex.automain` to designate the main function that will be executed when the script runs.

```Python
from sacred import Experiment

ex = Experiment()

@ex.automain
def my_main():
    print('Hello world!')
```

--------------------------------

### Configure Sacred Experiment Message with Dictionary

Source: https://sacred.readthedocs.io/en/stable/index.html/examples

This example shows how to configure a 'Hello World' experiment using a dictionary with `ex.add_config`. The message can be easily changed via the `with` command-line argument.

```Shell
$ ./02_hello_config_dict.py
WARNING - 02_hello_config_dict - No observers have been added to this run
INFO - 02_hello_config_dict - Running command 'main'
INFO - 02_hello_config_dict - Started
Hello world!
INFO - 02_hello_config_dict - Completed after 0:00:00
```

```Shell
$ ./02_hello_config_dict.py with message='Ciao world!'
WARNING - 02_hello_config_dict - No observers have been added to this run
INFO - 02_hello_config_dict - Running command 'main'
INFO - 02_hello_config_dict - Started
Ciao world!
INFO - 02_hello_config_dict - Completed after 0:00:00
```

--------------------------------

### Define a Sacred Experiment with Configuration

Source: https://sacred.readthedocs.io/en/stable/index.html/quickstart

This Python code extends the basic experiment by adding a configuration. The `@ex.config` decorator defines a function where configuration variables like `recipient` and `message` are set, which can then be accessed by the main function.

```Python
from sacred import Experiment

ex = Experiment('hello_config')

@ex.config
def my_config():
    recipient = "world"
    message = "Hello %s!" % recipient

@ex.automain
def my_main(message):
    print(message)
```

--------------------------------

### Override Sacred Configuration from CLI

Source: https://sacred.readthedocs.io/en/stable/index.html/quickstart

This command shows how to dynamically change configuration parameters of a Sacred experiment directly from the command line using the `with` keyword. This allows for flexible experimentation without modifying the source code.

```CLI Output
> python hello_config.py with recipient="that is cool"
INFO - hello_config - Running command 'my_main'
INFO - hello_config - started
Hello that is cool!
INFO - hello_config - finished after 0:00:00.
```

--------------------------------

### Print Sacred Experiment Configuration from CLI

Source: https://sacred.readthedocs.io/en/stable/index.html/quickstart

This command-line interaction demonstrates how to inspect the configuration of a Sacred experiment. Sacred automatically collects variables defined in `@ex.config` functions and makes them visible via the `print_config` command.

```CLI Output
> python hello_config.py print_config
INFO - hello_config - Running command 'print_config'
INFO - hello_config - started
Configuration:
  message = 'Hello world!'
  recipient = 'world'
  seed = 746486301
INFO - hello_config - finished after 0:00:00.
```

--------------------------------

### Run Docker Compose for Sacred Services

Source: https://sacred.readthedocs.io/en/stable/index.html/examples

This command starts all services defined in the `docker-compose.yml` file, including MongoDB, mongo-express, Sacredboard, and Omniboard. It pulls necessary images and builds containers, which may take several minutes. After execution, MongoDB, mongo-express (port 8081), Sacredboard (port 5000), and Omniboard (port 9000) should be accessible.

```Shell
docker-compose up
```

--------------------------------

### Configure Sacred Experiment Message with ConfigScope

Source: https://sacred.readthedocs.io/en/stable/index.html/examples

This example demonstrates configuring a 'Hello World' experiment using Sacred's special `ConfigScope`. Similar to `hello_config_dict`, the message can be changed with the `with` command-line argument, but `ConfigScope` also allows modifying individual components like the recipient.

```Shell
$ ./03_hello_config_scope.py
WARNING - hello_cs - No observers have been added to this run
INFO - hello_cs - Running command 'main'
INFO - hello_cs - Started
Hello world!
INFO - hello_cs - Completed after 0:00:00
```

```Shell
$ ./03_hello_config_scope.py with message='Ciao world!'
WARNING - hello_cs - No observers have been added to this run
INFO - hello_cs - Running command 'main'
INFO - hello_cs - Started
Ciao world!
INFO - hello_cs - Completed after 0:00:00
```

```Shell
$ ./03_hello_config_scope.py with recipient='Bob'
WARNING - hello_cs - No observers have been added to this run
INFO - hello_cs - Running command 'main'
INFO - hello_cs - Started
Hello Bob!
INFO - hello_cs - Completed after 0:00:00
```

--------------------------------

### Sacred Custom Command 'greet' with Parameter Override Output

Source: https://sacred.readthedocs.io/en/stable/index.html/examples

Demonstrates overriding a parameter for the 'greet' command using the 'with' flag, showing how command arguments can be customized at runtime.

```Shell
$ ./05_my_commands.py greet with name='Jane' -l WARNING
WARNING - my_commands - No observers have been added to this run
Hello Jane! Nice to greet you!

```

--------------------------------

### Install Neptune Client and Sacred Integration

Source: https://sacred.readthedocs.io/en/stable/index.html/observers

This command installs the necessary Python packages, `neptune-client` and `neptune-sacred`, required to integrate Neptune with Sacred experiments. These packages enable sending experiment metadata and tracking information to the Neptune UI.

```Bash
pip install neptune-client neptune-sacred
```

--------------------------------

### MongoDB Sacred Run Collection Example Entry

Source: https://sacred.readthedocs.io/en/stable/index.html/observers

This snippet shows an example document structure stored in the `runs` collection by Sacred's `MongoObserver`. It includes experiment metadata, configuration, host information, and captured output.

```MongoDB
> db.runs.find()[0]
{
    "_id" : ObjectId("5507248a1239672ae04591e2"),
    "format" : "MongoObserver-0.7.0",
    "status" : "COMPLETED",
    "result" : null,
    "start_time" : ISODate("2016-07-11T14:50:14.473Z"),
    "heartbeat" : ISODate("2015-03-16T19:44:26.530Z"),
    "stop_time" : ISODate("2015-03-16T19:44:26.532Z"),
    "config" : {
        "message" : "Hello world!",
        "seed" : 909032414,
        "recipient" : "world"
    },
    "info" : { },
    "resources" : [ ],
    "artifacts" : [ ],
    "captured_out" : "Hello world!\n",
    "experiment" : {
        "name" : "hello_cs",
        "base_dir" : "$(HOME)/sacred/examples/"
        "dependencies" : ["numpy==1.9.1", "sacred==0.7.0"],
        "sources" : [
            [
                "03_hello_config_scope.py",
                ObjectId("5507248a1239672ae04591e3")
            ]
        ],
        "repositories" : [{
            "url" : "git@github.com:IDSIA/sacred.git"
                            "dirty" : false,
                            "commit" : "d88deb2555bb311eb779f81f22fe16dd3b703527"}]
    },
    "host" : {
        "os" : ["Linux",
                "Linux-3.13.0-46-generic-x86_64-with-Ubuntu-14.04-trusty"],
        "cpu" : "Intel(R) Core(TM) i7-3770 CPU @ 3.40GHz",
        "hostname" : "MyAwesomeMachine",
        "python_version" : "3.4.0"
    }
}
```

--------------------------------

### Sacred Captured Functions Execution Output

Source: https://sacred.readthedocs.io/en/stable/index.html/examples

Demonstrates the output when running a Sacred experiment with captured functions, showing how parameters are automatically filled from configuration or can be explicitly overridden.

```Shell
$ ./04_captured_functions.py -l WARNING
WARNING - captured_functions - No observers have been added to this run
This is printed by function foo.
This is printed by function bar.
Overriding the default message for foo.

```

--------------------------------

### Sacred Custom Command 'greet' Execution Output

Source: https://sacred.readthedocs.io/en/stable/index.html/examples

Shows the command-line output when executing the 'greet' custom command defined in a Sacred experiment, illustrating basic command invocation.

```Shell
$ ./05_my_commands.py greet
WARNING - my_commands - No observers have been added to this run
INFO - my_commands - Running command 'greet'
INFO - my_commands - Started
Hello John! Nice to greet you!
INFO - my_commands - Completed after 0:00:00

```

--------------------------------

### Define Sacred Experiment for Config Updates

Source: https://sacred.readthedocs.io/en/stable/index.html/configuration

Sets up a foundational Sacred experiment with a configuration scope and a main function. This setup is used as a base to demonstrate subsequent examples of updating configuration entries during experiment runs.

```Python
from sacred import Experiment
ex = Experiment('config_demo')

@ex.config
def my_config():
    a = 10
    foo = {
        'a_squared': a**2,
        'bar': 'my_string%d' % a
    }
    if a > 8:
        e = a/2

@ex.main
def run():
    pass
```

--------------------------------

### Queue Flag

Source: https://sacred.readthedocs.io/en/stable/index.html/command_line

The `-q` or `--queue` flag prevents the experiment from running immediately, instead creating an entry in the database with a `QUEUED` status. This entry contains all experiment and configuration information, facilitating distributed worker setups to fetch and start queued runs.

```APIDOC
-q: Only queue this run, do not start it.
--queue: Only queue this run, do not start it.
```

--------------------------------

### Run Sacred Experiment with Named Configuration

Source: https://sacred.readthedocs.io/en/stable/index.html/configuration

These examples show how to execute a Sacred experiment, applying a specific named configuration ('variant1') either from the command line using the 'with' keyword or programmatically via the `ex.run()` method.

```shell
$ python named_configs_demo.py with variant1
```

```python
>> ex.run(named_configs=['variant1'])
```

--------------------------------

### Sacred Randomness with Fixed Seed Execution Output

Source: https://sacred.readthedocs.io/en/stable/index.html/examples

Shows the output of a Sacred experiment run multiple times with a fixed seed, demonstrating how Sacred ensures reproducible results by controlling randomness.

```Shell
:$ ./06_randomness.py with seed=12345 -l WARNING
[57]
[28]
695891797
[82]

```

--------------------------------

### Sacred Main Command Execution Output

Source: https://sacred.readthedocs.io/en/stable/index.html/examples

Illustrates that the main function of a Sacred experiment is also treated as a command, showing its default execution output when explicitly called.

```Shell
$ ./05_my_commands.py main
WARNING - my_commands - No observers have been added to this run
INFO - my_commands - Running command 'main'
INFO - my_commands - Started
This is just the main command. Try greet or shout.
INFO - my_commands - Completed after 0:00:00

```

--------------------------------

### Run Sacred Experiment with Named Configuration File

Source: https://sacred.readthedocs.io/en/stable/index.html/configuration

These examples illustrate how to run a Sacred experiment, applying a configuration from an external file ('my_variant.json') as a named configuration, either from the command line or programmatically.

```shell
$ python named_configs_demo.py with my_variant.json
```

```python
>> ex.run(named_configs=['my_variant.json'])
```

--------------------------------

### Sacred Custom Command 'shout' Execution Output

Source: https://sacred.readthedocs.io/en/stable/index.html/examples

Shows the command-line output when executing the 'shout' custom command defined in a Sacred experiment, demonstrating another custom command's behavior.

```Shell
$ ./05_my_commands.py shout
WARNING - my_commands - No observers have been added to this run
INFO - my_commands - Running command 'shout'
INFO - my_commands - Started
WHAZZZUUUUUUUUUUP!!!????
INFO - my_commands - Completed after 0:00:00

```

--------------------------------

### Example: Sacred Experiment Automain Usage

Source: https://sacred.readthedocs.io/en/stable/index.html/apidoc

This Python example demonstrates how to use the `@ex.main` decorator in conjunction with `if __name__ == '__main__': ex.run_commandline()` to define and automatically execute the main function of a Sacred experiment.

```Python
@ex.main
def my_main():
    pass

if __name__ == '__main__':
    ex.run_commandline()
```

--------------------------------

### Install Python Telegram Bot for Telegram Observer

Source: https://sacred.readthedocs.io/en/stable/index.html/observers

This command installs or upgrades the `python-telegram-bot` library, which is a prerequisite for using the `TelegramObserver` in Sacred experiments. It ensures the necessary dependencies are available for interacting with the Telegram Bot API.

```Bash
pip install --upgrade python-telegram-bot
```

--------------------------------

### Configure Sacred Global Settings in Python

Source: https://sacred.readthedocs.io/en/stable/index.html/settings

Demonstrates how to modify Sacred's global settings using both dictionary-style and attribute-style notation. This example specifically shows how to disable the collection of GPU information during host info gathering, which can reduce startup time.

```python
from sacred import SETTINGS
SETTINGS['HOST_INFO']['INCLUDE_GPU_INFO'] = False
SETTINGS.HOST_INFO.INCLUDE_GPU_INFO = False  # equivalent
```

--------------------------------

### Sacred Tensorflow LogFileWriter: Context Manager Example

Source: https://sacred.readthedocs.io/en/stable/index.html/tensorflow

This Python example illustrates using `sacred.stflow.LogFileWriter` as a context manager (`with LogFileWriter(ex):`). It demonstrates that `tensorflow.summary.FileWriter` instances created *within* the `with` block (`/tmp/1`, `./test`) are captured, while those created *outside* the block (`./nothing`) are not. The experiment must be in the RUNNING state for paths to be captured.

```python
ex = Experiment("my experiment")
def run_experiment(_run):
    with tf.Session() as s:
        with LogFileWriter(ex):
            swr = tf.summary.FileWriter("/tmp/1", s.graph)
            # _run.info["tensorflow"]["logdirs"] == ["/tmp/1"]
            swr3 = tf.summary.FileWriter("./test", s.graph)
            # _run.info["tensorflow"]["logdirs"] == ["/tmp/1", "./test"]
        # This is called outside the scope and won't be captured
        swr3 = tf.summary.FileWriter("./nothing", s.graph)
        # Nothing has changed:
        # _run.info["tensorflow"]["logdirs"] == ["/tmp/1", "./test"]

```

--------------------------------

### Example TinyDbObserver Metadata JSON Structure

Source: https://sacred.readthedocs.io/en/stable/index.html/observers

Provides a sample JSON structure for the `metadata.json` file, detailing the various fields stored for each experiment run, such as experiment configuration, host information, dependencies, and run status. Special tags like `{TinyDate}` and `{TinyFile}` indicate data converted upon reading.

```JSON
{
  "_id": "2118c70ef274497f90b7eb72dcf34598",
  "artifacts": [],
  "captured_out": "",
  "command": "run",
  "config": {
    "C": 1,
    "gamma": 0.7,
    "seed": 191164913
  },
  "experiment": {
    "base_dir": "/Users/chris/Dropbox/projects/dev/sacred-tinydb",
    "dependencies": [
      "IPython==5.1.0",
      "numpy==1.11.2",
      "sacred==0.7b0",
      "sklearn==0.18"
    ],
    "name": "iris_rbf_svm",
    "repositories": [],
    "sources": [
      [
        "test_exp.py",
        "6f4294124f7697655f9fd1f7d4e7798b",
        "{TinyFile}:\"6f4294124f7697655f9fd1f7d4e7798b\""
      ]
    ]
  },
  "format": "TinyDbObserver-0.7b0",
  "heartbeat": "{TinyDate}:2016-11-12T01:18:00.228352",
  "host": {
    "cpu": "Intel(R) Core(TM)2 Duo CPU     P8600  @ 2.40GHz",
    "hostname": "phoebe",
    "os": [
      "Darwin",
      "Darwin-15.5.0-x86_64-i386-64bit"
    ],
    "python_version": "3.5.2"
  },
  "info": {},
  "meta": {},
  "resources": [],
  "result": 0.9833333333333333,
  "start_time": "{TinyDate}:2016-11-12T01:18:00.197311",
  "status": "COMPLETED",
  "stop_time": "{TinyDate}:2016-11-12T01:18:00.337519"
}
```

--------------------------------

### TinyDB Observer Flag

Source: https://sacred.readthedocs.io/en/stable/index.html/command_line

The `-t BASEDIR` or `--tiny_db=BASEDIR` flag adds a TinyDB observer to your experiment. `BASEDIR` specifies the directory for storing experiment files. This flag requires the `tinydb`, `tinydb-serialization`, and `hashfs` packages to be installed.

```APIDOC
-t BASEDIR: add a TinyDB observer
--tiny_db=BASEDIR: add a TinyDB observer
```

--------------------------------

### Implement Sacred Configuration Hook for Experiment Initialization

Source: https://sacred.readthedocs.io/en/stable/index.html/ingredients

This example demonstrates how to define and use a `config_hook` in Sacred. Configuration hooks are executed during experiment initialization to update the experiment's configuration before any commands are run, taking `config`, `command_name`, and `logger` as arguments.

```python
ex = Experiment()

@ex.config_hook
def hook(config, command_name, logger):
    config.update({'hook': True})
    return config

@ex.automain
def main(hook, other_config):
    do_stuff()
```

--------------------------------

### MongoDB Sacred File Storage Collection Example Entry

Source: https://sacred.readthedocs.io/en/stable/index.html/observers

This snippet illustrates an example document from the `fs.files` collection, used by Sacred's `MongoObserver` to store associated files like experiment source code, including filename, MD5 hash, and upload date.

```MongoDB
> db.fs.files.find()[0]
{
    "_id" : ObjectId("5507248a1239672ae04591e3"),
    "filename" : "$(HOME)/sacred/examples/03_hello_config_scope.py",
    "md5" : "897b2144880e2ee8e34775929943f496",
    "chunkSize" : 261120,
    "length" : 1526,
    "uploadDate" : ISODate("2016-07-11T12:50:14.522Z")
}
```

--------------------------------

### Sacred Randomness with Fixed Seed and Varying Numbers Parameter Output

Source: https://sacred.readthedocs.io/en/stable/index.html/examples

Demonstrates how varying a parameter while keeping the seed fixed affects only the relevant parts of the output, showing the independence of function calls in Sacred's randomness model.

```Shell
:$ ./06_randomness.py with seed=12345 numbers=3 -l WARNING
[57, 79, 86]
[28, 90, 92]
695891797
[82, 9, 3]

```

--------------------------------

### Sacred Randomness with Fixed Seed, Reverse, and Numbers Parameters Output

Source: https://sacred.readthedocs.io/en/stable/index.html/examples

Illustrates that different function calls do not interfere with one another when parameters like 'reverse' are changed, maintaining deterministic results with a fixed seed across various configurations.

```Shell
:$ ./06_randomness.py with seed=12345 reverse=True numbers=3 -l WARNING
695891797
[57, 79, 86]
[28, 90, 92]
[82, 9, 3]

```

--------------------------------

### Sacred Run: start_time attribute

Source: https://sacred.readthedocs.io/en/stable/index.html/apidoc

The datetime when this run was started.

```APIDOC
`start_time` = None
  Description: The datetime when this run was started
```

--------------------------------

### Log Scalar Metrics in Sacred Experiments

Source: https://sacred.readthedocs.io/en/stable/index.html/collected_information

This Python example demonstrates how to use `_run.log_scalar` and `ex.log_scalar` within a Sacred experiment to track numerical metrics. It shows logging with an explicit step counter (incrementing by 2 for 'training.loss') and an implicit step counter (automatically incrementing by 1 for 'training.accuracy' and 'training.diff'). The example simulates an experiment loop, logging values periodically.

```python
@ex.automain
def example_metrics(_run):
    counter = 0
    while counter < 20:
        counter+=1
        value = counter
        ms_to_wait = random.randint(5, 5000)
        time.sleep(ms_to_wait/1000)
        # This will add an entry for training.loss metric in every second iteration.
        # The resulting sequence of steps for training.loss will be 0, 2, 4, ...
        if counter % 2 == 0:
           _run.log_scalar("training.loss", value * 1.5, counter)
        # Implicit step counter (0, 1, 2, 3, ...)
        # incremented with each call for training.accuracy:
        _run.log_scalar("training.accuracy", value * 2)
        # Another option is to use the Experiment object (must be running)
        # The training.diff has its own step counter (0, 1, 2, ...) too
        ex.log_scalar("training.diff", value * 2)
```

--------------------------------

### Add SqlObserver to Sacred Experiment

Source: https://sacred.readthedocs.io/en/stable/index.html/observers

Explains how to integrate a SqlObserver with Sacred experiments, either via command-line flags or directly in Python code. It requires the `sqlalchemy` package to be installed and a valid database URL for connection.

```Shell
./my_experiment.py -s DB_URL
./my_experiment.py --sql=DB_URL
```

```Python
from sacred.observers import SqlObserver

ex.observers.append(SqlObserver('sqlite:///foo.db'))

# It's also possible to instantiate a SqlObserver with an existing
# engine and session with:
ex.observers.append(SqlObserver.create_from(my_engine, my_session))
```

```APIDOC
sacred.observers.SqlObserver:
  description: Saves all relevant experiment information in a set of SQL tables.
  dependencies: sqlalchemy
  __init__(db_url: str):
    db_url: A URL specifying the dialect and server of the SQL database to connect to. Examples: 'postgresql://scott:tiger@localhost/mydatabase', 'mysql://scott:tiger@localhost/foo', 'sqlite:///foo.db'.
  create_from(engine, session):
    description: Instantiates a SqlObserver with an existing SQLAlchemy engine and session.
    parameters:
      engine: An existing SQLAlchemy engine.
      session: An existing SQLAlchemy session.
```

--------------------------------

### SQL Observer Flag

Source: https://sacred.readthedocs.io/en/stable/index.html/command_line

The `-s DB_URL` or `--sql=DB_URL` flag adds a SQL observer to your experiment. `DB_URL` must be a valid SQLAlchemy parseable string, typically in the form `dialect://username:password@host:port/database`. This flag requires the `sqlalchemy` package to be installed.

```APIDOC
-s DB_URL: add a SQL observer
--sql=DB_URL: add a SQL observer
```

--------------------------------

### Sacred Run: pdb attribute

Source: https://sacred.readthedocs.io/en/stable/index.html/apidoc

If true the pdb debugger is automatically started after a failure.

```APIDOC
`pdb` = None
  Description: If true the pdb debugger is automatically started after a failure
```

--------------------------------

### Access Sacred Ingredient Configuration in ConfigScopes and Captured Functions

Source: https://sacred.readthedocs.io/en/stable/index.html/ingredients

This example shows how to retrieve the configuration of a used Ingredient from Sacred's ConfigScopes and captured functions. The ingredient's configuration is accessed directly by its name.

```python
@ex.config
def cfg(dataset):  # name of the ingredient here
    abs_filename = os.path.abspath(dataset['filename'])  # access 'filename'

@ex.capture
def some_function(dataset):   # name of the ingredient here
    if dataset['normalize']:  # access 'normalize'
        print("Dataset was normalized")
```

--------------------------------

### Sacred Tensorflow LogFileWriter: Decorator Example

Source: https://sacred.readthedocs.io/en/stable/index.html/tensorflow

This Python example demonstrates using `sacred.stflow.LogFileWriter` as a decorator (`@LogFileWriter(ex)`) on an `ex.automain` function. It shows how `tensorflow.summary.FileWriter` instances created within the decorated function automatically have their log paths (`/tmp/1`, `./test`) captured and stored in `_run.info["tensorflow"]["logdirs"]`. The experiment must be in the RUNNING state for paths to be captured.

```python
from sacred.stflow import LogFileWriter
from sacred import Experiment
import tensorflow as tf

ex = Experiment("my experiment")

@ex.automain
@LogFileWriter(ex)
def run_experiment(_run):
    with tf.Session() as s:
        swr = tf.summary.FileWriter("/tmp/1", s.graph)
        # _run.info["tensorflow"]["logdirs"] == ["/tmp/1"]
        swr2 = tf.summary.FileWriter("./test", s.graph)
        #_run.info["tensorflow"]["logdirs"] == ["/tmp/1", "./test"]

```

--------------------------------

### Default Logging Output for Sacred Experiments

Source: https://sacred.readthedocs.io/en/stable/index.html/logging

This snippet shows the default console output when running a Sacred experiment, including INFO level log messages from the `hello_world.py` example. It illustrates the verbose logging behavior before any adjustments are made.

```Shell
>> python hello_world.py
INFO - hello_world - Running command 'main'
INFO - hello_world - Started
Hello world!
INFO - hello_world - Completed after 0:00:00
```

--------------------------------

### TinyDbObserver Hashed File Path Example

Source: https://sacred.readthedocs.io/en/stable/index.html/observers

Demonstrates the hierarchical directory structure used by the `hashfs/` component to store files based on their content hash. The first 6 characters of the hash are used to create three nested directories, with the rest forming the filename.

```Text
my_runs/
    metadata.json
    hashfs/
        59/
            ab/
                16/
                    5b3579a1869399b4838be2a125
```

--------------------------------

### Define Captured Functions in Sacred with @ex.capture

Source: https://sacred.readthedocs.io/en/stable/index.html/configuration

This Python example shows how to define a 'captured function' using `@ex.capture`. Sacred automatically injects configuration values ('a', 'b') into `print_a_and_b` even when no arguments are explicitly passed during its call from `my_main`.

```python
ex = Experiment('captured_func_demo2')

@ex.config
def my_config1():
    a = 10
    b = 'test'

@ex.capture
def print_a_and_b(a, b):
    print("a =", a)
    print("b =", b)

@ex.automain
def my_main():
    print_a_and_b()
```

--------------------------------

### Add S3Observer to Sacred Experiment

Source: https://sacred.readthedocs.io/en/stable/index.html/observers

Details how to configure an S3Observer for Sacred, which stores run information in a designated prefix location within an S3 bucket. It requires `boto3` to be installed and AWS credentials configured (e.g., via `aws configure`).

```Python
from sacred.observers import S3Observer
ex.observers.append(S3Observer(bucket='my-awesome-bucket',
                               basedir='/my-project/my-cool-experiment/'))
```

```APIDOC
sacred.observers.S3Observer:
  description: Stores run information in a designated prefix location within an S3 bucket.
  dependencies: boto3, AWS config file with credentials.
  __init__(bucket: str, basedir: str, region: str = None):
    bucket: The name of the S3 bucket.
    basedir: The base directory within the S3 bucket (e.g., '/my-project/my-cool-experiment/').
    region: (Optional) The AWS region. If not provided, uses the region set in your AWS config file. Will error if not set in config and not provided.
```

--------------------------------

### Execute a Custom Command on a Sacred Ingredient

Source: https://sacred.readthedocs.io/en/stable/index.html/ingredients

This command-line example shows how to invoke a custom command defined within a Sacred Ingredient. Using dotted notation (`dataset.stats`), the `stats` command of the `data_ingredient` is executed, printing the dataset statistics as defined in the ingredient's command function.

```shell
>> ./my_experiment dataset.stats
INFO - my_experiment - Running command 'dataset.stats'
INFO - my_experiment - Started
Statistics for dataset "my_dataset.npy":
mean = 13.37
INFO - my_experiment - Completed after 0:00:00
```

--------------------------------

### Creating a Basic Sacred Experiment

Source: https://sacred.readthedocs.io/en/stable/index.html/experiment

Demonstrates the fundamental way to instantiate a Sacred `Experiment` object and define its main function using the `@ex.main` decorator. This sets up the entry point for the experiment's execution.

```Python
from sacred import Experiment
ex = Experiment()

@ex.main
def my_main():
    pass

```

--------------------------------

### Capture Functions for Automatic Parameter Resolution in Sacred

Source: https://sacred.readthedocs.io/en/stable/index.html/experiment

This example illustrates how Sacred's @ex.capture decorator allows functions to automatically receive configuration values as parameters. When a captured function is called, Sacred attempts to fill missing arguments from the experiment's configuration. It shows various call patterns and how configuration values override default function parameters.

```Python
from sacred import Experiment
ex = Experiment('my_experiment')

@ex.config
def my_config():
    foo = 42
    bar = 'baz'

@ex.capture
def some_function(a, foo, bar=10):
    print(a, foo, bar)

@ex.main
def my_main():
    some_function(1, 2, 3)     #  1  2   3
    some_function(1)           #  1  42  'baz'
    some_function(1, bar=12)   #  1  42  12
    some_function()            #  TypeError: missing value for 'a'

```

--------------------------------

### Sacred: View Experiment Dependencies and Source Files

Source: https://sacred.readthedocs.io/en/stable/index.html/command_line

Explains the `print_dependencies` command, which provides an overview of an experiment's package dependencies, source files with their MD5 hashes, and version control status (e.g., git repository, commit hash, and dirty status).

```Shell
>> ./03_hello_config_scope.py print_dependencies
INFO - hello_cs - Running command 'print_dependencies'
INFO - hello_cs - Started
Dependencies:
  numpy                == 1.11.0
  sacred               == 0.7.0

Sources:
  03_hello_config_scope.py                     53cee32c9dc77870f7b39622434aff85

Version Control:
M git@github.com:IDSIA/sacred.git              bcdde712957570606ec5087b1748c60a89bb89e0

INFO - hello_cs - Completed after 0:00:00
```

--------------------------------

### Sacred `sacred.run.Run` Class API Reference

Source: https://sacred.readthedocs.io/en/stable/index.html/apidoc

This section provides the full API documentation for the `sacred.run.Run` class. It details the constructor parameters, available methods for managing experiment artifacts, resources, and logging, and properties that expose various aspects of the run's state and configuration.

```APIDOC
class sacred.run.Run(config, config_modifications, main_function, observers, root_logger, run_logger, experiment_info, host_info, pre_run_hooks, post_run_hooks, captured_out_filter=None)
  Description: Represent and manage a single run of an experiment.

  Methods:
    __call__(*args)
      Description: Start this run.
      Parameters:
        *args: parameters passed to the main function
      Returns: the return value of the main function

    add_artifact(filename, name=None, metadata=None, content_type=None)
      Description: Add a file as an artifact. In Sacred terminology an artifact is a file produced by the experiment run. In case of a MongoObserver that means storing the file in the database. See also sacred.Experiment.add_artifact().
      Parameters:
        filename (str): name of the file to be stored as artifact
        name (str, optional): optionally set the name of the artifact. Defaults to the filename.
        metadata (dict): optionally attach metadata to the artifact. This only has an effect when using the MongoObserver.
        content_type (str, optional): optionally attach a content-type to the artifact. This only has an effect when using the MongoObserver.

    add_resource(filename)
      Description: Add a file as a resource. In Sacred terminology a resource is a file that the experiment needed to access during a run. In case of a MongoObserver that means making sure the file is stored in the database (but avoiding duplicates) along its path and md5 sum. See also sacred.Experiment.add_resource().
      Parameters:
        filename (str): name of the file to be stored as a resource

    log_scalar(metric_name, value, step=None)
      Description: Add a new measurement. The measurement will be processed by the MongoDB observer during a heartbeat event. Other observers are not yet supported.
      Parameters:
        metric_name: The name of the metric, e.g. training.loss
        value: The measured value
        step: The step number (integer), e.g. the iteration number. If not specified, an internal counter for each metric is used, incremented by one.

  Properties:
    beat_interval: The time between two heartbeat events measured in seconds
    capture_mode: Determines the way the stdout/stderr are captured
    captured_out: Captured stdout and stderr
    captured_out_filter: Filter function to be applied to captured output
    config: The final configuration used for this run
    config_modifications: A ConfigSummary object with information about config changes
    debug: Determines whether this run is executed in debug mode
    experiment_info: A dictionary with information about the experiment
    fail_trace: A stacktrace, in case the run failed
    force: Disable warnings about suspicious changes
    host_info: A dictionary with information about the host
    info: Custom info dict that will be sent to the observers
```

--------------------------------

### Sacred Global Configuration Options Reference

Source: https://sacred.readthedocs.io/en/stable/index.html/settings

A comprehensive reference of all currently available configuration options within Sacred's `SETTINGS` object. Each entry details its purpose, default value, and potential impact on experiment behavior, covering aspects like stdout/stderr capture, configuration key validation, host information collection, and command-line argument parsing.

```APIDOC
CAPTURE_MODE (default: 'fd' (linux/osx) or 'sys' (windows)): configure how stdout/stderr are captured. ['no', 'sys', 'fd']
CONFIG:
  ENFORCE_KEYS_MONGO_COMPATIBLE (default: True): Make sure all config keys are compatible with MongoDB.
  ENFORCE_KEYS_JSONPICKLE_COMPATIBLE (default: True): Make sure all config keys are serializable with jsonpickle. IMPORTANT: Only deactivate if you know what you’re doing.
  ENFORCE_VALID_PYTHON_IDENTIFIER_KEYS (default: False): Make sure all config keys are valid python identifiers.
  ENFORCE_STRING_KEYS (default: False): Make sure all config keys are strings.
  ENFORCE_KEYS_NO_EQUALS (default: True): Make sure no config key contains an equals sign.
  IGNORED_COMMENTS (default: ['^pylint:', '^noinspection']): List of regex patterns to filter out certain IDE or linter directives from in-line comments in the documentation.
  READ_ONLY_CONFIG (default: True): Make the configuration read-only inside of captured functions. This only works to a limited extend because custom types cannot be controlled.
HOST_INFO:
  INCLUDE_GPU_INFO (default: True): Try to collect information about GPUs using the nvidia-smi tool. Deactivating this can cut the start-up time of a Sacred run by about 1 sec.
  INCLUDE_CPU_INFO (default: True): Try to collect information about the CPU using py-cpuinfo. Deactivating this can cut the start-up time of a Sacred run by about 3 sec.
  CAPTURED_ENV (default: []): List of ENVIRONMENT variable names to store in the host-info.
COMMAND_LINE:
  STRICT_PARSING (default: False): Disallow string fallback if parsing a value from command-line failed. This enforces the usage of quotes in the command-line. Note that this can be very tedious since bash removes one set of quotes, such that double quotes will be needed.
```

--------------------------------

### Load Configuration from Files (Sacred)

Source: https://sacred.readthedocs.io/en/stable/index.html/configuration

Illustrates how to load configuration entries directly from different file types (JSON, Pickle, YAML) into a Sacred experiment using `ex.add_config`.

```Python
ex.add_config('conf.json')
ex.add_config('conf.pickle')  # if configuration was stored as dict
ex.add_config('conf.yaml')    # requires PyYAML
```

--------------------------------

### Apply Sacred Named Configurations via CLI

Source: https://sacred.readthedocs.io/en/stable/index.html/command_line

Shows how to define named configurations within a Sacred experiment and then apply them from the command line using the 'with' argument. It also notes that the order of applying multiple named configurations matters, as later ones can overwrite earlier settings.

```Python
ex = Experiment('named_configs_demo')

@ex.config
def cfg():
    a = 10
    b = 3 * a
    c = "foo"

@ex.named_config
def variant1():
    a = 100
    c = "bar"
```

```Bash
./named_configs_demo.py with variant1
```

--------------------------------

### Add TinyDbObserver from Command Line

Source: https://sacred.readthedocs.io/en/stable/index.html/observers

Demonstrates how to add the TinyDbObserver to a Sacred experiment using command-line flags `-t` or `--tiny_db`, specifying the base directory for the database and hashfs. Intermediate directories are created automatically.

```Bash
>> ./my_experiment.py -t BASEDIR
>> ./my_experiment.py --tiny_db=BASEDIR
```

--------------------------------

### sacred.Experiment Class API Reference

Source: https://sacred.readthedocs.io/en/stable/index.html/apidoc

Detailed API documentation for the `sacred.Experiment` class, including its constructor and methods for managing experiment configurations and artifacts. This class is fundamental for setting up and running experiments with Sacred. It inherits methods from `sacred.Ingredient`.

```APIDOC
class sacred.Experiment(name: Optional[str] = None, ingredients: Sequence[sacred.ingredient.Ingredient] = (), interactive: bool = False, base_dir: Union[str, bytes, pathlib.Path, None] = None, additional_host_info: Optional[List[sacred.host_info.HostInfoGetter]] = None, additional_cli_options: Optional[Sequence[sacred.commandline_options.CLIOption]] = None, save_git_info: bool = True)
  Description: The central class for each experiment in Sacred. It manages the configuration, the main function, captured methods, observers, commands, and further ingredients. An Experiment instance should be created as one of the first things in any experiment-file.

  __init__(name: Optional[str] = None, ingredients: Sequence[sacred.ingredient.Ingredient] = (), interactive: bool = False, base_dir: Union[str, bytes, pathlib.Path, None] = None, additional_host_info: Optional[List[sacred.host_info.HostInfoGetter]] = None, additional_cli_options: Optional[Sequence[sacred.commandline_options.CLIOption]] = None, save_git_info: bool = True)
    Description: Create a new experiment with the given name and optional ingredients.
    Parameters:
      name (Optional[str]): Optional name of this experiment, defaults to the filename. (Required in interactive mode)
      ingredients (list[sacred.Ingredient], optional): A list of ingredients to be used with this experiment.
      interactive (bool): If set to True will allow the experiment to be run in interactive mode (e.g. IPython or Jupyter notebooks). However, this mode is discouraged since it won’t allow storing the source-code or reliable reproduction of the runs.
      base_dir (Union[str, bytes, pathlib.Path, None]): Optional full path to the base directory of this experiment. This will set the scope for automatic source file discovery.
      additional_host_info (Optional[List[sacred.host_info.HostInfoGetter]]): Optional dictionary containing as keys the names of the pieces of host info you want to collect, and as values the functions collecting those pieces of information.
      save_git_info (bool): Optionally save the git commit hash and the git state (clean or dirty) for all source files. This requires the GitPython package.

  add_artifact(filename: Union[str, bytes, pathlib.Path], name: Optional[str] = None, metadata: Optional[dict] = None, content_type: Optional[str] = None) -> None
    Description: Add a file as an artifact. In Sacred terminology an artifact is a file produced by the experiment run. In case of a MongoObserver that means storing the file in the database. This function can only be called during a run, and just calls the sacred.run.Run.add_artifact() method.
    Parameters:
      filename (Union[str, bytes, pathlib.Path]): name of the file to be stored as artifact
      name (Optional[str]): optionally set the name of the artifact. Defaults to the relative file-path.
      metadata (Optional[dict]): optionally attach metadata to the artifact. This only has an effect when using the MongoObserver.
      content_type (Optional[str]): optionally attach a content-type to the artifact. This only has an effect when using the MongoObserver.
    Returns: None

  add_config(cfg_or_file=None, **kw_conf)
    Description: Add a configuration entry to this ingredient/experiment. Can be called with a filename, a dictionary xor with keyword arguments. Supported formats for the config-file so far are: json, pickle and yaml. The resulting dictionary will be converted into a ConfigDict.
    Parameters:
      cfg_or_file (dict or str): Configuration dictionary of filename of config file to add to this ingredient/experiment.
      kw_conf: Configuration entries to be added to this ingredient/experiment.

  add_named_config(name, cfg_or_file=None, **kw_conf)
    Description: Add a named configuration entry to this ingredient/experiment. Can be called with a filename, a dictionary xor with keyword arguments. Supported formats for the config-file so far are: json, pickle and yaml. The resulting dictionary will be converted into a ConfigDict. See Named Configurations
    Parameters:
      name:
      cfg_or_file (dict or str): Configuration dictionary of filename of config file to add to this ingredient/experiment.
      kw_conf: Configuration entries to be added to this ingredient/experiment.
```

--------------------------------

### Add Configuration with Keyword Arguments (Sacred)

Source: https://sacred.readthedocs.io/en/stable/index.html/configuration

Shows an alternative and equivalent way to add configuration entries to a Sacred experiment by passing them as keyword arguments to `ex.add_config`.

```Python
ex.add_config(
    foo=42,
    bar='baz'
)
```

--------------------------------

### Update Configuration via Command-Line Interface (Sacred)

Source: https://sacred.readthedocs.io/en/stable/index.html/configuration

Demonstrates how to update configuration entries from the command-line interface using the `with` keyword when executing a Sacred experiment.

```Shell
$ python config_demo.py print_config with a=6
INFO - config_demo - Running command 'print_config'
INFO - config_demo - Started
Configuration (modified, added, typechanged, doc):
  a = 6                              # some integer
  seed = 681756089                   # the random seed for this experiment
  foo:                               # a dictionary
    a_squared = 36
    bar = 'my_string6'
INFO - config_demo - Completed after 0:00:00
```

--------------------------------

### Name Flag

Source: https://sacred.readthedocs.io/en/stable/index.html/command_line

The `-n NAME` or `--name=NAME` flag allows you to set a custom name for the current experiment run. This option changes the experiment's identifier before it starts, aiding in organization and tracking.

```APIDOC
-n NAME: Set the name for this run.
--name=NAME: Set the name for this run.
```

--------------------------------

### Sacred: Combine Named and Regular Updates

Source: https://sacred.readthedocs.io/en/stable/index.html/command_line

Demonstrates how Sacred handles a combination of named updates and regular updates from the command line. Regular updates take precedence and are fixed before named updates are applied, resulting in a final configuration.

```Shell
>>> ./named_configs_demo.py with variant1 'a=23'
```

--------------------------------

### Add Sacred FileStorageObserver via Command Line

Source: https://sacred.readthedocs.io/en/stable/index.html/observers

Demonstrates how to add a `FileStorageObserver` to a Sacred experiment directly from the command line using the `-F` or `--file_storage` flags, specifying the base directory for run data.

```Bash
>> ./my_experiment.py -F BASEDIR
>> ./my_experiment.py --file_storage=BASEDIR
```

--------------------------------

### Enforce Clean Flag

Source: https://sacred.readthedocs.io/en/stable/index.html/command_line

The `-e` or `--enforce_clean` flag ensures that experiments are only run on a clean version control repository, meaning no uncommitted changes are present. This flag requires the `GitPython` package to be installed to function correctly.

```APIDOC
-e: Fail if any version control repository is dirty.
--enforce_clean: Fail if any version control repository is dirty.
```

--------------------------------

### Instantiate TinyDbReader in Python

Source: https://sacred.readthedocs.io/en/stable/index.html/observers

Shows how to create an instance of the `TinyDbReader` class by passing the path to the root directory created by the `TinyDbObserver`, enabling querying of stored experiment results.

```Python
from sacred.observers import TinyDbReader

reader = TinyDbReader('my_runs')
```

--------------------------------

### Override Injected Arguments in Sacred Captured Functions

Source: https://sacred.readthedocs.io/en/stable/index.html/configuration

This Python code demonstrates how to override configuration values injected into a captured function (`print_a_and_b`) by explicitly passing arguments. It shows examples of positional and keyword argument overrides.

```python
@ex.automain
def my_main():
    print_a_and_b()          # prints '10' and 'test'
    print_a_and_b(3)         # prints '3'  and 'test'
    print_a_and_b(3, 'foo')  # prints '3'  and 'foo'
    print_a_and_b(b='foo')   # prints '10' and 'foo'
```

--------------------------------

### Sacred: Inspect Experiment Configuration with print_config

Source: https://sacred.readthedocs.io/en/stable/index.html/command_line

Demonstrates using the `print_config` command to display the full, indented configuration of a Sacred experiment. It shows how the command outputs the current values, including nested dictionaries.

```Shell
>>> ./hello_config print_config
INFO - hello_config - Running command 'print_config'
INFO - hello_config - Started
Configuration (modified, added, typechanged):
  message = 'Hello world!'
  recipient = 'world'
  seed = 946502320
  d:
    bar = 2
    foo = 1
INFO - hello_config - Completed after 0:00:00
```

--------------------------------

### Add MongoObserver from command line

Source: https://sacred.readthedocs.io/en/stable/index.html/observers

Demonstrates how to add a MongoObserver to a Sacred experiment using the -m flag with a database name. This method is suitable for connecting to a local MongoDB instance.

```shell
./my_experiment.py -m MY_DB
```

--------------------------------

### View Experiment Configuration with Sacred Ingredient Settings

Source: https://sacred.readthedocs.io/en/stable/index.html/ingredients

This command-line output demonstrates how the configuration defined within a Sacred Ingredient is integrated into the overall experiment configuration. Running `print_config` reveals a nested entry for the 'dataset' ingredient, showing its default `filename` and `normalize` parameters.

```shell
./my_experiment.py print_config
INFO - my_experiment - Running command 'print_config'
INFO - my_experiment - Started
Configuration (modified, added, typechanged):
  seed = 586408722
  dataset:
    filename = 'my_dataset.npy'
    normalize = True
INFO - my_experiment - Completed after 0:00:00
```

--------------------------------

### Configure Sacred FileStorageObserver with Custom Report Template

Source: https://sacred.readthedocs.io/en/stable/index.html/observers

Demonstrates how to initialize the Sacred FileStorageObserver to enable custom report generation using a Mako template. It shows importing the observer and appending it to an experiment, specifying the output directory and the path to the custom template file.

```Python
from sacred.observers import FileStorageObserver

ex.observers.append(FileStorageObserver('my_runs', template='/custom/template.txt'))
```

--------------------------------

### Combine Multiple Configuration Sources (Sacred)

Source: https://sacred.readthedocs.io/en/stable/index.html/configuration

Demonstrates how to combine multiple configuration sources, such as config scopes and dictionaries, within a single Sacred experiment. It highlights how later configurations can access and potentially override values from earlier declarations.

```Python
ex = Experiment('multiple_configs_demo')

@ex.config
def my_config1():
    a = 10
    b = 'test'

@ex.config
def my_config2(a):  # notice the parameter a here
    c = a * 2       # we can use a because we declared it
    a = -1          # we can also change the value of a
    #d = b + '2'    # error: no access to b

ex.add_config({'e': 'from_dict'})
# could also add a config file here
```