Customizing your experiments

Experiments are stored in special files consisting solely of a single Python dictionary literal.

There are three kinds of experiments: (1) standard experiments (2) sequences of experiments called a “metarun”, and (3) quick scripts. These categories are outline when you run make prep? to list the available experiments. Each type has specific requirements outlined in the acme section, but all three types make use of a large block of text named settings.

Two other key variables are important to the experiments: a params file which contains input specifications for gromacs and processed by write_mdp(), and the relative path to the procedure script.

Settings

Settings are written in a custom format loosely based on the YAML format. In short, settings are specified by key-value pairs delimited by a colon. Python will try to evaluate the following text using its eval statement, otherwise the result is stored as a string. Multiline texts use a blasé colon-pipe :| operator which reads indented text. Any tab sequence is allowed, and the parser stops reading the text where the indentation ends.

Automacs makes all of the settings available in the shared namespace by using either standard dictionary notation (state['water_thickness']) or a more concise attribute notation (state.water_thickness). For this reason, all settings keys have spaces replaced by the underscore character. The settings are not actually loaded into state, which checks settings for keys that cannot be found inside of it. The state.q('key','default') function works like the dictionary get function in python, allowing you to provide a default value of the key also cannot be found in the settings block.

Many automacs functions refer to the settings to guide the construction of the simulation.

Extensions

Extensions can be specified using wildcards so you can import the entire inputs/extras package by including inputs/extras/*.py in the extensions list in an experiment. Extensions are automatically imported by automacs whenever it is imported. This saves users the trouble of managing the imports: any function in any extension is elevated to the automacs namespace. Users can still use standard, pythonic imports from these extensions (see an example in the acme section), however the experiment’s extensions list manages everything that goes into the namespace.

The extensions list also overrides core automacs functionality, which means that you can easily tune or change these functions however you like, in new extensions. Your extensions can also make use of any third-party or entirely generic code modules (read: those codes not affiliated with automacs).