ExternalVendorCode/trick
1
0
Fork 0
mirror of https://github.com/nasa/trick.git synced 2024-12-18 20:57:55 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Revise Documentation, Correct a single constant (#1326) (#1489)

Browse Source 
* Fix formatting, grammar, and syntax

Additionally, a sentence that referenced something that isn't used anywhere was removed.

* Promote headers, Format stuff

Many headers were far too deep. In some cases, the highest header was h4. To correct this, the offending headers were promoted once or twice as appropriate. Minor formatting changes were made, too.

* Fixed an incorrect conversion constant.

* Update library dependency explanation

The old explanation was confusing and seemingly self contradicting in places. This new explanation aims to fix that.

Co-authored-by: Matthew Elmer <m.elmer@mailbox.org>
This commit is contained in:
Jacqueline Deans 2023-04-21 17:32:31 -05:00 committed by GitHub
parent 78bc708f0f
commit 6c685d8400
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
30 changed files with 587 additions and 563 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/documentation/building_a_simulation/Making-the-Simulation.md
View File

@ -2,11 +2,11 @@
|------------------------------------------------------------------|
### Simulation Compilation Environment Variables
## Simulation Compilation Environment Variables
The -Ipaths in TRICK_CFLAGS and TRICK_CXXFLAGS tell Trick where to find model source files. The flags also can contain compiler settings, for instance the -g flag is used for compiling in debug mode. See section Trick_Environment for more detail and information on variables for linking in external libraries, setting the compiler etc.
### Making the Simulation for the First Time.
## Making the Simulation for the First Time.
Makefiles contain all of the rules for building the simulation. When a simulation is ready to be built for the very first time, the configuration processor script (CP) is executed in the simulation directory.
@ -24,7 +24,7 @@ After the initial CP is run, when there are changes made to model source code or
UNIX prompt> make
```
### How Trick Finds Simulation Source Code
## How Trick Finds Simulation Source Code
Trick compiles all user model source code referenced in the S_define either through file inclusion or user supplied "library dependencies". Trick begins at the S_define and recursively follows code dependencies to create the entire source tree.
@ -34,7 +34,7 @@ Model source files are found through LIBRARY DEPENDENCIES specified in the Trick
Once the entire source tree is created, rules to compile all of these files are written to the makefile.
### Changing Simulation Compilation through Makefile Overrides
## Changing Simulation Compilation through Makefile Overrides
Sometimes a programmer may want Trick to pick up specific compiler flags or some special makefile rule for building a model or building the simulation. Trick allows the programmer to override the default Makefile rules with a facility we are calling "makefile overrides".
@ -58,7 +58,7 @@ Other possibilities are: ```c_objects``` , ```f_objects``` , ```l_objects``` , `
For overrides in sim directories, there is a sim specific overrides file called `S_overrides.mk`. If this file is present in the sim directory, it is included after the directory-specific overrides. The rules in this file are the last word in how things are going to compile.
#### Example Of How To Add a Pre-compiled Library to the Simulation
### Example Of How To Add a Pre-compiled Library to the Simulation
Go to simulation dir.
@ -71,7 +71,7 @@ Edit a file called "S_overrides.mk". Append to the TRICK_USER_LINK_LIBS variable
```
TRICK_USER_LINK_LIBS = -L/path/to/library -lmy_lib
```
#### Example Of How To Exclude a Directory from ICG during CP
### Example Of How To Exclude a Directory from ICG during CP
Go to simulation dir.
@ -83,7 +83,7 @@ Edit a file called "S_overrides.mk". Append to the TRICK_ICG_EXCLUDE variable.
TRICK_ICG_EXCLUDE += /path/to/exclude:/another/path/to/exclude
#### Example Of How To Exclude a Directory from most CP processing
### Example Of How To Exclude a Directory from most CP processing
Edit a file called "S_overrides.mk". Append to the TRICK_EXCLUDE variable.
@ -91,7 +91,7 @@ Edit a file called "S_overrides.mk". Append to the TRICK_EXCLUDE variable.
TRICK_EXCLUDE += /path/to/exclude:/another/path/to/exclude
```
### Cleaning Up
## Cleaning Up
There are several levels of clean.

296
docs/documentation/building_a_simulation/Model-Source-Code.md
View File

@ -5,13 +5,13 @@ This section details the syntax for creating headers and source code that Trick
It also details the operation of the Trick Interface Code Generator (ICG) that processes headers, and the Module Interface Specification Processor (MIS) that processes source code.
#### Programming Language Support
## Programming Language Support
The majority of model source for simulations is written in C and C++ . Trick supports auto generating IO code to peek and poke C and C++ structures, classes, and enumerations. Trick also generates the necessary makefile rules to compile and link C and C++ model code into the simulation.
The majority of model source for simulations is written in C and C++. Trick supports auto generating IO code to peek and poke C and C++ structures, classes, and enumerations. Trick also generates the necessary makefile rules to compile and link C and C++ model code into the simulation.
Models written in other languages may be included in the simulation. It is possible to include Fortran 77, Fortran 90, Ada, and/or Java code in the simulation. These models cannot be called directly from the Trick scheduler, but may be called through C language wrapper functions provided by the user that executes the other language calls.
#### C Header Files
## Header Files
Trick processes header files in order to auto generate IO source code for the simulation. IO source code is the heart of how Trick does its input processing. The following describes the syntax for a header file.
@ -44,78 +44,98 @@ Introduced in Trick 16
*/
typedef enum {
enum_label [=enum_value],
enum_label [= enum_value],
last_enum_label [= enum_value]
} enum_name ;
} enum_name;
[typedef] struct [struct_tag] {
char|short|int|long|long long|
unsigned char|unsigned short|unsigned int|unsigned long|unsigned long long|
float|double [*]* param_name [[dim]]* ;
float|double [*]* param_name [[dim]]*;
/* [**|*i|*o|*io] (trick_io|io)([**|*i|*o|*io]) (trick_chkpnt_io|cio)([**|*i|*o|*io])
trick_units([measurement_units]) description */
any_other_type [*]* param_name [[dim]]* ;
any_other_type [*]* param_name [[dim]]*;
/* [**|*i|*o|*io] trick_io([**|*i|*o|*io]) trick_chkpnt_io([**|*i|*o|*io])
trick_units(measurement_units) description */
} struct_name ;
} struct_name;
class <class_name> {
[
friend InputProcessor ;
friend init_attr<class_name>() ;
friend InputProcessor;
friend init_attr<class_name>();
]
(public|protected|private):
char|short|int|long|long long|
unsigned char|unsigned short|unsigned int|unsigned long|unsigned long long|
float|double [*]* param_name [[dim]]* ;
float|double [*]* param_name [[dim]]*;
/* [**|*i|*o|*io] trick_io([**|*i|*o|*io]) trick_chkpnt_io([**|*i|*o|*io])
trick_units([measurement_units]) description */
any_other_type [*]* param_name [[dim]]* ;
any_other_type [*]* param_name [[dim]]*;
/* [**|*i|*o|*io] trick_io([**|*i|*o|*io]) trick_chkpnt_io([**|*i|*o|*io])
trick_units([measurement_units])measurement_units description */
} ;
};
```
##### Comment Header
### Comment Header
The Trick comment header, which is optional, begins with `/* PURPOSE:`. Within the Trick comment header, the `PROGRAMMERS`, `REFERENCES`, `ASSUMPTIONS AND LIMITATIONS` and `ICG` are optional entries. Since parentheses, (), are used to delineate fields within the comment header, parentheses are not allowed as characters within the comment fields. Any other formatted comments may appear before and/or after the Trick comment header.
The Trick comment header, which is optional, begins with `/* PURPOSE:`. Within
the Trick comment header, the `PROGRAMMERS`, `REFERENCES`, `ASSUMPTIONS AND
LIMITATIONS` and `ICG` are optional entries. Since parentheses, (), are used to
delineate fields within the comment header, parentheses are not allowed as
characters within the comment header's fields. Any other formatted comments may appear
before and/or after the Trick comment header.
###### C++ Language Override, `LANGUAGE: (C++)`
#### C++ Language Override, `LANGUAGE: (C++)`
If a header file has a C++ extension (e.g *.hh ) Trick’s parsers will realize that it is a C++ file and handle it appropriately. If the extension is *.h, Trick will assume it is a C file (not C++). If you want to make a C++ header file name with the *.h extension, you must explicitly tell Trick it is a C++ file with the `LANGUAGE: (C++)` declaration in the Trick comment header.
###### Telling ICG to ignore this header file, `ICG: (No)`
#### Telling ICG to ignore this header file, `ICG: (No)`
If `ICG: (No)` is in the comment header, Trick will not to process the header. This is useful if the header contains anything that Trick cannot process, or if the programmer wishes Trick to skip this header. For skipping entire sets of headers, see next item.
If `ICG: (Nocomment)` is in the comment header, Trick will not process any comments within the file. This option is useful if the user wants ICG to process the file but the file does not have comments that are Trick compliant.
###### Library Dependencies
#### Library Dependencies
Library dependencies are the model source code files required by the simulation.
They can be listed 1) within model header files, 2) within model source files,
or 3) within the `S_define`. Each library dependency only needs to be listed once,
and the preferred approach is to list each library dependency within its
respective model header file.
<b>Listing Library Dependencies Within Model Header Files:</b> (preferred approach)<br>
Listing library dependencies within the model header files is as simple as
providing the path of each source file for which the header file makes
declarations. The path should be relative to the base path that was set in
S_overrides.mk (See the link below).
[Compiling and Building the Simulation](https://nasa.github.io/trick/tutorial/ATutAnalyticSim#compiling-and-building-the-simulation)
By doing it this way, you don't have to recall every single source file in your
simulation when you're listing the library dependencies. You only need to list
the source files relevant to the current header file, and Trick does the heavy
lifting by bringing them all together when it processes the header files.
A model header consistent with this approach would contain a
`LIBRARY DEPENDENCY` field that looked like the following:<br>
```
LIBRARY DEPENDENCY:
((relative_path/model_1.c)
(relative_path/model_2.cpp))
((relative_path/source_file.c)
(relative_path/other_source_file.cpp))
```
Library dependencies list out model source code files required by the simulation. There are several locations to add library dependencies, one of which is in model source headers. The format of dependencies in the S_define file is a relative path to the model source file. The path is relative to -I include paths found in TRICK_CFLAGS and TRICK_CXXFLAGS.
For example if the full path to our model is /this/is/a/full/path/to/model.c and in our TRICK_CFLAGS we have -I/this/is/a/full as one of the included search paths, the library dependency must complete the full path to the file, in this case path/to/model.c. Library dependencies in the S_define file differ from ones found in model source code as they must be the full path to the source file not the object file.
This is the preferred library dependency syntax. There are other forms of library dependencies that are still valid and listed below.
The LIBRARY DEPENDENCY field may contain the object code files which the current file depends on. A self-reference is not necessary.
For example, for a file this.c which calls
* a function within the file that.c
* a function in a user object library my_library/libdog.a
* a function foo.c
The `LIBRARY DEPENDENCY` field might look like this:
<b>Listing Library Dependencies Within Model Source Files:</b><br>
If you find it more intuitive to instead list library dependencies for each
model source file, it is possible to do so. In each model source file, list the
object files and libraries that the current model source file depends on.
Self-references are allowed, but not necessary. For a file `this.c` which calls
* a function within the file `that.c`
* a function in a user object `library my_library/libdog.a`
* a function in a shared library `libcow.so`
* a function `foo.c`
The `LIBRARY DEPENDENCY` field might look like this:<br>
```
LIBRARY DEPENDENCY:
((this.o)
@ -129,11 +149,11 @@ For references to objects outside the current source directory, the directory pa
There are two ways to specify dependencies to actual libraries, i.e. lib\*.a files:
`* <relative path>="">/<libraryname>.a`
`* <relative path>="">/<library name>.a`
If you use a relative path to the library, Trick will search the TRICK_CFLAGS for a directory that contains source code for the library. Once Trick locates the source code, it will automatically build the library and link it in the simulation.
`* <libraryname>.a`
`* <library name>.a`
If you do NOT specify a relative path, Trick will NOT build the library for you. It will simply search your -L paths in your `TRICK_USER_LINK_LIBS` for the library. If found, it will link the library into the simulation.
@ -154,21 +174,25 @@ LIBRARY DEPENDENCY:
(${FOO_ENV_VAR}/foo.o))
```
Best practice is to add library dependencies for source code files for prototypes listed in the header.
<b>Listing Library Dependencies Within the `S_define`:</b><br>
Listing library dependencies within the `S_define` is just like listing them
within the model header files, but all model source files are listed in one spot
instead of per header file. If you choose to do it this way, don't forget to
update the list each time you add or remove a model source file.
###### `ICG_IGNORE_TYPES`
#### `ICG_IGNORE_TYPES`
The `ICG IGNORE TYPES` field lists the structs or classes to be ignored. Any parameters of this type or inherited from are ignored. The `ICG IGNORE TYPES` field is only valid for the current file. It does not extend to included header files.
###### `PYTHON_MODULE`
#### `PYTHON_MODULE`
Specifying a `python_module` name will place any class/struct and function definitions in this header file in a python module of the same name. All classes and functions are flattened into the python `trick` namespace by default. This capability allows users to avoid possible name collisions between names when they are flattened. An empty `python_module` statement will be ignored.
##### Compiler Directives
### Compiler Directives
Trick handles all compiler directives (`#if`, `#ifdef`, `#endif`, `#define`, `#include`, etc.) ICG also uses the -D and -U command line arguments for defines and undefines, respectively.
##### trick_parse
### trick_parse
The trick_parse directive is a Doxygen style field serving the same functionality as the `PURPOSE:` keyword and `ICG: (No)`. The trick_parse directive like all Doxygen style directives are prefixed with either a `\` or an `@` character.
@ -178,11 +202,11 @@ The trick_parse directive is a Doxygen style field serving the same functionalit
`@trick_parse(dependencies_only)`: Treat this comment as the Trick header comment. Search for library dependencies in this comment. Do not process the file any further.
##### `trick_exclude_typename`
### `trick_exclude_typename`
`@trick_exclude_typename(type)` is equivalent to `ICG_IGNORE_TYPES` in a Doxygen style field. The `trick_exclude` field lists the structs or classes to be ignored. Multiple `trick_exclude_typename` fields may be used to ignore multiple types.
##### Enumerated Type Definitions
### Enumerated Type Definitions
Trick provides complete support for enumerated types. Simple mathematical expressions using enumerated types are supported as well.
@ -192,8 +216,8 @@ a.h
```C
typedef enum {
FIRST_ENUM = 45
} A_ENUM ;
FIRST_ENUM = 45
} A_ENUM;
```
b.h
@ -210,7 +234,7 @@ typedef enum {
THIRD_ENUM = FIRST_ENUM * 3,
FOURTH_ENUM = SECOND_ENUM * 4,
FIFTH_ENUM = ME_TOO * 6
} B_ENUM ;
} B_ENUM;
```
c.h
@ -225,14 +249,14 @@ typedef struct {
int ia1[FIRST_ENUM]; /* No comment necessary */
int ia2[SECOND_ENUM]; /* No comment necessary */
int ia3[FIFTH_ENUM]; /* No comment necessary */
} DATA ;
} DATA;
```
##### Data Structure Definitions and Parameter Declarations
### Data Structure Definitions and Parameter Declarations
The data structure type definition statements, `typedef struct { ... } name;`, and `typedef union { ... } name;` `struct Foo { } name;` follows standard C syntax, and are supported by Trick. However, Trick requires a C comment immediately following every parameter declaration.
##### Parameter Data Types
### Parameter Data Types
Trick allows any data type declaration within the data structure `typedef` statement. However, only the following data types will be processed by Trick:
@ -257,13 +281,13 @@ Trick allows any data type declaration within the data structure `typedef` state
All other types are ignored. Types may be defined and used within the same header if the types are defined before they are used (this is a C syntax rule, too).
##### Pointers
### Pointers
Any combination of pointers and array dimensions up to 8 dimensions may be used for parameter declarations; for example, `double ** four_dimensional_array[2][2];`, will be processed. Void pointers and function pointers are not processed. Parameters declared with pointers (like `four_dimensional_array` example), are treated differently; these are called unconstrained arrays. Trick will generate dynamic memory allocation source code for the developer which allows the developer to size the array dimensions (represented by the pointers) via special syntax in the runstream input file. The developer may 1) use the input file to input data to the arrays, 2) output the data via standard Trick logging functions, or 3) share the data through the variable server.
The user does have the option to perform their own memory management for parameters declared as pointers. In this case, instead of specifying the allocation in the input file, the user may allocate the data in a job. In order for Trick to process the data as if it was its own managed memory (and provide capabilities like logging, checkpointing, etc.), the memory address, and number and size of the allocation must be passed to the Trick `TMM_declare_extern_var` function. The user is also responsible for freeing the memory when done.
##### Intrinsic typedef and struct Support
### Intrinsic typedef and struct Support
Types declared using `typedef struct`, `typedef union`, and `typedef enum` are recognized by Trick. Intrinsic typedefs are supported as well and may be nested in structures. The example that follows details a header that Trick will handle:
@ -286,50 +310,50 @@ typedef double my_double;
typedef my_short my_short2;
struct Animal_Sound {
int moo ; /* -- Cow */
int baa ; /* -- Lamb */
int sss ; /* -- Snake */
int moo; /* -- Cow */
int baa; /* -- Lamb */
int sss; /* -- Snake */
};
typedef struct {
my_uchar uc ; /* -- unsigned char */
my_char c ; /* -- char */
my_char ca[80] ; /* -- char */
my_wchar wc; /* -- wchar_t */
my wchar wca[100]; /* -- wchar_t */
my_shortint si ; /* -- short int */
my_short *s ; /* -- short stuff */
my_ushortint usi ; /* -- short stuff */
my_ushort us ; /* -- short stuff */
my_int i ; /* -- count */
my_int ia[5] ; /* -- count */
my_uint ui ; /* -- count */
my_longint li ; /* -- count */
my_long l ; /* -- count */
my_ulongint uli ; /* -- count */
my_ulong ul ; /* -- count */
my_float f ; /* -- count */
my_double d ; /* -- count */
my_short2 s20; /* -- short 20 */
my_short2 s21; /* -- short 21 */
struct Animal_Sound as /* -- Wild Kingdom */
} DATA ;
my_uchar uc; /* -- unsigned char */
my_char c; /* -- char */
my_char ca[80]; /* -- char */
my_wchar wc; /* -- wchar_t */
my wchar wca[100]; /* -- wchar_t */
my_shortint si; /* -- short int */
my_short *s; /* -- short stuff */
my_ushortint usi; /* -- short stuff */
my_ushort us; /* -- short stuff */
my_int i; /* -- count */
my_int ia[5]; /* -- count */
my_uint ui; /* -- count */
my_longint li; /* -- count */
my_long l; /* -- count */
my_ulongint uli; /* -- count */
my_ulong ul; /* -- count */
my_float f; /* -- count */
my_double d; /* -- count */
my_short2 s20; /* -- short 20 */
my_short2 s21; /* -- short 21 */
struct Animal_Sound as; /* -- Wild Kingdom */
} DATA;
typedef DATA MY_DATA;
typedef MY_DATA MY_DATA_2;
typedef struct {
DATA id; /* -- testing typedef of struct */
MY_DATA mid; /* -- testing typedef of struct */
MY_DATA_2 mid2; /* -- testing typedef of struct */
} DATA_2 ;
DATA id; /* -- testing typedef of struct */
MY_DATA mid; /* -- testing typedef of struct */
MY_DATA_2 mid2; /* -- testing typedef of struct */
} DATA_2;
```
##### Parameter Comments
### Parameter Comments
Each parameter declaration within a data structure definition may be accompanied by a trailing comment. There are six possible fields in the parameter comment, but only two are required. All six fields of the parameter comment are stored for later reuse at simulation runtime.
###### The Input/Output Specification
#### The Input/Output Specification
The first three fields in the parameter comment are optional and specify the input/output processing for the parameter. I/O permissions may be set globally or individual capabilities may set their permissions separately. I/O permissions for checkpointing is available to set separately.
@ -347,33 +371,33 @@ Checkpoint I/O may be set separately by adding `trick_chkpnt_io([**|*i|*o|*io])`
* `*o` indicates only checkpoint output is allowed for the parameter. Parameter is written to the checkpoint, but not reloaded.
* `*io` specifies that both input and output are allowed for the checkpointing.
###### The Measurement Units Specification
The second field, `trick_units([measurement_units])`, is a required field and specifies the internal source code units for the parameter. These units are important because they give the input processor the knowledge of what units the user's input data needs to be converted to. Trick uses a third-party package, UDUNITS, for units support. It's syntax is specified [here](https://www.unidata.ucar.edu/software/udunits/udunits-current/doc/udunits/udunits2lib.html#Syntax).
#### The Measurement Units Specification
The second field, `trick_units([measurement_units])`, is a required field and specifies the internal source code units for the parameter. These units are important because they give the input processor the knowledge of what units the user's input data needs to be converted to. Trick uses a third-party package, UDUNITS, for units support. It's syntax is specified [here](https://www.unidata.ucar.edu/software/udunits/udunits-2.2.28/udunits2lib.html#Syntax).
###### User Defined Attributes Fields
#### User Defined Attributes Fields
Following the measurement units specification, in the parameter comment, are two optional, user-defined attribute fields. Using these fields, a user can associate (up to 2) character strings with a parameter. These strings are stored in the ATTRIBUTES structures (in the io_src directory) generated by ICG. The first of these optional fields is delimited by brackets (‘[‘ and ‘]’) and is stored in the element ATTRIBUTES->alias. The second is delimited by braces (‘{‘ and ‘}’) and is stored in the element ATTRIBUTES->user_defined. The definition of the ATTRIBUTES structure is found in $TRICK_HOME/trick_source/sim_services/include/attributes.h.
###### Description Fields
#### Description Fields
The description field is required and must be the last field of the comment. The description field is basically everything after the first three fields. The description field may span multiple lines.
##### C++ Header Files
### C++ Header Files
C++ headers may include constructs and concepts not found in C header files. In addition to all C syntax, Trick parses and understands many C++ features.
##### Public, Protected, and Private Access
### Public, Protected, and Private Access
Trick generates several files to support its various features. The data recorder and checkpointer rely on code produced by the Interface Code Generator (ICG), which bookkeeps the memory layout of variables within the simulation. `public` members are always available to these features. `protected` and `private` data is also available if there is no use of `TRICK_ICG` in the header file. If use is found, Trick will issue a warning during simulation compilation, and `private` and `protected` data will only be accessible to Trick if the following `friend`s are added to the offending classes:
```C++
friend class InputProcessor ;
friend void init_attr<class_name>() ;
friend class InputProcessor;
friend void init_attr<class_name>();
```
The input processor and variable server rely on code produced by a third-party tool, the [Simplified Wrapper and Interface Generator (SWIG)](http://www.swig.org/). SWIG provides the functions that allow access to simulation variables from Python contexts. These features can only access `public` members. It is not possible to expose `protected` and `private` data to them.
##### Inheritance
### Inheritance
Trick may use model code with any type of inheritance. Some limitations are present to Trick's ability to input process, checkpoint, etc. inherited variables.
@ -382,47 +406,47 @@ Trick may use model code with any type of inheritance. Some limitations are pres
* Multiple inheritance is processed but not well tested.
* Template inheritance is not currently supported.
##### Namespaces
### Namespaces
Currently one level of namespace is supported. Additional levels of namespaces are ignored. Similarly classes and enumerations embedded in other classes are ignored.
```C++
namespace my_ns {
// BB is processed
class BB {
public:
std::string str ;
// Class CC is ignored.
class CC {
...
}
} ;
// Everything enclosed in inner_ns is ignored.
namespace inner_ns {
...
} ;
} ;
// BB is processed
class BB {
public:
std::string str;
// Class CC is ignored.
class CC {
...
}
};
// Everything enclosed in inner_ns is ignored.
namespace inner_ns {
...
};
};
```
##### Function Overloading
### Function Overloading
Trick parses function declarations for input file use. The python input processor understands class method overloading. Overloaded methods with different arguments may be called in the input files. Default arguments are to methods are understood and honored in the input file. Operator overloading is skipped by Trick processors. Operator overloading is not implemented in the input file.
##### Templates and the Standard Template Libraries (STL)
### Templates and the Standard Template Libraries (STL)
Trick attempts to process user defined templates. Simple templates are handled. We do not have a good definition of simple. Typedefs of templates is supported and encouraged. All protected and private data is ignored within templates. This is because it is not possible to specify the correct io_src friend function. Templates within templates are not processed. Finally abstract templates are not supported by Trick. These templates should be excluded from Trick processing. See below to see how to exclude code from processing.
STLs may be used in models. However, STL variables are not data recordable, they are not visible in the variable server, nor are they directly accessible in the input file. Some STLs are automatically checkpointed: array, vector, list, deque, set, multiset map, multimap, stack, queue, priority_queue, pair.
STLs may be used in models. However, STL variables are not data recordable, they are not visible in the variable server, nor are they directly accessible in the input file. Some STLs are automatically checkpointed: `array`, `vector`, `list`, `deque`, `set`, `multiset`, `map`, `multimap`, `stack`, `queue`, `priority_queue`, `pair`.
##### Noncopyable Objects
### Noncopyable Objects
Sometimes classes contain members that are not copyable or the math modeler wants to prevent the class from being copied. Declaring an unimplemented private copy constructor and assignment, "=", operator prevents the class from being copied.
```C++
class CantCopyMe {
private:
CantCopyMe( const CantCopyMe & ) ;
CantCopyMe & operator = ( const CantCopyMe ) ;
private:
CantCopyMe(const CantCopyMe&);
CantCopyMe& operator= (const CantCopyMe);
}
```
@ -430,35 +454,35 @@ When using such classes in Trick, classes that include non copyable classes must
```C++
class MysimObject : public Trick::SimObject {
public:
CantCopyMe ccm ;
private:
MysimObject( const MysimObject & ) ;
MysimObject& operator = ( const MysimObject) ;
public:
CantCopyMe ccm;
private:
MysimObject(const MysimObject&);
MysimObject& operator= (const MysimObject);
}
```
##### Source Code in Header Files
### Source Code in Header Files
Trick attempts to skip over class code in header files while searching for class variables and method declarations. However, code can sometimes confuse Trick and cause it to abort processing of header files. It is recommended to keep code out of the header file..
Trick attempts to skip over class code in header files while searching for class variables and method declarations. However, code can sometimes confuse Trick and cause it to abort processing of header files. It is recommended to keep code out of the header file.
##### Library Dependencies
### Library Dependencies
It is good practice to list all the source code files that define class methods in the class header file.
##### Excluding Header File Code
### Excluding Header File Code
There are several ways to exclude code from processing.
Excluding Directories
#### Excluding Directories
Add paths to exclude to the TRICK_ICG_EXCLUDE environment variable or makefile variable. This works for both C and C++ headers.
###### Excluding File
#### Excluding File
Add `ICG: (No)` to the Trick comment header.
###### Excluding Lines
#### Excluding Lines
When processing header files Trick defines 2 #define variables, TRICK_ICG and SWIG. Code may be excluded by enclosing it in #ifndef blocks.
```C++
@ -470,7 +494,7 @@ code that cannot be processed by ICG or SWIG
#endif
```
##### Source Files
## Source Files
By source files, in this context, we mean functional model source code, i.e. *.c files.
@ -479,9 +503,11 @@ By source files, in this context, we mean functional model source code, i.e. *.c
PURPOSE:
(Purpose statement.)
[REFERENCES:
((Reference #1) (Reference #n)])]
((Reference #1)
[(Reference #n)])]
[ASSUMPTIONS AND LIMITATIONS:
((Assumption #1) (Assumption #n)])]
((Assumption #1)
[(Assumption #n)])]
[LIBRARY DEPENDENCY:
(
(object.o|lib.a|lib.so|<relative_path>/lib.a)
@ -489,17 +515,17 @@ PURPOSE:
)]
[PROGRAMMERS:
(((Name) (Company) (Date) [(other info)])
[((Name) (Company) (Date) [(other info)])]]
[((Name) (Company) (Date) [(other info)])])]
*/
// source code...
```
##### Comment Header
### Comment Header
The Trick header is an optional comment block at the top of each source file. It is used for auto-documentation, and more importantly is the means of specifying dependencies to objects or libraries not processed by Trick. Separate functions within a source file do NOT require additional headers. Since parentheses, ( ), are used to delineate fields within the comment header, parentheses are not allowed as characters within the comment fields. NOTE: Even if you are coding a C++ file, you must still specify the comment header using C style comments (not C++ style comments).
###### Job Description
#### Job Description
* The PURPOSE field should be a brief description of what the module does.
* The REFERENCES field may contain any number of references, with each reference possessing any number of sub items; notice the nested parentheses for the REFERENCES field.
@ -507,12 +533,12 @@ The Trick header is an optional comment block at the top of each source file. It
* The LIBRARY DEPENDENCIES. See Library_Dependencies section in the model header section
* The PROGRAMMERS field may contain any number of programmer fields, each of which may contain any number of sub items; e.g. programmer name, company, mod date, etc. The programmer fields are meant to provide an in-code means to track code changes.
##### Source Code
### Source Code
Trick is only interested in the header comment if one is present in source code files. Anything goes for the rest of the source code file.
##### Trick Version Compatibility
### Trick Version Compatibility
Trick is always changing. The interface to Trick functions may change with each major version. Sometimes even minor version upgrades changes the interface. When Trick builds model source code it includes -DTRICK_VER=<version> and -DTRICK_MINOR=<minor_version> to the TRICK_CFLAGS and TRICK_CXXFLAGS. This allows developers to key off the Trick version in model source code. If there are any compile issues dependent on Trick version, this #define may be useful.
Trick is always changing. The interface to Trick functions may change with each major version. Sometimes even minor version upgrades change the interface. When Trick builds model source code, it includes -DTRICK_VER=<version> and -DTRICK_MINOR=<minor_version> to the TRICK_CFLAGS and TRICK_CXXFLAGS. This allows developers to key off the Trick version in model source code. If there are any compile issues dependent on Trick version, this #define may be useful.
[Continue to Environment Variables](Environment-Variables)

62
docs/documentation/building_a_simulation/Simulation-Definition-File.md
View File

@ -69,7 +69,7 @@ class <sim_object_type_name> : public Trick::SimObject {
[void create_connections() { <glue_code> }]
```
### Trick Header Comment
## Trick Header Comment
This optional section of the S_define file is a C style comment found anywhere in the S_define file.
CP will parse the Trick Header comment looking for library dependencies and default data. Library
@ -81,7 +81,7 @@ instance name, and the relative path to the default data file. CP will read in
substituting each occurrence of the structure type in the file with the instance name. All of the default
data files are concatenated to the S_default.dat file.
#### S_define Library Dependencies
### S_define Library Dependencies
```
LIBRARY DEPENDENCY:
((relative_path/model_1.c)
@ -99,42 +99,42 @@ full path to the file, in this case path/to/model.c. Library dependendencies in
differ from ones found in model source code as they must be the full path to the source file not the
object file.
### Include files
## Include files
There are two types of includes in the S_define file.
#### Single pound "#" includes.
### Single pound "#" includes.
Include files with a single pound "#" are parsed as they are part of the S_define file. They are
treated just as #include files in C or C++ files. These files usually include other sim objects or
instantiations as part of the S_define file.
#### Double pound "#" includes.
### Double pound "#" includes.
Include files with a double pound "##" are not parsed as part of the S_define file. These files are the
model header files. They include the model class and structure definitions as well as C prototypes for
functions used in the S_define file. Double pound files are copied, minus one pound, to S_source.hh.
### User Header Code Block
## User Header Code Block
This section of the S_define (encapsulated by "%header{...%}") can be used for including header files
directly into the S_source.hh. Header files listed here will not be input processed.
### User Code Block
## User Code Block
This section of the S_define (encapsulated by %{.....%}) can be used for any user specific
global C code. CP will simply insert this section of code into the S_source.c file after
all header files are included. Typically this feature is used as a quick method for customizing
simulations with additions of global variables and functions.
### Simulation Object Definition
## Simulation Object Definition
A simulation definition file may contain any number of simulation object definitions.
A simulation object definition is of the form: class <sim_object_name> : public Trick::SimObject { ... }.
All sim objects must inherit from the Trick::SimObject or a derivative. A sim object definition
may contain zero or more data structure declarations and zero or more module declarations.
### Model Classes and Data Structures
## Model Classes and Data Structures
Model classes and data structures are declared within a sim object. Model classes and data structures
may be public, protected, or private within the sim object. Standard C++ privacy rules apply to
@ -143,7 +143,7 @@ processor.
Intrinsic types are allowed as sim object data members.
### Job Declarations
## Job Declarations
Jobs are the hands and feet of the simulation. They are the building blocks for the
simulation. Jobs are C or C++ routines with special Trick tags that determine scheduling,
@ -158,7 +158,7 @@ Jobs only appear in the constructor of the sim object.
Most of these fields are optional depending on how the module is classified or utilized
within the sim. The following subsections detail the usage and purpose of each of these fields.
#### Child Thread Specification
### Child Thread Specification
The first field of a module declaration is an optional child process specification in
the form of a capital C immediately followed by an integer child ID number; i.e. C1, C2, C3,
@ -190,7 +190,7 @@ first child thread; jobs with a C2 specification will be executed by the second
Child Threads have three different scheduling choices. See Section XYZ for child thread scheduling
details.
#### Job Tagging
### Job Tagging
This optional field allows you to tag a job or set of jobs. The tag is surrounded in curly
braces. In the input file, you may then operate on the tag. All jobs with the same tag will be
@ -208,7 +208,7 @@ tagged BLUE with the following:
trick.add_read(10.0, """trick.exec_set_job_onoff("BLUE" , False)""")
```
#### Job Phasing
### Job Phasing
The next field of a job declaration is an optional phase number specification in the form of a
capital P immediately followed by an integer phase ID number from 1 to 65534, e.g., P1, P2, P3, etc.
@ -217,7 +217,7 @@ used on all class jobs to sequence the execution of jobs in the same class. Job
execute first, then P2, etc. Jobs with the same phase number are executed in the order they are
in the S_define.
#### Execution Schedule Time Specification
### Execution Schedule Time Specification
The execution schedule specification specifies the job's execution cycle time, start time, and
stop time. The time specs must be a comma separated list of floating point numbers enclosed by
@ -240,7 +240,7 @@ All other job classes categorized in Table SD_1 should NOT specify an execution
- FREEZE (purple color) are tied to the freeze frame (EXCEPT for freeze_scheduled class jobs which DO need the spec.)
- CHECKPOINT (orange color) are tied to checkpointing and run only once.
##### Job Class
#### Job Class
The job class determines where in the simulation a job is run. Each job in the S_define file
requires a job class.
@ -319,7 +319,7 @@ requires a job class.
</table>
</center>
##### Job Return Type
#### Job Return Type
All integration class jobs must return an integer value which represents the current integration
pass identifier. If all integration passes are complete, the job must return a zero.
@ -333,7 +333,7 @@ integer or else the executive will assume an error occurred an immediately termi
If the job does not return an integer, Trick will not take any action based on a return value. Note
that initialization job return values are NOT checked by the executive.
##### Job Name
#### Job Name
This field specifies the job name of the job as defined in the job’s source code.
@ -361,17 +361,17 @@ class MySimObject() : public Trick::SimObject {
```
#### Job Calling Arguments
### Job Calling Arguments
Job calling arguments adhere to C++ calling argument standards.
### Sim Object Methods
## Sim Object Methods
Methods may be defined within a sim object. These methods may be used as simulation jobs.
A possible use for sim object methods would be to call non C/C++ code with minimal overhead from
the S_define file.
### Specifying Scheduled Loop Job Class Order
## Specifying Scheduled Loop Job Class Order
This section of the S_define (encapsulated by "job_class_order{...};) can be used to specify a new
scheduled loop job class order. The user may simply re-order the existing job classes that exist or
@ -391,14 +391,14 @@ job_class_order {
};
```
### Simulation Object C++ properties
## Simulation Object C++ properties
Sim objects are C++ objects. They possess all of the capabilities of C++ objects. This section
describes how to use some C++ features with sim objects.
#### Simulation Object Instantiations
### Simulation Object Instantiations
##### Multiple Instantiations
#### Multiple Instantiations
Sim objects are instantiated within the S_define file. They are regular class objects, and as such
are treated that way. Sim objects may be multiply instantiated. Multiply instantiated sim objects
@ -422,7 +422,7 @@ ballSimObject ball ;
ballSimObject ball2 ;
```
##### Sim Object Constructor Arguments and Initializer Lists
#### Sim Object Constructor Arguments and Initializer Lists
Sim objects instantiations may take arguments. These arguments may be used in the sim object's
initialization list. An initialization list constructs member variables of the class. They
@ -446,7 +446,7 @@ class ballSimObject : public Trick::SimObject {
ballSimObject ball(5) ;
```
##### Sim Object Constructor Arguments and Job Control
#### Sim Object Constructor Arguments and Job Control
Arguments to sim objects may also be used to control job execution. Most items in the job
specification may be set to the value of an argument.
@ -469,7 +469,7 @@ ballSimObject ball(1 , 10.0 , ~@~\initialization~@~]) ;
ballSimObject ball2( 2 , 5.0 , ~@~\default_data~@~] ) ;
```
#### Multiple Constructors
### Multiple Constructors
Sim objects may define multiple constructors. Each constructor may define different job
parameters or even an entirely different set of jobs. Arguments to the sim object
@ -496,7 +496,7 @@ ballSimObject ball(1 , 10.0 , "initialization") ;
ballSimObject ball2( "default_data" ) ;
```
#### Sim Object Inheritance
### Sim Object Inheritance
Sim objects may inherit from other sim objects. Jobs in the derived class will be run after those
of the base sim object class. Both C and C++ jobs may be inherited.
@ -521,7 +521,7 @@ class anotherBallSimObject : public ballSimObject {
anotherBallSimObject ball() ;
```
#### Polymorphism in Sim Object jobs.
### Polymorphism in Sim Object jobs.
Polymorphism can be used to dynamically set objects at initialization or even change object types
during runtime. Given an abstract class and two derived classes:
@ -567,7 +567,7 @@ ball.ball_ptr = trick.TMM_declare_var_s("Soccerball[1]")
trick.add_read(20.0 , """ball.ball_ptr = trick.TMM_declare_var_s("Baseball[1]")""")
```
### State Integration Specification
## State Integration Specification
Trick manages state integration with exceptional flexibility. The integration specification
allows the developer to group the derivative, integration, and dynamic_event class modules
@ -597,7 +597,7 @@ cycle time in seconds. At least one sim object name must be specified followed b
of additional sim object names separated by commas. An S_define can have at most one integrate
statement per sim object, and at least one integrate statement for all sim objects.
### Parameter Collection Mechanism
## Parameter Collection Mechanism
The parameter collection mechanism is probably the most difficult capability of the CP to
understand and utilize. This capability is useful when the user wants a single job to handle
@ -743,7 +743,7 @@ Several aspects of this example code which need mentioning are listed below.
example, the parameters collected were single dimensioned double precision arrays with
three elements per array.
### Create Connections
## Create Connections
The create_connections section contains arbitrary code that is executed right after sim
object instantiations. Code in this section is performed before any job of any job class.

32
docs/documentation/data_products/DP-Product-File-Format.md
View File

@ -5,7 +5,7 @@ Since Trick 10, the DP Product Specification File Format is changed to XML. The
DTD is defined as following:
### Product.dtd
## Product.dtd
```
<!-- Trick DP Product definition -->
@ -110,7 +110,7 @@ text formats. The product specification file may contain any number of pages and
page or table. <b>extfn</b> refers to an external program designed to manipulate recorded data
into a format which is more easily displayed and its occurrence is not required.
### DP Page Element Specifications
## DP Page Element Specifications
A DP product file may have one or more <b>page</b> elements. Each <b>page</b> element must
have at least one <b>plot</b> elment and may have more plots sepcified. All attributes of a
<b>page</b> element as stated earlier in @ref product_dtd "Product.dtd" are:
@ -120,7 +120,7 @@ The <b>page</b> element will be discussed in following sections: @ref plot_eleme
@ref specific_variable_options "6.2.1.3 DP Specific Y (or Z) Variable Options", and
@ref curves "6.2.1.4 Curves".
#### DP Plot Element Specifications
### DP Plot Element Specifications
The <b>tstart</b> and <b>tstop</b> options have the same function as in the session file. If either of these options
is specified, they will override any values specified in the session file for this particular plot page.
@ -128,7 +128,7 @@ Each plot page specification can include up to nine individual plot specificatio
of the plots on a plot page is automatically sized to fit within the plot page window regardless of
the number of plots specified for the plot page.
#### General Variable Options
### General Variable Options
The general variable options are options that apply to a variable regardless when it's for X, or Y, or Z.
They are:
@ -146,7 +146,7 @@ specified at the plot level.
value by a factor of the value specified by this attribute. The scale factor is applied after the
measurement units (if specified) conversion is performed.
#### DP Specific Y (or Z) Variable Options
### DP Specific Y (or Z) Variable Options
The Y (Z) variable specification has additional options which allow the user to specify distinct line, symbol,
and color attributes. Even though <b>var</b> element XML specification doesn't limit a X variable having
@ -168,7 +168,7 @@ The <b>line_color</b> attribute of <b>var</b> allows the user to specify a color
the <b>gnuplot_line_sytle</b> attribute of <b>var</b> allows the user to change the line style in a Gnuplot.
You may specify the line style by name. The default is lines.
#### Curves
### Curves
Each curve has either specified 2 or 3 variables stated as <b>var</b> or has <b>
varcase</b> specified. The first <b>var</b> element is for X, the second <b>var</b>
element is for Y and the third is for Z. A <b>curve</b> element can not have both <b>var</b>
@ -216,7 +216,7 @@ both RUN_A and RUN_B.
</product>
```
### DP Table Specifications
## DP Table Specifications
Each table is comprised of one or more columns and each column is only for one variable. Each <b>column</b> element
has an optional <b>format</b> attribute that allows the user to specify the text format for the variable's data. The
@ -288,13 +288,13 @@ An example data of the specified table:
-6.740139e-01 -4.309353e-01 -6.740139e+00 -4.309353e+00
```
### DP External Programs
## DP External Programs
The <b>extfn</b> element provides a means for transforming data. Users build a program that is dynamically linked into
Trick data products for manipulating data specified in the DP Product XML file and its document type definition file
is stated as @ref product_dtd "Product.dtd".
#### Element extfn Specifications
### Element extfn Specifications
The <b>extfn</b> needs to have 3 element specifications associated with it. These elements are <b>fname</b>, <b>inputs</b>, and <b>outputs</b>.
The <b>fname</b> is a full path to a program which accepts the inputs and generates the outputs. This
program must adhere to strict interface requirements. This program will be dynamically linked into the data products,
@ -340,7 +340,7 @@ The product specification file (DP_* file) might look like this:
</product>
```
#### External Program Source Code
### External Program Source Code
To use the external program feature of the product specification file, a user must either access a previously written
program, or write their own.
@ -361,14 +361,14 @@ int extGetNextRecord(double *in, int numIn __attribute__ ((unused)), double *out
}
```
#### Building The External Program
### Building The External Program
##### Linux
#### Linux
- Step 1. cc -c <myprogram1>.c (compile all individual object this way)
- Step 2. ld -shared -o <myprogram>.so <myfunction1>.o <myfunction2>.o ... <myfunctionN>.o <myLib>.a -lc
##### MacOS X
#### MacOS X
- Step 1. cc -c <myprogram1>.c (compile all individual object this way)
- Step 2. cc -bundle -o <myprogram>.so <myfunction1>.o <myfunction2>.o ... <myfunctionN>.o <myLib>.a -lc
@ -381,7 +381,7 @@ Do the following to see if your newly created shared object has unresolved depen
- @b UNIX @b Prompt> nm <myprogram>.so
#### External Program Summary
### External Program Summary
To use an external program:
1. Build a DP spec file with the program name, inputs and outputs.
@ -389,7 +389,7 @@ To use an external program:
3. Build the external program.
4. Run the data products, and hopefully the results you expect will be there.
#### External Program Proglems And Caveats
### External Program Proglems And Caveats
- Can't load shared library!!! The external program (*.so program) may have unresolved dependencies.
Try "nm" on your external program, and look for "U"s. The objects that you have linked in might have extern definitions that aren't there.
@ -398,7 +398,7 @@ Try "nm" on your external program, and look for "U"s. The objects that you have
- External programs convert everything to doubles, and only accept and output doubles.
- External programs have no notion of unit conversion.
### A general DP Product XML File Example
## A general DP Product XML File Example
```
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>

4
docs/documentation/data_products/DP-Session-File-Format.md
View File

@ -4,7 +4,7 @@
Since Trick 10, the DP Session file is changed to XML format. The Session XML Document
Type Definitions(DTD) is defined as following:
### Session.dtd
## Session.dtd
```
<!-- Trick DP Session definition -->
@ -97,7 +97,7 @@ The optional <b>machine, port</b> attributes of <b>session</b> specify the name
number for plotting.
### DP Session File Example
## DP Session File Example
```
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>

150
docs/documentation/data_products/Data-Products-GUIs.md
View File

@ -12,7 +12,7 @@ These two applications work together and allow the user to plot and tabularize T
This section gives various examples of viewing Trick logged data using Trick DP and Trick QP.
### Trick DP - Data Products Application
## Trick DP - Data Products Application
The trick_dp (data products) is designed to make use of data product specification files (DP files). DP specification
files are input files which tell data products how and what to display in plots and tables. If time is taken to create the DP
@ -22,7 +22,7 @@ detailed information on its use. To launch the program:
- <b>UNIX Prompt></b> trick_dp&
### Trick DP GUI
## Trick DP GUI
![trick_dp](images/trick_dp.jpg)
@ -34,9 +34,9 @@ as shown in the above image. The interface is explained with further details in
- Display areas
#### Trick DP Menu bar
### Trick DP Menu bar
##### Trick DP Session Menu
#### Trick DP Session Menu
![trick_dp_session_menu](images/trick_dp_session_menu.jpg)
@ -55,7 +55,7 @@ as shown in the above image. The interface is explained with further details in
- <b>Exit</b>
- Exits the GUI. If Show Exit Confirmation Prompt is checked, Confirm Exit dialog box would be displayed. Otherwise, exits immediately.
##### Trick DP Simrun Menu
#### Trick DP Simrun Menu
![trick_dp_simrun_menu](images/trick_dp_simrun_menu.jpg)
@ -86,7 +86,7 @@ as shown in the above image. The interface is explained with further details in
- Fermi
- Gnuplot
##### Trick DP Actions Menu
#### Trick DP Actions Menu
![trick_dp_actions_menu](images/trick_dp_actions_menu.jpg)
@ -113,7 +113,7 @@ as shown in the above image. The interface is explained with further details in
- <b>Create PDF Booklet...</b>
- Allows users to view, merge, or create a PDF file for the selected postscript file(s).
##### Trick DP Help Menu
#### Trick DP Help Menu
![trick_dp_help_menu](images/trick_dp_help_menu.jpg)
@ -122,7 +122,7 @@ as shown in the above image. The interface is explained with further details in
- <b>About...</b>
- Shows the information about this application.
#### Toolbar
### Toolbar
![trick_dp_toolbar](images/trick_dp_toolbar.jpg)
@ -130,7 +130,7 @@ These icon buttons eables easier access to those commonly used functions. The fu
the menu item that shares the same icon. A tooltip of the button will be displayed if moving the mouse pointer over any
of these buttons.
#### Display areas
### Display areas
There are 5 display areas that are Sims/Runs Tree (upper left), DP Tree (upper right),
Run Selections (middle left), DP Selections (middle right) and the bottom is
@ -139,7 +139,7 @@ a message display area.
Please note that all sim directories start with <b>SIM</b>, all run directories starts with <b>RUN</b> or <b>MONTE_RUN</b>, and
all data product files start with <b>DP</b> and are placed in <b>DP_Product</b> directory within a <b>SIM</b> directory.
##### Sims/Runs Tree
#### Sims/Runs Tree
Launching trick_dp in a directory that contains SIM directories will cause those SIM directories to be displayed
in this area as shown below. If no SIM directories exist in the launch directory, trick_dp will display SIMs from
@ -154,7 +154,7 @@ in grey contain no data.
![trick_dp_simrun_area](images/trick_dp_simrun_area.jpg)
##### Sims/Runs Tree Popup Menus
#### Sims/Runs Tree Popup Menus
![trick_dp_simrun_popup1](images/trick_dp_simrun_popup1.jpg)
@ -167,7 +167,7 @@ in grey contain no data.
- <b>Remove</b>
- Removes the highlighted directory from the tree. It does not physically remove the directory from your file system.
##### Sims/Runs Tree Popup Menus
#### Sims/Runs Tree Popup Menus
![trick_dp_simrun_popup2](images/trick_dp_simrun_popup2.jpg)
@ -185,7 +185,7 @@ in grey contain no data.
- <b>Remove</b>
- Removes the selected directory from the tree. It does not physically remove the directory from your file system.
###### Sims/Runs Tree Popup Menus
##### Sims/Runs Tree Popup Menus
![trick_dp_simrun_popup3](images/trick_dp_simrun_popup3.jpg)
@ -196,7 +196,7 @@ in grey contain no data.
- <b>Run Sim</b>
- Runs the sim from each sim directory using the input.py from the corresponding highlighted RUN directory.
###### DP Tree
##### DP Tree
DP files in DP_Product of SIM directories are displayed here in a tree structure. Double clicking a SIM node
or single clicking the node icon on the left of a SIM node from the Sims/Runs Tree will make all DP files
@ -207,11 +207,11 @@ from Sims/Runs Tree and selecting Read DP List from the popup menu list.
![trick_dp_dptree_area](images/trick_dp_dptree_area.jpg)
###### DP Tree Popup Menus
##### DP Tree Popup Menus
Right clicking on a tree node at any level from the DP Tree as shown above causes a corresponding popup menu displayed.
###### DP Tree Popup Menus
##### DP Tree Popup Menus
![trick_dp_tree_popup1](images/trick_dp_tree_popup1.jpg)
@ -222,7 +222,7 @@ Right clicking on a tree node at any level from the DP Tree as shown above cause
- <b>Remove</b>
- Removes the highlighted directory from the tree. It does not physically remove the directory from your file system.
###### DP Tree Popup Menus
##### DP Tree Popup Menus
![trick_dp_tree_popup2](images/trick_dp_tree_popup2.jpg)
@ -233,7 +233,7 @@ Right clicking on a tree node at any level from the DP Tree as shown above cause
- <b>Remove</b>
- Removes the highlighted directory from the tree. It does not physically remove the directory from your file system.
###### DP Tree Popup Menus
##### DP Tree Popup Menus
![trick_dp_tree_popup3](images/trick_dp_tree_popup3.jpg)
@ -242,7 +242,7 @@ Right clicking on a tree node at any level from the DP Tree as shown above cause
- <b>Refresh</b>
- Refreshes all highlighted directories.
###### DP Tree Popup Menus
##### DP Tree Popup Menus
![trick_dp_tree_popup4](images/trick_dp_tree_popup4.jpg)
@ -251,7 +251,7 @@ Right clicking on a tree node at any level from the DP Tree as shown above cause
- <b>Edit DP...</b>
- Opens the selected DP file with Quickplot application for editing.
###### Run Selections
##### Run Selections
All selected RUN directories for retriving data from for plotting are listed here. You can select a RUN or RUN(s) by:
- Double clicking a RUN directory in black from Sims/Runs Tree
@ -261,7 +261,7 @@ All selected RUN directories for retriving data from for plotting are listed her
![trick_dp_runselections_area](images/trick_dp_runselections_area.jpg)
###### Run Selections Popup Menus
##### Run Selections Popup Menus
Right clicking on a RUN from the list brings up a popup menu.
@ -279,13 +279,13 @@ Right clicking on a RUN from the list brings up a popup menu.
![trick_run_selections_input_timename](images/trick_run_selections_input_timename.jpg)
###### DP Selections
##### DP Selections
All selected DP files that tell data products how and what to display in plots and tables are listed here.
<b>Trick DP - DP Selections</b>
![trick_dp_dpselections_area](images/trick_dp_dpselections_area.jpg)
###### DP Selections Popup Menus
##### DP Selections Popup Menus
Right clicking on a DP file from the list brings up a popup menu.
@ -298,13 +298,13 @@ Right clicking on a DP file from the list brings up a popup menu.
- <b>Remove All</b>
- Removes all DP files from the list.
###### Message Display
##### Message Display
This display redirects all screen printout to here to let users know what it is been doing or what has gone wrong.
<b>Trick DP - Message Display</b>
![trick_dp_msg_area](images/trick_dp_msg_area.jpg)
### Trick QP - Quickplot Application
## Trick QP - Quickplot Application
The trick_qp is designed for a quick peek at data in a particular RUN. It is also designed to create the DP specification
files that the trick_dp uses. Quickplot usage can be abused. It is best to take time to make a DP specification file using
@ -323,7 +323,7 @@ OR
<b>UNIX Prompt></b> trick_qp RUN<name> &
```
#### Trick QP GUI
### Trick QP GUI
![trick_qp](images/trick_qp.jpg)
@ -334,11 +334,11 @@ as shown in the above image. The interface is explained with further details in
- Toolbar
- Display areas
##### Menu bar
#### Menu bar
This table shows all of the menus along with their menu items and functionalities related to the Trick QP menu bar:
##### Trick QP File Menu
#### Trick QP File Menu
![trick_qp_file_menu](images/trick_qp_file_menu.jpg)
@ -359,7 +359,7 @@ This table shows all of the menus along with their menu items and functionalitie
- <b>Exit</b>
- Exits the GUI. If Show Exit Confirmation Prompt is checked, Confirm Exit dialog box would be displayed. Otherwise, exits immediately.
##### Trick QP Vars Menu
#### Trick QP Vars Menu
![trick_qp_vars_menu](images/trick_qp_vars_menu.jpg)
@ -380,7 +380,7 @@ This table shows all of the menus along with their menu items and functionalitie
- <b>Change Units...</b>
- Prompts for changing highlighted variables (first one if multiple variables selected) units.
##### Trick QP Runs Menu
#### Trick QP Runs Menu
![trick_qp_runs_menu](images/trick_qp_runs_menu.jpg)
@ -389,7 +389,7 @@ This table shows all of the menus along with their menu items and functionalitie
- <b>Remove Run</b>
- Removes all highlighted RUN directories from "Runs" area.
##### Trick QP Plots Menu
#### Trick QP Plots Menu
![trick_qp_plots_menu](images/trick_qp_plots_menu.jpg)
@ -404,7 +404,7 @@ This table shows all of the menus along with their menu items and functionalitie
- <b>New Varcase</b>
- Adds a new varcase to the currently selected curve.
##### Trick QP Tables Menu
#### Trick QP Tables Menu
![trick_qp_tables_menu](images/trick_qp_tables_menu.jpg)
@ -415,7 +415,7 @@ This table shows all of the menus along with their menu items and functionalitie
- <b>New Column</b>
- Adds a new empty column to the currently selected table.
##### Trick QP Programs Menu
#### Trick QP Programs Menu
![trick_qp_programs_menu](images/trick_qp_programs_menu.jpg)
@ -427,14 +427,14 @@ This table shows all of the menus along with their menu items and functionalitie
- <b>New Output...</b>
- Adds a new output for the currently selected program.
##### Trick QP Programs Menu
#### Trick QP Programs Menu
![trick_qp_settings_menu](images/trick_qp_settings_menu.jpg)
- <b>Plot Utility</b>
- Selects either Fermi or Gnuplot for plotting.
##### Trick QP Programs Menu
#### Trick QP Programs Menu
![trick_qp_actions_menu](images/trick_qp_actions_menu.jpg)
@ -451,7 +451,7 @@ This table shows all of the menus along with their menu items and functionalitie
- <b>Table Error...</b>
- TBD.
##### Trick QP Programs Menu
#### Trick QP Programs Menu
![trick_qp_help_menu](images/trick_qp_help_menu.jpg)
@ -460,7 +460,7 @@ This table shows all of the menus along with their menu items and functionalitie
- <b>About...</b>
- Shows the information about this application.
##### Toolbar
#### Toolbar
![trick_qp_toolbar](images/trick_qp_toolbar.jpg)
@ -469,25 +469,25 @@ the menu item that shares the same icon. A tooltip of the button will be display
of these buttons.
##### Display areas
#### Display areas
There are 5 display areas that are Vars (upper left), DP Content (upper right),
Runs (middle left), Property Notebook (middle right) and the bottom is
a message display area.
##### Vars
#### Vars
All variables that are found in Trick log data files from the selected RUN directories are listed here. If variables shown in red, means that they do not exist in every RUN directory.
<b>Trick QP - Vars</b>
![trick_qp_vars_area](images/trick_qp_vars_area.jpg)
##### Vars Popup Menus
#### Vars Popup Menus
Right clicking on a variable from the Vars as shown above causes a corresponding popup menu displayed. This menu is actually the same as Vars menu.
##### Vars Popup Menus
#### Vars Popup Menus
![trick_vars_popup1](images/trick_qp_vars_popup1.jpg)
- <b>Add Var</b>
@ -507,7 +507,7 @@ Right clicking on a variable from the Vars as shown above causes a corresponding
- <b>Change Units...</b>
- Prompts for changing highlighted variables (first one if multiple variables selected) units.
###### DP Content
##### DP Content
DP Content area presents the content of a DP file graphically.
@ -515,11 +515,11 @@ DP Content area presents the content of a DP file graphically.
![trick_qp_dpcontent_area](images/trick_qp_dpcontent_area.jpg)
###### DP Content Popup Menus
##### DP Content Popup Menus
Right clicking on a tree node at any level from the DP Content as shown above causes a corresponding popup menu displayed.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup1](images/trick_qp_dpcontent_popup1.jpg)
@ -528,7 +528,7 @@ Right clicking on a tree node at any level from the DP Content as shown above ca
- <b>Remove All Pages</b>
- Removes all pages.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup2](images/trick_qp_dpcontent_popup2.jpg)
@ -537,7 +537,7 @@ Right clicking on a tree node at any level from the DP Content as shown above ca
- <b>Remove</b>
- Removes this page.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup3](images/trick_qp_dpcontent_popup3.jpg)
@ -546,7 +546,7 @@ Right clicking on a tree node at any level from the DP Content as shown above ca
- <b>Remove</b>
- Removes this plot.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup4](images/trick_qp_dpcontent_popup4.jpg)
@ -562,7 +562,7 @@ Right clicking on a tree node at any level from the DP Content as shown above ca
- Adds a new varcase node.
- If there are already variables added for this curve, new varcase node can not be added.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup5](images/trick_qp_dpcontent_popup5.jpg)
@ -573,7 +573,7 @@ Right clicking on a tree node at any level from the DP Content as shown above ca
- Y variable can be removed.
- Y variable can not be replaced. You need to simply remove the Y variable, and then add a new variable.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup6](images/trick_qp_dpcontent_popup6.jpg)
@ -590,7 +590,7 @@ Right clicking on a tree node at any level from the DP Content as shown above ca
- Y variable can be removed.
- Y variable can not be replaced. You need to simply remove the Y variable, and then add a new variable.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup7](images/trick_qp_dpcontent_popup7.jpg)
@ -599,7 +599,7 @@ Right clicking on a tree node at any level from the DP Content as shown above ca
- <b>Remove All Tables</b>
- Removes all tables.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup8](images/trick_qp_dpcontent_popup8.jpg)
@ -608,14 +608,14 @@ Right clicking on a tree node at any level from the DP Content as shown above ca
- <b>Remove</b>
- Removes this table.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup9](images/trick_qp_dpcontent_popup9.jpg)
- <b>Remove</b>
- Removes this column.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup10](images/trick_qp_dpcontent_popup10.jpg)
@ -623,7 +623,7 @@ Right clicking on a tree node at any level from the DP Content as shown above ca
- Removes the this hightlighted variable.
- Also removes the column which it belongs to as each column has only on variable associated with it.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup11](images/trick_qp_dpcontent_popup11.jpg)
@ -633,28 +633,28 @@ Right clicking on a tree node at any level from the DP Content as shown above ca
- <b>Remove All Programs</b>
- Removes all programs. Currently only one program is supported.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup12](images/trick_qp_dpcontent_popup12.jpg)
- <b>Remove</b>
- Removes the program.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup13](images/trick_qp_dpcontent_popup13.jpg)
- <b>Add Var</b>
- Adds highlighted variables from Vars to Input.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup14](images/trick_qp_dpcontent_popup14.jpg)
- <b>Remove</b>
- Removes the highlighted variable.
###### DP Content Popup Menus
##### DP Content Popup Menus
![trick_qp_dpcontent_popup15](images/trick_qp_dpcontent_popup15.jpg)
@ -667,11 +667,11 @@ Right clicking on a tree node at any level from the DP Content as shown above ca
![trick_qp_dpcontent_popup17](images/trick_qp_dpcontent_popup17.jpg)
##### Trick QP Run Selections
#### Trick QP Run Selections
All selected RUN directories for retriving data from for plotting are listed here.
![trick_qp_runs_area](images/trick_qp_runs_area.jpg)
###### Runs Popup Menus
##### Runs Popup Menus
Right clicking on a RUN from the list brings up a corresponding popup menu.
@ -684,7 +684,7 @@ Right clicking on a RUN from the list brings up a corresponding popup menu.
- By default, RUN's time name is sys.exec.out.time
![trick_qp_runs_selections_input_timename](images/trick_qp_runs_selections_input_timename.jpg)
###### Property Notebook
##### Property Notebook
All editable data entries for the selected node from DP Content are displayed here.
You are required to click <b>Apply Change</b> button to save all the changes made.
@ -693,21 +693,21 @@ Otherwise, all changes will be lost if browsing a different node and come back t
![trick_qp_notebook_area](images/trick_qp_notebook_area.jpg)
###### Message Display
##### Message Display
This display redirects all screen printout to here to let users know what it is been doing or what has gone wrong.
<b>Trick QP - Message Display</b>
![trick_qp_msg_area](images/trick_qp_msg_area.jpg)
### Viewing Data
## Viewing Data
In this section, <b>SIM_cannon_analytic</b> that comes with Trick distribution and is located at $TRICK_HOME/trick_sims will be used.
Assuming you already have had corresponding data recorded by executing the related sim. The data from a single run will be viewed
using Trick DP together with Trick QP. When plotting, single plotting is used. Please see Trick Tutorial
for more examples that also have comparison or error plotting with multiple runs. You certainly can perform similar exercises using your own sim.
#### Plotting With Trick DP & Trick QP
### Plotting With Trick DP & Trick QP
Begin by launching Trick DP.
@ -716,7 +716,7 @@ Begin by launching Trick DP.
<b>UNIX Prompt></b> trick_dp &
```
##### Plotting Time -vs- Postion
#### Plotting Time -vs- Postion
1. Double click the pathname containing your sim directory if it is not expanded yet (or single click the symbol next to the name)
1. Double click the SIM_cannon_analytic name in the Sims/Runs Tree. This will reveal the RUN_test directory.
@ -744,7 +744,7 @@ Begin by launching Trick DP.
![plot1](images/plot1.jpg)
##### Plotting XPosition -vs- YPosition
#### Plotting XPosition -vs- YPosition
Now, let's change the default X variable from sys.exec.out.time to a different variable.
1. Assuming the Trick QP application is still up, click the "New" plot icon located on the far left of the toolbar.
@ -757,7 +757,7 @@ Now, let's change the default X variable from sys.exec.out.time to a different v
![plot3](images/plot3.jpg)
#### Creating DP Product File
### Creating DP Product File
The information needed for the plot created earlier can be saved off to a file using Trick QP and can be reused by both
Trick DP and Trick QP. This example shows how to save XPosition -vs- YPosition plotting stated earlier
@ -774,7 +774,7 @@ Choose the directory button SIM_cannon_analytic/DP_Product". Enter file name as
- A file called DP_cannon_xy.xml is saved as it is in XML format.
1. Close the quick plot GUI, but keep trick_dp up and running.
#### Plotting with only Trick DP using a DP file
### Plotting with only Trick DP using a DP file
Now that DP_cannon_xy has been saved, the data can be viewed with Trick DP.
1. Assuming the Trick DP is still up and running from the previous steps, Click "Session->Refresh..."
@ -791,7 +791,7 @@ mouse button. Notice that there is a tiny circle on each x-y point recorded.
![plot4](images/plot4.jpg)
#### Plotting with only Trick QP
### Plotting with only Trick QP
1. Go to the SIM directory we have worked on earlier and launch Trick QP as:
- <b>UNIX Prompt></b> trick_qp RUN_test &
@ -806,7 +806,7 @@ mouse button. Notice that there is a tiny circle on each x-y point recorded.
- The selected DP_ file is presented graphically in DP Content
1. To see the trajectory again, click the plain white single sheet on the toolbar.
#### Creating DP Session File
### Creating DP Session File
1. Launch Trick DP as:
- <b>UNIX Prompt></b> trick_dp &
@ -817,7 +817,7 @@ mouse button. Notice that there is a tiny circle on each x-y point recorded.
- A file with xml extension is saved as the session file is in XML format.
#### Plotting from the Command Line
### Plotting from the Command Line
Once you a DP session file created, you can view the data the way as you specified using "fxplot" or "gxplot" command.
- Go to the SIM directory you have your session file saved.
- <b>UNIX Prompt></b> fxplot <session_file>
@ -826,9 +826,9 @@ Once you a DP session file created, you can view the data the way as you specifi
- You should see plots as you specified in the file.
#### Using Tables
### Using Tables
##### Using Tables Exercise A
#### Using Tables Exercise A
1. Go to the SIM_cannon_analytic directory and launch Trick QP as:
- <b>UNIX Prompt></b> trick_qp RUN_test &
@ -843,7 +843,7 @@ Once you a DP session file created, you can view the data the way as you specifi
![plot5](images/plot5.jpg)
##### Using Tables Exercise B
#### Using Tables Exercise B
1. Go to the SIM_cannon_analytic directory and launch Trick QP as:
- <b>UNIX Prompt></b> trick_qp RUN_test &
@ -858,7 +858,7 @@ Once you a DP session file created, you can view the data the way as you specifi
![plot6](images/plot6.jpg)
#### Using External Program
### Using External Program
The external program $TRICK_HOME/trick_source/data_products/Apps/ExternalPrograms/dp_substract.c that comes with Trick distribution will be used in this section. This program takes 2 double inputs and returns the subtraction of these 2 inputs. Assuming the program is alreay built and the corresponding shared object is available for use.

34
docs/documentation/miscellaneous_trick_tools/Miscellaneous-Trick-Tools.md
View File

@ -1,7 +1,7 @@
| [Home](/trick) → [Documentation Home](../Documentation-Home) → Miscellaneous Trick Tools |
|------------------------------------------------------------------|
### Interface Code Generator - ICG
## Interface Code Generator - ICG
ICG is the processor that %Trick uses to parse header files. It is normally called
internally from the main %Trick processor, CP. However, it may be used manually by
@ -14,8 +14,8 @@ into a simulation which uses the types parsed.
The command syntax for the ICG is as follows (with restrictions outlined afterward):
```
<b>UNIX Prompt></b> ICG [-d] [-D <define>] [-U <undefine>] <filename>.h
<b>UNIX Prompt></b> ICG -u
UNIX prompt> ICG [-d] [-D <define>] [-U <undefine>] <filename>.h
UNIX prompt> ICG -u
```
The ICG can process multiple files at a
@ -47,7 +47,7 @@ In general, the following items are not processed by the ICG:
The ICG will always give the "ICG complete." message upon successful completion of processing.
### Building Model Source
## Building Model Source
Trick's main processor, CP handles building models from a high level. However,
developers may desire to build a local cache of source and include files in a model
@ -55,7 +55,7 @@ directory. Or the developer may want to build a library from a model directory
source and include files. Trick's make_build and UNIX's make may be used for these
purposes.
#### Makefile Generator - make_build
### Makefile Generator - make_build
The make_build processor takes the src and include files in a model directory and
autogenerates a Makefile. Note that make_build will work for mixed *.c and *.h files
@ -66,7 +66,7 @@ definition files. This ensures the io_*.c files created by ICG are processed by
make_build. The command syntax for make_build is as follows:
```
<b>UNIX Prompt></b> make_build [lib <lib_name>]
UNIX prompt> make_build [lib <lib_name>]
```
The lib argument causes make_build to generate Makefile syntax for building an
@ -74,7 +74,7 @@ archived (UNIX ar) library for the object files and give the library the name <l
The make_build command is rarely used.
#### Make Processor - make
### Make Processor - make
Developers will be running GNU make on Makefiles in the SIM directory or model
directories. Running make in a SIM_ directory with a Makefile generated by CP will
@ -85,26 +85,26 @@ source local to that directory or a library.
Makefile options may be found by typing in:
```
<b>UNIX Prompt></b> make help
UNIX prompt> make help
```
Additional documentation for make can be found in UNIX manuals for your workstation.
#### Viewing Parameters In SIE Database
### Viewing Parameters In SIE Database
Sometimes you are trying to remember the name of a parameter.... "Ummm. Let's see.
It's errr. Uhhh. clock something..." Try running this in your built simulation
directory where the S_sie.resource file is located.
```
<b>UNIX Prompt></b> sie [-nocase] <search string>
UNIX prompt> sie [-nocase] <search string>
```
As an example, if you know the parameter name contains clock but don't know
anything else, try:
```
<b>UNIX Prompt></b> sie clock
UNIX prompt> sie clock
```
The search returns each %Trick processed variable (including Trick's "sys" variables)
@ -115,28 +115,28 @@ input/output spec, and units spec.
For a case-insensitive search (e.g., to find occurrences of "clock" and "Clock"),
simply specify the -nocase option.
### kill_sim
## kill_sim
The following command will kill all simulations and their children that you own.
```
<b>UNIX Prompt></b> kill_sim
UNIX prompt> kill_sim
```
### Current Trick Version
## Current Trick Version
The following command echoes the installed %Trick version release:
```
<b>UNIX Prompt></b> trick_version
UNIX prompt> trick_version
```
### Checksumming
## Checksumming
Trick comes with a file that contains checksums for the %Trick package. You may run:
```
<b>UNIX Prompt></b> trick_verify_checksums
UNIX prompt> trick_verify_checksums
```
at any time to see what, if any, files have changed from the original package. The checksum is

44
docs/documentation/running_a_simulation/Input-File.md
View File

@ -9,7 +9,7 @@ Rather than discuss an explicit syntax definition (which would probably be more
confusing than informative), each specific capability of the input processor, and
its associated input file syntax, will be discussed.
### Accessing Simulation Parameters
## Accessing Simulation Parameters
The parameter naming convention for ALL input parameters is the parameter's actual
source code name. The following is a line from an input file :
@ -84,7 +84,7 @@ print ball.daa
# is printed
```
### Accessing Simulation Enumerated Types
## Accessing Simulation Enumerated Types
Global Enumerations are available through the `trick` module.
@ -95,7 +95,7 @@ print trick.True trick.False trick.Yes trick.No
1 0 1 0
```
### Accessing Simulation Functions and Object Member functions
## Accessing Simulation Functions and Object Member functions
Almost all functions and public object methods are available to call from the Python input file.
Arguments must be filled in just as they would be in C/C++ code. There is more information about what
@ -145,7 +145,7 @@ foo(float(length))
Structure and class variables do not carry around units, and therefore the units do not have to be removed.
### Creating New Objects and Allocating Memory
## Creating New Objects and Allocating Memory
It is possible to create new objects and allocate new memory for structures directly in the Python
input file. There are at least two ways to allocate memory.
@ -236,7 +236,7 @@ def foo():
```
### Comments
## Comments
Comments in Python come in two forms.
@ -249,7 +249,7 @@ three sets of double quotes.
"""
```
### Nested File Inclusion
## Nested File Inclusion
There are several ways to include files in Python.
@ -264,7 +264,7 @@ sys.path.append("/my/python/dir") ;
import my_new_module
```
### Local Python Variables
## Local Python Variables
Local variables may be used anywhere in the Python input file. Local variables will follow normal
Python scoping rules. Shortcut variable names may be created to reference simulation variables.
@ -279,7 +279,7 @@ print ball.obj.state.output_position
# printout would read "4.5, 6.7"
```
### Environment Variables
## Environment Variables
Environment Variables are available through the Python `os.getenv` call
@ -287,7 +287,7 @@ Environment Variables are available through the Python `os.getenv` call
print os.getenv("TRICK_CFLAGS")
```
### Measurement Units
## Measurement Units
Every input parameter has associated measurement units specified in its corresponding data
structure definition file declaration. It specifies the units for the internal source code to
@ -329,7 +329,7 @@ Printing parameters in the Python script will include the attached units.
[1.0m , 2.0m , 3.0m]
```
### Time Based Input Processing
## Time Based Input Processing
The input processor allows pieces of the input file to be processed at a later simulation time.
To process code at a later time call `trick.add_read(<time>, "<code_to_be_executed>")`.
@ -355,7 +355,7 @@ read = 5.0
trick.add_read(read , ... )
```
### Freeze the Simulation
## Freeze the Simulation
To freeze a simulation call `trick.freeze([<freeze_time>])`. `trick.freeze()` called with no
arguments will freeze immediately. An optional freeze time may be provided to freeze some time
@ -373,7 +373,7 @@ trick.freeze(trick.exec_get_sim_time() + 5.0)
```
### Checkpoint the Simulation
## Checkpoint the Simulation
To checkpoint a simulation call `trick.checkpoint([<checkpoint_time>])`. `trick.checkpoint()` called with no
arguments will checkpoint immediately. An optional checkpoint time may be provided to checkpoint some time
@ -390,7 +390,7 @@ trick.checkpoint(100.0)
trick.checkpoint(trick.exec_get_sim_time() + 5.0)
```
### Stopping the Simulation
## Stopping the Simulation
To shutdown a simulation call trick.stop([<stop_time>]). trick.stop() called with no
arguments will shutdown immediately. An optional stop time may be provided to shutdown some time
@ -407,13 +407,13 @@ trick.stop(100.0)
trick.stop(trick.exec_get_sim_time() + 5.0)
```
### Events and Malfunctions
## Events and Malfunctions
Trick 10 events are a hybrid of Trick 07 events and malfunctions. A Trick 07 event has one or more conditions, one action, and is evaluated by the input processor. A Trick 07 malfunction also has one or more conditions (called triggers) that you can disable/enable, multiple actions, manual mode, and is evaluated before/after a specified job. Multiple conditions in malfunctions are ORed in 07, while multiple conditions in events can be specified by the user as being ORed or ANDed. Here is the Python syntax showing how Trick 10 events implement all of this functionality.
For information on how Trick processes events during runtime, see [Event Processing](/trick/documentation/simulation_capabilities/Event-Manager).
#### Basic Event Usage
### Basic Event Usage
```python
# Create an event that can be viewed and manipulated in MTV, and can be checkpointed
@ -454,7 +454,7 @@ trick.add_event(<event name>)
trick.terminate_on_event_parse_error(<True|False>)
```
#### Advanced Event (Malfunction) Usage
### Advanced Event (Malfunction) Usage
```python
# Insert the event before/after a "target" job so that it is evaluated then (as opposed to top of frame)
@ -520,12 +520,12 @@ trick.delete_event(<event_name>)
<event name>.manual_done()
```
#### Setting variables synchronously: Real Time Variable Injector
### Setting variables synchronously: Real Time Variable Injector
You can also use `rti_add`/`rti_fire` commands in your event action syntax (or as standalone commands in the input file or
via the variable server) to set variables. See "Real Time Variable Injector".
#### Accessing the current Event state
### Accessing the current Event state
```python
<event name>.condtion_fired(<index>) # boolean: test if a particular event condition fired this cycle
@ -544,7 +544,7 @@ via the variable server) to set variables. See "Real Time Variable Injector".
<event name>.manual_fired # boolean: test if this event was fired manually this cycle
```
#### Event Example
### Event Example
Hopefully this example shows the various things you can do using events without being too confusing. Even the event components themselves can be queried and changed.
@ -587,13 +587,11 @@ trick.add_event_before(change_event, "ball.obj.state_integ")
trick.add_event_after(over100_event, "data_record_group1.Ball")
```
### Trick Specific Python Usage
## Trick Specific Python Usage
Many of Trick's functions can be called using Python commands in the input file (or via the variable server)
to perform various operations or to customize/configure Trick.
Look for a Trick flag icon like this beside each user callable function for details in the Class pages listed below.
### I Just Want to Know How Do I Set this Value...
## I Just Want to Know How Do I Set this Value...
[Continue to Runtime GUIs](runtime_guis/Runtime-GUIs)

60
docs/documentation/running_a_simulation/runtime_guis/MalfunctionsTrickView.md
View File

@ -1,7 +1,7 @@
| [Home](/trick) → [Documentation Home](../../Documentation-Home) → [Running a Simulation](../Running-a-Simulation) → [Runtime GUIs](Runtime-GUIs) → Malfunctions |
|------------------------------------------------------------------|
### Events/Malfunctions Trick View
## Events/Malfunctions Trick View
Events/Malfunctions Trick View (hereafter referred to as MTV) is a graphical user interface that has two main functions:
1. to view/control Trick-managed event activity while the simulation is running, and
@ -9,7 +9,7 @@ Events/Malfunctions Trick View (hereafter referred to as MTV) is a graphical use
"Malfunctions" is a legacy term from when events and malfunctions were separate entities in a previous version of Trick. The functionality of both malfunctions and events have been combined and simply called "Events".
#### Launching
### Launching
Typically MTV is launched via the Actions menu in the @ref SimControlPanel "Simulation Control Panel". MTV will then load and display any events you've defined in your Run input file:
![MTV Launch](images/mtv_launch.jpg)
@ -30,38 +30,38 @@ on the command line in your simulation directory (without the <hostname> or <por
For additional launching options, see "Automatically Launching Applications".
#### The MTV GUI (in View Mode)
### The MTV GUI (in View Mode)
MTV has two main screens, one for viewing events in a running simulation (View Mode), and one for creating / editing events (Edit Mode). The MTV GUI pictured below is in **View** Mode. It may have a different look and feel based on the architecture of the machine on which it is running,
but the functionality will remain the same.
![MTV View](images/mtv_view.jpg)
##### View/Edit Tab
#### View/Edit Tab
Click the "View" Tab to view the events for a running simulation (View Mode). Click the "Edit" Tab to create / edit an event (Edit Mode).
##### Some Background on Event Processing
#### Some Background on Event Processing
There is a Trick job called process_event() that is run near the top of the execution frame to evaluate all "Added" events. See @ref Event_Processing "Event Processing" for more details.
##### Event / Condition / Action Active Toggle
#### Event / Condition / Action Active Toggle
The 1st column in View Mode is the Active Toggle.
* Clicking an Active toggle button for an **Event** will make that Event active/inactive in Normal mode.
* Clicking the Active toggle for a **Condition** will make that Condition active/inactive in Normal mode.
* Clicking the Active toggle for an **Action** will make that Action active/inactive in both Normal and Manual mode.
##### Event Name, Conditions and Actions
#### Event Name, Conditions and Actions
The 2nd column in View Mode is the event name. Each event name is shown on a gray line in the MTV display.
The name is the string that was passed to the `new_event()` command. The event's condition(s) are listed next, followed by the event's action(s). The first 50 characters of each condition/action string are shown, unless the optional comment was passed to the `condition()` or `action()` command. If the comment was specified, it is what will be displayed as the condition or action name. The number in parentheses shown in each condition / action is the index number (from 0..n) used in the `condition()` or `action()` command.
##### Event Fired & Ran Status
#### Event Fired & Ran Status
Columns 3, 4, 5, and 6 in View Mode show when and how many times the event and its components fired/ran.
* A **Condition** fires when it is Active in Normal mode and is evaluated as true.
* An **Event** fires when it is Active in Normal mode and its condition(s) are evaluated as true, or when it is in Manual mode and the command issued is either `manual_fire()` or `manual_on()`.
* An **Action** runs if it is Active and the event fires. An event runs when at least one of its actions runs.
##### Condition Hold Toggle
#### Condition Hold Toggle
The 7th column in View Mode is the Hold toggle, only valid for Conditions. Clicking the Hold toggle on a Condition will turn on/off the Hold status for that condition. If Hold is on, when the condition evaluates to true it will be "held" as true so that the condition will fire each time it is evaluated.
##### Event Mode
#### Event Mode
The 8th column in View Mode is the Event Mode selector:
1. **Normal** The default, event conditions are evaluated to determine when the event fires (issues a `manual_done()` command).
@ -73,14 +73,14 @@ When in one of the Manual modes, the event's conditions are not evaluated, the m
NOTE: The `manual_fire()` command has the side effect of "restarting" an event's cycle. For instance, if the event cycle is 1.0, in Normal mode it will be evaluated at time 0.0, 1.0, 2.0, etc. However, if you issue a `manual_fire()` command at say, time 2.5, when you return to Normal mode the event will be evaluated at 3.5, 4.5, etc.
##### Event Added Toggle
#### Event Added Toggle
The 9th column in View Mode is the Event Added Toggle. Clicking an Event's Added toggle will add/remove the event from the list of events that Trick's process_event() job will evaluate. If an event is not added, then it will not fire cyclically in Normal mode or even in Manual ON mode. However, you can fire an event that has not been added, only one shot at a time by issuing a manual FIRE (`manual_fire()`) command. When you click on the Added toggle to uncheck it, a `remove_event()` command is issued.
NOTE: Instead of adding an event (via `add_event()`) to the list to be evaluated by `process_event()`, you can alternatively add an event before or after a model job with the `add_event_before()` or `add_event_after()` command. When you do this, the event is evaluated immediately before/after that model job (the event cycle is ignored). The initial `add_event_before()` or `add_event_after()` command must be done in the Run input file, but from then on if you click the Added toggle in MTV to remove that event and then click Added to add it later, MTV will remember where it was and will add the event back in the same position before or after the model job you removed it from.
So when you click on the Added Toggle to check it, the event is added using either `add_event()`, `add_event_before()`, or `add_event_after()`.
##### Colors Used in MTV
#### Colors Used in MTV
1. **Black font** An event in Normal mode that is both Active and Added, having been added using the `add_event()` command.
1. **Brown font** An event in Normal mode that is both Active and Added, having been added using the `add_event_before()` or `add_event_after()` command.
1. **Gray font** An event that is either not Active or not Added, or a condition/action that is not Active (this color overrides the previous two colors).
@ -88,14 +88,14 @@ So when you click on the Added Toggle to check it, the event is added using eith
1. **Red background** An event's Fired Time column is highlighted in red when it fires.
1. **Green background** An event's Ran Time column is highlighted in green when it runs.
##### File Menu
#### File Menu
You can select Load Event(s) from the File menu to have Trick read in a file containing one or more events when MTV is connected to a simulation. MTV will then add the newly loaded events to the View Mode window.
##### View Menu
###### Delete Event
#### View Menu
##### Delete Event
If you select an event row in the MTV display, then select Delete Event from the View Menu, you can delete an event permanently from the simulation you are connected to. MTV will remove the event from the display and you can no longer reference that event during the simulation. This will NOT delete any file where the event was loaded from. The event object itself will be deleted from memory in the running simulation.
###### Customize Event Display
##### Customize Event Display
Selecting Customize Event Display from the File Menu will pop up a window where you can select which events you want MTV to display. This is handy when your simulation contains many events and the display window cannot display them all without scrolling. The default is for MTV to display all events contained in the running simulation, up to a maximum of 500. If your simulation has more than 500 events, you must use Customize Event Display to choose a set of 500 or fewer events to display (only the first 500 loaded will initially be shown).
If you have the need to use many events, you may want to create event "groups" by defining your events in the Run input file using Python classes. For instance, the events `mygroup.this_event` and `mygroup.that_event` shown in the MTV GUI picture above were defined like this :
@ -122,29 +122,29 @@ The Customize Event Display popup will recognize such event groups and allow you
You may notice some events named "no_name_specified". These are either events created for `add_read()` statements in the Run input file, or events created by the `new_event()` command when no name string was passed in. By default MTV does not display unnamed events, but you can display them if you want by selecting them in Customize Event Display.
##### Cycle Menu
#### Cycle Menu
The Cycle Menu allows you to set how fast the MTV GUI receives updates from the simulation it is connected to. The default cycle update rate is 0.50, but the Cycle Menu lets you pick from 0.05 (fastest) to 1.0 (slowest).
##### Connection Status Bar
#### Connection Status Bar
At the bottom of the MTV GUI is the Connection Status Bar. At the far left of the bar is an area where status messages are displayed. It normally says "Connected" or "Disconnected" depending on if MTV is connected to a running simulation. When the MTV GUI display updates the events being displayed (at startup or after you selected Customize Event Display), each event name will be briefly displayed in this status message area while loading.
There are two text fields containing the host name and port number of the connected simulation. When not connected, the user can enter the appropriate host name and port number into these text fields and click the Connect button at the right to connect to a running simulation. (The port number is the Trick variable server port number that can be found on the bottom of the "Simulation Control Panel" if it is up.)
#### The MTV GUI (in Edit Mode)
### The MTV GUI (in Edit Mode)
MTV has two main screens, one for viewing events in a running simulation (View Mode), and one for creating / editing events (Edit Mode). The MTV GUI pictured below is in **Edit** Mode.
![MTV Edit](images/mtv_edit.jpg)
##### View/Edit Tab
#### View/Edit Tab
Click the "Edit" Tab to create / edit an event (Edit Mode). Click the "View" Tab to view the events for a running simulation (View Mode).
##### Event Name Text Field
#### Event Name Text Field
When you first bring up the Edit Mode screen in MTV, the Event Name string is set to "put_new_event_name_here". You must enter a new Event Name string here before you can begin to edit the event. Note that you must press the "Enter" key on your keyboard to register the new Event Name and enable the "Event Syntax" and "User Data" areas.
##### Event Syntax Area
#### Event Syntax Area
Once you've entered an Event Name, MTV will automatically generate a default set of commands to configure your new event. The part of the commands shown under the Event Syntax column on the left is not editable. You can add or delete commands using the "Edit Menu" described below.
##### User Data Area
#### User Data Area
The part of the event commands shown under the User Data column on the right is editable. You can double click the User Data text you want to change and enter in whatever you want. Note that there is no means of checking your syntax, so if you enter incorrect syntax, you won't find out until you send the event to your simulation and it is evaluated by Trick during execution. A Python syntax error in your event will be printed to the screen and looks something like this:
```
File "<string>", line 1
@ -154,23 +154,23 @@ SyntaxError: unexpected EOF while parsing
Where "XXX" is the offending string from your event command.
##### Send To Sim Button
#### Send To Sim Button
When you have created and edited an event to your satisfaction, you can click the Send To Sim button to the right of the Event Name to send the new event to a connected simulation. Trick will read in the new event and it will be displayed in the MTV View Mode window.
##### File Menu
#### File Menu
You can select Save Event from the File Menu if you want to save your newly created event to a file. If you don't do this, it will be lost once you quit MTV or when your connected simulation terminates.
Currently there is no way to Load Event(s) from a file into the MTV editor. It is strictly for creating new events from scratch.
##### Edit Menu
###### Create New Event
#### Edit Menu
##### Create New Event
If you select Create New Event from the Edit Menu, any editing you've done that is currently displayed under Event Syntax and User Data will be discarded, and the Event Name will be set to "put_new_event_name_here" where you must enter a new Event Name string to continue.
###### Delete Line
##### Delete Line
If you select an event statement shown under Event Syntax / User Data, then select Delete Line from the Edit Menu, that line will be deleted from the event you are editing.
###### Add Line to condition/action
##### Add Line to condition/action
You can add more line(s) to a condition or action by first selecting a condition or action statement under Event Syntax / User Data, then select Add Line to condition/action from the Edit Menu.
###### Add Statement
##### Add Statement
You can add more event commands to the event you are editing by selecting Add Statement from the Edit Menu. A selection of common valid event commands are then popped up for you to select. Some advanced Trick commands, such as trick.remove_event(), can only be added manually after you have "stubbed-out" a new event via MTV.

16
docs/documentation/running_a_simulation/runtime_guis/MonteMonitor.md
View File

@ -1,12 +1,12 @@
| [Home](/trick) → [Documentation Home](../../Documentation-Home) → [Running a Simulation](../Running-a-Simulation) → [Runtime GUIs](Runtime-GUIs) → Monte Monitor |
|------------------------------------------------------------------|
### Monte Monitor
## Monte Monitor
Monte Monitor (hereafter referred to as MM) is a graphical user interface that allows users to view and modify the states
of slaves in a Monte Carlo simulation.
#### Launching
### Launching
MM can be launched from the command line via:
@ -17,19 +17,19 @@ ${TRICK_HOME}/bin/mm [options]
Pass <code>--help</code> for a description of available options. For additional launching options, see
"Automatically Launching Applications".
#### The GUI
### The GUI
The GUI pictured below may have a different look and feel based on the architecture of the machine on which it is running,
but the functionality will remain the same.
![Monte Monitor](images/MonteMonitor.jpg)
##### Progress Bar
#### Progress Bar
The progress bar displays a visual and textual representation of how far the Monte Carlo has progressed. The format is
<code>\<resolved runs\> / \<total runs\> (\<percent resolved\>)</code>.
##### Slave Table
#### Slave Table
The slave table displays information on each of the slaves. From left to right, this information is:
@ -85,18 +85,18 @@ The slave table displays information on each of the slaves. From left to right,
The number of runs the slave has completed.
</ul>
##### New Slave Field
#### New Slave Field
The new slave field allows the user to add a new slave by machine name while the Monte Carlo is running. Note that slaves
that fail to spawn for any reason (a bad machine name, for instance) will nevertheless appear in the slave table with a
status of <code>Initializing</code>.
##### Connection Panel
#### Connection Panel
The connection panel displays host and port information when MM is connected to a simulation, and allows the user to
specify these parameters when disconnected.
#### Starting and Stopping
### Starting and Stopping
Slaves can be started and stopped while the Monte Carlo is running via the <code>Monte Carlo</code> and
<code>Slaves</code> menus. Selecting a command from the <code>Monte Carlo</code> menu is equivalent to applying the same

34
docs/documentation/running_a_simulation/runtime_guis/Runtime-GUIs.md
View File

@ -3,23 +3,23 @@
Trick provides the following graphical user interfaces:
### Simulation Control Panel
## Simulation Control Panel
Send control commands to and view the status of a simulation.
### [Trick View](TrickView)
## [Trick View](TrickView)
Browse and modify a simulation's variables while it's running. Launch integrated strip charts.
### [Events/Malfunctions Trick View](MalfunctionsTrickView)
## [Events/Malfunctions Trick View](MalfunctionsTrickView)
Manage the events and malfunctions of a simulation.
### [Monte Monitor](MonteMonitor)
## [Monte Monitor](MonteMonitor)
Monitor the status of a Monte Carlo simulation; create, start, and stop slaves.
### Managing External Applications
## Managing External Applications
External applications are managed by instantiating and invoking calls on instances of launcher classes, which provide interfaces for setting up external applications from the input file or user model code. For instance, to manipulate Trick View from the input file:
```
@ -39,19 +39,19 @@ trick.add_external_application(trickView)
Provided launcher classes are derived from and listed in Trick::ExternalApplication. Some functionality is shared among launcher classes, and each class provides its own specific additional options. Trick allows any number of instances of any subclass of ExternalApplication. This means you could automatically launch two different Trick Views with completely separate settings (if you find that sort of thing useful).
### Automatically Launching Applications
## Automatically Launching Applications
Applications can be set to automatically launch during the initialization job phase by adding them to the queue of external applications managed by Trick. To do this, instantiate an instance of the appropriate launcher class (see above) and call Trick::ExternalApplication::add_external_application.
### Manually Launching Applications
## Manually Launching Applications
Trick automatically launches all applications that have been added to its queue during simulation initialization. However, applications may also be manually launched via Trick::ExternalApplication::launch.
### Launch Command
## Launch Command
Default commands suitable to launch each application are provided by their individual constructors. However, they may be changed, if desired, via Trick::ExternalApplication::set_startup_command.
### Launching Custom Applications or Commands
## Launching Custom Applications or Commands
Having Trick automatically launch a custom application, or execute any command at all really, is a simple matter of instantiating an instance of the base class ExternalApplication and then setting the desired command as described above.
```
@ -65,11 +65,11 @@ Note that ExternalApplication automatically appends the host and port argument u
Why would anyone want to have Trick automatically run additional commands? Well, for one thing, it saves you from manually running them each time you run a sim or writing a script to do it. But more importantly, applications managed by Trick are included in binary checkpoints, which means they can be saved and restored with no work on your part!
### Shared Options
## Shared Options
As each Trick GUI was written by a different developer and few standards were in place, most options vary according to each GUI. The following apply to at least Trick View and Monte Monitor. Application-specific options can be passed from the input file or user model code via Trick::ExternalApplication::set_arguments or Trick::ExternalApplication::add_arguments.
#### Host
### Host
The host of the Variable Server to which the application will connect at launch can be specified via one of:
@ -78,7 +78,7 @@ The host of the Variable Server to which the application will connect at launch
If no host is specified, it will automatically be set to that of the simulation which is launching this application.
#### Port
### Port
The port of the Variable Server to which the application will connect at launch can be specified via one of:
@ -87,7 +87,7 @@ The port of the Variable Server to which the application will connect at launch
If no port is specified, it will automatically be set to that of the simulation which is launching this application.
#### Automatically Reconnect
### Automatically Reconnect
The application can be configured to automatically reestablish lost connections via one of:
@ -97,13 +97,13 @@ The application can be configured to automatically reestablish lost connections
The default value is false.
#### Window Size and Placement
### Window Size and Placement
The window's coordinates and dimensions at launch can be set via one of:
- From the command line, use the --x, --y, --width, or --height options.
- From the input file or user model code, use Trick::ExternalApplication::set_x, Trick::ExternalApplication::set_y, Trick::ExternalApplication::set_width, or Trick::ExternalApplication::set_height.
#### Cycle Period
### Cycle Period
The period (in seconds) at which the Variable Server sends information to the application can be specified via one of:
@ -113,7 +113,7 @@ The period (in seconds) at which the Variable Server sends information to the ap
The cycle period must be a non-negative number. Specify 0 to recieve updates at the maximum rate. Values below the minimum cycle period will be set to the minimum cycle period.
#### Minimum Cycle Period
### Minimum Cycle Period
The minimum period (in seconds) at which the Variable Server can be requested to send information to the application can be specified via one of:
@ -122,7 +122,7 @@ The minimum period (in seconds) at which the Variable Server can be requested to
The minimum cycle period must be a non-negative number. The recommended and default value is 0.1. Values below this may cause instability in Trick GUIs.
#### Application Behavior
### Application Behavior
The application can take one of several actions when it loses the connection with the simulation:

64
docs/documentation/running_a_simulation/runtime_guis/TrickView.md
View File

@ -3,7 +3,7 @@
Trick View (hereafter referred to as TV) is a graphical user interface that allows users to view and modify Trick-managed variables in a simulation while it is running. It also provides for the launching of integrated strip charts and can save and restore lists of variables and their associated strip charts.
#### Launching
### Launching
TV can be launched via one of:
- From the Simulation Control Panel, under the **Actions** menu.
@ -16,7 +16,7 @@ TV can be launched via one of:
For additional launching options, see [Automatically Launching Applications](Runtime-GUIs#automatically-launching-applications).
#### Automatically Opening Files
### Automatically Opening Files
Files that are to be automatically opened when TV launches can be specified via one of:
@ -28,7 +28,7 @@ Files that are to be automatically opened when TV launches can be specified via
Opening a TV file will overwrite the current cycle period or any argument to `--cycle` with the value from the file, subject to the minimum cycle period.
#### Automatically Opening and Setting Files
### Automatically Opening and Setting Files
Files that are to be automatically opened and set when TV launches can be specified via one of:
@ -40,7 +40,7 @@ Files that are to be automatically opened and set when TV launches can be specif
Opening a TV file will overwrite the current cycle period or any argument to `--cycle` with the value from the file, subject to the minimum cycle period.
#### Automatically Setting Files
### Automatically Setting Files
Files that are to be automatically set when TV launches can be specified via one of:
@ -50,7 +50,7 @@ Files that are to be automatically set when TV launches can be specified via one
- From the input file or user model code, use `Trick::TrickView::set_auto_set_file`.
File paths are relative to the directory containing the S_main executable.
#### Strip-Chart-Only Mode
### Strip-Chart-Only Mode
Once a collection of strip charts is established and saved to a TV file, you may wish to prevent future launches from displaying the main GUI window to allow users to view the strip charts without providing them (potentially dangerous) access to the simulation's internal variables. You can cause Trick View to launch in strip-chart-only mode via one of:
@ -60,13 +60,13 @@ Once a collection of strip charts is established and saved to a TV file, you may
Note that you must provide a TV file to be automatically opened as described above when launching in strip-chart-only mode.
#### The Trick View GUI
### The Trick View GUI
The GUI pictured below may have a different look and feel based on the architecture of the machine on which it is running, but the functionality will remain the same.
![TrickView](images/TrickView.jpg)
##### File Buttons
#### File Buttons
The file buttons provide persistent storage of variable lists. From left to right, they are:
@ -85,11 +85,11 @@ The file buttons provide persistent storage of variable lists. From left to righ
- **Save**
Opens a dialog allowing the user to specify a file name. The variables in the variable table and their associated information, the cycle period, and any strip charts will be written to the file.
##### Monitor Button
#### Monitor Button
The monitor button displays the current state of the monitor and allows the user to toggle receiving updates on the variables in the variable table. A blue screen indicates that updates are being received. A black screen indicates they are not.
##### Variable Buttons
#### Variable Buttons
The variable buttons affect variables in the variable table. From left to right, they are:
@ -99,15 +99,15 @@ The variable buttons affect variables in the variable table. From left to right,
- **Delete**
Removes the selected variables from the variable table and all strip charts.
##### Variable Hierarchy Tree
#### Variable Hierarchy Tree
This panel displays all of the simulation's Trick-managed variables in a hierarchical format. Initially, only the top-level simulation objects are displayed. A variable representing a structure or class containing variables can be expanded or collapsed by double-clicking its name or by single-clicking the expand/collapse node to the left of its name. Double-clicking a variable that does not represent a structure or class will add it to the variable table. Multiple variables can be simultaneously selected via the shift and control (command on Mac) keys. Variables can also be added by selecting them, right-clicking anywhere in the variable hierarchy tree, and selecting **Add Selection** from the pop-up menu. Adding a variable that represents a structure or class will add all of its contained variables (at all lower levels). The top layer of the variable hierarchy tree will be populated when TV has finished parsing the information from the simulation, which takes place in the background. Lower levels are loaded on-demand as the tree is expanded. Although unlikely to occur in practice, it is possible that expanding every node in a large simulation will consume all of the application's available memory, in which case it will become unresponsive.
##### Search Panel
#### Search Panel
The search panel allows the user to search the variable hierarchy tree by partial name or regular expression, with an option for case sensitivity. Resulting listed variables can be added to the variable table in manners similar to those of the variable hierarchy tree. The search panel becomes available for use at the same time as the variable hierarchy tree. Search progress is indicated by a progress bar below the results list. During the initial search, only an indication of activity is given while the application counts the total number of variables. In subsequent searches, a quantitative value of progress is displayed.
##### Index Specification Window
#### Index Specification Window
When adding variables to the variable table, if any variables are pointers or arrays, the index specification window will be displayed, allowing the user to specify the ranges to add.
@ -115,7 +115,7 @@ When adding variables to the variable table, if any variables are pointers or ar
Each array displays a combo box over its allowable range. Each pointer has a single text box that accepts values in the form `minimum-maximum`. Character pointers and arrays have a check box allowing them to be treated as strings. The position radio buttons specify where in the variable table the variables will be added, relative to the currently selected row.
##### Variable Table
#### Variable Table
The variable table lists all the added variables, displaying their names, values, units, and formats. Columns can be freely rearranged by clicking and dragging their headers. Rows can be sorted by clicking the column header corresponding to the property by which they should be sorted. Rows are sorted first by the most recently clicked column header, then by the header clicked before that, and so forth. Rows can be manually reordered by clicking and dragging them. Note that manual reordering will remove any currently applied sorting. Further display customization is available via the Column Control Menu, which is accessed by clicking the miniature table icon in the upper right-hand corner of the table. Pressing the **Delete** key while the variable table has focus is equivalent to clicking the delete variable button.
@ -129,11 +129,11 @@ Variable formats are displayed via a combo box containing all of the supported f
Multiple, non-contiguous selections are allowed and may be used to affect mass value, unit, and format changes. When performing a mass edit, the assigned/selected value will only be applied to variables that can accept it.
###### Invalid References
##### Invalid References
Variables that the Variable Server failed to resolve display values of **\<Invalid Reference\>** and are highlighted in red. Such a variable's value and units cannot be changed, but its name can still be modified for the purpose of adding new variables.
##### Manual Entry Field
#### Manual Entry Field
The manual entry field provides the user a means by which to directly add a variable of any name. This is useful if a variable's information is not present in the S_sie.resource file or the file itself is not present, or if the variable is a pointer to the beginning of an array. Multiple elements of an arrayed variable can be added by specifying the range within the brackets, such as:
@ -141,30 +141,30 @@ The manual entry field provides the user a means by which to directly add a vari
Note that pointers cannot be dereferenced using the pointer dereference operator (*) in TV. Instead, the user should treat the pointer as a single-element array and append the variable's name with `[0]`.
##### Purge Button
#### Purge Button
The purge button removes all variables from the variable table that have a value of **\<Invalid Reference\>**.
##### Resolve Button
#### Resolve Button
The resolve button submits a request to the Variable Server to attempt to resolve all invalid references to legal values, which can be useful if a previously null pointer has become valid.
##### Connection Status Bar
#### Connection Status Bar
The connection panel displays host and port information when TV is connected to a simulation. When disconnected, clicking on the combo box displays a list of available simulations to which to connect. Alternately, the information can be entered directly into the panel in the form of `host:port`.
##### Clearing Logged Data
#### Clearing Logged Data
TV records the value of every variable in the variable table each time the Variable Server sends a report. This allows newly launched strip charts to include data going back all the way to the point at which the variable was first added. This can eventually result in a large amount of memory usage. If performance begins to degrade, you can clear the log of all values via the **Action** menu of either TV or any strip chart. Note that this will erase any data currently being displayed on any strip charts.
##### Settings
#### Settings
The Settings dialog can be accessed via the **File** menu and allows the user to alter the behavior of TV.
See [[Runtime GUIs]] for a detailed description of Application Behavior and Cycle Period options.
![](images/Settings.png)
###### Variable Tree Order
##### Variable Tree Order
The order in which the variable hierarchy is displayed has three options:
@ -177,31 +177,31 @@ The order in which the variable hierarchy is displayed has three options:
- **Descending Alphabetical**
Variables are sorted alphabetically Z to A.
###### Variable Addition
##### Variable Addition
The placement of newly added variables within the variable table is specified via the Position combo box. The available options are **Top**, **Before**, **After**, and **Bottom**. The **Before** and **After** options are relative to the currently selected row.
Character pointers and arrays can be treated as strings by default by checking the **char[] as string** check box. When added as such, arrays will be collapsed into single string entries. Otherwise, they will be displayed element by element.
###### Font Size
##### Font Size
This setting affects the variable hierarchy tree, search panel, and variable table text size.
###### Default Units
##### Default Units
Default units for each unit type can be specified via its corresponding combo box, which lists all of its available units. Selecting **xx** results in units as specified in the model code. The **Default All** check box, when selected, is equivalent to selecting **xx** for all unit types.
###### Default Formats
##### Default Formats
Default formats for each variable type can be specified via its corresponding combo box.
#### The Strip Chart GUI
### The Strip Chart GUI
Strip charts allow users to plot variables in the variable table in real-time. The GUI pictured below may have a different look and feel based on the architecture of the machine on which it is running, but the functionality will remain the same.
![stripchart](images/Stripchart.jpg)
##### Domain Axis Panel
#### Domain Axis Panel
The domain axis panel allows the user to affect the range of the domain axis.
@ -214,7 +214,7 @@ The domain axis panel allows the user to affect the range of the domain axis.
- **Fixed**
The domain axis will not automatically change.
##### Display Panel
#### Display Panel
The display panel allows the user to specify whether or not the chart should display certain features.
@ -227,11 +227,11 @@ The display panel allows the user to specify whether or not the chart should dis
- **Legend**
When enabled, the chart's legend will be shown.
##### Variables Panel
#### Variables Panel
The variables panel allows the user to add and remove dependent variables, and to change the independent variable. To add a dependent variable, select it from the adjacent combo box and click the **Add** button. To remove a dependent variable, select it from the adjacent combo box and click the **Remove** button. To change the independent variable, select it from the adjacent combo box.
##### Right-Click Menu
#### Right-Click Menu
Right-clicking the plot area will display a context menu with the following options:
@ -257,7 +257,7 @@ Right-clicking the plot area will display a context menu with the following opti
- **Auto Range**
Automatically adjusts one or both axes.
##### Chart Properties Dialog
#### Chart Properties Dialog
The Chart Properties dialog can be opened by selecting **Properties** from the plot's right-click menu. It allows the user to customize the appearance of the chart. These settings are part of the properties that are saved in TV files.
![ChartPropertiesTitleTab](images/ChartPropertiesTitleTab.jpg)
@ -276,7 +276,7 @@ The **Appearance** tab within the **Plot** tab allows the user to set the plot's
The **Other** tab allows the user to set the background color of the area surrounding the plot (outside of the plot's borders) and also provides for toggling of the anti-aliasing feature. Modifying series properties is not currently supported.
#### TV Files
### TV Files
TV files allow the user to store the states of the variable table and any existing strip charts to persistent memory. This saves configuration time for commonly used variable lists and strip chart selections.

6
docs/documentation/simulation_capabilities/Command-Line-Arguments.md
View File

@ -6,7 +6,7 @@ The Trick::CommandLineArguments class stores the command line arguments specifie
by the user when starting the simulation. The class provides routines to
access the arguments.
### Accessing the Command Line Arguments
## Accessing the Command Line Arguments
The command line arguments are available to user classes through the following two calls.
@ -24,7 +24,7 @@ const char * command_line_args_get_default_dir() ;
const char * command_line_args_get_cmdline_name() ;
```
### Modifying the Output Directory
## Modifying the Output Directory
By default the RUN directory of the input file is the output directory. To change this
specify the <tt>-O</tt> or the <tt>-OO</tt> command line arguments.
@ -35,7 +35,7 @@ S_main_${TRICK_HOST_CPU}.exe RUN_dir/input.py -O <output_dir>
All Trick core output files will be written to the specified <output_dir>.
### TimeStamping the Output Directory
## TimeStamping the Output Directory
The user may also specify a time stamped output directory in the input file.

46
docs/documentation/simulation_capabilities/Data-Record.md
View File

@ -7,7 +7,7 @@ at different frequencies to different files in different formats.
All data is written to the simulation output directory.
### Format of Recording Groups
## Format of Recording Groups
Trick allows recording in three different formats. Each recording group is readable by
different external tools outside of Trick.
@ -23,7 +23,7 @@ your executable larger, but you will not have to deal with LD_LIBRARY issues. T
anywhere on your system. To tell Trick you have HDF5 run ${TRICK_HOME}/configure --with-hdf5=/path/to/hdf5.
Re-compile Trick to enable HDF5 support.
### Creating a New Recording Group
## Creating a New Recording Group
To create a new recording group, in the Python input file instantiate a new group by format name:
<tt><variable_name> = trick.<data_record_format>() ;</tt>
@ -36,7 +36,7 @@ drg = trick.DRBinary() ;
Note: drg is just an example name. Any name may be used.
### Adding a Variable To Be Recorded
## Adding a Variable To Be Recorded
To add variables to the recording group call the <tt>drg.add_variable("<string_of_variable_name>")</tt> method of the recording group.
For example:
@ -58,7 +58,7 @@ drg.add_variable("ball.obj.state.output.position[1]", "y_pos")
Only individual primitive types can be recorded. Arrays, strings/char *, structured objects, or STL types are not supported.
### Changing the Recording Rate
## Changing the Recording Rate
To change the recording rate call the <tt>set_cycle()</tt> method of the recording group.
@ -66,7 +66,7 @@ To change the recording rate call the <tt>set_cycle()</tt> method of the recordi
drg.set_cycle(0.01)
```
### Buffering Techniques
## Buffering Techniques
Data recording groups have three buffering options:
@ -92,7 +92,7 @@ drg.set_buffer_type(trick.DR_Buffer)
All buffering options (except for DR_No_Buffer) have a maximum amount of memory allocated to
holding data. See Trick::DataRecordGroup::set_max_buffer_size for buffer size information.
### Recording Frequency: Always or Only When Data Changes
## Recording Frequency: Always or Only When Data Changes
Data recording groups have three recording frequency options:
@ -119,7 +119,7 @@ then <tt>ball.obj.state.output.position[0]</tt> and <tt>ball.obj.state.output.po
<tt>ball.obj.state.output.velocity[0]</tt> changes. Multiple parameters may be watched by adding more change variables, in which case
data will be recorded when any of the watched variable values change.
### Turn Off/On and Record Individual Recording Groups
## Turn Off/On and Record Individual Recording Groups
At any time during the simulation, model code or the input processor can turn on/off individual
recording groups as well as record a single point of data.
@ -140,7 +140,7 @@ trick.dr_disable_group("<group_name>") ; # same as <group_name>.disable()
trick.dr_record_now_group("<group_name>") ;
```
### Changing the thread Data Recording runs on.
## Changing the thread Data Recording runs on.
To change the thread that the data recording group runs on use the DataRecordGroup::set_thread
method. The thread number follows the same numbering as the child threads in the S_define file.
@ -153,7 +153,7 @@ record a time homogeneous set of data.
drg.set_thread(<thread_number>)
```
### Changing the Job Class of a Data Record Group
## Changing the Job Class of a Data Record Group
The default job class of a data record group is "data_record". This job class is run after all
of the cyclic job classes have completed. The job class of the data record group can be
@ -165,7 +165,7 @@ drg.set_job_class(<string class_name>)
```
### Changing the Max File Size of a Data Record Group (Ascii and Binary only)
## Changing the Max File Size of a Data Record Group (Ascii and Binary only)
The default size of a data record is 1 GiB. A new size can be set through the set_max_file_size method. For unlimited size, pass 0.
@ -173,7 +173,7 @@ The default size of a data record is 1 GiB. A new size can be set through the se
drg.set_max_file_size(<uint64 file_size_in_bytes>)
```
### Example Data Recording Group
## Example Data Recording Group
This is an example of a data recording group in the input file
@ -194,7 +194,7 @@ trick.add_data_record_group(drg0, trick.DR_Buffer)
drg0.thisown = 0
```
### User accessible routines
## User accessible routines
Create a new data recording group:
@ -241,7 +241,7 @@ int Trick::DRAscii::set_delimiter
int Trick::DataRecordGroup::set_single_prec_only
```
### DRAscii Recording Format
## DRAscii Recording Format
The DRAscii recording format is a comma separated value file named log_<group_name>.csv. The contents
of this file type are readable by the Trick Data Products packages, ascii editors, and Microsoft Excel.
@ -256,14 +256,14 @@ value1,value2,etc...
value1,value2,etc...
```
### DRBinary Recording Format
## DRBinary Recording Format
The DRBinary recording format is a Trick simulation specific format. Files written in this format are named
log_<group_name>.trk. The contents of this file type are readable by the Trick Data Products packages from
Trick 07 to the current version. The format of the file follows.
<a id=drbinary-file></a>
### DRBinary-File
## DRBinary-File
|Value|Description|Type|#Bytes|
|---|---|---|---|
|Trick-\<vv>-\<e>| \<vv> is trick version (2 chars, "07" or "10"). \<e> is endianness (1 char) 'L' -> little endian, and 'B' -> big endian.|char|10|
@ -274,7 +274,7 @@ Trick 07 to the current version. The format of the file follows.
<a id=variable-descriptor-list></a>
#### Variable-Descriptor-List
### Variable-Descriptor-List
A Variable-Descriptor-List is a sequence of [Variable-Descriptors](#variable-descriptor).
The number of descriptors in the list is specified by *numparms*. The list describes each of the recorded variables, starting with the simulation time variable.
@ -285,7 +285,7 @@ The number of descriptors in the list is specified by *numparms*. The list descr
|| Descriptor for Variable # *numparms* |[Variable-Descriptor](#variable-descriptor)|variable|
<a id=variable-descriptor></a>
#### Variable-Descriptor
### Variable-Descriptor
A Variable-Descriptor describes a recorded variable.
|Value|Description|Type|Bytes|
@ -304,7 +304,7 @@ A Variable-Descriptor describes a recorded variable.
3. If *vv* = "10", use [Trick 10 Data Types](#trick-10-data-types).
<a id=time-variable-descriptor></a>
#### *Time-Variable-Descriptor*
### *Time-Variable-Descriptor*
|Value|Description|Type|Bytes|
|---|---|---|---|
|17| Length of Variable Name |int|4|
@ -319,7 +319,7 @@ A Variable-Descriptor describes a recorded variable.
1. Here, we are assuming "vv" = "10", and so, referring to [Trick 10 Data Types](#trick-10-data-types), Variable Type = 11, which corresponds to **double**.
<a id=data-record-list></a>
#### Data-Record-List
### Data-Record-List
A Data-Record-List contains a collection of [Data-Records](#data-record), at regular times.
|Value|Description|Type|Bytes|
@ -329,7 +329,7 @@ A Data-Record-List contains a collection of [Data-Records](#data-record), at reg
||Data-Record #Last|[Data-Record](#data-record)||
<a id=data-record></a>
#### Data-Record
### Data-Record
A Data-Record contains a collection of values for each of the variables we are recording, at a specific time.
|Value|Description|Type|Bytes|
@ -339,7 +339,7 @@ A Data-Record contains a collection of values for each of the variables we are r
|*value*|Value of Variable #numparms |*typeof( Variable#numparms)*|*sizeof( type-of( Variable#numparms))* |
<a id=trick-07-data-types></a>
### Trick 7 Data Types
## Trick 7 Data Types
The following data-types were used in Trick-07 data recording files (that is for, *vv* = "07").
|Type value|Data Type|
@ -362,7 +362,7 @@ The following data-types were used in Trick-07 data recording files (that is for
|17|Boolean (C++)|
<a id=trick-10-data-types></a>
### Trick 10 Data Types
## Trick 10 Data Types
The following data-types are used in Trick versions >= 10, that is for, *vv* = "10".
|Type value|Data Type|
@ -382,7 +382,7 @@ The following data-types are used in Trick versions >= 10, that is for, *vv* = "
|14|long long|
|15|unsigned long long|
|17|Boolean (C++)``|
### DRHDF5 Recording Format
## DRHDF5 Recording Format
HDF5 recording format is an industry conforming HDF5 formatted file. Files written in this format are named
log_<group_name>.h5. The contents of this file type are readable by the Trick Data Products packages from

2
docs/documentation/simulation_capabilities/Echo-Jobs.md
View File

@ -16,7 +16,7 @@ All jobs (user jobs and Trick jobs) of the following job class will be echoed:
Echo Jobs uses Trick's messaging system to publish each sim time / job name message,
which means it will be sent to any enabled message subscribers (see @ref StatusMessageSystem "Status Message System").
### User accessible routines
## User accessible routines
```
int echo_jobs_on() ;

4
docs/documentation/simulation_capabilities/Event-Manager.md
View File

@ -4,7 +4,7 @@
This page describes the methods available in the Trick::EventManager and Trick::EventProcessor class.
See [Input_File](/trick/documentation/running_a_simulation/Input-File) for detailed information on the syntax of the input processor file.
### User accessible routines
## User accessible routines
These commands are for adding and removing events from the Event Manager
@ -16,7 +16,7 @@ int add_event_before( Trick::Event * in_event, std::string target_name, unsigned
int remove_event( Trick::Event * in_event )
```
### Event Processing Flow
## Event Processing Flow
The next set of flowcharts details how the %Trick Event Processor processes events.

106
docs/documentation/simulation_capabilities/Executive-Scheduler.md
View File

@ -7,7 +7,7 @@ The scheduler is in charge of simulation execution. The scheduler maintains sim
The scheduler is implemented by the Trick::Executive class.
### Executive Flow
## Executive Flow
The next set of flowcharts details how the Trick main executable runs.
@ -51,11 +51,11 @@ Execution is diverted to the Freeze loop when the Freeze command is set in the S
The shutdown phase calls the shutdown phase jobs and exits. Easy peasy.
### Executive Time
## Executive Time
Accessing the simulation time is one of the more common user interactions with the executive. The executive keeps track of only simulation time. The executive does not keep track of realtime. That is the job of Trick::RealtimeSync. The executive also does not keep track of other times including mission elapsed time, universal time, or other model generated time.
#### Reading the Time
### Reading the Time
The executive provides 2 calls to get the simulation time.
@ -68,7 +68,7 @@ exec_get_sim_time() is a returns a double representing simulation elapsed second
exec_get_time_tics() returns the number of elapsed time tics. The time tic is explained below.
#### Setting the Time
### Setting the Time
Trick provides 2 calls to set the simulation time.
@ -81,7 +81,7 @@ exec_set_time() sets the current simulation time to the incoming value. This sh
exec_set_time_tics() sets the simulation time based on time tics. The time tic is explained below.
#### Time tic
### Time tic
```c
int exec_get_time_tic_value( void ) ;
@ -94,7 +94,7 @@ Example 1: A job is set to run at 128Hz or at 0.0078125 seconds. This is conve
Example 2: Job 1 is set to run at 300Hz, 0.003333 seconds. This is converted to 3333 tics and will not run at exactly 300Hz using the default 1us time tic. Job 2 is set to run at 100Hz. To run both jobs at their correct rates, we call exec_set_time_tic_value(3000000). Job 1 will run every 10000 tics. Job 2 will run every 30000 tics.
### Software Frame
## Software Frame
The software frame sets the cycle rates of the top_of_frame and end_of_frame class jobs. Jobs run at the software frame are used to synchronize to real-time, synchronize multiple simulations together, and inject variables values. The scheduled loop and the freeze loop have separate software frame values. They are read and written with the following commands.
@ -112,20 +112,20 @@ exec_set_software_frame(double) and exec_set_freeze_frame(double) both take fram
exec_get_software_frame() and exec_get_freeze_frame() return the frame values in seconds.
exec_get_software_frame_tics() and exec_get_freeze_frame_tics() return the frame values in number of tics.
### User Mode Control
## User Mode Control
Users may toggle the Executive mode between Freeze and Run as well as command simulation Shutdown.
#### Getting the current mode
### Getting the current mode
```
```python
# Python code
SIM_MODE trick.exec_get_mode()
```
exec_get_mode returns the current mode of the simulation. See the SIM_MODE definition for the enumeration values.
#### Commanding to Freeze
### Commanding to Freeze
```c
// C/C++ code
@ -133,7 +133,7 @@ exec_get_mode returns the current mode of the simulation. See the SIM_MODE defi
exec_freeze()
```
```
```python
# Python code
trick.freeze()
trick.freeze(<double freeze_time>)
@ -141,21 +141,21 @@ trick.freeze(<double freeze_time>)
Users may command freeze in model code by calling exec_freeze(). Inside the input file users may call freeze with an optional time argument. Calling trick.freeze() without an argument will freeze the simulation when all jobs at the current time step are complete. Using a freeze_time argument will freeze the simulation in the future. The freeze_time argument must be greater than the current time. The freeze_time argument is elapsed simulation seconds.
```
```python
# Python code
trick.exec_set_freeze_command(int on_off)
```
Calling exec_set_freeze_command() with a non-zero argument will start the simulation in freeze. This is here to replicate a call from previous versions of Trick. A call to trick.freeze() in the input file will accomplish the same result. A call to trick.freeze(0.0) will not work. This is because freeze times must be greater than the current sim time.
```
```python
# Python code
trick.exec_set_freeze_on_frame_boundary(int on_off)
```
Calling exec_set_freeze_on_frame_boundary() with a non-zero argument will force all freezes to synchronize with the software frame. Freeze commands received in the middle of the frame will be saved and executed at the next available frame boundary.
```
```python
# Python code
trick.exec_set_enable_freeze( int on_off )
int trick.exec_get_enable_freeze() ;
@ -163,17 +163,17 @@ int trick.exec_get_enable_freeze() ;
Calling exec_set_enable_freeze() with a non-zero argument will enable the CTRL-C keyboard interrupt signal to freeze/unfreeze the simulation. The default is off. When enable_freeze is off, a CTRL-C keystroke will terminate the simulation.
#### Commanding to Run
### Commanding to Run
```
```python
exec_run()
```
exec_run() is called when the Run button on an attached sim_control panel is pressed. It is rare that a user job calls exec_run.
#### Commanding to Shutdown
### Commanding to Shutdown
```
```python
# Python code
trick.exec_set_terminate_time(double time_value)
double trick.exec_get_terminate_time() ;
@ -188,13 +188,13 @@ exec_terminate_with_return(int ret_code, const char *file_name, int line, const
Users may terminate simulation execution at any time by calling one of the exec_terminate varieties. Both versions set the the Executive mode to shutdown. The exec_terminate routine The exec_terminate_with_return allows users to set the simulation exit code as well as include a line number in the error message.
### Job Control
## Job Control
The executive provides routines to control job execution.
#### Turning Jobs On/Off
### Turning Jobs On/Off
```
```python
# Python code
trick.exec_set_job_onoff(char * job_name , int instance_num , int on) ;
```
@ -203,7 +203,7 @@ The exec_set_job_onoff() routine allows users to turn individual jobs on and off
If there is a job tag specified for one of more jobs in the S_define file, you can turn all jobs with that tag on/off by specifying the tag as the job_name argument.
```
```python
# Python code
trick.exec_set_sim_object_onoff(char * sim_object_name , int on) ;
```
@ -226,9 +226,9 @@ trick.exec_set_sim_object_jobs_onoff(char * sim_object_name , int on) ;
The exec_set_sim_object_jobs_onoff allows users to turn all of the jobs in a sim_object on or off, but does not change the overall sim object's disabled status.
#### Job Cycle Time
### Job Cycle Time
```
```python
# Python code
trick.exec_set_job_cycle(char * job_name, int instance_num, double in_cycle)
double trick.exec_get_job_cycle(char * job_name)
@ -238,28 +238,28 @@ Each job cycle time is available to read and to set. Some job classes ignore cy
If there is a job tag specified for one of more jobs in the S_define file, you can set the cycle for all jobs with that tag by specifying the tag as the job_name argument.
### Thread Control
## Thread Control
Jobs may be assigned to specific threads. See the Simulation Definition File -> Child Thread Specification section for information about assigning jobs to threads.
Trick provides 3 types of threads. Each thread type synchronizes to the main threads differently. Setting the thread process type determines how the executive synchronizes child threads to run.
```
```python
# Python code
trick.exec_set_thread_process_type( unsigned int thread_id , int process_type )
```
Sets the synchronization type of a child thread. There are three synchronization types, PROCESS_TYPE_SCHEDULED, PROCESS_TYPE_ASYNC_CHILD, and PROCESS_TYPE_AMF_CHILD. See the Trick::ProcessType.
#### PROCESS_TYPE_SCHEDULED Threads
### PROCESS_TYPE_SCHEDULED Threads
Jobs in scheduled threads run in step with the main thread. The main thread will wait for jobs in scheduled threads to finish before advancing to the simulation time step. Scheduled thread simulation time always matches the main thread.
#### PROCESS_TYPE_ASYNC_CHILD Threads
### PROCESS_TYPE_ASYNC_CHILD Threads
Asynchronous threads have 2 modes of operation depending on if a synchronization time is specified. A cycle synchronization time is set through the exec_set_thread_async_cycle_time call.
```
```python
# Python code
trick.exec_set_thread_async_cycle_time( unsigned int thread_id , double cycle_time ) ;
```
@ -268,22 +268,22 @@ If the synchronization cycle time is set to zero, then the asynchronous threads
If the synchronization cycle time is non zero, then the asynchronous thread attempts to synchronize to the main thread. At the end of the synchronization cycle if the asynchronous thread has completed, then it will be triggered to run its next frame of jobs. If the asynchronous thread has not completed, then it will not be triggered to run the next frame of jobs. This condition is not considered an overrun and is not logged as one. The non completed thread will be checked at the next synchronization cycle time for completion. Between synchronization times, async threads maintain their own simulation time. The simulation time on the thread may not match the main thread.
#### PROCESS_TYPE_AMF_CHILD Threads
### PROCESS_TYPE_AMF_CHILD Threads
AMF stands for Asynchronous Must Finish. Threads of this type synchronize to the main thread at regular intervals set by exec_set_thread_amf_cycle_time(). Between synchronizations, AMF threads maintain their own simulation time. Jobs in AMF threads are run as fast as possible. The AMF thread simulation time may not match the main thread
When using an AMF thread the executive needs to know how often to synchronize with the child thread.
```
```python
# Python code
trick.exec_set_thread_amf_cycle_time( unsigned int thread_id , double cycle_time ) ;
```
exec_set_thread_amf_cycle_time sets the synchronization cycle rate with the main thread.
#### Main Thread CPU release.
### Main Thread CPU release.
```
```python
# Python code
trick.exec_set_rt_nap(int on_off)
trick.exec_get_rt_nap()
@ -291,18 +291,18 @@ trick.exec_get_rt_nap()
While the main thread is waiting for child threads to finish execution, it furiously spins waiting for them to finish. Calling exec_set_rt_nap() with a non-zero argument will tell the main thread to momentarily give up the CPU if it needs to wait for child threads to finish.
#### Asynchronous Threads at Shutdown
### Asynchronous Threads at Shutdown
```
```python
# Python code
trick.exec_set_thread_async_wait( unsigned int thread_id , int yes_no ) ;
```
By default the executive does not wait for asynchronous or AMF threads during shutdown. Calling exec_set_thread_async_wait() will tell the executive to wait for a thread before calling shutdown routines and exiting.
#### Thread Priorities
### Thread Priorities
```
```python
# Python code
trick.exec_set_thread_priority(unsigned int thread_id , unsigned int req_priority)
```
@ -311,25 +311,25 @@ exec_set_thread_priority() will set the thread's priority. The main thread is t
Setting a simulation to run as priority 1 may lock out keyboard and mouse processing.
```
```python
# Python code
trick.exec_set_thread_cpu_affinity(unsigned int thread_id , int cpu_num) ;
```
exec_set_thread_cpu_affinity assigns a thread to a specific CPU. If called multiple times, you can add multiple CPUs to a thread and the OS scheduler will choose one of those CPUs for the thread. The main thread is thread_id=0. 1-n are the child threads. Setting a thread to run on a CPU does not exclude other processes to continue to run on the same CPU.
#### Thread Priorities
### Thread Priorities
```
```python
# Python code
trick.exec_set_lock_memory(int yes_no) ;
```
Lock all of the process memory for best real-time performance. This prevents process memory to be swapped out to virtual memory on disk. This option may move to the Trick::RealtimeSync class in the future.
#### Thread Job Dependencies
### Thread Job Dependencies
```
```python
# Python code
trick.exec_add_depends_on_job(char * target_job_string , unsigned int t_instance ,
char * depend_job_string , unsigned int d_instance )
@ -337,7 +337,7 @@ trick.exec_add_depends_on_job(char * target_job_string , unsigned int t_instance
Jobs in different threads may need other jobs in other threads to run first before executing. Trick provides a depends_on feature. Jobs that depend on other jobs will not execute until all dependencies have finished. The instance value in the above call to take care of the case where the same job name is called multiple times in a sim_object. Instance values start at 1.
#### Getting Thread ID
### Getting Thread ID
```c
unsigned int exec_get_process_id() ;
@ -348,13 +348,13 @@ exec_get_process_id() will return the current thread the caller is on. 0 = main
exec_get_num_threads() returns the number of child threads spawned by the main thread.
### Debugging Help
## Debugging Help
The Executive provides several parameters that can help a model developer debug a simulation.
#### Trapping signals
### Trapping signals
```
```python
# Python code
trick.exec_set_trap_sigbus(int on_off)
trick.exec_set_trap_sigfpe(int on_off)
@ -368,18 +368,18 @@ trick.exec_get_trap_sigchld()
The set_trap routines listed above set a signal handler for the SIGBUS, SIGFPE, SIGSEGV, and SIGCHLD signals respectively. The get_trap routines return the on/off status of the trap. Trapping the signals allows the Trick to gracefully shutdown the simulation and to possibly write important information about the signal before exiting execution. Turning off the traps will revert signal handling to the default system signal handler. By default the traps for SIGBUS, SIGSEGV, and SIGCHLD are true. SIGFPE is not trapped by default.
#### Printing a Stack (Call) Trace on Signal
### Printing a Stack (Call) Trace on Signal
```
```python
# Python code
trick.exec_set_stack_trace(int on_off)
```
This is a Linux only option. By default, printing a stack trace when a signal is trapped is enabled. When a signal is trapped a debugger is automatically connected to the running simulation and a printout of the calling stack is printed before the simulation exits.
#### Attaching a debugger on Signal
### Attaching a debugger on Signal
```
```python
# Python code
trick.exec_set_attach_debugger(int on_off)
```
@ -388,15 +388,15 @@ This is a Linux only option. By default, this option is off. If enabled, when
The debugger executable may be set with the following. The default is "/usr/bin/gdb".
```
```python
# Python code
trick.exec_set_debugger_command(char * command)
char * trick.exec_get_debugger_command()
```
#### Getting Build Information
### Getting Build Information
```
```python
# Python code
char * trick.exec_get_current_version()
```

2
docs/documentation/simulation_capabilities/Frame-Logging.md
View File

@ -22,7 +22,7 @@ trick.add_read(600.0, "trick.frame_log_off()")
trick.add_read(1500.0, "trick.frame_log_on()")
```
### User accessible routines
## User accessible routines
```
int frame_log_on() ;

2
docs/documentation/simulation_capabilities/Input-Processor.md
View File

@ -4,7 +4,7 @@
This page describes the methods available in the Trick::InputProcessor class.
<b>See [Input File](../running_a_simulation/Input-File) for detailed information on the syntax of the input processor file.
### User accessible routines
## User accessible routines
```
int shutdown()

2
docs/documentation/simulation_capabilities/Integrator.md
View File

@ -87,7 +87,7 @@ If a developer wishes to use their own integration scheme, then the <i> integrat
should be reviewed so that the proper interfaces can be maintained. The <i> integrate() </i> source code is
located in the ${TRICK_HOME}/trick_source/sim_services/integ/integrate.c file.
### Integrator Control Inputs
## Integrator Control Inputs
There can be any number of <i> integration </i> class jobs listed within the S_define file;
each integration job should have an associated <i> IntegLoop </i> declaration.

10
docs/documentation/simulation_capabilities/Master-Slave.md
View File

@ -19,7 +19,7 @@ case you must provide your own class derived from MSConnect.
Master/Slave synchronization is an optional class and need not be specified in
the S_define file when building a normal (non-Master/Slave) simulation.
### User accessible routines
## User accessible routines
The following routine is used to create a socket connection for either Master or Slave:
@ -60,12 +60,12 @@ int Trick::Slave::set_connection_type(Trick::MSConnect * in_connection) ;
Trick::Slave::sync_error_terminate
```
### Input File Setup
## Input File Setup
The way to set up Master/Slave synchronization is to use the above routines and attributes
in a Python input file. Here is an example of how to set up a Master and a Slave in their respective input files.
#### Master Input File Example
### Master Input File Example
```
new_connection = trick.MSSocket()
@ -79,7 +79,7 @@ master_slave.master.add_slave(new_slave)
master_slave.master.enable()
```
#### Slave Input File Example
### Slave Input File Example
```
new_connection = trick.MSSocket()
@ -87,7 +87,7 @@ master_slave.slave.set_connection_type(new_connection)
master_slave.slave.sync_error_terminate = 1
```
#### Dumping and Loading a Checkpoint
### Dumping and Loading a Checkpoint
By default, the Master will command the Slave to dump or load a checkpoint when the Master dumps or loads a checkpoint.
The Master will send its checkpoint file name to the Slave, and the Slave will use that file name for its checkpoint (in

8
docs/documentation/simulation_capabilities/Realtime-Injector.md
View File

@ -5,7 +5,7 @@ The Real Time Injector (RTI) allows the user to set simulation variables
synchronously without impacting real-time performance. The RTI performs the injection
as a top of frame job ensuring thread-safe variable operations.
### Adding and Injecting Variables
## Adding and Injecting Variables
```
trick.rti_add( char * var_name , long long value)
@ -27,7 +27,7 @@ The injection occurs at the top of the next real-time frame only after the rti_f
All variable(s) added with rti_add are set according to the values in the rti_add statement(s).
The queue of pending injections is then cleared.
### Adjusting Firing Frame
## Adjusting Firing Frame
A frame multiple and offset may be set to only allow injections to occur on a frame multiple boundary
and offset.
@ -37,7 +37,7 @@ trick.rti_set_frame_multiple( unsigned int thread_id , unsigned int mult )
trick.rti_set_frame_offset( unsigned int thread_id , unsigned int offset )
```
### Listing Scheduled Injections
## Listing Scheduled Injections
```
trick.rti_list()
@ -46,7 +46,7 @@ trick.rti_list()
rti_list prints the list of pending injections to the screen.
Listing the injections is not a real-time friendly operation.
### Debugging Injections
## Debugging Injections
```
trick.rti_set_debug( True | False )

2
docs/documentation/simulation_capabilities/Realtime.md
View File

@ -74,7 +74,7 @@ an external timer instead of an itimer. To do so you must provide your specific
timer functionality by deriving from Trick's Timer class. (Trick provides the ITimer class
as a derivative of Timer). See [Realtime_Timer](Realtime-Timer).
### User accessible routines
## User accessible routines
```
int real_time_enable() ;

2
docs/documentation/simulation_capabilities/STL-capabilities.md
View File

@ -3,7 +3,7 @@
# Standard Template Libraries (STL) in Trick
STLs may be used in models. However, STL variables (currently) are not data recordable, visible in the variable server, nor directly accessible in the input file. Some STLs can be checkpointed: array, vector, list, deque, set, multiset, map, multimap, stack, queue, priority_queue, pair.
STLs may be used in models. However, STL variables (currently) are not data recordable, visible in the variable server, nor directly accessible in the input file. Some STLs can be checkpointed: `array`, `vector`, `list`, `deque`, `set`, `multiset`, `map`, `multimap`, `stack`, `queue`, `priority_queue`, `pair`.
STL classes cannot be directly registered with the memory manager, but they can be processed by the checkpoint agent when nested inside normal C++ classes (including sim objects).

6
docs/documentation/simulation_capabilities/Status-Message-System.md
View File

@ -3,7 +3,7 @@
The Message Publisher publishes executive and/or model messages. A Message Subscriber gets the messages published by the Publisher.
### Message Publisher
## Message Publisher
Trick creates one instance of the Message Publisher (in the `S_define` file). It is responsible for keeping track of all Message Subscribers,
and sending any message that is published to all of the Message Subscribers. A subscriber is made known to the Message Publisher by calling its
@ -11,7 +11,7 @@ and sending any message that is published to all of the Message Subscribers. A s
Publishing a message that you want to be output by all subscribers is done by calling `::message_publish`.
If there are no subscribers, then publishing a message has no effect.
### Message Subscriber
## Message Subscriber
There can be any number of Message Subscribers, whose job is to receive (and usually output) published messages. Trick automatically creates three Message Subscribers:
- `Trick::MessageCout` - outputs messages to the standard output stream
@ -33,7 +33,7 @@ trick_message.mtcout.init()
trick.message_subscribe(trick_message.mtcout)
```
### User accessible routines
## User accessible routines
To publish a message:

70
docs/documentation/simulation_capabilities/Variable-Server.md
View File

@ -16,7 +16,7 @@ do so through the variable server. The external application need not be on the s
machine since the connection to the variable server is via a Trick communication
TCP/IP socket.
### User accessible routines
## User accessible routines
These commands are for enabling/disabling the variable server, and for getting its status.
The variable server is enabled by default.
@ -47,7 +47,7 @@ int set_var_server_log_off();
int set_var_server_log_on();
```
#### Getting and Setting the Variable Server Port Information
### Getting and Setting the Variable Server Port Information
To set the variable server port to a fixed number in the input file use var_server_set_port()
@ -73,7 +73,7 @@ trick.var_server_create_tcp_socket( const char * source_address, unsigned short
```
### Commands
## Commands
The variable server accepts commands in the form of strings. The variable server parses
these commands using the Python input processor. So in theory, any Python valid syntax
@ -85,7 +85,7 @@ over the socket. The variable server will send back information to the requestin
If the command contains a syntax error, Python will print an error message to the screen,
but nothing will be returned to the client.
#### Adding a Variable
### Adding a Variable
```python
trick.var_add( string var_name )
@ -107,9 +107,9 @@ Simulation time as a decimal number in "seconds" is available through a special
trick.var_add("time")
```
#### Time Homogeneous or Synchronous Data
### Time Homogeneous or Synchronous Data
##### Copying Data Out of Simulation.
#### Copying Data Out of Simulation.
```python
trick.var_set_copy_mode(int mode)
@ -118,14 +118,14 @@ trick.var_set_copy_mode(int mode)
There are 3 options to when the variable server will copy data out from the simulation.
Each option has unique capabilites.
###### Asynchronous Copy (mode = trick.VS_COPY_ASYNC or 0)
##### Asynchronous Copy (mode = trick.VS_COPY_ASYNC or 0)
This is the default. Values are copied out of the sim asynchronously. Copies are done
approximately at the var_cycle() rate during run and freeze mode. A separate thread
is used to copy the data. The data is not guaranteed to be time homogenous. This mode
does not affect the main thread real-time performance.
###### End of Main Thread Execution Copy (mode = trick.VS_COPY_SCHEDULED or 1)
##### End of Main Thread Execution Copy (mode = trick.VS_COPY_SCHEDULED or 1)
This mode copies data at the end of execution frame. Copies are done exactly at the
var_cycle() rate after the main thread has finished all of it's jobs scheduled to run
@ -134,7 +134,7 @@ main thread are guaranteed to be time homogenous. Variables calculated in child
threads are not guaranteed to be time homogenous. Copying data may very slightly
affect the main thread real-time performance.
###### Top of Frame Copy (mode = trick.VS_COPY_TOP_OF_FRAME or 2)
##### Top of Frame Copy (mode = trick.VS_COPY_TOP_OF_FRAME or 2)
This mode copies data at the top of frame. Copies are done at a multiple and offset of
the Executive software frame. During freeze mode copies are made at a multiple and offset
@ -154,7 +154,7 @@ trick.var_set_freeze_frame_multiple(int mult)
trick.var_set_freeze_frame_offset(int offset)
```
##### Writing Data Out of Simulation.
#### Writing Data Out of Simulation.
```python
trick.var_set_write_mode(int mode)
@ -162,19 +162,19 @@ trick.var_set_write_mode(int mode)
There are 2 options when the variable server writes the data.
###### Asynchronous Write ( mode = trick.VS_WRITE_ASYNC or 0 )
##### Asynchronous Write ( mode = trick.VS_WRITE_ASYNC or 0 )
This is the default. Values are written onto the socket asynchronously. Writes are done
approximately at the var_cycle() rate during run and freeze mode. A separate thread
is used to copy write data. This mode does not affect the main thread real-time performance.
###### Write When Copied ( mode = trick.VS_WRITE_WHEN_COPIED or 1 )
##### Write When Copied ( mode = trick.VS_WRITE_WHEN_COPIED or 1 )
Values are written onto the socket as soon as they are copied from the simulation. The
write rate depends on the copy. Writes are done in the main thread of execution. This
can greatly affect real-tim performance if a large amount of data is requested.
##### Old Style var_sync() Command
#### Old Style var_sync() Command
```python
trick.var_sync(bool mode)
@ -190,7 +190,7 @@ trick.var_sync(1) # end of main thread copy and asynchronous write.
trick.var_sync(2) # end of main thread copy and write when copied.
```
#### Sending the Return Values Immediately
### Sending the Return Values Immediately
```python
trick.var_send()
@ -199,7 +199,7 @@ trick.var_send()
The var_send command forces the variable server to return the list of values to the
client immediately.
#### Sending variables only once and immediately
### Sending variables only once and immediately
```python
trick.var_send_once( string var_name)
@ -215,7 +215,7 @@ trick.var_send_once( string var_list, int num_vars)
var_send_once can also accept a comma separated list of variables. The number of variables
in this list must match num_vars, or it will not be processed.
#### Changing the Units
### Changing the Units
```python
trick.var_units( string var_name , string units )
@ -225,7 +225,7 @@ The returned values can be converted to other units of measurments. The var_unit
tells the variable server what units to use. If the units are changed, then the units
are included in the returned string to the client.
#### Removing a Variable
### Removing a Variable
```python
trick.var_remove( string var_name )
@ -233,7 +233,7 @@ trick.var_remove( string var_name )
Removing a variable removes the variable from the list returned to the client.
#### Clearing the List of Variables
### Clearing the List of Variables
```python
trick.var_clear()
@ -241,7 +241,7 @@ trick.var_clear()
To clear the whole list of variables sent to the client.
#### Exiting the Variable Server
### Exiting the Variable Server
```python
trick.var_exit()
@ -249,7 +249,7 @@ trick.var_exit()
Disconnects the current client from the variable server.
#### Checking for existence of a variable
### Checking for existence of a variable
```python
trick.var_exists( string var_name )
@ -264,7 +264,7 @@ followed by a (1 byte) value of 0 or 1 to indicate the existence of the variable
In **var_ascii** mode: the message indicator of the response will be "1" followed
by a tab, then an ASCII "0" or "1" to indicate the existence of the variable.
#### Changing the Return Value Cycle Rate
### Changing the Return Value Cycle Rate
```python
trick.var_cycle( double cycle_rate )
@ -273,7 +273,7 @@ trick.var_cycle( double cycle_rate )
Changes the rate of the return messages to the client. This rate is estimated and may not
perfectly match the requested rate.
#### Pause the Variable Server
### Pause the Variable Server
```python
trick.var_pause()
@ -282,7 +282,7 @@ trick.var_pause()
Pauses the return values sent to the client. Even when paused, the variable server will
accept new commands.
#### Unpause the Variable Server
### Unpause the Variable Server
```python
trick.var_unpause()
@ -290,7 +290,7 @@ trick.var_unpause()
Resumes sending the return values to the client.
#### Setting Ascii Return Format
### Setting Ascii Return Format
```python
trick.var_ascii()
@ -298,7 +298,7 @@ trick.var_ascii()
Sets the return message format to ASCII. See below for the format of the message.
#### Setting Binary Return Format
### Setting Binary Return Format
```python
trick.var_binary()
@ -313,7 +313,7 @@ trick.var_binary_nonames()
This variation of the binary format reduces the amount of data that is sent to the client.
See below for the exact format.
#### Sending stdout and stderr to client
### Sending stdout and stderr to client
```python
trick.var_set_send_stdio(bool on_off)
@ -345,7 +345,7 @@ print "trick.exec_get_current_version()"
<- a single newline is the second message
```
#### Debugging Variable Server Messages
### Debugging Variable Server Messages
```python
trick.var_debug(int level)
@ -354,7 +354,7 @@ trick.var_debug(int level)
The level may range from 0-3. The larger the number the more debugging information is printed to
the screen (for the current client only).
#### Logging Messages to file.
### Logging Messages to file.
These commands are for toggling information messages from the variable server (for this client only).
The messages only go to a dedicated "varserver_log" file in the RUN directory.
@ -368,7 +368,7 @@ trick.var_server_log_on()
trick.var_server_log_off()
```
#### Setting Variable Server Client Tag
### Setting Variable Server Client Tag
```python
trick.var_set_client_tag(string name)
@ -381,13 +381,13 @@ displayed. Information messages are displayed as a result of
@c var_debug(). For instance, Trick sets a name tag for each of its variable server clients (simulation control panel is "SimControl",
TV is "TRICK_TV", etc.).
#### Byteswapping
### Byteswapping
```python
trick.var_byteswap(bool on_off)
```
### Returned Values
## Returned Values
By default the values retrieved are sent asynchronously to the client. That is, the values
retrieved by the variable server are pulled directly from memory asynchronously and do not
@ -396,7 +396,7 @@ command is used. Values will be returned to the client in the same order that th
issued in the var_add command(s). Typically the client receives the data from the variable
server in a buffer via the tc_read command (see TrickComm for more information).
### Ascii Format
## Ascii Format
The default format, or if var_ascii is commanded specifically, causes the variable server
to return a buffer containing a tab delimited character string in the following format:
@ -446,7 +446,7 @@ If a var_add command was issued for a non-existent variable, there will be a one
message printed to the screen, but the resulting data sent to the client is still ok. The value
returned for the non-existent variable is the string "BAD_REF".
### Binary Format
## Binary Format
By specifying the var_binary or var_binary_nonames command, the variable server will return
values in a binary message formatted as follows:
@ -486,7 +486,7 @@ If a var_add command was issued for a non-existent variable, there will be a one
message printed to the screen, but the resulting data sent to the client is still ok. The message
returned for the non-existent variable will have a type of 24 and it's value will be the string "BAD_REF".
### Stdio Format
## Stdio Format
These messages are sent to the client if stdout and stderr are redirected. See "Sending stdout
and stderr to client" for more details.
@ -509,7 +509,7 @@ Calls to sys.stdout.write() only generate 1 message.
Error messages printed by python to stderr may be sent in multiple messages.
### Variable Server Broadcast Channel
## Variable Server Broadcast Channel
To connect to the variable server for any simulation, a client needs to know the
hostname and port. As of 10.5, the port number is determined by the OS. For external

6
docs/documentation/simulation_capabilities/memory_manager/MemoryManager-Declaration-String.md
View File

@ -2,7 +2,7 @@
|------------------------------------------------------------------|
### Memory Manager Declaration
## Memory Manager Declaration
A declaration provides a data type description of a chunk of memory.
A MemoryManager declaration consists of four parts from left to right:
@ -11,11 +11,11 @@ A MemoryManager declaration consists of four parts from left to right:
3. Zero or one (variable) names
4. Zero or more bracketed integers
#### Intrinsic Type Specifiers
### Intrinsic Type Specifiers
"char", "unsigned char", "short", "unsigned short", "int", "unsigned int", "long",
"unsigned", "float", "double", "long long", "unsigned long long", "bool", "wchar_t"
#### User Defined Type Specifiers
### User Defined Type Specifiers
```
<user-defined-type> ::= NAME

60
docs/documentation/simulation_capabilities/memory_manager/MemoryManager.md
View File

@ -25,7 +25,7 @@ This makes other services possible, such as :
- TrickView (TV) Variable Viewer
- Third-party simulation clients
### Memory Manager Interfaces
## Memory Manager Interfaces
A Trick simulation contains exactly one Memory Manager. One can access it as follows:
```
@ -37,7 +37,7 @@ From 'C' code, the Memory Manager can be accessed using a set of wrapper functio
*memorymanager_c_intf.h*
```
### Registering an Object
## Registering an Object
The Memory Manager can either register a supplied object or it can allocate an
object as described by its declaration, and then register it. Here *object* just
means a chunk of memory that one would get by calling malloc, new, or mmap.
@ -96,7 +96,7 @@ Where:
The remaining arguments are identical to those of declare_var.
### Example Allocations using C and C++ Interfaces
## Example Allocations using C and C++ Interfaces
The following two *declare_var* calls do exactly the same thing.
@ -116,7 +116,7 @@ double *D = (double*)TMM_declare_var_s("double[3]");
double *D = (double*)TMM_declare_var_1d("double",3);
```
### Allocation Examples
## Allocation Examples
Allocation of an anonymous double:
```
@ -154,7 +154,7 @@ namespace "FOO":
FOO::BAR (*A)[3][4] = (FOO::BAR(*)[3][4])TMM_declare_var_s("FOO::BAR my_array[3][4]");
```
### Checkpoints
## Checkpoints
A checkpoint is a textual representation of Trick managed memory objects at
a particular instance in time. When commanded, the MemoryManager (by way of a
@ -181,7 +181,7 @@ require one assignment for each of its non-composite data members.
- Checkpoint Directives - invoke a checkpoint specific command.
### Writing Checkpoints
## Writing Checkpoints
Checkpoint every allocation that the MemoryManager knows about to a std::stream.
```
@ -226,7 +226,7 @@ Checkpoint every allocation that the MemoryManager knows about to a file.
void TMM_write_checkpoint( const char* filename) ;
```
### Example - Checkpointing a Named, Local Allocation
## Example - Checkpointing a Named, Local Allocation
In the example below we ask the Memory Manager to allocate an array of three
doubles named *dbl_array*. **declare_var** returns a pointer to the array. Using
the pointer, we then initialize the array. Finally we checkpoint the variable to
@ -255,7 +255,7 @@ Declarations* section cause variables to be allocated just like the declare_var(
call above. The assignments in the *Variable Assignments* section restore the
values of the variables.
#### Checkpoint Content
### Checkpoint Content
```
// Variable Declarations.
double dbl_array[3];
@ -265,7 +265,7 @@ dbl_array =
{1.1, 2.2, 3.3};
```
### Example - Checkpointing an Anonymous, Local Allocation
## Example - Checkpointing an Anonymous, Local Allocation
In the following example, we are not giving a name to the variable that we are
creating.
@ -281,7 +281,7 @@ trick_MM->write_checkpoint( std::cout );
In the checkpoint below, notice that the variable is given a **temporary** name
for checkpointing.
#### Checkpoint Content
### Checkpoint Content
```
// Variable Declarations.
double trick_anon_local_0[3];
@ -291,7 +291,7 @@ trick_anon_local_0 =
{1.1, 2.2, 3.3};
```
### Example - Checkpointing a Named, External Allocation
## Example - Checkpointing a Named, External Allocation
In this example, we are allocating the memory for the variable directly rather
than asking the Memory Manager to do it.
@ -310,7 +310,7 @@ Because this object is **extern**, the MemoryManager must be able to lookup its
address by name. Therefore the simulation must ensure that the object exists and
is cataloged before attempting to reload its contents from a checkpoint.
#### Checkpoint Content
### Checkpoint Content
```
// Variable Declarations.
// extern double dbl_array[3];
@ -320,7 +320,7 @@ dbl_array =
{1.1, 2.2, 3.3};
```
### Example - Checkpointing an Anonymous, External Allocation
## Example - Checkpointing an Anonymous, External Allocation
In the following example, we are allocating the memory for the variable directly
and not giving it a name. **This is typically not a good idea**.
@ -343,7 +343,7 @@ extern object, we need to make sure that it has a name, and is cataloged.
In the checkpoint note the temporary name indciates that the variable is
allocated externally to the Memory Manager.
#### Checkpoint Content
### Checkpoint Content
```
// Variable Declarations.
@ -352,9 +352,9 @@ trick_anon_extern_0 =
{1.1, 2.2, 3.3};
```
### Example - Checkpointing a Constrained Array
## Example - Checkpointing a Constrained Array
#### Allocation of an two-dimensional constrained array of doubles:
### Allocation of an two-dimensional constrained array of doubles:
```
#include "memorymanager_c_intf.h"
@ -376,7 +376,7 @@ double (*A)[3][4] = (double(*)[3][4]) TMM_declare_var_s("double A[3][4]");
![Figure1](images/MM_figure_1.jpg)
#### Checkpoint Content
### Checkpoint Content
```
// Variable Declarations.
double A[3][4];
@ -391,9 +391,9 @@ A =
};
```
### Example - Checkpointing an Unconstrained Array
## Example - Checkpointing an Unconstrained Array
#### Allocation of an anonymous two-dimensional unconstrained array of doubles:
### Allocation of an anonymous two-dimensional unconstrained array of doubles:
```
#include "memorymanager_c_intf.h"
@ -418,7 +418,7 @@ A[2][3] = 23.0;
![Figure2](images/MM_figure_2.jpg)
#### Checkpoint Content
### Checkpoint Content
```
// Variable Declarations.
double* trick_anon_local_0[3];
@ -440,7 +440,7 @@ trick_anon_local_3 =
{20, 21, 22, 23};
```
### Example - Another Checkpoint of an Unconstrained Array
## Example - Another Checkpoint of an Unconstrained Array
Allocation of a two-dimensional unconstrained array of doubles with contiguous storage:
@ -471,7 +471,7 @@ A[2][3] = 23.0;
![Figure3](images/MM_figure_3.jpg)
#### Checkpoint Content
### Checkpoint Content
```
// Variable Declarations.
double* A[3];
@ -489,13 +489,13 @@ A_store =
};
```
### Reading and Restoring Checkpoints
## Reading and Restoring Checkpoints
Restoring a checkpoint consists of reading and executing the statements from a
checkpoint file or stream. Declaration statements cause data-typed objects to be
created and registered. Assignment statements cause values specified on the
right hand side to the variables identified on the right.
#### Checkpoint Restore Methods
### Checkpoint Restore Methods
Restore the checkpoint from the given std::stream:
```
@ -517,7 +517,7 @@ int Trick::MemoryManager::read_checkpoint_from_string(const char *s);
```
int Trick::MemoryManager::read_checkpoint_from_string(const char *s);
```
### Example: Checkpoint Restore from C++
## Example: Checkpoint Restore from C++
```
#include "MemoryManager.hh"
@ -536,16 +536,16 @@ for (int ii=0; ii < 10; ii++) {
}
std::cout << std::endl;
```
#### Output
### Output
```
1 2 3 4 5 6 7 8 9 10
```
### Checkpoint Tailoring Options
## Checkpoint Tailoring Options
Checkpoint tailoring options allow one to generate checkpoints that most suite
their needs.
#### Reduced Checkpoint
### Reduced Checkpoint
This (default) option allows the MemoryManager to generate smaller checkpoints.
It does this by adding a **clear_all_vars** directive to the checkpoint
following the variable declarations. Then assignment statements are generated
@ -565,7 +565,7 @@ Where: **flag** - **1** means no zeroes are assigned, otherwise zeroes are
assigned.
#### Hexfloat Checkpoint
### Hexfloat Checkpoint
This option causes floating point values in the checkpoint to be represented in
**Hex Float** format. This format preserves precision in floating point numbers.
The downside is that they are not very human readable. Not by normal humans
@ -586,7 +586,7 @@ void TMM_hexfloat_checkpoint(int flag);
Where:
**flag** - **1** means no zeroes are assigned, otherwise zeroes are assigned.
### Unregistering/Deleting an Object
## Unregistering/Deleting an Object
An object can be unregistered by name or by address.
```
int Trick::MemoryManager::delete_var (void *address);

2
trick_source/sim_services/Integrator/unittest/IBall.cpp
View File

@ -8,7 +8,7 @@
#include <string.h>
#define PI 3.141592653589793
#define RAD_PER_DEG (2.0*PI/180.0)
#define RAD_PER_DEG (PI/180.0)
typedef struct {
double pos[2];

2
trick_source/web/README.md
View File

@ -3,4 +3,4 @@ Trick has the capability to create a custom built web server for your sim.
You can find documentation here:
[Web Server Documentation](https://nasa.github.io/trick/documentation/simulation_capabilities/web/)
[Web Server Documentation](/docs/documentation/web/Adding_a_Web_Server_to_Your_Sim)