Gin Config

In Gin, parameters are injected at call time, meaning evaluated references are re-evaluated every time the function is called. In Fiddle, an fdl.Config is evaluated exactly once during fdl.build. If that config is a parameter of an fdl.Partial, subsequent calls to the partial will reuse the same value.

To preserve Gin's re-evaluation semantics, as_config and as_partial automatically detect if an fdl.Config is inside an fdl.Partial. If so, they use ReevaluatedConfig and PartialWithReevaluations to ensure parameters are re-evaluated on every call.

If you know your configuration does not rely on this behavior (e.g., partials are only called once), you can disable it by setting reevaluate_configs_inside_partials=False to improve performance or simplify the object graph.

To ensure multiple bindings receive the exact same instance of an object, use the gin.singleton configurable function.

1. Define a scope for the singleton.
2. Bind the singleton's constructor to a callable.
3. Reference the singleton using @scope/gin.singleton().

Subsequent calls to the same singleton scope will return the cached instance.

# In config.gin:
shared_object_name/gin.singleton.constructor = @callable

some_function.shared_object = @shared_object_name/gin.singleton()
another_function.shared_object = @shared_object_name/gin.singleton()

Using macros with singletons:

# In config.gin:
SHARED_OBJECT = @shared_object_name/gin.singleton()
shared_object_name/gin.singleton.constructor = @callable

some_function.shared_object = %SHARED_OBJECT
another_function.shared_object = %SHARED_OBJECT

Macros allow you to define a value once and reuse it across multiple bindings, reducing maintenance.

In a Gin config file, a binding without an argument name (e.g., name = value) is interpreted as a macro. You can reference this macro using the % syntax.

Important Note on Instances: When using a macro to refer to an evaluated configurable reference (like @some_scope/some_fun()), each reference to the macro implies a separate call to the underlying function. If you need to share the exact same instance of an object, use gin.singleton instead.

# Standard macro usage via @gin.configurable
@gin.configurable
def macro(value):
  return value

# In config.gin:
num_layers = 10
network.num_layers = %num_layers

Gin allows you to pass other configurable functions, classes, or instances as parameters using configurable references.

• Reference a function/class: Use the @ prefix followed by the name (e.g., @tf.nn.tanh or @MyClass).
• Evaluate a reference (pass an instance): Use the @name() syntax. This instructs Gin to call the function or constructor with its own Gin-configured parameters just before passing the result to the target parameter. Note that evaluated references are not cached; a new instance is created for every call to the parent function.

# Inside "config.gin"

# Passing a function/class reference
dnn.activation_fn = @tf.nn.tanh
train_fn.optimizer_cls = @tf.train.GradientDescentOptimizer

# Passing an evaluated instance (calling the constructor)
build_model.network_fn = @DNN()

When a configurable function is called multiple times and requires different parameter values for each call, use Gin's scoping mechanism.

In a .gin file, you can prefix a configurable reference or a parameter binding with a scope name followed by a /. This allows you to create separate 'buckets' of configuration for different instances of the same function.

Example: To give two different optimizers different learning rates:

# In the .gin file
gan_trainer.generator_optimizer = @generator/GradientDescentOptimizer
gan_trainer.discriminator_optimizer = @discriminator/GradientDescentOptimizer

generator/GradientDescentOptimizer.learning_rate = 0.01
discriminator/GradientDescentOptimizer.learning_rate = 0.001

Gin allows you to pass other configurable functions or classes as parameters using the @name syntax (known as configurable references).

• Passing a reference: Use @function_name or @module.function_name to pass the object itself.
• Evaluating a reference: Use @name() to pass the result of calling the function or class constructor. Note that evaluated references are not cached; a new instance is created for each call to the parent function.

# Inside "config.gin"

# Passing a reference (the function/class itself)
dnn.activation_fn = @tf.nn.tanh
train_fn.optimizer_cls = @tf.train.GradientDescentOptimizer

# Passing an evaluated reference (the result of a call)
build_model.network_fn = @DNN()

For complex experiments, you can combine multiple .gin files and pass individual parameter overrides via command-line flags.

A common pattern using absl flags is to define multi_string flags for files and parameters, then parse them using gin.parse_config_files_and_bindings.

Importing Python modules in Gin

To make dependencies explicit, you can import Python modules directly within a .gin file using standard Python syntax. This ensures the modules are imported and their configurables are registered when the Gin file is parsed.

import some.module.spec

Including other Gin files

You can split large configurations into smaller components using the include statement. The included file is parsed as if its content were literally pasted at the location of the include statement.

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