tempus Glossary
Symbols A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
This glossary is intended to help current and prospective tempus users gain a better understanding of how tempus works, and how it can be used. We have tried to provide definitions for all unfamiliar or specially defined terms likely to be encountered in the course of using the tempus visual editor and/or working with tempus at the source code level; if you find any omissions, please email us at tempus@mza.com. For the convenience of those less familiar with object-oriented programming (OOP) and C++, we have included some of that terminology as well; for a more thorough treatment see The C++ Programming Language by Bjarne Stroustrup. Among the terms defined are a number of C++ classes, functions, and operators; all C++ source code appears in a fixed font to distinguish it from ordinary text. Class names and operators are indicated by parenthetical comments, while function names are indicated by empty parentheses. Only the most commonly encountered classes and functions are documented here; for complete source code documentation see the tempus Programmer’s Manual. All terms appearing in italics in definitions are themselves defined in the glossary.
=>> (C++
operator)
a C++ binary operator used to establish connections between subsystem
outputs or external inputs (on the left side) and subsystem inputs or external
outputs (on the right side).
<<= (C++
operator)
a C++ binary operator used to establish connections between subsystem
outputs or external inputs (on the right side) and subsystem inputs or
external outputs (on the left side).
advanceTime()
A global function used to control the advance of virtual time in the
current default virtual universe. advanceTime()
takes a single argument specifying the amount by which the virtual time
is to be advanced.
advanceTimeUntil()
A global function used to control the advance of virtual time in the
current default virtual universe. advanceTimeUntil()
takes a single argument specifying the time to which the virtual time is
to be advanced.
Atomic system class
A system class which contains no subsystems. Generally the .h file
for an atomic system class will have been modified by hand in order to
define the behavior desired by the system class designer; otherwise systems
of the class would simply be inert. Defining the behavior would involve
overriding one or more of the four respondTo- methods, possibly
adding logic to the constructor and/or destructor, and possibly adding
additional data members and/or member functions. For system classes with
simple behaviors the designer may choose to keep complete implementation
may be in kept .h file, but for more complex behaviors it is good practice
to put the logic in a separate .cpp file, to permit separate compilation.
See also
system class, .h file, .cpp file, respondTo-
methods.
Base class
A class from which another more specialized class is derived, which
defines a portion of the interface and/or implementation of the derived
class. See also derived class.
Binary operator
An operator such as + or = which takes two arguments, which appear
on either side of the operator. Apart from the syntax, a binary operator
is exactly equivalent to a function taking two arguments. A binary operator
can be defined either as a global function, or as a member function of
its first (left side) argument.
(C++ intrinsic type)
bool is a C++ intrinsic type used to represent Boolean (true/false) values.
C++
One of the most widely used object-oriented programming languages (OOPL).
"C++ code"
There are two places in the visual editor where the user can type in
C++ source code to be inserted into the automatically generated source
code. One is in the system class edit window, for code to be inserted
in the system class .h file before the class declaration, and is typically
used to put in include statements for C++ header files which define functions
and/or constants for use in setting expressions. Other possible applications
would include defining functions or constants in-line, or precomputing
results needed in multiple setting expressions. The second place is in
the run set edit window, for code to be inserted at the top of the
main program, and is used in much the same way.
cancelEvent()
A method of class System used in system classes to cancel previously
scheduled events. cancelEvent() takes one
argument, of type EventId, used to specify
which event is to be canceled. (The EventId
for an event is the return value of scheduleEvent.)
cancelEvents()
a method of class System used in system classes to cancel all previously
scheduled events. cancelEvents() takes
no arguments.
Class
One of the key concepts in object-oriented programming, a class is
the most general kind of user-defined type, defining both the state information
used by objects of the class (data members) and their behavior (member
functions). Classes may be related to one another via inheritance
relationships, wherein base classes define portions of the interface
and/or implementation of derived classes.
Complex is a C++ class, part of the tempus support libraries, use to represent complex numbers. The memory layout exactly matches the way complex numbers are stored in Fortran, so that complex numbers and arrays can be passed between Fortran and C++. In the near future all occurrences of Complex in tempus will be replaced with complex<float>, which shares the same memory layout, and is part of the new ANSI standard for C++.
Composite system class
A system class with contains one or more subsystems. Unlike an atomic
system class, the .h file for a composite system class would normally be
hand-modified. Instead, the behavior of a composite system is defined by
the behaviors of its subsystems, their parameter settings, and the way
they are connected. See also system class, atomic system class.
A “connection” in tempus refers to a relationship established between an object used to refer some other object, e.g. a subsystem input, and another object which serves as the referent for the first object, e.g. a subsystem output. Connections are represented graphically in the GUI as arrows from the referent objects to the reference objects.
const
A C++ keyword related to the notion of read-only access. An object
or reference may be designated as const, to make it clear that it should
not be modified within the given context. A member function of a class
may also be designated const, to indicate that calling that function will
not result in a change in the object’s state, and therefore that that function
may be called for a const object.
Constructor
A special member function of a class, used to create and initialize
objects of that class.
.cpp file
A C++ source code file.
.cpp file (for a run set)
A C++ source code file containing the main program for a run set, with
a name of the form <system class name>+"Run"+<run set name>+".cpp".
.cpp file (for a system class)
A C++ source code file sometimes used to store the functions defining
the behavior of a system class, named the same as the system class, but
with the extension ".cpp". A .cpp file is used only in cases where the
.h file has been modified by hand, and only when the system class designer
chooses to do so, in order to permit separate compilation.
Data member
An object (or variable) that constitutes part of the state information
for a given class. A class may have any number of data members, each with
its own unique name, and each may be of any legal C++ type. Ordinary (non-static)
data members are used to store data related to one specific object of the
class, and are accessed using a ‘dotted" notation, as shown:
myObject.myDataMember.
Static data members are used to store data shared among all objects of
the class, and are accessed using the class name followed by a double colon,
as follows: MyClass::myStaticDataMember.
Deep copy
A copy operation performed on a usage instance of a class, that involves
copying not only the instance information, but also the class itself, and
also any other classes needed by that class. For example whenever the user
cuts and pastes a subsystem from a work directory to any other directory
(another work directory or a library directory), a deep copy is
performed: all the classes for the subsystem, its subsystems, and so forth
found in the source directory are copied to the destination directory.
Classes from library directories are not copied however, as they should
still be accessible from the destination directory. See also shallow
copy.
Default value (for input or parameter)
A setting expression provided by the designer of a system class
to be used to set the value of an input to that class in case that input
is not connected and no other setting expression has been provided. The
expression is evaluated in the scope of the containing class, so the only
way to ensure that it will be valid is to use either no symbols at all,
e.g. a numerical consant, or only symbols defined in the user-provided
C++ code. Alternately, the designer may choose to use symbols in the default
expression, and rely on the automatic error-checking mechanisms to inform
the user about the undefined symbols, which he may then choose to make
parameters of the containing system class.
Derived class
A class that is derived from another less specialized class, its base
class, which defines a portion of the interface and/or implementation of
the derived class. See also derived class.
Destructor
A special member function for a class, called when an object of that
class is to be removed from memory, and typically used to perform any necessary
cleanup, such as freeing dynamically allocated memory.
double is a C++ intrinsic type used to represent real-valued numbers, similar to float, but with greater precision and range.
Event
Events are used in modeling discrete transitions in a system’s state
caused by its internal time dependence. Generally each system which undergoes
such transitions schedule events for itself, and only for itself, using
the method scheduleEvent(). Each call to scheduleEvent()
results in a delayed call-back to the virtual method respondToScheduledEvent(),
unless it is cancelled before, using cancelEvent().
Each event has a character string descriptor, used to distinguish between
different types of state transitions, and a void*
pointer which can be used to attach information pertaining to the event.
For example in modeling a packet-based communications system the pointer
might be used to attach the contents of a message packet.
Event queue
A data structure containing all pending events for all systems within
a given virtual universe, in order of their scheduled execution times.
The simulation progresses, and virtual time advances, as events are pulled
off the front of the queue and executed; this happens within advanceTime().
Events can be placed on the queue using scheduleEvent(),
and removed from the queue using cancelEvent().
EventId (C++
class)
An object used to identify a specific event, which can be used for
the purpose of canceling that event. Each call to scheduleEvent()
returns an EventId, and cancelEvent()
takes an EventId as an argument.
External input
An input to a system or system class; the adjective "external" is sometimes
used to make it clear we are referring to an input of the system, rather
than an input of one of its subsystems.
External output
An output of a system or system class; the adjective "external" is
sometimes used to make it clear we are referring to an output of the system,
rather than an output of one of its subsystems.
For-loop
A loop that repeats the same sequence of comands until a specified
condition is met. Typically a for-loop has a loop variable, and
integer variable which starts at zero and increments with each iteration
of the loop, and exit condition is met when that counter reaches a specified
number.
float is a C++ intrinsic type used to represent real-valued numbers.
Grid is a C++ template class, part of the tempus support libraries, used to define a two-dimensional rectangular grid over a specific rectangular region on a plane. A Gird<float> can be used to define a real-valued function over such a region, e.g. light intensity, while a Grid<float> can be used to define a complex-valued function, such as a complex field. Grid is used extensively in WaveTrain, both internally, and at the user interface level, where parameters of type Grid can be used to specify things like reflectance maps and detector responsivities.
GridGeometry is a C++ class, part of the tempus support libraries, used to define the geometry of a two-dimensional rectangular grid over a specific rectangular region on a plane. GridGeometry is used to specify the geometry for instances of the template class Grid, which is used extensively in WaveTrain, to describe things like optical wavefronts, reflectance maps and detector responsivities.
.h file
See header file.
.h file (for a system class)
A C++ header file which contains the source code definition for a system
class, named the same as the system class, but with the extension ".cpp".
The .h file may be entirely automatically generated – generally the case
for composite system classes – or it may be modified by hand – generally
the case for atomic system classes. When a .h file has been hand-modified,
and is later automatically regenerated, e.g. when the user modifys the
interface in the visual editor then does a "save", the obsolete hand-modified
version is automatically appended to the new generated version, for use
in cutting and pasting.
Hard real-time
A hard real-time application is one in which strict and precise time
constraints apply, and failure to meet those constraints would result in
unacceptable consequences. A typical example would be an automated control
loop for a weapons system.
hasChanged()
A method of class Input, used by a
system to check whether the value of a particular Input has changed since
the last call to respondToChangedInputs(). hasChanged()
takes no arguments, and returns a bool.
It is typically called within respondToChangedInputs(),
to determine which inputs have changed, and which have not.
Header file
A source code file, typically with the extension ".h", intended to
be included into other source code files, both .h and .cpp. One common
use is define constants used in multiple places; another is to define the
interface for one or more classes and/or global functions, but often not
the actual implementation, which instead is put into a separate .cpp file,
so that it may be compiled separately.
.html file (for a system class)
A hypertext help file for the system class, named the same as the system
class, but with the extension ".cpp". A simple version is generated automatically,
listing inputs, outputs, parameters, and subsystems, and so forth; additional
text can be added by hand as desired.
Include file
See header file.
Include statement
A C++ precompiler directive, used to indicated that the source code
from a specified header file should be included into that of the
present file, at the site of the include statement, prior to compilation.
This mechanism is used to introduce definitions for classes, functions,
and/or constants to be used later in the present file.
Inheritance
One of the key concepts of object-oriented programming (OOP), inheritance
is the mechanism by which one class, a derived class, can derive
part of its interface and/or implementation from another, its base class.
The derived class inherits all the data members and member functions of
its base class, and may add its own. Also, a base class may define virtual
methods, used to provide a common external interface to all derived
classes, while permitting their specific behaviors to differ.
Input
A part of the external interface of a system or system class, used
to define how a system’s environment can act upon the system. An input
is a proxy object, an object which "stands for" some other object,
typically an output from some other system. An input provides only read-only
access to the referent object. This relationship is established by connecting
the input to the output, using one of the operators <<=
or =>>. Each input must be connected to
exactly one output, unless a default value has been provided, in which
case it need not be connected. A system may have any number of inputs,
and each has a name (a character string, which must be a legal C++ variable
name) and a type (any C++ type, including user-defined types). A system
is automatically notified each time any of its inputs may be about to undergo
a discrete state transition, such as a change of value, via a call to the
virtual method respondToInputWarning(),
and receives a second notice after the transition has occurred via a call
to the virtual method respondToChangedInputs().
Also, whenever a system tries to access the value of one of its inputs,
the system with the connected output is notified via a call to the virtual
method respondToOutputRequest().
Input
(C++ class)
Part of the tempus kernel library, Input
is a C++ template class used to represent system inputs.
int is a C++ intrinsic type used to represent integer-valued numbers.
Instance (of a class)
Generally, the term "instance" refers to a specific object of the class,
resident in memory. Sometimes the term is also used to refer to a specific
variable of the class type, such as a data member of a class, even when
that same variable may represent multiple actual objects. For each (non-static)
data member of a class, there are as many actual objects as there were
instances of the class. We sometimes refer to the latter case as a usage
instance, to distinguish it from the first.
Library (or library directory)
A directory used to store tempus system classes intended for reuse.
To designate a directory to be a library, one puts a text file named "tempus_resources"
in the directory, containing the line "IS_LIBRARY=TRUE"; any directory
containing tempus system classes and not so designated is considered a
"work directory". The distinction between the two is that in a work directory
it is assumed that the user is trying to use tempus as a tool, to solve
a problem, whereas a library directory is used to extend the capabilities
of tempus, by providing a set of reusable and mutually compatible components.
In a work directory the user typically makes frequent changes to his system
classes, as he develops and refines his overall system model or models,
so it would not make sense to use those same system classes as subsystems
in unrelated models. In contrast, system classes in a library directory
are intended for reuse and designed for it, and may be used as subsystems
in any number of work directories. This difference is reflected in tempus’
copy mechanism: when one copies a subsystem from a system class in a library
directory into a system class in another directory, a shallow copy
is performed; which introduces a dependence between the destination directory
and the library directory. When one copies a subsystem from a system class
in a work directory into a system class in another directory, a deep
copy is performed, and no such dependence is introduced.
Lazy evaluation
The strategy of waiting until the results of a computation are needed
before performing the computation, as opposed to, for example, computing
it as soon as new inputs value become available. This strategy is especially
useful when the inputs may change more often than the results are needed,
and each computation costs appreciable cpu-time.
Legal variable name (in C++)
Legal variable names in C++ may be up to 255 characters long, consisting
of letters, numerals, and underscores, and must begin with a letter or
underscore. Variable names cannot be the same as C++ keywords, or the same
as other variable names in the namespace. C++ is case-sensitive.
Loop variable
An integer variable, used in conjunction with a for-loop, which
starts at zero and increments with each iteration of the loop, and exit
condition is met when that counter reaches a specified number.
Loop variable (in a run set)
Loop variables are a special type of run variable, used to define
a set of nested for-loops within a run set, while the actual simulation
runs would take place inside the innermost loop. To add a for-loop in the
Run Set Edit window, one simply adds a new run variable, say iloop,
and sets its type to int and its value
to $loop(niter), where niter
specifies the number of loop iterations. In the generated source code this
would appear as follows, where we have set niter
equal to 3:
for (iloop=0; iloop<3; iloop++){…}
Generally the reason one would wish to set up a for-loop would be to change the value of one or more system parameters with each iteration of the loop. This is done by setting the value of the parameter to an expression of the form [iloop]:{v1,v2,v3…}, where v1,v2,v3… are the desired values for the parameter, one for each loop iteration, or of the form [iloop]: expression, where expression is any legal C++ expression, generally involving the loop variable. If multiple loop variables are used, the for-loops are nested, with the loop corresponding to the first loop variable outermost. To make a parameter dependent on two or more loop variables, one simply lists them inside the square brackets, separated by commas, as follows: [iloop,jloop,kloop] The total number of runs in the run set is given by the product of the numbers of iterations for all loop variables.
Member function
A function associated with a particular class that defines part of
the interface and behavior of that class. Ordinary (non-static) member
functions define operations that effect one specific object of the class,
and are invoked using a ‘dotted" notation, as shown: myObject.myMemberFunction().
Static member functions define operations not necessarily related to any
specific object of the class, such as operations that involve static data
members of the class, and are invoked using the class name followed
by a double colon, as follows: MyClass::myStaticMemberFunction()
Method
A synonym for member function.
MutableInput
(C++ class)
Similar to an ordinary input, except that it provides full read-write
access to the referent object. A mutableInput cannot be connected to an
ordinary output; instead they can only be connected to a mutableOutput
or an object, both of which support read-write access. See also
Input,
Input
(the C++ class).
Similar to an ordinary output, except it permits full read-write access to its referencors. A mutableOutput may be connected to ordinary inputs, mutableInputs, or both. See also Output, Output (the C++ class).
now()
now() is a member function of class System
which returns the current virtual time. It takes no arguments.
Object
One of the key concepts of object-oriented programming (OOP), an OOP
object is analogous to a real world object, in that objects can be created
and destroyed, and each object has its own state information, which can
evolve over time, in accordance with specified behavioral rules. In C++
each object is an instance of some class, and it is the class that
defines the nature of the state information, in the form of data members,
and behavior, in the form of member functions.
Object (C++
class)
Part of the tempus kernel library, Object
is a template class which defines a simple kind of proxy object,
a wrapper for an object of arbitrary type which can serve as the referent
for any number of system inputs. Any action which would modify the state/value
of the underlying object is automatically trapped, and any systems with
attached inputs are called with respondToInputWarning().
object()
A member function of Output that returns
a non-const reference to the underlying object. The result is equivalent
to that of the dereference operator (*),
or to implicit or explicit type conversion (to the type of the underlying
object), but using the explicit function call can make the code more readable.
Any systems with attached inputs are automatically called with
respondToInputWarning().
In logic that requires repeated access to an output’s underlying object
we recommend calling object() once, to initialize a reference, then using
the reference for all subsequent accesses.
Object-oriented programming
A programming paradigm based on the concepts of objects and
classes,
as opposed to procedures. Many developers find that object-oriented programming,
or OOP, conforms much more closely to the way they naturally think about
problem solving and design.
Object-oriented software composition
Object-oriented software composition, component-based software, is an approach for extending traditional object-oriented programming techniques for very large projects, and/or projects which involve the combined use of many separately designed and developed software components. The essential idea is to adopt an architecture and methodology which allows the programmer to treat software components more or less like “black boxes”, which he can connect together to accomplish the desired purpose without detailed knowledge of their inner workings.
OOP
An acronym for object-oriented programming.
Output
A part of the external interface of a system or system class, used
to define how a system can act upon its environment. An output is essentially
a wrapper for an underlying object, which can be of any C++ type, where
the output can be used as the referent for one or more inputs of that same
type. This relationship is established by connecting the input to
the output, using one of the operators <<=
or =>>. A system may have any number of
outputs, and each has a name (a character string, which must be a legal
C++ variable name) and a type (any C++ type, including user-defined types).
A system is automatically notified each time any of its outputs is about
to be accessed through a connected input, via a call to the virtual method respondToOutputRequest.
Also, whenever a system attempts to modify an output, e.g. in an assignment
statement, all systems with connected inputs are automatically warned,
via calls to the virtual method respondToInputWarning.
Output (C++
class)
Part of the tempus kernel library, Output
is a C++ template class used to represent system outputs.
Parameter
Parameters are variables used to fine-tune the behavior of each instance
of a particular system class, and/or to define its initial conditions;
at the source code level, parameters appear as constructor arguments. A
system class may have any number of parameters, and each has a name (a
character string, which must be a legal C++ variable name) and a type (any
C++ type, including user-defined types). When an instance of a system class
appears as a subsystem within another system class, its parameter values
are specified by setting expressions defined in terms of the parameters
of the containing system class. When a system class serves as the basis
of a run set, its parameter values are specified by setting expressions
defined in terms of the run variables defined for the run set. Typically
the run variables would include one or more loop variables, used
to set up multiple simulation runs, using different parameter values.
pendingEvents
A data member of class System, a list of all events the system currently
has pending, i.e. scheduled, but not yet executed. For a system that schedules
events, this list constitutes an important part of the system’s state,
and in some cases it may be necessary or useful to make use of the pending
events list within the system’s respondTo- methods.
Pointer
A simple object that records the address of some other object, of some
specified type. Pointers can be used to access the pointed-to object by
means of the dereference operator (*) and
the member dereference operator (->).
Proxy object
An object used to represent another object, so that actions performed
on the proxy object are actually forwarded to the object it represents.
A proxy object is similar to a reference, but unlike a reference,
it is a first class object, defined by a class, with its own data members
and member functions. A typical application is to trap attempts to access
the represented object, and then perform some appropriate action. Ideally,
one should be able to substitute a proxy object for the represented object
in any valid expression and get exactly the same result, but unfortunately
in C++ this is not possible, because of subtleties related to the rules
for automatic type conversion and the member access (.)
operator. To get around this, the designers of proxy classes typically
define a member function or operator which returns a reference to the underlying
object, which can then be used in any expression. In tempus, the proxy
classes Input, Output, and SaveVariable provide both,
via the dereference operator (*), implicit
or explicit type conversion, and the member functions value() (const access)
and object() (non-const access, Output and SaveVariable only).
Reference
In C++ a reference is similar to a pointer, except that, unlike pointers,
references are used syntactically just like the represented object, and
are not themselves considered first class objects, in that once a reference
has been defined no further action can be performed on it, since all actions
are forwarded to the referred-to object.
Recallable
(C++ class)
A recallable is a variable whose value may change with the advance
of virtual time, and for which it is possible to recall its value at earlier
virtual times by calling valueAt(),
a member function which takes a single argument, the time for which the
value is desired. Recallables are generally used only when there is reason
to expect that it will be necessary to access values from earlier times,
as is the case for subsystems used to drive others which rely on being
able to access their inputs at earlier times. Recallable
is a template class (Recallable<T>),
where the template argument is the variable type. See also recallRecallable,
SaveVariable.
recallRecallable()
A virtual method of class System, used
only in systems which make use of recallables, either in their internal
logic, or as outputs. recallRecallable
takes two arguments, one to identify which recallable, one to specify the
virtual time for the recalled value. recallRecallable
does not have a return value; instead, the recalled value is stored in
a data member of class Recallable<T>,
called recalledValue. We do it that way
because the recalled values for different recallables have different types.
See also Recallable, SaveVariable.
RectangularRegion is a C++ class, part of the tempus support libraries, used to define a two-dimensional rectangular region on a plane. RectangularRegion is closely related to the class GridGeometry, used to specify the geometry for instances of the template class Grid, which is used extensively in WaveTrain, to describe things like optical wavefronts, reflectance maps and detector responsivities.
respondTo- methods
A set of four virtual methods of the class System, used to define the
behaviors of all system classes. The four methods – respondToChangedInputs(),
respondToInputWarning(),
respondToOutputRequest(),
respondToScheduledEvent()
– define the system’s responses to changes to its inputs, requests for
its outputs, and scheduled events.
respondToChangedInputs()
One of the four respondTo- methods used to define the behavior
of a system class, respondToChangedInputs()
is called whenever one or more of the system’s inputs have changed, after
they have assumed their new values, but before virtual time is allowed
to advance. It has no arguments. Note that "Inputs" is plural, reflecting
the fact that the values of two or more inputs may change at the same virtual
time; to find out which ones have changed, the programmer can use hasChanged(),
a member function of the class Input.
respondToInputWarning(0
One of the four respondTo- methods used to define the behavior
of a system class, respondToInputWarning()
is called whenever any one of the system’s inputs is about to change, before
it has assumed its new value. There is one argument, which identifies the
input. Generally speaking, respondToChangedInputs()
should be used in preference to respondToInputWarning();
this allows the programmer to deal with multiple changed inputs at the
same time, after their new values are available, and avoids possible deadlock
conditions.
respondToOutputRequest()
One of the four respondTo- methods used to define the behavior
of a system class, respondToOutputRequest()
is called whenever any one of the system’s outputs is about to be accessed.
There is one argument, which identifies the output. This gives the programmer
the option of adopting a strategy of lazy evaluation, i.e. computing
the value of the output only when it is requested. One reason one might
choose that strategy is efficiency, especially in the case of outputs whose
values may change much more often than they are accessed, and where each
output evaluation takes a significant amount of CPU time. Another reason
would be if the output models a quantity that may change continuously in
time, such as the instantaneous position of a damped harmonic oscillator.
By waiting for the output request, we can compute the position for the
precisely the right instant in virtual time.
respondToScheduledEvent()
One of the four respondTo- methods used to define the behavior
of a system class, respondToScheduledEvent()
is called whenever an event scheduled by the system reaches the top of
the event queue. There are three?????????????? arguments, ….
.run file
A text file used by the tempus visual editor to store the definition
of a run set, named the same as the system class, but with the extension
".cpp". .run files are user-readable, containing the same information displayed
in the edit run set window, and can be useful as a form of documentation.
Run set
A set of simulation runs, all based on the same system class, and generally
executed as part of the same main program, but differing in the values
used for one or more system parameters. A run set is typically used to
perform a specific parameter study based on the given system model, e.g.
how does such-and-such performance measure change when one turns some particular
knob? For system models that include stochastic effects one of the parameters
varied would often be a random number seed, for the purpose Monte Carlo
averaging. Run sets can be created and modified using the run set edit
window, where the user specifies which parameters are to be varied
and what values they should be set to, what values the other parameters
should be set to, the simulation stop time, what outputs to record, and
so forth. The information pertaining to a run set is stored on disk in
a .run file, kept in the same directory as the system class on which
the run set is based. See also simulation run, run set edit window,
run
variable, loop variable, .run file, and .trf file.
Run set edit window
One of the two main windows in the tempus visual editor, used to create
and modify run sets. To see the window layout, click here.
See also run set, simulation run, run variable and loop
variable.
Run variable
A variable used within a run set for specifying parameter values and/or
setting up for-loops over parameters. One application would be to define
quantities to be used in multiple setting expressions; another would be
to store expensive-to-compute results which can be reused in multiple simulation
runs. There is one special type of run variable, called a loop variable,
used for setting up for-loops over parameters.
SaveVariable
(C++ class)
A type of recallable variable which keeps track of its own past
values, rather than relying upon some System to do so. Each time a saveVariable
is modified it records the new value and the virtual time, so that later
it can recall its value at any past virtual time. SaveVariable
provides a convenient mechanism for keeping track of the time history of
quantities that can undergo only discrete changes; quantities that can
vary continuously should be modeled using the more general recallable/recallRecallable
approach. SaveVariable is a template class
(SaveVariable<T>) where the template
argument is the variable type.
scheduleEvent()
A method of class System used to schedule events, used to trigger discrete
changes in a system’s state related to its own internal time dependence.
ScheduleEvent takes three arguments: the delay (in virtual time) after
which the event should occur, a character string descriptor used to distinguish
between different types of events, and a void* pointer which can be used
to attach information pertaining to the event. ScheduleEvent()
returns an EventId, which can be
used to cancel the event should that become necessary.
seedSequence
A global function provided to tempus users which allows the generation of a
deterministic sequence of random number seeds from a single random number seed.
tempus is often used for Monte Carlo runs where it is necessary to change the
random number seed for each sample. However, it would be inconvenient for the
user to explicitly specify the seed to be used for every single case.
seedSequence provides a mechanism to set the seed in a deterministic way
depending on a single user-specified seed and iteration number. The form of
seedSequence is:
int seedSequence(const int seed, const int index) {return (seed + (2*index));}
seedSequence is usually used in conjunction with a loop variable. Suppose we have loop variable irand. We can run a Monte Carlo study by setting the random number seed for some entity (such as the atmospheric path) to:
[irand]:seedSequence(-123456789,irand)
On the first iteration the seed -123456789 will be used, on the next -123456787, and so on. This sceme works well in seeding random number generators for which it is unlikely that two numbers, even if they are almost equal, are unlikely to be close to each other in a given random sequence. Some random number generators (in particular, the one in the Intel performance library) do not have this feature so we do not use it.
One might ask why we don't use a single random number seed to seed all random number processes throughout the simulation. This has the undesirable feature that it would be difficult to hold one random process constant while allowing another to vary. Also, the actual sequences that were generated would depend on how many numbers were drawn and if we changed the number of numbers slightly we could get significantly different results.
Setting expression
A C++ expression used to specify a value for a parameter, input, or
output, which may be as simple as a numerical constant, e.g. "5.0", or
as complicated as needed. A system class may specify default values for
its own parameters, inputs, and outputs, and may set the values for its
subsystems’ parameters and inputs, which overrides any defaults specified
in the subsystem’s system classes. Also, run sets use setting expressions
to specify the parameter values for the system model used. Setting expressions
are evaluated in the scope where the value is needed, and must therefore
be valid C++ expressions within that scope. This means that the setting
expressions for subsystem parameters and inputs and external outputs can
involve only the parameters of the containing system class, or symbols
defined in the user-provided C++ code for the class. Default setting
expressions for parameters and inputs are likewise evaluated within the
containing class, not the class where they were defined. The only way to
ensure that a default expression will be valid expressions is to use either
no symbols at all, or only symbols defined in the user-provided C++ code.
Alternately, one can use symbols in the default expression, and rely on
the automatic error-checking mechanisms to inform the user about the undefined
symbols, which he may then choose to make parameters of the containing
system class.
Shallow copy
A copy operation performed on a usage instance of a class, that involves
copying only the instance information, not the class itself. For example
whenever the user cuts and pastes a subsystem from a library directory
to any other directory (another work directory or a library directory),
a shallow copy is performed, creating a new usage instance of the
existing class. See also deep copy.
Simulation run
A single execution of a simulation, generally occurring within the
innermost for-loop of a run set main program. A simulation run generally
consists of (1) the construction of a new virtual universe, (2) a call
to the constructor of the system class on which the run set is based, which
each parameter value set as specified in the run set, (3) set up of output
recording as specified in the run set, and (4) a call to advanceTime,
used to advance virtual time to the stop time specified either in the run
set, or on the command line. Simulation runs can also be used in other
ways, such as in conjunction with a nonlinear minimization algorithm for
design optimization or fitting a model to data, or as part of an interactive
training environment.
Soft real-time
A soft real-time application is one in which time constraints apply,
but they are not terribly strict, somewhat imprecise, and failure to meet
those constraints would not result in unacceptable consequences. A typical
example would be an interactive training environment for operators of some
complex system.
Subsystem
A system which is used as part of a larger system or system class.
Every subsystem is an instance of some system class, with its parameter
values defined by setting expressions defined in terms of the parameters
of the containing system class, and its inputs and outputs connected to
other subsystems and/or external inputs and outputs as specified by the
containing system class.
System
In tempus a system is a C++ object, an instance of a system class,
a C++ class derived from the base class System.
The class System is designed to be a software
representation of the abstract notion of a system, as the term is used
in science and engineering, where a system can be just about anything,
provided that it has well-defined inside – the system itself - and outside
– its environment. Following the methods of systems engineering, any system
can be described in terms of its inputs, outputs, internal state, and behavior,
where its behavior consists of its response to changes in its inputs and
its internal time dependence. The class System
is designed for use as a base class for a wide variety of more specialized
classes, each representing a specific type of system, with its own particular
inputs, outputs, and behavior. These classes, called system classes,
can be created and modified using the tempus visual editor. Some,
called composite system classes, are made up of simpler systems,
called subsystems, connected together. Others, called atomic system
classes, contain no other systems. The behaviors of composite systems
are defined by the behaviors of their subsystems; the behaviors of atomic
systems are defined by source code. All system classes, both atomic and
composite, are generally parameterized, meaning that their behaviors
and/or initial conditions are defined in terms of a number of parameters,
passed in as constructor arguments. A tempus system is simply one instance
of some system class, possibly one of many. Any changes to a system class
will affect all its instances, unless the user elects to rename the modified
class, in which case he can choose which instances will be affected by
the changes, and which will not.
System (C++
class)
Part of the tempus kernel library, the class System,
which serves as the base class for all tempus system classes,, is designed
to be a software representation of the abstract notion of a system, as
the term is used in science and engineering. System
provides a customizable interface mechanism based on the use of inputs
and outputs, instances of the template classes Input<T>
and Output<T>, where inputs are used
to define the means by which a system’s environment can act upon the system,
and outputs are used to define the means by which a system can act upon
its environment. System has four virtual methods, collectively called the
respondTo-
methods, which are used to define the behavior of each system class:respondToChangedInputs(),
respondToInputWarning(),
respondToOutputRequest(),
respondToScheduledEvent().
The default behavior for each is to do nothing, and for composite system
classes that generally suffices, while atomic system classes will generally
override one or more of the four. For more details consult the tempus
Programmer’s Manual.
System class
A class derived from the base class System,
and representing a specific type of system, with its own particular inputs,
outputs, and behavior. System classes may be composite,
i.e. made up of subsystems
(instances of other system classes), or atomic.
The behaviors of composite systems are defined by the behaviors of their
subsystems. The behaviors of atomic systems are defined by source code.
System classes can be created and modified using the tempus
visual editor, which automatically generates a four files for each,
a .tsd file, a .h
file, a .view file, and a .html
file. Talk about different directories. The two most important
of these are the .tsd file,
which describes the class to the visual editor, and the .h file, which
contains its C++ class definition. When the .h file is generated, the respondTo-
methods used to define the class’s behavior are commented out; to implement
a desired behavior the user would edit the .h file by hand, uncomment one
or more of the respondTo- methods, then put the appropriate logic in the
function bodies. It may also be necessary or useful to add data members,
modify the constructor logic, and so forth; any changes that do not affect
the external interface are allowed. It is important to remember that a
system class may be used in more than one place, that is instances of the
class may appear as subsystems in more than one composite system, or more
than once within the same composite system, and that any changes to the
system class will affect all instances. For more details, consult the tempus
Programmer’s Manual.
System class edit window
One of the two main window in the tempus visual editor, the system
class edit window is used to edit or view system classes, represented graphically,
as block diagrams. The user may open any number of edit windows, each of
which shows one system class at a time. The user can cut and paste subsystems,
inputs, and outputs between windows, and can rearrange subsystems, make
and break connections, and so forth, all by direct manipulation. He can
also navigate through a complete hierarchical system model, double-clicking
on a subsystem to descend into the corresponding system class, double-clicking
on whitespace to ascend to the level above. If two or more edit windows
happen to be looking at the same system class, all actions performed in
one will also be reflected in the other. There is an undo capability, and
automated error-trapping. A status button at the bottom right turns red
whenever any errors are detected; clicking on it brings up a detailed report.
Template
Templates are the C++ version of generic types, used to define classes
and functions that can be used with typed objects, where the type matters,
but where at least part of the desired behavior can be defined independent
of the specific type. Typical examples include multi-object container classes,
such as lists, and proxy objects. A template class or function is defined
in terms of one or more template arguments, used to represent the
unspecified type or types.
Template argument
An argument used in the definition of a template class or function
to represent the unspecified type or types, and/or to convey other information
needed at compile time, such as array dimensions. In the definition of
a template class or function, the template arguments appear at the top,
immediately following the keyword template,
and enclosed in angle brackets:
template <class T> Input {…};
In usage, the template arguments appear immediately after the class or function name, again enclosed in angle brackets.
Input<float> u;
Within the definition of the class or function, a template argument representing a class is used in place of the class name in declarations, type casts and so forth. To refer to an instance of a template class where a template argument is unspecified we typically write "T" in place of the template argument, as in "Input<T>".
Template class
A class defined in terms of one or more template arguments.
Template function
A function defined in terms of one or more template arguments.
tempus Programmer’s Guide
An informal how-to guide for all the basic activities involved in the
using tempus at the source code level. The guide is designed for ease of
use, and is not intended to be completely comprehensive.
tempus Programmer’s Manual
A comprehensive user’s manual guide for all the basic activities involved
in the using tempus at the source code level. Our intention is for the
manual to eventually cover every detail of every feature, but as tempus
is still in active development it will be some time before that is true.
tempus recorder file
See .trf file.
tempus User’s Guide
An informal how-to guide for all the basic activities involved in the
use of tempus, from installing the software to building system models and
performing parameter studies in the tempus visual editor, then looking
at the simulation outputs in Matlab. It does not cover use of tempus at
the source code level. The guide is designed for ease of use, and is not
intended to be completely comprehensive.
tempus User’s Manual
A comprehensive user’s manual for all the basic activities involved
in the use of tempus, from installing the software to building system models
and performing parameter studies in the tempus visual editor, then looking
at the simulation outputs in Matlab. It does not cover use of tempus at
the source code level. Our intention is for the manual to eventually cover
every detail of every feature, but as tempus is still in active development
it will be some time before that is true.
tempus visual editor
The tempus graphical user interface (GUI), called the "visual editor"
because it is a visual programming environment, used to create and modify
tempus system classes and run sets.
.trf file
A specially formatted random access file used to store tempus simulation
output, generated when a run set main program is executed, named the same
as the system class, but with the extension ".cpp". The format preserves
the structure character of the output data, and support searching and browsing
without having to load the contents of the file. "trf" stands for "tempus
recorder file". Interfaces have been implemented for accessing and manipulating
trf files from C++ , DOS, Unix, and Matlab; these are described in the
.trf File User’s Manual.
.tsd file
A text file used by the tempus visual editor to store the definition
of a system class, named the same as the system class, but with the extension
".cpp". .tsd files are user-readable, containing the same information displayed
in the edit system class window, and can be useful as a form of
documentation.
Universe (C++
class)
Part of the tempus kernel library, the Universe
is a C++ class designed to represent a virtual universe, within
which we can construct a system model, then cause virtual time to advance,
independent of any other virtual universes and system models within the
same process. Often only a single virtual universe is in use at any one
time – that’s the case in a typical run set – but some applications require
multiple virtual universes, such as those that involve models within models.
Usage instance (of a class)
A variable representing an object of a given class, which does not
necessarily refer to a single specific object in memory (i.e. an "instance"
in the ordinary sense), because which object in memory it refers to depends
upon the usage context. For example, if class A
has a non-static data member b of class B,
there would be one b for each instance
of A – possibly many, or zero - so b
would be considered a usage instance of B,
but not an instance in the ordinary sense.
User-defined types
Object-oriented programming languages such as C++ allow programmers
to define their own data types, which can then be used just as the intrinsic
types defined by the language are. The term user-defined type is
almost synonymous with the term class, but in C++ there is also
a simpler form called a struct, which can be thought of as a class without
any member functions and with all data members publicly accessible.
value()
A member function defined for both inputs and outputs, which returns
a const reference to the underlying/referent object. In the case of an
input, a call to value() triggers a call to respondToOutputRequest()
for the system with the connected output. In the case of an output, calling value()is
recommended in logic that requires only read-access to the underlying object,
because unlike read-write access mechanisms (e.g. calling object()
or using implicit type conversion) it does not trigger calls to
respondToInputWarning()
for systems with connected inputs.
valueAt()
A member function of recallables and saveVariables, used
to access the value of the underlying object at some past moment in virtual
time.
Vector<T> (C++ template class)
Vector is a C++ template class, part of the tempus support libraries, used to describe an ordered set of similar objects. Vector is used extensively in WaveTrain, both internally and at the user interface level, where parameters of type Grid can be used to specify things like phase screen locations and strengths..
Virtual member function
A member function of a class designed for use as a base class, used
to define a common interface to all derived classes, while allowing the
behaviors of derived classes to differ. The base class may define a default
behavior (implementation of the function), which the designer of a derived
class may choose to override. If the base class does not provide a default
the function is called a "pure virtual function", and each derived class
must provide its own implementation.
Virtual method
See virtual member function.
Virtual time
Virtual time plays the same role in a computer simulation that real
time does in the real world; when a real world system has been correctly
modeled, the behavior of the model unfolds as virtual time advances in
a manner closely corresponding to the behavior of the actual system in
real time. Unlike real time, virtual time is subject to our complete control,
so we can ensure that all simulation events occur at exactly the correct
times and in the correct sequence, deterministic and repeatable. Depending
on the application, the model, and the computer system, virtual time may
advance much more slowly than real time, or much more quickly. In some
applications, such as interactive training environments, it is desirable
for virtual time to advance at the same pace as real time; given sufficient
computing power this is generally easy to do in an approximate sense, but
impossible to do with exactitude for an arbitrary computer model. For this
reason standard virtual time simulation techniques can be applied directly
to soft real-time applications, but not necessarily for hard
real-time applications. Simulation techniques can be useful in hard
real-time applications, but it is then necessary to either restrict the
kinds of software components used (e.g fixed time algorithms), or else
adopt an architecture that partly decouples the simulation from the control
loop proper.
Void
A C++ keyword used in place of the return type to indicate that a function
does not have a return value, and also used in place of the referent type
when declaring pointers to objects of unspecified type.
Work directory
Any directory used to store tempus system classes and run sets, and
not specifically designated to be a library directory. The distinction
between the two is that in a work directory it is assumed that the user
is trying to use tempus as a tool, to solve a problem, whereas a library
directory is used to extend the capabilities of tempus, by providing a
set of reusable and mutually compatible components. In a work directory
the user typically makes frequent changes to his system classes, as he
develops and refines his overall system model or models, so it would not
make sense to use those same system classes as subsystems in unrelated
models. In contrast, system classes in a library directory are intended
for reuse and designed for it, and may be used as subsystems in any number
of work directories. This difference is reflected in tempus’ copy mechanism:
when one copies a subsystem from a system class in a library directory
into a system class in another directory, a shallow copy is performed;
which introduces a dependence between the destination directory and the
library directory. When one copies a subsystem from a system class in a
work directory into a system class in another directory, a deep copy
is performed, and no such dependence is introduced.