PRECONFIG, a versatile configuration file generator

Overview

Preconfig is a Python program used to vary parameter values in files.

Description

Preconfig reads the template file from top to bottom, identifying snippets of code which are surrounded by double square brackets. It then executes this code using the Python interpreter, proceeding recursively whenever multiple values are specified. Values are eventually converted to their string representation, and substituted in place of the code snippet. In this way, Preconfig will generate all the possible combinations following the order in which these combinations were specified in the file. Importantly, any accompanying text in the template file is copied verbatim to the output file, such that any syntax present in the configuration file can be maintained during the process.

At least one template file should be specified, and other arguments are optional. If several template files are specified, they will be processed sequentially. The names of the produced files are built from the name of the template by removing any second extension, and inserting an integer of constant width.

Examples:

The width of the variable part (default=4) can be changed on the command line. For example, to specify a width of 2, simply add "-2".

Syntax

preconfig [OPTIONS] TEMPLATE_FILE [ADDITIONAL_TEMPLATE_FILES]

Options

Code Snippets

Any plain Python code can be embedded in the file, and functions from the Random Module can be used. It is possible to use multiple bracketed expressions in the same file, and to define variables in the Python environment. An integer 'n', starting at zero and corresponding to the file being generated is automatically defined.

Example 1

Generate all combinations with multiple values for 2 parameters

rate = [[ [1, 10, 100] ]]
speed = [[ [-1, 0, 1] ]]

To generate the files, issue this command in the terminal:

> preconfig config.cym.tpl

In this case, Preconfig will generate 9 files.

Example 2

Scan multiple parameters values randomly

diffusion_rate = [[ random.uniform(0,1) ]]
reaction_rate = [[ random.choice([1, 10, 100]) ]]
abundance = [[ random.randint(0, 1000) ]]

> preconfig 100 config.cym.tpl

In this case, Preconfig is instructed to generate 100 files.

Example 3

Regularly scan 2 parameters with 10 values each, one according to a linear scale, and the other with a geometric scale

[[ x = range(10) ]]
[[ y = range(10) ]]
reaction_rate = [[ 1 + 0.5 * x ]]
diffusion_rate = [[ 1.0 / 2**y ]]

> preconfig config.cym.tpl

In this case, Preconfig will generate 100 files.

Example 4

Randomize two parameters while keeping their ratio constant.

[[ x = random.uniform(0,1) ]] 
binding_rate = [[ 10.0 * x ]]
unbinding_rate = [[ x ]]

> preconfig 100 config.cym.tpl

In this case, Preconfig is instructed to generate 100 files.

Example 5

Boolean variables can be used to introduce qualitative differences:

[[ enable = random.choice([0, 1]) ]]
feeback = [[ random.uniform(0, 1) if (enable) else 0  ]]

> preconfig 100 config.cym.tpl

Example 6

Randomize a value, and print this value as a comment in the file. The second line below constructs a string, from the value of 'x'.

[[ x = random.uniform(0,1) ]]
[[ "%set x= " + str(x) ]]

> preconfig 100 config.cym.tpl

Tutorial

To use Preconfig, follow this steps:

Requirements

A template file, and the Python interpreter

Testing

We provide three type of template files to test Preconfig:

To test them, please enter the following commands, one by one:

preconfig configA.cym.tpl
preconfig configB.cym.tpl 16
preconfig configC.cym.tpl
preconfig smoldyn.txt.tpl
preconfig BioModel.xml.tpl

Download

To install, move 'preconfig' into your $PATH, and make sure it is executable:

	chmod +x preconfig

Credits & Licence

We wish to thank the members of the Nedelec group, and all users of Cytosim for their feedback which has contributed greatly to this development. We also thank Shaun Jackman and Steven Andrews for valuable feedback!

Copyright Francois J. Nedelec, 2010--2017.

This is Free Software with absolutely no WARANTY.

Preconfig is distributed under GPL3.0 Licence (see LICENCE)

Feedback

Your feedback is very much appreciated, please send it to: feedback(xxx)cytosim.org