### Hierarchical Configuration for Training Setup

Source: https://github.com/google/gin-config/blob/master/docs/walkthrough.md

This example demonstrates a generic training setup configured hierarchically using Gin. It shows how to wire up modular functions and use scoped references for flexibility in defining network functions, optimizers, datasets, and loss functions.

```python
@gin.configurable
def build_model_fn(network_fn, loss_fn, optimize_loss_fn):
  def model_fn(features, labels):
    logits = network_fn(features)
    loss = loss_fn(labels, logits)
    train_op = optimize_loss_fn(loss)
    ...
  return model_fn

@gin.configurable
def optimize_loss(loss, optimizer_cls, learning_rate):
  optimizer = optimizer_cls(learning_rate)
  return optimizer.minimize(loss)

@gin.configurable
def input_fn(file_pattern, batch_size, ...):
  ...

@gin.configurable
def run_training(train_input_fn, eval_input_fn, estimator, steps=1000):
  estimator.train(train_input_fn, steps=steps)
  estimator.evaluate(eval_input_fn)
  ...
```

```gin
run_training.train_input_fn = @train/input_fn
run_training.eval_input_fn = @eval/input_fn

input_fn.batch_size = 64  # Shared by both train and eval...
train/input_fn.file_pattern = ...
eval/input_fn.file_pattern = ...


run_training.estimator = @tf.estimator.Estimator()
tf.estimator.Estimator.model_fn = @build_model_fn()

build_model_fn.network_fn = @dnn
dnn.layer_sizes = (1024, 512, 256)

build_model_fn.loss_fn = @tf.losses.sparse_softmax_cross_entropy

build_model_fn.optimize_loss_fn = @optimize_loss

optimize_loss.optimizer_cls = @tf.train.MomentumOptimizer
MomentumOptimizer.momentum = 0.9

optimize_loss.learning_rate = 0.01
```

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

### Hierarchical Configuration Example

Source: https://github.com/google/gin-config/blob/master/README.md

Demonstrates a generic training setup configured hierarchically using Gin. This example shows how to wire up modular functions and use scoped references for flexibility in training configurations.

```python
@gin.configurable
def build_model_fn(network_fn, loss_fn, optimize_loss_fn):
  def model_fn(features, labels):
    logits = network_fn(features)
    loss = loss_fn(labels, logits)
    train_op = optimize_loss_fn(loss)
    ...
  return model_fn

@gin.configurable
def optimize_loss(loss, optimizer_cls, learning_rate):
  optimizer = optimizer_cls(learning_rate)
  return optimizer.minimize(loss)

@gin.configurable
def input_fn(file_pattern, batch_size, ...):
  ...

@gin.configurable
def run_training(train_input_fn, eval_input_fn, estimator, steps=1000):
  estimator.train(train_input_fn, steps=steps)
  estimator.evaluate(eval_input_fn)
  ...

```

```gin
# Inside "config.gin"
run_training.train_input_fn = @train/input_fn
run_training.eval_input_fn = @eval/input_fn

input_fn.batch_size = 64  # Shared by both train and eval...
train/input_fn.file_pattern = ...
eval/input_fn.file_pattern = ...


run_training.estimator = @tf.estimator.Estimator()
tf.estimator.Estimator.model_fn = @build_model_fn()

build_model_fn.network_fn = @dnn
dnn.layer_sizes = (1024, 512, 256)

build_model_fn.loss_fn = @tf.losses.sparse_softmax_cross_entropy

build_model_fn.optimize_loss_fn = @optimize_loss

optimize_loss.optimizer_cls = @tf.train.MomentumOptimizer
MomentumOptimizer.momentum = 0.9

optimize_loss.learning_rate = 0.01
```

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

### Minimal Gin-Config Example

Source: https://github.com/google/gin-config/blob/master/_autodocs/QUICK_START.md

Defines a configurable function and applies configuration from a .gin file. This example shows the basic setup for using Gin-Config.

```python
import gin

@gin.configurable
def hello(name='World', greeting='Hello'):
    print(f'{greeting}, {name}!')

if __name__ == '__main__':
    gin.parse_config_file('config.gin')
    hello()
```

```gin
hello.name = 'Gin'
hello.greeting = 'Hi'
```

```bash
python main.py
# Output: Hi, Gin!
```

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

### Install Gin from Source

Source: https://github.com/google/gin-config/blob/master/docs/walkthrough.md

Install Gin from its source repository using git and setup.py for development or specific versions.

```shell
git clone https://github.com/google/gin-config
cd gin-config
python -m setup.py install
```

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

### Install PyTorch

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/pytorch-integration.md

Use pip to install PyTorch. You can install with CUDA support by specifying the appropriate index URL.

```bash
# Install PyTorch
pip install torch torchvision

# Or with CUDA support
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
```

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

### Install Gin-Config

Source: https://github.com/google/gin-config/blob/master/_autodocs/QUICK_START.md

Install the gin-config library using pip.

```bash
pip install gin-config
```

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

### Example Experiment Configuration File

Source: https://github.com/google/gin-config/blob/master/_autodocs/configuration.md

An example of an experiment-specific Gin configuration file that includes base configurations and overrides specific parameters. Use this to define experiment-specific settings.

```gin
%include 'base/default.gin'
%include 'base/models.gin'

train.learning_rate = 0.01
train.batch_size = 64
```

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

### Basic Binding Example

Source: https://github.com/google/gin-config/blob/master/_autodocs/config-syntax.md

Illustrates setting numerical and string parameters for a 'model' configurable.

```gin
model.units = 256
model.dropout = 0.5
model.name = 'my_model'
```

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

### GAN Trainer Example Setup

Source: https://github.com/google/gin-config/blob/master/docs/index.md

This Python code defines a GAN trainer function that accepts generator and discriminator optimizers. It uses `@gin.configurable` with an `allowlist` to specify which parameters can be configured.

```python
gin.external_configurable(tf.train.GradientDescentOptimizer)

@gin.configurable(allowlist=['generator_optimizer', 'discriminator_optimizer'])
def gan_trainer(
    generator_loss, generator_vars, generator_optimizer,
    discriminator_loss, discriminator_vars, discriminator_optimizer):
  # Construct the optimizers and minimize w.r.t. the correct variables.
  generator_train_op = generator_optimizer().minimize(
      generator_loss, generator_vars)
  discriminator_train_op = discriminator_optimizer().minimize(
      discriminator_loss, discriminator_vars)
  ...
```

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

### Complete MNIST Training Example with Gin-Config

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/pytorch-integration.md

A full example demonstrating how to configure a PyTorch MNIST training pipeline using Gin-Config. It includes data loading, model building, and training loop configuration.

```python
import gin
import gin.torch
import torch
import torch.nn as nn
import torchvision
import torchvision.transforms as transforms

CONFIG = '''
load_data.batch_size = 64
load_data.num_workers = 4

build_model.hidden_units = 256

train.epochs = 10
train.optimizer = @torch.optim.Adam()
torch.optim.Adam.lr = 0.001
torch.optim.Adam.weight_decay = 1e-5
'''

@gin.configurable
def load_data(batch_size=32, num_workers=0):
    transform = transforms.Compose([
        transforms.ToTensor(),
        transforms.Normalize((0.1307,), (0.3081,))
    ])
    
    dataset = torchvision.datasets.MNIST(
        './data', train=True, download=True, transform=transform
    )
    
    return torch.utils.data.DataLoader(
        dataset, batch_size=batch_size, shuffle=True, num_workers=num_workers
    )

@gin.configurable
def build_model(hidden_units=128):
    return nn.Sequential(
        nn.Linear(28 * 28, hidden_units),
        nn.ReLU(),
        nn.Dropout(0.2),
        nn.Linear(hidden_units, 10),
    )

@gin.configurable
def train(model, optimizer, epochs=5):
    dataloader = gin.get_configurable('load_data')()
    criterion = nn.CrossEntropyLoss()
    
    for epoch in range(epochs):
        total_loss = 0
        for batch_x, batch_y in dataloader:
            batch_x = batch_x.view(-1, 28 * 28)
            
            optimizer.zero_grad()
            logits = model(batch_x)
            loss = criterion(logits, batch_y)
            loss.backward()
            optimizer.step()
            
            total_loss += loss.item()
        
        avg_loss = total_loss / len(dataloader)
        print(f'Epoch {epoch}: loss={avg_loss:.4f}')

if __name__ == '__main__':
    gin.parse_config(CONFIG)
    
    model = gin.get_configurable('build_model')()
    optimizer = torch.optim.Adam(model.parameters(), lr=0.001)
    
    gin.get_configurable('train')(model=model, optimizer=optimizer)
    
    print('\nOperative Config:')
    print(gin.operative_config_str())

```

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

### Install TensorFlow

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/tensorflow-integration.md

Install TensorFlow using pip. Use `tensorflow-gpu` for GPU support.

```bash
# Install TensorFlow
pip install tensorflow

# Or GPU version
pip install tensorflow-gpu
```

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

### Complete Gin Configuration File

Source: https://github.com/google/gin-config/blob/master/_autodocs/INDEX.md

An example of a comprehensive Gin configuration file that includes importing other configuration files and modules, and setting various parameters.

```gin
%include 'base.gin'

import models
import training

models.ResNet.depth = 50
training.train.learning_rate = 0.01
```

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

### Install Gin with pip

Source: https://github.com/google/gin-config/blob/master/docs/walkthrough.md

Install Gin using pip for easy integration into your Python projects.

```shell
pip install gin-config
```

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

### Gin Configuration File Format Examples

Source: https://github.com/google/gin-config/blob/master/_autodocs/README.md

Illustrates the syntax for binding parameters, using scopes, referencing other functions, using macros and constants, importing modules, including other files, and adding comments within a Gin configuration file.

```gin
# Binding
function.parameter = value

# Scoped binding
scope/function.parameter = value

# Reference
function.param = @other_function

# Evaluated reference
function.param = @other_function()

# Macro
MAX_EPOCHS = 100
function.epochs = %MAX_EPOPOCHS

# Const
function.required_param = %gin.REQUIRED

# Import
import module_name

# Include
%include 'other.gin'

# Comment
# This is a comment
```

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

### Complete TensorFlow and Gin-Config Integration Example

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/tensorflow-integration.md

This comprehensive example integrates Gin-Config with TensorFlow Keras for defining and training a model. It includes configurable functions for dataset loading, model building, and training, along with a sample configuration string.

```python
import gin
import gin.tf
import tensorflow as tf

# Configuration functions
@gin.configurable
def load_dataset(batch_size=32):
    (x_train, y_train), _ = tf.keras.datasets.mnist.load_data()
    dataset = tf.data.Dataset.from_tensor_slices((x_train, y_train))
    dataset = dataset.batch(batch_size).prefetch(10)
    return dataset

@gin.configurable
def build_model(hidden_units=128):
    return tf.keras.Sequential([
        tf.keras.layers.Flatten(input_shape=(28, 28)),
        tf.keras.layers.Dense(hidden_units, activation='relu'),
        tf.keras.layers.Dropout(0.2),
        tf.keras.layers.Dense(10, activation='softmax'),
    ])

@gin.configurable
def train(model, optimizer, epochs=5):
    model.compile(
        optimizer=optimizer,
        loss='sparse_categorical_crossentropy',
        metrics=['accuracy']
    )
    
    dataset = gin.get_configurable('load_dataset')()
    model.fit(dataset, epochs=epochs)

# Config file: config.gin
CONFIG = '''
load_dataset.batch_size = 64

build_model.hidden_units = 256

train.epochs = 10
train.optimizer = @tf.keras.optimizers.Adam()
tf.keras.optimizers.Adam.learning_rate = 0.001
'''

# Main
if __name__ == '__main__':
    gin.parse_config(CONFIG)
    
    model = gin.get_configurable('build_model')()
    gin.get_configurable('train')(model=model)
    
    # Print operative config
    print(gin.operative_config_str())
```

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

### gin.singleton()

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/core-api.md

Gets or creates a singleton instance of a configurable object.

```APIDOC
## gin.singleton()

### Description
Get or create a singleton instance.

### Signature:
```python
gin.singleton(constructor)
```

### Parameters:
#### Path Parameters
- **constructor** (callable) - Required - Constructor function/class to create singleton.

### Returns:
The singleton instance, created by calling `constructor()` on first access.

### Example:
```python
import gin

@gin.configurable
def get_database(host='localhost', port=5432):
    # This is called once per scope
    return Database(host=host, port=port)

@gin.configurable
def train(db):
    pass

# In config:
# train.db = @gin.singleton(get_database)

gin.parse_config('train.db = @gin.singleton(get_database)')
gin.parse_config('get_database.host = "prod-server"')
```
```

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

### Multi-Level Scoped Binding Example

Source: https://github.com/google/gin-config/blob/master/_autodocs/config-syntax.md

Demonstrates setting parameters within nested scopes for 'train' and 'eval' preprocessing.

```gin
train/preprocessing/load_data.batch_size = 64
eval/preprocessing/load_data.batch_size = 128
```

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

### Tuple Values

Source: https://github.com/google/gin-config/blob/master/_autodocs/config-syntax.md

Shows examples of defining tuples, including a single-element tuple.

```gin
model.shape = (32, 64, 128)
model.pair = (1, 2)
model.single_tuple = (1,)
```

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

### Example Usage of GinConfigSaverHook with tf.estimator

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/tensorflow-integration.md

Demonstrates how to use GinConfigSaverHook with a tf.estimator.Estimator to save and summarize the operative configuration during training. Ensure TensorFlow and Gin are installed and configured.

```python
import gin
import gin.tf
import tensorflow as tf

@gin.configurable
def build_model():
    return tf.keras.Sequential([
        tf.keras.layers.Dense(128, activation='relu'),
        tf.keras.layers.Dense(10, activation='softmax'),
    ])

gin.parse_config([
    'build_model.units = [128, 64, 10]',
])

# Create estimator
estimator = tf.estimator.Estimator(
    model_fn=my_model_fn,
    model_dir='./model_dir',
)

# Add Gin hook
gin_hook = gin.tf.GinConfigSaverHook(
    output_dir='./model_dir',
    base_name='operative_config',
    summarize_config=True,
)

# Use in training
estimator.train(
    input_fn=train_input_fn,
    steps=1000,
    hooks=[gin_hook],
)
```

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

### ConfigurableReference Example Usage

Source: https://github.com/google/gin-config/blob/master/_autodocs/types.md

Demonstrates how ConfigurableReference is created when using '@optimizer' syntax in config files. References can be evaluated or unevaluated.

```python
import gin

@gin.configurable
def optimizer(learning_rate=0.001):
    return lr

@gin.configurable
def train(opt):
    return opt()

# When parsing "@optimizer" in a config, a ConfigurableReference is created
# References can be evaluated (@optimizer()) or unevaluated (@optimizer)
```

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

### Distributed PyTorch Training Setup with Gin

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/pytorch-integration.md

Configure distributed training for PyTorch models using Gin. This includes setting up the distributed environment and building distributed models with `DistributedDataParallel`.

```python
import gin
import gin.torch
import torch
import torch.distributed as dist
from torch.nn.parallel import DistributedDataParallel as DDP

@gin.configurable
def setup_distributed(rank, world_size):
    os.environ['MASTER_ADDR'] = 'localhost'
    os.environ['MASTER_PORT'] = '12355'
    dist.init_process_group(
        backend='nccl',
        rank=rank,
        world_size=world_size
    )

@gin.configurable
def build_distributed_model(model_fn, rank):
    model = gin.get_configurable(model_fn)()
    model = DDP(model, device_ids=[rank])
    return model

@gin.configurable
def train_distributed(model, optimizer, epochs=5):
    for epoch in range(epochs):
        # Training code
        pass

# Config
gin.parse_config('''
build_distributed_model.model_fn = @build_model
build_model.hidden_units = 512

train_distributed.epochs = 20
train_distributed.optimizer = @torch.optim.DistributedDataParallel()
''')
```

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

### Scope Inheritance Example

Source: https://github.com/google/gin-config/blob/master/_autodocs/config-syntax.md

Illustrates how unscoped parameters are inherited and can be overridden by specific scopes.

```gin
model.units = 128           # All scopes use 128
train/model.units = 256     # train scope overrides to 256
eval/model.units = 64       # eval scope overrides to 64
```

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

### ImportStatement Formatting Example

Source: https://github.com/google/gin-config/blob/master/_autodocs/types.md

Demonstrates how to parse a config file and format ImportStatement objects. This is useful for understanding how import directives are represented and can be converted back into their string representation.

```python
import gin
from gin import config_parser

# Parse a config file to get import statements
# In config:
# import models
# from optimizers import adam_optimizer

# Statements are created and can be formatted
stmt = config_parser.ImportStatement(
    module='models',
    is_from=False,
    alias=None,
    location=config_parser.Location('config.gin', 1, None, 'import models')
)
print(stmt.format())  # 'import models'
```

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

### Literal Number Values

Source: https://github.com/google/gin-config/blob/master/_autodocs/config-syntax.md

Shows examples of assigning float, integer, and scientific notation numbers.

```gin
model.learning_rate = 0.001      # Float
model.batch_size = 32             # Integer
model.large_number = 1e-5         # Scientific notation
```

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

### Configuring Distributed TensorFlow Training

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/tensorflow-integration.md

Set up distributed training for TensorFlow models using Gin-Config. This example configures the number of steps and the `tf.estimator.RunConfig` for checkpoint saving and logging.

```python
import gin
import gin.tf
import tensorflow as tf

@gin.configurable
def train(estimator_config, num_steps):
    distribution = tf.distribute.MirroredStrategy() # Note: This line is present in the source but not directly configured by gin in this snippet.
    
    estimator = tf.estimator.Estimator(
        model_fn=model_fn, # Note: model_fn is assumed to be defined elsewhere.
        model_dir='./model_dir',
        config=estimator_config
    )
    
    estimator.train(
        input_fn=train_input_fn, # Note: train_input_fn is assumed to be defined elsewhere.
        steps=num_steps,
        hooks=[
            gin.tf.GinConfigSaverHook('./model_dir')
        ]
    )

gin.parse_config('''
train.num_steps = 50000
train.estimator_config = @tf.estimator.RunConfig()
tf.estimator.RunConfig.save_checkpoints_steps = 1000
tf.estimator.RunConfig.log_step_count_steps = 100
''')
```

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

### Getting Values from Gin Configuration

Source: https://github.com/google/gin-config/blob/master/_autodocs/QUICK_START.md

Use gin.parse_config to set parameters, gin.get_bindings to inspect bound parameters, and gin.query_parameter to retrieve specific values. operative_config_str() shows the effective configuration.

```python
import gin

@gin.configurable
def model(units=128):
    return Model(units)

gin.parse_config('model.units = 256')

# Check what's bound
bindings = gin.get_bindings(model)
print(bindings)  # {'units': 256}

# Check a specific parameter
value = gin.query_parameter('model.units')
print(value)  # 256

# Get operative config (what was actually used)
config = gin.operative_config_str()
print(config)
```

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

### Get or Create Singleton Instance

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/core-api.md

Retrieves a singleton instance, creating it via the provided constructor on first access. This is useful for ensuring a single instance of a resource like a database connection is used across different parts of the application.

```python
import gin

@gin.configurable
def get_database(host='localhost', port=5432):
    # This is called once per scope
    return Database(host=host, port=port)

@gin.configurable
def train(db):
    pass

# In config:
# train.db = @gin.singleton(get_database)

gin.parse_config('train.db = @gin.singleton(get_database)')
gin.parse_config('get_database.host = "prod-server"')
```

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

### Gin-config Main Entry Point

Source: https://github.com/google/gin-config/blob/master/_autodocs/QUICK_START.md

Parses configuration files and bindings from command-line arguments to set up an application. This pattern is useful for flexible application initialization.

```python
import gin
import sys

def main():
    # Parse config files from command line
    # Usage: python main.py config.gin model.units=512
    gin.parse_config_files_and_bindings(
        config_files=sys.argv[1:-len(sys.argv[2:])],
        bindings=sys.argv[2:],
        finalize_config=True
    )
    
    # Now run your application
    train()
    
    # Print what was actually used
    print(gin.operative_config_str())

if __name__ == '__main__':
    main()
```

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

### Parse Configuration from File

Source: https://github.com/google/gin-config/blob/master/_autodocs/QUICK_START.md

Load configuration settings from a .gin file.

```python
gin.parse_config_file('config.gin')
```

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

### Define and Configure a Say Hello Function with Gin

Source: https://github.com/google/gin-config/blob/master/gin/gin_intro.ipynb

Demonstrates how to make a Python function configurable with Gin and how to parse configuration strings to override default parameter values.

```python
gin.clear_config()

@gin.configurable
def say_hello(name="world"):
  print("Hello %s!" % name)

# Decorated functions or classes preserve their default behavior.
say_hello()

# Bindings are usually specified in a file, e.g., "config.gin". For simplicity
# here we pass a string directly to `gin.parse_config`.
gin.parse_config("""
say_hello.name = "Gin"
""")

# With the above config, the "name" parameter now defaults to "Gin".
say_hello()

# But the caller can always override it.
say_hello("world")
```

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

### Parse Gin Config File with Options

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/core-api.md

Demonstrates using `gin.parse_config_file()` with options to skip unknown configurations or print include/import summaries. These options help manage complex configurations and debug parsing issues.

```python
# With skip_unknown
gin.parse_config_file('config.gin', skip_unknown=True)

# Print structure of includes
gin.parse_config_file('config.gin', print_includes_and_imports=True)
```

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

### Parse Gin Config from Environment Variables

Source: https://github.com/google/gin-config/blob/master/_autodocs/configuration.md

Demonstrates how to load Gin configuration files and bindings from environment variables. Useful for setting up different configurations without modifying code.

```python
import gin
import os

# Pass config file from env var
config_file = os.getenv('GIN_CONFIG', 'default.gin')
gin.parse_config_file(config_file)

# Pass bindings from env var
bindings = os.getenv('GIN_BINDINGS', '').split(',')
if bindings:
    gin.parse_config(bindings)

# Set constants from env
gin.constant('DATA_DIR', os.getenv('DATA_DIR', '/data'))
gin.constant('MODEL_DIR', os.getenv('MODEL_DIR', './models'))
```

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

### Import Gin

Source: https://github.com/google/gin-config/blob/master/docs/walkthrough.md

Import the core Gin library for configuration management.

```python
import gin
```

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

### Parse Gin Configuration from String and Files

Source: https://github.com/google/gin-config/blob/master/_autodocs/README.md

Parse configuration settings directly from a string or from one or more configuration files. Supports combining multiple files with explicit bindings.

```python
# From string
gin.parse_config('function.param = value')

# From file
gin.parse_config_file('config.gin')

# Multiple files and bindings
gin.parse_config_files_and_bindings(
    config_files=['base.gin', 'experiment.gin'],
    bindings=['model.units = 512']
)
```

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

### Get Current Gin Configuration

Source: https://github.com/google/gin-config/blob/master/_autodocs/errors.md

Prints the current configuration as a string. Use `operative_config_str` to show provenance.

```python
import gin

print(gin.config_str())
print(gin.operative_config_str(show_provenance=True))
```

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

### Basic Binding Syntax

Source: https://github.com/google/gin-config/blob/master/_autodocs/config-syntax.md

Defines a parameter for a configurable. Use this for simple, direct assignments.

```gin
configurable_name.parameter_name = value
```

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

### Gin Imports and Includes

Source: https://github.com/google/gin-config/blob/master/_autodocs/configuration.md

Demonstrates how to import Python modules and include other configuration files within a Gin configuration. Supports direct imports and package path imports.

```gin
# Import Python modules
import my_module
from my_module import my_function

# Import from package path
import package.submodule

# Include other config files
%include 'base.gin'
%include 'experiments/exp1.gin'
```

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

### Triggering Non-Enum Class Error with @gin.constants_from_enum

Source: https://github.com/google/gin-config/blob/master/_autodocs/errors.md

This example shows the error raised when the `@gin.constants_from_enum()` decorator is applied to a class that does not inherit from `enum.Enum`.

```python
import gin

@gin.constants_from_enum()
class NotAnEnum:
    A = 1
    B = 2
```

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

### Parse Configuration from String

Source: https://github.com/google/gin-config/blob/master/_autodocs/QUICK_START.md

Configure function parameters by parsing a string containing bindings.

```python
gin.parse_config('train.learning_rate = 0.01')
gin.parse_config('train.batch_size = 64')
```

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

### Register and Use gin.validate_macros_hook

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/utilities.md

Register `gin.validate_macros_hook` as a finalize hook to validate macros in the configuration. This example demonstrates how to catch `ValueError` when an undefined macro is present.

```python
import gin

gin.register_finalize_hook(gin.validate_macros_hook)

gin.parse_config(''
model.param = %UNDEFINED_MACRO
'')

try:
    gin.finalize()
except ValueError:
    print("Invalid macro detected")
```

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

### Hyperparameter Search with Gin-Config and itertools

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/pytorch-integration.md

Demonstrates how to perform a grid search over hyperparameters by dynamically generating and parsing Gin configurations. It iterates through combinations of parameters, trains a model, and collects results to find the best configuration.

```python
import gin
import itertools

# Config templates
BASE_CONFIG = '''
build_model.hidden_units = {}
load_data.batch_size = {}
torch.optim.Adam.lr = {}
train.epochs = 10
'''

# Grid search
hidden_units_options = [128, 256, 512]
batch_sizes = [32, 64, 128]
learning_rates = [0.0001, 0.001, 0.01]

results = []

for hidden_units, batch_size, lr in itertools.product(
    hidden_units_options, batch_sizes, learning_rates
):
    gin.clear_config()
    config = BASE_CONFIG.format(hidden_units, batch_size, lr)
    gin.parse_config(config)
    gin.finalize()
    
    model = gin.get_configurable('build_model')()
    optimizer = torch.optim.Adam(model.parameters())
    
    val_loss = train_and_evaluate(model, optimizer)
    
    results.append({
        'hidden_units': hidden_units,
        'batch_size': batch_size,
        'lr': lr,
        'val_loss': val_loss,
        'config': gin.operative_config_str(),
    })

# Find best config
best = min(results, key=lambda x: x['val_loss'])
print(f"Best config:\n{best['config']}")
```

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

### Get Configurable Function/Class

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/core-api.md

Retrieve the Gin-wrapped version of a configurable function or class. This allows applying Gin bindings to it. Can accept a callable or a string selector.

```python
import gin

@gin.configurable
def process(mode='train', threshold=0.5):
    pass

gin.parse_config('process.threshold = 0.8')

# Get configurable version and use it
process_fn = gin.get_configurable(process)
result = process_fn()  # threshold=0.8

# Can also use string selector
process_fn2 = gin.get_configurable('process')
result2 = process_fn2()  # threshold=0.8
```

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

### Using Singletons

Source: https://github.com/google/gin-config/blob/master/_autodocs/README.md

Mechanisms for creating and managing singleton instances within gin-config.

```APIDOC
## @gin.singleton()

### Description
Decorator to ensure a function or class is instantiated only once (singleton) when configured.

### Usage
```python
@gin.singleton()
@gin.configurable
def my_singleton_service():
    pass
```
```

```APIDOC
## gin.singleton_value()

### Description
Creates a singleton value that can be used in Python code.

### Usage
```python
singleton_instance = gin.singleton_value(MyClass())
```
```

```APIDOC
## @gin.singleton_per_graph()

### Description
Decorator for TensorFlow integration to create singletons scoped per graph.

### Usage
```python
@gin.singleton_per_graph()
@gin.configurable
def my_tf_singleton():
    pass
```
```

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

### Parse Configuration from Command-Line

Source: https://github.com/google/gin-config/blob/master/_autodocs/QUICK_START.md

Load configuration from files and command-line arguments. Arguments are passed as 'name=value' pairs.

```python
import sys
gin.parse_config_files_and_bindings(
    config_files=['config.gin'],
    bindings=sys.argv[1:]  # Pass as: python train.py train.learning_rate=0.01
)
```

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

### Get Bindings for a Configurable with Python

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/core-api.md

Use `gin.get_bindings` to inspect all parameters bound to a given configurable. This function can resolve references and inherit scopes by default.

```python
import gin

@gin.configurable
def preprocess(crop_size=64, normalize=True):
    pass

gin.parse_config([
    'preprocess.crop_size = 128',
    'preprocess.normalize = False',
])

bindings = gin.get_bindings(preprocess)
print(bindings)  # {'crop_size': 128, 'normalize': False}
```

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

### Gin Configuration with References

Source: https://github.com/google/gin-config/blob/master/_autodocs/INDEX.md

Uses references to other configurable objects, like specifying an optimizer and its learning rate.

```gin
train.optimizer = @Adam
Adam.learning_rate = 0.001
```

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

### Register and Use gin.find_unknown_references_hook

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/utilities.md

Register `gin.find_unknown_references_hook` as a finalize hook to detect unknown references in the configuration. This example shows how to catch `ValueError` when a reference to a nonexistent configurable is found.

```python
import gin

gin.register_finalize_hook(gin.find_unknown_references_hook)

gin.parse_config('model.fn = @nonexistent_function')

try:
    gin.finalize()
except ValueError as e:
    print(f"Unknown reference: {e}")
```

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

### Gin Configuration File Structure

Source: https://github.com/google/gin-config/blob/master/_autodocs/QUICK_START.md

Organize your Gin configuration into separate files for models, training, and constants. Use %include directives to compose them in a main configuration file.

```gin
# model.gin - Model configuration
import models

models.ResNet.depth = 50
models.ResNet.num_classes = %NUM_CLASSES

# training.gin - Training configuration
import training

training.train.learning_rate = %LEARNING_RATE
training.train.batch_size = %BATCH_SIZE
training.train.epochs = 100

# constants.gin - Shared constants
NUM_CLASSES = 1000
LEARNING_RATE = 0.001
BATCH_SIZE = 64

# main.gin - Compose everything
%include 'constants.gin'
%include 'model.gin'
%include 'training.gin'
```

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

### singleton_per_graph()

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/tensorflow-integration.md

Get or create a singleton instance that is unique per TensorFlow graph. This is useful in multi-graph scenarios or when using multiple sessions, ensuring that each graph has its own isolated instance.

```APIDOC
## singleton_per_graph()

Get or create a singleton per TensorFlow graph.

**Signature:**
```python
@gin.configurable
def singleton_per_graph(constructor)
```

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| constructor | callable | — | Function to construct singleton. Called once per graph. |

**Returns:**
The singleton instance for the current graph.

**Description:**
Similar to `gin.singleton()` but creates a separate instance for each TensorFlow graph (useful in multi-graph scenarios or with multiple sessions).

**Example:**

```python
import gin
import gin.tf
import tensorflow as tf

@gin.configurable
def get_embedding_table(embedding_dim=128):
    return tf.Variable(
        tf.random.normal([10000, embedding_dim]),
        trainable=True
    )

@gin.configurable
def model(embeddings):
    pass

# In config
gin.parse_config('''
model.embeddings = @gin.singleton_per_graph(get_embedding_table)
get_embedding_table.embedding_dim = 256
''')

# Each graph gets its own embedding table
with tf.Graph().as_default():
    model()  # Creates embedding table for this graph

with tf.Graph().as_default():
    model()  # Creates separate embedding table for new graph
```

**Source:** `gin/tf/utils.py:35`
```

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

### Creating Singletons

Source: https://github.com/google/gin-config/blob/master/_autodocs/config-syntax.md

Use @gin.singleton to create objects that are instantiated only once and reused throughout the configuration. This is useful for resources like databases or caches.

```gin
train.database = @gin.singleton(create_database)
train.cache = @gin.singleton(create_cache)
```

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

### Dynamic Registration Error Example

Source: https://github.com/google/gin-config/blob/master/_autodocs/errors.md

Illustrates a dynamic registration error in Gin-Config when `__gin__.dynamic_registration` is enabled. This occurs when referencing an unregistered configurable that cannot be imported. Ensure the configurable is registered before being referenced.

```python
import gin

gin.parse_config('''
%from __gin__ import dynamic_registration

@nonexistent.function()
''')
```

```python
import gin

# Register the configurable first
@gin.configurable
def my_function(param=1):
    pass

gin.parse_config('''
%from __gin__ import dynamic_registration

@my_function()
''')
```

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

### gin.parse_config_files_and_bindings

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/core-api.md

Parses multiple configuration files and command-line bindings, optionally finalizing the configuration and handling unknown configurables.

```APIDOC
## gin.parse_config_files_and_bindings()

### Description
Parse multiple config files and additional command-line bindings.

### Method
Python Function

### Parameters
#### Path Parameters
- **config_files** (Sequence[str] or None) - Optional - List of config file paths to parse in order.
- **bindings** (Sequence[str] or None) - Optional - List of binding strings (e.g., from command-line arguments).
- **finalize_config** (bool) - Optional - Whether to call `gin.finalize()` after parsing. Defaults to True.
- **skip_unknown** (bool or Sequence[str]) - Optional - Whether to skip unknown configurables. Defaults to False.
- **print_includes_and_imports** (bool) - Optional - Whether to print include/import hierarchy. Defaults to False.

### Returns
List of `ParsedConfigFileIncludesAndImports` for each config file.

### Example
```python
import gin

# Typical usage in main()
gin.parse_config_files_and_bindings(
    config_files=['defaults.gin', 'experiment.gin'],
    bindings=['model.learning_rate=0.01', 'train.num_epochs=100']
)
```
```

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

### Get Parsed Configuration as Gin String

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/core-api.md

Retrieves all parsed configuration bindings as a Gin string, including those not actively used. Useful for debugging or saving the complete configuration state.

```python
import gin

@gin.configurable
def model(units=128):
    pass

@gin.configurable
def train(epochs=10):
    pass

gin.parse_config([
    'model.units = 256',
    'train.epochs = 50',
])

# Config string includes both even if only model() is called
config_str = gin.config_str()
print(config_str)
```

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

### Import Gin PyTorch Functionality

Source: https://github.com/google/gin-config/blob/master/docs/walkthrough.md

Import PyTorch-specific extensions for Gin configuration.

```python
import gin.torch
```

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

### Including Other Gin Files

Source: https://github.com/google/gin-config/blob/master/docs/index.md

Demonstrates how to include the contents of another Gin file into the current file using the `include` statement. This facilitates modularity and configuration inheritance.

```python
include 'path/to/another/file.gin'
```

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

### Triggering RuntimeError: Finalize Called Twice

Source: https://github.com/google/gin-config/blob/master/_autodocs/errors.md

This example shows how to trigger a RuntimeError by calling `gin.finalize()` more than once without unlocking the configuration. Ensure `finalize()` is called only once or use `gin.clear_config()` before subsequent calls.

```python
import gin

gin.finalize()
gin.finalize()  # Raises RuntimeError
```

```python
# Only call finalize once
gin.finalize()

# If you need to call again, unlock first
gin.clear_config()  # Implicitly unlocks
gin.finalize()
```

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

### Get Current Scope String

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/core-api.md

Retrieves the active configuration scope as a string. Returns an empty string if no scope is active. Useful for debugging or conditional logic based on the current scope.

```python
import gin

gin.current_scope_str()  # ''

with gin.config_scope('train'):
    gin.current_scope_str()  # 'train'
    
with gin.config_scope('train/validation'):
    gin.current_scope_str()  # 'train/validation'
```

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

### Invalid Import Statement Example

Source: https://github.com/google/gin-config/blob/master/_autodocs/errors.md

Shows an invalid import statement syntax in Gin-Config. Ensure the `%import` directive follows the correct Python import syntax. This error is triggered by malformed `%import` directives.

```python
import gin

# Invalid import syntax
gin.parse_config('%import not a valid import')
```

```python
# Use proper import syntax in config
gin.parse_config('import my_module')
gin.parse_config('from my_module import function')
```

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

### Correct Parameter Name in Gin Parse Config

Source: https://github.com/google/gin-config/blob/master/_autodocs/QUICK_START.md

Ensure parameter names in `gin.parse_config` calls exactly match the function's parameter names. This example corrects a common typo in a parameter name.

```python
gin.parse_config('train.learning_rate = 0.01')  # RIGHT
```

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

### Keep Base Gin Configurations Simple

Source: https://github.com/google/gin-config/blob/master/_autodocs/config-syntax.md

Define minimal and clear default configurations in a base file (e.g., 'defaults.gin').

```gin
# defaults.gin - minimal, clear defaults
model.units = 128
train.epochs = 10
```

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

### Get Operative Configuration String

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/core-api.md

Generates a string representation of the configuration parameters that were actually used during the program's execution. This excludes parameters from unreferenced configurables. Useful for understanding runtime behavior and debugging.

```python
import gin

@gin.configurable
def model(units=128, dropout=0.5):
    return {'units': units, 'dropout': dropout}

@gin.configurable
def optimizer(learning_rate=0.001):
    return learning_rate

gin.parse_config('model.units = 256')

# Call model but not optimizer
model()

# Get operative config (only includes model)
config_str = gin.operative_config_str()
print(config_str)
# Output:
# model.dropout = 0.5
# model.units = 256
```

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

### Configure Device for PyTorch Model

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/pytorch-integration.md

Define Gin-configurable functions to get the appropriate device ('cuda' or 'cpu') and to move a PyTorch model to that device. This ensures compatibility between the training device and the model's device.

```python
@gin.configurable
def get_device(use_gpu=True):
    return 'cuda' if use_gpu and torch.cuda.is_available() else 'cpu'

@gin.configurable
def train(model, device='cpu'):
    model.to(device)
    # Training code

gin.parse_config('get_device.use_gpu = True')
device = gin.get_configurable('get_device')()
```

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

### Fix Invalid Constant Selector Error in Gin

Source: https://github.com/google/gin-config/blob/master/_autodocs/errors.md

Ensure that constant selectors adhere to valid Python identifier naming rules, which means they should not contain special characters like hyphens and should not start with a number.

```python
# Use valid Python identifiers
gin.constant('PI', 3.14159)
gin.constant('NUM_CLASSES', 10)
gin.constant('module.constant_name', 'value')
```

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

### Define and Configure a Picker Class with Gin

Source: https://github.com/google/gin-config/blob/master/gin/gin_intro.ipynb

Shows how to make a Python class configurable with Gin, affecting its constructor. Demonstrates binding complex Python literals to class parameters.

```python
gin.clear_config()

@gin.configurable
class Picker(object):
  # Bindings affect the constructor of the class.
  def __init__(self, items):
    self._items = items

  def pick(self):
    print(random.choice(self._items))

Picker(['item']).pick()

gin.parse_config("""
Picker.items = ['one', 2, ((), (), ()),]
""")

Picker().pick()
```

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

### Handle Required Parameters with gin.REQUIRED

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/core-api.md

Use `gin.REQUIRED` as a default value to indicate that a parameter must be provided either through configuration or as a call-time argument. This example demonstrates how to check for and raise an error if a required parameter is not specified.

```python
import gin

@gin.configurable
def model(num_classes=gin.REQUIRED, hidden_size=128):
    if num_classes is gin.REQUIRED:
        raise ValueError('num_classes must be specified')
    return Model(num_classes, hidden_size)

# Must bind or provide num_classes:
gin.parse_config('model.num_classes = 10')
model()  # Works

gin.clear_config()
try:
    model()  # Raises ValueError
except ValueError as e:
    print(e)
```

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

### Python: Get Current Configuration Scope with gin.current_scope

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/core-api.md

Illustrates how to retrieve the list of currently active configuration scopes using gin.current_scope(). This is helpful for debugging and understanding the active configuration context within nested scopes.

```python
import gin

gin.current_scope()  # []

with gin.config_scope('train'):
    gin.current_scope()  # ['train']
    with gin.config_scope('nested'):
        gin.current_scope()  # ['train', 'nested']
```

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

### Outputting Configuration

Source: https://github.com/google/gin-config/blob/master/_autodocs/README.md

Functions to retrieve the current configuration state as strings.

```APIDOC
## gin.operative_config_str()

### Description
Returns a string representation of the operative configuration, including resolved bindings.

### Usage
```python
config_string = gin.operative_config_str()
```
```

```APIDOC
## gin.config_str()

### Description
Returns a string representation of all parsed configurations.

### Usage
```python
all_config_string = gin.config_str()
```
```

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

### Trace Gin Configuration Provenance

Source: https://github.com/google/gin-config/blob/master/_autodocs/errors.md

Prints the operative configuration string, including provenance information to trace the origin of bindings.

```python
import gin

# Include provenance in output
config_str = gin.operative_config_str(show_provenance=True)
print(config_str)
```

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

### Parse Gin Config from List

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/core-api.md

Load configuration bindings by passing a list of strings to `gin.parse_config()`. This allows for programmatic construction of configurations.

```python
gin.clear_config()
gin.parse_config([
    'model.hidden_units = 512',
    'model.dropout = 0.1',
])
```

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

### Retrieve Operative Configuration String

Source: https://github.com/google/gin-config/blob/master/docs/index.md

Use `gin.operative_config_str()` to get a string representation of the current operative configuration. This string can be parsed by `gin.parse_config` and includes all configurable parameter values affecting the current execution, along with dynamically imported modules.

```python
import gin

# ... your gin configuration and code ...

operative_config = gin.operative_config_str()
print(operative_config)
```

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

### Extend Base Configs with Experiment Configs in Gin

Source: https://github.com/google/gin-config/blob/master/_autodocs/config-syntax.md

Use the '%include' directive to extend base configurations and override specific parameters for experiments.

```gin
# experiment.gin
%include 'defaults.gin'

# Override for this experiment
model.units = 512
train.epochs = 50
train.learning_rate = 0.01
```

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

### Invalid Binding Syntax Examples

Source: https://github.com/google/gin-config/blob/master/_autodocs/errors.md

Demonstrates malformed binding syntax in Gin-Config files. These errors occur due to incorrect parameter formatting, invalid Python literals, or bad scope syntax. Use correct assignment operators and Python literal formats.

```python
import gin

# Invalid: missing '='
gin.parse_config('model.units 256')

# Invalid: bad Python literal
gin.parse_config("model.name = 'unclosed string")

# Invalid: bad scope syntax
gin.parse_config('//model.units = 256')
```

```python
# Correct syntax
gin.parse_config('model.units = 256')
gin.parse_config("model.name = 'valid_string'")
gin.parse_config('scope/model.units = 256')
```

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

### Parsing Configuration from Files

Source: https://github.com/google/gin-config/blob/master/_autodocs/configuration.md

Use gin.parse_config to load configurations from file-like objects. This allows for managing configurations in separate files.

```python
import gin

# From file
with open('config.gin') as f:
    gin.parse_config(f)
```

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

### Simple Gin Configuration

Source: https://github.com/google/gin-config/blob/master/_autodocs/INDEX.md

Defines basic key-value pairs for model units and training epochs.

```gin
model.units = 256
train.epochs = 100
```

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

### Run Configured Function

Source: https://github.com/google/gin-config/blob/master/_autodocs/QUICK_START.md

Call the configurable function to execute with the applied configurations.

```python
train()  # Uses configured parameters
```

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

### Using Explicit Scopes with `gin.config_scope`

Source: https://github.com/google/gin-config/blob/master/docs/index.md

Shows how to wrap a call site with an explicit configuration scope using the `gin.config_scope` context manager. This allows for scope-specific bindings.

```python
with gin.config_scope('scope_name'):
  some_configurable_function()
```

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

### gin.resource_reader.system_path_reader()

Source: https://github.com/google/gin-config/blob/master/_autodocs/api-reference/utilities.md

Loads a Gin configuration file as a resource from a Python package. This function is useful for managing configurations within package structures.

```APIDOC
## gin.resource_reader.system_path_reader()

### Description
Load a Gin config as a resource from a Python package.

### Signature
```python
gin.resource_reader.system_path_reader(config_path)
```

### Parameters
#### Path Parameters
- **config_path** (str) - Required - Path like `'my_package.configs/model'` (becomes `my_package/configs/model.gin`).

### Returns
File-like object for reading the config.

### Example
```python
import gin
from gin import resource_reader

gin.register_file_reader(
    resource_reader.system_path_reader,
    resource_reader.system_path_file_exists
)

# Load from package resource
gin.parse_config_file('my_package.configs/model')
```
```

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

### Evaluating References in Gin

Source: https://github.com/google/gin-config/blob/master/gin/gin_intro.ipynb

Shows how to use the `@fn_or_class()` syntax in Gin to immediately evaluate a reference to a configurable function or class, executing it and using its return value.

```python
gin.parse_config("""
print_arg.arg = @return_a_value()
""")
print_arg(gin.REQUIRED)
```

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

### Parse Gin Configuration Files and Bindings

Source: https://github.com/google/gin-config/blob/master/docs/index.md

Use `gin.parse_config_files_and_bindings` to parse configuration settings from specified Gin files and command-line parameter bindings. This function integrates configurations from multiple sources.

```python
import gin

# Assuming FLAGS.gin_file and FLAGS.gin_param are defined and populated
gin.parse_config_files_and_bindings(FLAGS.gin_file, FLAGS.gin_param)
```

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

### Gin-Config File Format

Source: https://github.com/google/gin-config/blob/master/_autodocs/QUICK_START.md

Define configurations in a .gin file. Supports basic bindings, macros, and comments.

```gin
# Basic binding
train.learning_rate = 0.01
train.batch_size = 64
train.epochs = 100

# Using macros
EPOCHS = 100
LR = 0.01
train.epochs = %EPOCHS
train.learning_rate = %LR
```