-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathREADME.html
218 lines (151 loc) · 7.81 KB
/
README.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
<h1>PRECONFIG, a versatile configuration file generator</h1>
<h1>Overview</h1>
<p>Preconfig generates files from a template by evaluating doubly-bracketed Python code.</p>
<h1>Description</h1>
<p>Preconfig reads a 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.</p>
<p>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.</p>
<p>Examples:</p>
<ul>
<li>config.cym.tpl --> config0000.cym, config0001.cym, config0002.cym, etc.</li>
<li>config.txt.tpl --> config0000.txt, config0001.txt, config0002.txt, etc.</li>
<li>model.xml.tpl --> model0000.xml, model0001.xml, model0002.xml, etc.</li>
</ul>
<p>The width of the variable part (default=4) can be changed on the command line.
For instance, to specify a width of 2, simply invoke "preconfig -2 ...".</p>
<h1>Syntax</h1>
<pre><code>preconfig [OPTIONS] TEMPLATE_FILE [ADDITIONAL_TEMPLATE_FILES]
</code></pre>
<h2>Options</h2>
<ul>
<li><p>if a positive integer REPEAT is specified, each template file will be
processed REPEAT times, for example: <code>preconfig 3 config.cym.tpl</code> will parse
the template three times and generate three times more files.</p></li>
<li><p>if the path to an existing directory is specified, files will be created
in this directory, for example: <code>preconfig dir config.cym.tpl</code></p></li>
<li><p>DEFINITIONS can be specified on the command line as 'name=value' or
'name=sequence', with no space around the '='. They are added to the
dictionary used to evaluate the code snippets found inside the template file,
for example: <code>preconfig n_molecules=100 config.cym.tpl</code></p></li>
<li><p>if a negative integer is specified, this will set the width of the integer
that is used to build the file namess.
For example: <code>preconfig -2 config.cym.tpl</code> will create 'config00.cym', etc.</p></li>
<li><p>if a '-' is specified, all accessory output is suppressed</p></li>
<li><p>if a '+' is specified, more detailed information on the parsing is provided.</p></li>
<li><p>if '++' or 'log' is specified, a file 'log.csv' will be created containing one
line for each file created, containing the substitutions operated for this file.</p></li>
<li><p>if '--help' is specified, this documentation will be printed.</p></li>
</ul>
<h2>Code Snippets</h2>
<p>Any plain python code can be embedded in the file, and functions from the
<a href="https://docs.python.org/library/random.html">Random Module</a> 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.</p>
<h3>Example 1</h3>
<p>Generate all combinations with multiple values for 2 parameters</p>
<pre><code>rate = [[ [1, 10, 100] ]]
speed = [[ [-1, 0, 1] ]]
</code></pre>
<p>To generate the files, issue this command in the terminal:</p>
<p><code>> preconfig config.cym.tpl</code></p>
<p>In this case, Preconfig will generate 9 files.</p>
<h3>Example 2</h3>
<p>Scan multiple parameters values randomly</p>
<pre><code>diffusion_rate = [[ random.uniform(0,1) ]]
reaction_rate = [[ random.choice([1, 10, 100]) ]]
abundance = [[ random.randint(0, 1000) ]]
</code></pre>
<p><code>> preconfig 100 config.cym.tpl</code></p>
<p>In this case, Preconfig is instructed to generate 100 files.</p>
<h3>Example 3</h3>
<p>Regularly scan 2 parameters with 10 values each,
one according to a linear scale, and the other with a geometric scale</p>
<pre><code>[[ x = range(10) ]]
[[ y = range(10) ]]
reaction_rate = [[ 1 + 0.5 * x ]]
diffusion_rate = [[ 1.0 / 2**y ]]
</code></pre>
<p><code>> preconfig config.cym.tpl</code></p>
<p>In this case, Preconfig will generate 100 files.</p>
<h3>Example 4</h3>
<p>Randomize two parameters while keeping their ratio constant.</p>
<pre><code>[[ x = random.uniform(0,1) ]]
binding_rate = [[ 10.0 * x ]]
unbinding_rate = [[ x ]]
</code></pre>
<p><code>> preconfig 100 config.cym.tpl</code></p>
<p>In this case, Preconfig is instructed to generate 100 files.</p>
<h3>Example 5</h3>
<p>Randomize one parameter, using 256 values in ascending order:</p>
<pre><code>[[ x = sorted([random.uniform(0.10, 0.25) for i in range(256)]) ]]
binding_rate = [[ x ]]
</code></pre>
<p>Command: <code>preconfig TEMPLATE_FILE</code>
In this case, the number of files (256) is specified in the template</p>
<h3>Example 6</h3>
<p>Boolean variables can be used to introduce qualitative differences:</p>
<pre><code>[[ enable = random.choice([0, 1]) ]]
feeback = [[ random.uniform(0, 1) if (enable) else 0 ]]
</code></pre>
<p><code>> preconfig 100 config.cym.tpl</code></p>
<h3>Example 7</h3>
<p>Randomize a value, and print this value as a comment in the file:</p>
<pre><code>[[ x = random.uniform(0,1) ]]% [[x]]
</code></pre>
<p>This sets a value for x, and print this value after '%',
In this case the '%' is used to indicate a comment, such that the line is skipped by
the simulation program that reads the file. However, the value can be read by any
analysis script that will later process the results of the simulation.
The value <code>x</code> can be used later:</p>
<pre><code>binding_rate = [[ 10*x ]]
unbinding_rate = [[ 2*x ]]
</code></pre>
<p>To generate 256 files:</p>
<p><code>> preconfig 256 TEMPLATE_FILE</code></p>
<h1>Tutorial</h1>
<p>To use Preconfig, follow this steps:</p>
<ul>
<li>copy a configuration file and add '.tpl' to the name (<code>cp config.cym config.cym.tpl</code>)</li>
<li>edit the template file you created, to add some double bracketed snippets,
following the examples above.</li>
<li>run Preconfig (<code>preconfig config.cym.tpl</code>)</li>
<li>invoke your favorite simulation tool with each file (e.g. with the UNIX command <a href="https://en.wikipedia.org/wiki/Xargs">xargs</a>)</li>
</ul>
<h1>Requirements</h1>
<p>A template file, and the <a href="https://www.python.org">Python</a> interpreter</p>
<h1>Testing</h1>
<p>We provide three type of template files to test Preconfig:</p>
<ul>
<li><a href="www.cytosim.org">Cytosim</a> configuration files: <code>config?.cym.tpl</code></li>
<li><a href="www.smoldyn.org">Smoldyn</a> configuration file: <code>smoldyn.txt.tpl</code></li>
<li><a href="www.biomodels.org">BioModel</a> XML configuration file: <code>BioModel.xml.tpl</code></li>
</ul>
<p>To test them, please enter the following commands, one by one:</p>
<pre><code>preconfig configA.cym.tpl
preconfig configB.cym.tpl 16
preconfig configC.cym.tpl
preconfig smoldyn.txt.tpl
preconfig BioModel.xml.tpl
</code></pre>
<h1>Credits & Licence</h1>
<p>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!</p>
<p>Copyright Francois J. Nedelec, 2010--2017.</p>
<p>This is Free Software with absolutely no WARRANTY.</p>
<p>Preconfig is distributed under GPL3.0 Licence (see LICENSE)</p>
<h1>Feedback</h1>
<p>Your feedback is very much appreciated, please send it to:
feedback(xxx)cytosim.org</p>