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
219
220
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML><HEAD>
<TITLE>Basic User Experience</TITLE>
<LINK rel="Bookmark" title="libctl Manual" href="index.html">
<LINK rel="Bookmark" title="Ab Initio Physics Home Page"
href="http://ab-initio.it.edu">
<LINK rel="Contents" href="index.html">
<LINK rel="Copyright" href="license.html">
<LINK rel="Start" href="index.html">
<LINK rel="Previous" href="introduction.html">
<LINK rel="Next" href="advanced-user.html">
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFFF">
Go to the <a href="advanced-user.html">next</a>, <a
href="introduction.html">previous</a>, or <a href="index.html">main</a>
section.
<hr>
<h1>Basic Control Files</h1>
At their most basic level, <b>ctl</b> files are simply a collection of
values for parameters required by the simulation.
<p>For example, suppose that the simulation solves a one-dimensional
differential equation and requires an input called "grid-size"
specifying the number of grid points used in the discretization of the
problem. We might specify this in a ctl file by the statement:
<pre>
(set! grid-size 128)
</pre>
<p>All input variable settings follow the format <code>(set!
<i>variable</i> <i>value</i>)</code>. The parentheses are important,
but white space is ignored.
<p>Settings of input variables can appear in any order at all in the
file. They can even be omitted completely in many cases, and a
reasonable default will be used. Variables can be of many different
types, including integers, real numbers, boolean values
(<code>true</code> and <code>false</code>), strings, 3-vectors, and
lists. Here is how we might set some parameters of various types:
<pre>
(set! time-step-dt 0.01) ; a real number
(set! output-file-name
"data.hdf") ; a string
(set! propagation-direction (vector3 0 0.2 7)) ; a 3-vector
(set! output-on-time-steps ; a list of integers...
(list 25 1000
257 128 4096))
</pre>
<p>Everything appearing on a line after a semicolon (";") is a
<b>comment</b> and is ignored. Note also that we are free to split
inputs over several lines--as we mentioned earlier, white space is
ignored.
<p>3-vectors are constructed using <code>(vector3 <i>x [y
[z]]</i>)</code>. If the <i>y</i> or <i>z</i> components are omitted,
they are set to zero. Lists may contain any number of items
(including zero items), and are constructed with <code>(list <i>[item1
item2 ...]</i>)</code>.
<p>A typical control file is terminated with a single statement:
<pre>
(run) ; run the computation
</pre>
This tells the program to run its computation with whatever parameter
values have been specified up to the point of the <code>(run)</code>.
This command can actually appear multiple times in the ctl file,
causing multiple runs, or not at all, which drops the user into an
interactive mode that we will discuss later.
<h2>Running a simulation</h2>
The user runs the simulation program simply by:
<pre>
<i>program</i> <i>ctl-files</i>
</pre>
Here, <code><i>program</i></code> is the name of the simulation
program executable and <i>ctl-files</i> are any ctl files that you
want to use for the run. The result is as if all the <i>ctl-files</i>
were concatenated, in sequence, into a single file.
<h2>Structured Data Types</h2>
For many programs, it is useful to structure the input into more
complicated data types than simple numbers, vectors, and lists. For
example, an electromagnetic simulation might take as input a list of
geometric objects specifying the dielectric structure. Each object
might have several parameters--for example, a sphere might have a
radius, a center, and a dielectric constant.
<p>libctl allows programs to specify structured datatypes, called
<b>classes</b>, that have various properties which may be set. Here
is what a list of geometric objects for a dielectric structure might
look like:
<pre>
(set! geometry
(list
(make sphere (epsilon 2.8) (center 0 0 1) (radius 0.3))
(make block (epsilon 1.7) (center 0 0 1) (size 1 3.5 2))))
</pre>
<p>In this case, the list consists of two objects of classes called
<code>sphere</code> and <code>block</code>. The general format for
constructing an object (instance of a class) is <code>(make
<i>class</i> <i>properties</i>)</code>. <i>Properties</i> is a
sequence of <code>(<i>property</i> <i>value</i>)</code> items setting
the properties of the object.
<p>Properties may have default values that they assume if nothing is
specified. For example, the <code>block</code> class might have
properties <code>e1</code>, <code>e2</code>, and <code>e3</code> that
specify the directions of the block edges, but which default to the
coordinate axes if they are not specified. Typically, each class will
have some properties that have defaults, and some that you are
required to specify.
<p>Property values can be any of the primitive types mentioned
earlier, but they can also be other objects. For example, instead of
specifying a dielectric constant, you might instead supply an object
describing the material type:
<pre>
(define Si (make material-type (epsilon 11.56)))
(define SiO2 (make material-type (epsilon 2.1)))
(set! geometry
(list
(make sphere (material Si) (center 0 0 1) (radius 0.3))
(make block (material SiO2) (center 0 0 1) (size 1 3.5 2))))
</pre>
<p>We have snuck in another feature here: <code>(define
<i>new-variable</i> <i>value</i>)</code> is a way of defining new
variables for our own use in the control file. (This and other
features of the Scheme language are discussed in the next section.)
<h2>What Do I Enter?</h2>
Every program will have a different set of variables that it expects
you to set, and a different set of classes with different properties.
Whatever program you are using should come with documentation saying
what it expects.
<p>You can also get the program to print out help by inserting the
<code>(help)</code> command in your ctl file, or by entering it in <a
href="advanced-user.html#interactive">interactive mode</a>. You can
also simply enter the following command in your shell:
<pre>
echo "(help)" | <i>program</i>
</pre>
<p>For example, the output of <code>(help)</code> in the
electromagnetic simulation we have been using in our examples might
look like:
<pre>
Class block:
Class geometric-object:
material-type material
vector3 center
vector3 e1 = #(1 0 0)
vector3 e2 = #(0 1 0)
vector3 e3 = #(0 0 1)
vector3 size
Class sphere:
Class geometric-object:
material-type material
vector3 center
number radius
Class geometric-object:
material-type material
vector3 center
Class material-type:
number epsilon
number conductivity = 0.0
Input variables:
vector3 list k-points = ()
geometric-object list geometry = ()
integer dimensions = 3
Output variables:
number list gaps = ()
number mean-dielectric = 0.0
</pre>
<p>As can be seen from above, the help output lists all of the classes
and their properties, along with the input and output variables (the
latter will be described later). Any default values for properties
are also given. Along with each variable or property is given its
type.
<p>You should also notice that the class <code>geometric-object</code>
is listed as a part of the classes <code>block</code> and
<code>sphere</code>. These two classes are <b>subclasses</b> of
<code>geometric-object</code>. A subclass inherits the property list
of its superclass and can be used any place its superclass is allowed.
So, for example, both spheres and blocks can be used in the
<code>geometry</code> list, which is formally a list of
geometric-objects. (The astute reader will notice the
object-oriented-programming origins of our class concept; our classes,
however, differ from OOP in that they have no methods.)
<hr>
Go to the <a href="advanced-user.html">next</a>, <a
href="introduction.html">previous</a>, or <a href="index.html">main</a>
section.
</BODY>
</HTML>
|
