diff --git a/docs/documentation/building_a_simulation/Making-the-Simulation.md b/docs/documentation/building_a_simulation/Making-the-Simulation.md index 73ca61b0..e506a27e 100644 --- a/docs/documentation/building_a_simulation/Making-the-Simulation.md +++ b/docs/documentation/building_a_simulation/Making-the-Simulation.md @@ -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. diff --git a/docs/documentation/building_a_simulation/Model-Source-Code.md b/docs/documentation/building_a_simulation/Model-Source-Code.md index 15c56389..896845a0 100644 --- a/docs/documentation/building_a_simulation/Model-Source-Code.md +++ b/docs/documentation/building_a_simulation/Model-Source-Code.md @@ -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 { [ - friend InputProcessor ; - friend init_attr() ; + friend InputProcessor; + friend init_attr(); ] (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. +Listing Library Dependencies Within Model Header Files: (preferred approach)
+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:
``` 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: +Listing Library Dependencies Within Model Source Files:
+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:
``` 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: -`* ="">/.a` +`* ="">/.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. -`* .a` +`* .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. +Listing Library Dependencies Within the `S_define`:
+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() ; +friend class InputProcessor; +friend void init_attr(); ``` 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|/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= and -DTRICK_MINOR= 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= and -DTRICK_MINOR= 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) diff --git a/docs/documentation/building_a_simulation/Simulation-Definition-File.md b/docs/documentation/building_a_simulation/Simulation-Definition-File.md index d5911819..c38868d6 100644 --- a/docs/documentation/building_a_simulation/Simulation-Definition-File.md +++ b/docs/documentation/building_a_simulation/Simulation-Definition-File.md @@ -69,7 +69,7 @@ class : public Trick::SimObject { [void create_connections() { }] ``` -### 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 : 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. -##### 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. diff --git a/docs/documentation/data_products/DP-Product-File-Format.md b/docs/documentation/data_products/DP-Product-File-Format.md index fc282b78..6e9a948c 100644 --- a/docs/documentation/data_products/DP-Product-File-Format.md +++ b/docs/documentation/data_products/DP-Product-File-Format.md @@ -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 ``` @@ -110,7 +110,7 @@ text formats. The product specification file may contain any number of pages and page or table. extfn 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 page elements. Each page element must have at least one plot elment and may have more plots sepcified. All attributes of a page element as stated earlier in @ref product_dtd "Product.dtd" are: @@ -120,7 +120,7 @@ The page 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 tstart and tstop 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 var element XML specification doesn't limit a X variable having @@ -168,7 +168,7 @@ The line_color attribute of var allows the user to specify a color the gnuplot_line_sytle attribute of var 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 var or has varcase specified. The first var element is for X, the second var element is for Y and the third is for Z. A curve element can not have both var @@ -216,7 +216,7 @@ both RUN_A and RUN_B. ``` -### DP Table Specifications +## DP Table Specifications Each table is comprised of one or more columns and each column is only for one variable. Each column element has an optional format 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 extfn 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 extfn needs to have 3 element specifications associated with it. These elements are fname, inputs, and outputs. The fname 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: ``` -#### 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 .c (compile all individual object this way) - Step 2. ld -shared -o .so .o .o ... .o .a -lc -##### MacOS X +#### MacOS X - Step 1. cc -c .c (compile all individual object this way) - Step 2. cc -bundle -o .so .o .o ... .o .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 .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 ``` diff --git a/docs/documentation/data_products/DP-Session-File-Format.md b/docs/documentation/data_products/DP-Session-File-Format.md index 5b00c49e..d5584c1a 100644 --- a/docs/documentation/data_products/DP-Session-File-Format.md +++ b/docs/documentation/data_products/DP-Session-File-Format.md @@ -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 ``` @@ -97,7 +97,7 @@ The optional machine, port attributes of session specify the name number for plotting. -### DP Session File Example +## DP Session File Example ``` diff --git a/docs/documentation/data_products/Data-Products-GUIs.md b/docs/documentation/data_products/Data-Products-GUIs.md index 0154aba1..4ca11433 100644 --- a/docs/documentation/data_products/Data-Products-GUIs.md +++ b/docs/documentation/data_products/Data-Products-GUIs.md @@ -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: - UNIX Prompt> 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 - Exit - 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 - Create PDF Booklet... - 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 - About... - 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 SIM, all run directories starts with RUN or MONTE_RUN, and all data product files start with DP and are placed in DP_Product directory within a SIM 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. - Remove - 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. - Remove - 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. - Run Sim - 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 - Remove - 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 - Remove - 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 - Refresh - 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 - Edit DP... - 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. Trick DP - DP Selections ![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. - Remove All - 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. Trick DP - Message Display ![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 UNIX Prompt> trick_qp RUN & ``` -#### 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 - Exit - 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 - Change Units... - 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 - Remove Run - 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 - New Varcase - 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 - New Column - 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 - New Output... - 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) - Plot Utility - 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 - Table Error... - 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 - About... - 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. Trick QP - Vars ![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) - Add Var @@ -507,7 +507,7 @@ Right clicking on a variable from the Vars as shown above causes a corresponding - Change Units... - 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 - Remove All Pages - 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 - Remove - 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 - Remove - 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 - Remove All Tables - 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 - Remove - Removes this table. -###### DP Content Popup Menus +##### DP Content Popup Menus ![trick_qp_dpcontent_popup9](images/trick_qp_dpcontent_popup9.jpg) - Remove - 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 - Remove All Programs - 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) - Remove - Removes the program. -###### DP Content Popup Menus +##### DP Content Popup Menus ![trick_qp_dpcontent_popup13](images/trick_qp_dpcontent_popup13.jpg) - Add Var - 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) - Remove - 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 Apply Change 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. Trick QP - Message Display ![trick_qp_msg_area](images/trick_qp_msg_area.jpg) -### Viewing Data +## Viewing Data In this section, SIM_cannon_analytic 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. UNIX Prompt> 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: - UNIX Prompt> 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: - UNIX Prompt> 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. - UNIX Prompt> fxplot @@ -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: - UNIX Prompt> 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: - UNIX Prompt> 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. diff --git a/docs/documentation/miscellaneous_trick_tools/Miscellaneous-Trick-Tools.md b/docs/documentation/miscellaneous_trick_tools/Miscellaneous-Trick-Tools.md index a7156bed..abdbea84 100644 --- a/docs/documentation/miscellaneous_trick_tools/Miscellaneous-Trick-Tools.md +++ b/docs/documentation/miscellaneous_trick_tools/Miscellaneous-Trick-Tools.md @@ -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): ``` -UNIX Prompt> ICG [-d] [-D ] [-U ] .h -UNIX Prompt> ICG -u +UNIX prompt> ICG [-d] [-D ] [-U ] .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: ``` -UNIX Prompt> make_build [lib ] +UNIX prompt> make_build [lib ] ``` 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 UNIX Prompt> 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. ``` -UNIX Prompt> sie [-nocase] +UNIX prompt> sie [-nocase] ``` As an example, if you know the parameter name contains clock but don't know anything else, try: ``` -UNIX Prompt> 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. ``` -UNIX Prompt> kill_sim +UNIX prompt> kill_sim ``` -### Current Trick Version +## Current Trick Version The following command echoes the installed %Trick version release: ``` -UNIX Prompt> trick_version +UNIX prompt> trick_version ``` -### Checksumming +## Checksumming Trick comes with a file that contains checksums for the %Trick package. You may run: ``` -UNIX Prompt> 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 diff --git a/docs/documentation/running_a_simulation/Input-File.md b/docs/documentation/running_a_simulation/Input-File.md index 68cfd5b4..4410b9db 100644 --- a/docs/documentation/running_a_simulation/Input-File.md +++ b/docs/documentation/running_a_simulation/Input-File.md @@ -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(