Nengo configuration

Certain features of Nengo can be configured globally through RC settings.

RC settings can be manipulated either through the nengo.rc object, or through RC configuration files.

The nengo.rc object

The nengo.rc object gives programmatic access to globally configured features of Nengo.

nengo.rc = <nengo.rc._RC object>

Allows reading from and writing to Nengo RC settings.

This object is a configparser.ConfigParser, which means that values can be accessed and manipulated like a dictionary:

oldsize = nengo.rc["decoder_cache"]["size"]
nengo.rc["decoder_cache"]["size"] = "2 GB"

All values are stored as strings. If you want to store or retrieve a specific datatype, you should coerce it appropriately (e.g., with int()). Booleans are more flexible, so you should use the getboolean method to access boolean values.

simple = nengo.rc["exceptions"].getboolean("simplified")

In addition to the normal configparser.ConfigParser methods, this object also has a reload_rc method to reset nengo.rc to default settings:

nengo.rc.reload_rc()  # Reads defaults from configuration files
nengo.rc.reload_rc(filenames=[])  # Ignores configuration files

Configuration files

nengo.rc is initialized with configuration settings read from the following files with precedence to those listed first:

1. nengorc in the current directory. This is intended to allow for project specific settings without hard coding them in the model script.

2. An operating system specific file in the user’s home directory.

   • Windows: %userprofile%\.nengo\nengorc

   • Other (OS X, Linux): ~/.config/nengo/nengorc

3. INSTALL/nengo-data/nengorc (where INSTALL is the installation directory of the Nengo package).

The RC file is divided into sections by lines containing the section name in brackets, i.e. [section]. A setting is set by giving the name followed by a : or = and the value. All lines starting with # or ; are comments.

For example, to set the size of the decoder cache to 512 MB, add the following to a configuration file:

[decoder_cache]
size = 512 MB

Configuration options

All of the configuration options are listed in the example configuration file, which is included with Nengo and copied below.

Commented lines show the default values for each setting.

[precision]

# Default bit precision for all NumPy arrays made by Nengo (e.g., bits: 64
# would use float64/int64 dtypes). Must be one of '16', '32', or '64'. (string)
#bits: 64

# --- Settings for the decoder cache
[decoder_cache]

# Enable or disable the cache. (bool)
#enabled = True

# Path where the cached decoders will be stored. (str)
#path = ~/.cache/nengo/decoders  # Linux/Mac OS X default

# Set the cache to readonly. In readonly mode cached decoders will be
# loaded, but no newly calculated decoders will be written to the cache.
# (bool)
#readonly = False

# Set the maximum cache size. Whenever the cache exceeds this limit, cached
# decoders will be deleted, beginning with the oldest, until the limit
# is met again. Please specify the unit (e.g., 512 MB). (str)
#size = 512 MB


# --- Settings for error messages due to exceptions
[exceptions]

# Use simplified exceptions. In most cases, simplified exceptions will be
# easier to read and more useful for model development. However,
# developers of Nengo internals or tools extending Nengo
# may benefit from full exception tracebacks.
#simplified = True


# --- Settings for the progress bar used when running the simulator
[progress]

# Set the progress bar to use. The default of 'auto' or will display
# a progress bar when the estimated simulation run time exceeds one second.
# Setting this to 'none' will disable to progress bar. Any other string
# will be interpreted as a module and class name
# (e.g., 'nengo.utils.progress.ProgressBar'), which Nengo will attempt
# to load. (str)
#progress_bar = auto


# --- Settings for the Nengo core simulator
[nengo.Simulator]

# Fail misconfigured operators immediately. If True, operators are tested
# when they are created in build functions, rather than when they are
# initialized by the simulator. Failing fast is useful when creating and
# debugging new operators, but adds some time to the build.
#fail_fast = False