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

Remove doxygen documentation now housed on wiki #189

Browse Source 
Verified all documentation deleted with this issue resides on
our wiki.  Nothing is lost.  Modified the doxygen makefile and
main page to point to the wiki where the user's guide used to be.

TODO: Need to move the requirements and design doxygen files.
This commit is contained in:
Alex Lin 2016-08-02 15:41:18 -05:00
parent 8198ce8a7f
commit 832679b7ee
67 changed files with 3 additions and 16668 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1931
doxygen/Doxyfile_rtf_users_guide
View File

File diff suppressed because it is too large Load Diff

80
doxygen/auto_number.pl
View File

@ -1,80 +0,0 @@
#!/usr/bin/perl
use strict ;
sub read_file($$$) {
my ($file_name, $levels, $prefix) = @_ ;
my ($out_file_name) ;
my ($ii) ;
local *FILE ;
local *OUTFILE ;
if ( $file_name =~ /dox_in$/ ) {
if ( ! -e $file_name ) {
if ( ! -e "$ENV{TRICK_HOME}/trick_source/$file_name" ) {
die "could not open $file_name" ;
} else {
$file_name = "$ENV{TRICK_HOME}/trick_source/$file_name" ;
}
}
open FILE, "$file_name" or die "could not open $file_name" ;
$out_file_name = $file_name ;
$out_file_name =~ s/_in$// ;
open OUTFILE, "> $out_file_name" or die "could not open $file_name" ;
while ( <FILE> ) {
if ( /^#include\s+"(.*?)"/ ) {
my ($include_file) = $1 ;
my ($out_include_file) ;
$out_include_file = $include_file ;
if ( $out_include_file =~ s/_in$// ) {
print OUTFILE "#include \"$out_include_file\"\n" ;
read_file($include_file, $levels, $prefix) ;
} else {
print OUTFILE ;
}
} elsif ( /^(.*?)LEVEL(\d+)(cont)?(.*)/ ) {
my ($tag) = $1 ;
my ($level) = $2 ;
my ($cont) = $3 ;
my ($title) = $4 ;
my ($section, $level_dots) ;
if ( $cont eq "" ) {
$$levels[$level]++ ;
for( $ii = $level + 1 ; $ii < 8 ; $ii++ ) {
$$levels[$ii] = 0 ;
}
}
$section = sprintf "$prefix%02d" , $$levels[1] ;
$level_dots = "$$levels[1]" ;
for( $ii = 2 ; $ii <= $level ; $ii++ ) {
#$section .= $$levels[$ii] ;
$section .= sprintf "%02d" , $$levels[$ii] ;
$level_dots .= ".$$levels[$ii]" ;
}
if ( $tag =~ /\@\w+\s+$/ ) {
print OUTFILE "$tag$section $level_dots $title\n" ;
} else {
print OUTFILE "$tag$level_dots $title\n" ;
}
} else {
print OUTFILE ;
}
}
}
}
my @levels = { 0 , 0 , 0 , 0 , 0 , 0 , 0 , 0 } ;
die "Usage: auto_number.pl <prefix>" if ( scalar @ARGV != 1 ) ;
read_file("main_page.dox_in", \@levels, @ARGV[0]) ;

6
doxygen/main_page.dox
View File

@ -1,9 +1,9 @@
/**
@mainpage Trick Documentation
-# @subpage users_guide "User's Guide"
-# @subpage requirements "Requirements Document"
-# @subpage design "Design Document"
Trick Users's Guide now found at http://github.com/nasa/trick/wiki
<p>
This documentation contains information about internal Trick classes and enumerations.
*/

7
doxygen/main_page_users_guide.dox
View File

@ -1,7 +0,0 @@
/**
@mainpage Trick User's Guide
*/
#include users_guide/main_page.dox

8
doxygen/makefile
View File

@ -5,18 +5,10 @@ export TRICK_MAJOR = $(shell echo $(TRICK_RELEASE) | cut -f 1 -d.)
export TRICK_MINOR = $(shell echo $(TRICK_RELEASE) | cut -f 2 -d.)
all:
cd users_guide ; ../auto_number.pl u
cd requirements ; ../auto_number.pl r
cd design ; ../auto_number.pl d
doxygen Doxyfile
@ cp */*.html ${TRICK_DOCS}/html
@ cp ${TRICK_HOME}/trick_source/java/src/trick/common/resources/trick_small.gif ${TRICK_DOCS}/html
@ cp ${TRICK_HOME}/doxygen/trick_icon.png ${TRICK_DOCS}/html
rtf_users_guide:
cd users_guide ; ../auto_number.pl u
doxygen Doxyfile_rtf_users_guide
clean:
@ test `uname -s` = Darwin \
&& \

22
doxygen/remove_user_doc.pl
View File

@ -1,22 +0,0 @@
#!/usr/bin/perl
use strict ;
my (@all_lines) ;
my ($contents) ;
foreach my $f ( @ARGV ) {
print "$f\n" ;
open (FH, "+< $f") ;
@all_lines = <FH> ;
$contents = join "" , @all_lines ;
$contents =~ s/(<dl[^\n]+Python Usage:.*?<\/div>)//igs ;
seek(FH,0,0) ;
print FH $contents ;
truncate(FH, tell(FH)) ;
close(FH) ;
}

158
doxygen/users_guide/CP.dox_in
View File

@ -1,158 +0,0 @@
/**
@page LEVEL2 Making the Simulation.
@section LEVEL3 Simulation Compilation Environment Variables
TRICK_CFLAGS and TRICK_CXXFLAGS affect where model source files are searched for and
how the files are compiled. See section @ref Trick_Environment for more information
to how to set TRICK_CFLAGS and TRICK_CXXFLAGS when compiling a simulation.
@section LEVEL3 Making the Simulation for the First Time.
Make and the makefiles contain all of the magic of building a simulation. When a
simulation is ready to be built for the very first time run we run the
configuration processor script (CP) in the simulation directory.
<tt><b>UNIX prompt></b> CP</tt>
CP creates a small makefile and calls make to start the simulation build process.
The small makefile does not change and is the same from simulation to simulation.
It can be copied from another simulation directory and the CP step may be skipped.
From this point CP does not need to be run again, all compilations use "make".
When make is invoked, the first rule it executes is to parse the S_define file.
The parser from this point will be referred to as CP. CP was the main compilation
command before %Trick 10. Using the S_define file created by the user, the CP
finds all source code related to the simulation, builds the code using a C compiler,
and puts it all together to make one executable. In its processing it
gathers/generates all the IO source code, default data, recursive
header/object dependencies and external library dependencies.
After the initial CP is run, when there are changes made to model source code or
the S_define file, they are recompiled using make.
<tt><b>UNIX prompt></b> make</tt>
@section LEVEL3 How Trick Finds Simulation Source Code
%Trick must compile a list of all of the source code required to create the
simulation described in the S_define file. %Trick does this by creating a list
of required header files, and the automatic I/O souce code it must build to go
with those header files, and the model source code files.
Header files are searched for starting from the S_define file. Any file that is
double pound "##" included in the S_define file is automatically included in the
list of header files. Each header file is recursively parsed to determine all
lower level header files on which the top level header is dependent on. Doing this
for all double pound files gives us the full list of header files.
Model source files are found through LIBRARY DEPENDENCIES. Starting in the S_define
file, any LIBRARY DEPENDENCIES listed are searched for. See
@ref S_define_Library_Dependencies for more information on how to add dependencies
in the S_define file. All of the header files gathered from the previous step are
also searched for library dependencies. Finally all model source code found from
the previous steps is recursively searched for additional dependencies.
See @ref Library_Dependencies for more information on how to add dependencies to
model source code. Rules to compile all of these files are written to the makefile.
@section LEVEL3 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”.
For overrides in model directories, a user can create a file called “makefile_overrides”.
In this file s/he can override any of the rules that are within the Makefile. When a
make_build command is issued, this makefile_overrides file is looked for and if it is
present, it is included from the Makefile. The rules contained in the overrides file are
then read in when make is called.
This same file is looked for in each directory when a CP is performed. Each
“makefile_overrides” file in this case is read into memory and certain rules are translated
so only those files in that directory are affected. Instead of just including these files
(where there can be multiple files), all of the translated output is inserted into the Makefile.
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.
@section LEVEL4 Example Of How To Optimize A Model
- Go to model dir to optimize
<tt><b>UNIX Prompt></b> cd /user/me/trick_models/ball/L1</tt>
- Edit a file called “makefile_overrides” with the following line:
<tt>objects: TRICK_CFLAGS += -O3</tt>
- Do a make_build
<tt><b>UNIX Prompt></b>make_build</tt>
After make_build, look at Makefile. There is a line
“include makefile_overrides”. This is what will pick up the optimization flag.
- Build the model.
<tt><b>UNIX Prompt></b> make</tt>
That’s it.
@section LEVEL4 Example Of How To Add a Pre-compiled Library to the Simulation
- Go to simulation dir.
<tt><b>UNIX Prompt></b> cd /user/me/trick_sims/SIM_ball_L1</tt>
- Edit a file called “S_overrides.mk". Append to the TRICK_USER_LINK_LIBS variable.
<tt>TRICK_USER_LINK_LIBS = -L/path/to/library -lmy_lib</tt>
@section LEVEL4 Example Of How To Exclude a Directory from ICG during CP
- Go to simulation dir.
<tt><b>UNIX Prompt></b> cd /user/me/trick_sims/SIM_ball_L1</tt>
- Edit a file called “S_overrides.mk”. Append to the TRICK_ICG_EXCLDUE variable.
<tt>TRICK_ICG_EXCLUDE += /path/to/exclude:/another/path/to/exclude</tt>
@section LEVEL4 Example Of How To Exclude a Directory from most CP processing
- Edit a file called “S_overrides.mk”. Append to the TRICK_EXCLDUE variable.
<tt>TRICK_EXCLUDE += /path/to/exclude:/another/path/to/exclude</tt>
@section LEVEL3 Cleaning Up
There are several levels of clean.
<tt><b>UNIX Prompt></b> make clean</tt>
Clean tries to remove only object files directly related to the current simulation.
It will remove all of the generated files in the simulation directory. Clean
also selectively removes model object files used to link this simulation.
<tt><b>UNIX Prompt></b> make real_clean</tt>
Real_clean is equivalent to clean.
<tt><b>UNIX Prompt></b> make spotless</tt>
Spotless is less discriminate in the files it removes. In addition to all
of the files that clean removes, spotless will remove complete model object
directories where any file included in the simulation was found.
<tt><b>UNIX Prompt></b> make apocalypse</tt>
Apocalypse is a special case rule when simulation libraries are used to build
a simulation. See section @ref Simulation_Libraries for more information
about. In addition to all of files that spotless removes, apocalype will
run the spotless rule on any simulation directory the current simulation
includes.
*/

795
doxygen/users_guide/S_define.dox_in
View File

@ -1,795 +0,0 @@
/**
@page LEVEL2 Simulation Definition File (S_define)
The “Simulation Definition File” or S_define is the file which outlays the architecture
of the simulation. Details about job frequencies, job class, job data, importing/exporting
data to other simulations, freeze cycles, integration, etc. are all housed in this one file.
It is the file which Trick’s main processor, CP, parses to determine what will be part of
the simulation and how the pieces fit together.
This section begins with the syntax for the S_define, then details each and every entry
in the syntax template. This section also details how to use Trick’s main processor, CP.
@verbatim
[/* [TRICK_HEADER]
PURPOSE: (purpose statement)
[LIBRARY DEPENDENCIES:
(
[(<rel_path_of_model>/<model_source_code_n.c>)]
)
]
[DEFAULT_DATA:
(
[(struct_type instance_name <rel_path_of_model>/<default_data_file>)]
)
]
*/]
#include "sim_objects/default_trick_sys.sm"
##include "<rel_path_of_model>/<model_header_file.h>"
%header{
/* User header code block */
%}
%{
/* User code block */
%}
class <sim_object_type_name> : public Trick::SimObject {
[(public|protected|private):]
<CLASS_TYPE|STRUCTURE_TYPE|ENUMERATED_TYPE|intrinsic_type> [*]* <data_varaible_name> [dims]*
<sim_object_type_name>([args]) {
[C<#>] [{job_tag}] [P<#>] ([<cycle_time>, [<start_time>, [<stop_time>,]]] <job_class>) \
[<return_var> =] <module>([args]) ;
}
[<method_name>([args]) { ... } ;]
} ;
[job_class_order {
<job_class_1>,
<job_class_2>,
...
} ;]
[<sim_object_type_name> <sim_object_instantiation>[(args)] ;]
[integrate <integrator_name> (<integration_dt>) <sim_object_name> [,<sim_object_name] ;]
[collect <reference> = {[<reference> [,<reference>]]};]
[void create_connections() { <glue_code> }]
@endverbatim
@section LEVEL3 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
dependencies are model source code files that are added to the list of files to be compiled and
linked into the simulation. These dependencies differ from the ones found in the actual model source
code in that they are the full relative path to the actual source code file, not the resulting object file.
CP also looks for old style default data files. Each default data entry has 3 fields, the structure type, the
instance name, and the relative path to the default data file. CP will read in the default data file
substituting each occurance 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.
@anchor S_define_Library_Dependencies
@section LEVEL4 S_define Library Dependencies
@verbatim
LIBRARY DEPENDENCY:
((relative_path/model_1.c)
(relative_path/model_2.cpp))
@endverbatim
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 the S_define file. 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 dependendencies 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.
@section LEVEL3 Include files
There are two types of includes in the S_define file.
@section LEVEL4 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.
@section LEVEL4 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.
@section LEVEL3 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.
@section LEVEL3 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.
@section LEVEL3 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.
@section LEVEL4 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
all data with the sim object. Sim object protected and private data will not be accessible to the input
processor.
Intrisic types are allowed as sim object data members.
@section LEVEL4 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,
object dependencies, etc.
Jobs only appear in the constructor of the sim object.
<tt>[C<#>] [{job_tag}] [P<#>] ([<cycle_time>, [<start_time>, [<stop_time>,]]] <job_class>) <module>([args]) ;</tt>
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.
@section LEVEL5 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,
etc. The child process specification allows parallel processing for simulation modules.
Every simulation has a parent process. A child specification will result in the spawning of
a thread for each distinct child ID specified. More than one job can be specified for each child ID.
Jobs with child specifications will run in parallel with other jobs within each software frame,
so users may be required to specify job dependencies (see Section 4.4.10) to keep parallel jobs
from stepping on each other’s common data access. The collection of the parent process and all
of its children defined in one S_define file is referred to as a Process Group (PG). A simulation
can be composed of multiple synchronized or non-synchronized PGs which will be discussed in more
detail in Section 4.4.12. and Section 7.2.
In most cases, for maximum execution performance, jobs should only be specified to run on a child
process if the host workstation has more than one CPU; and preferably, one CPU per child specified.
With the same rule in mind, using more than one PG in the simulation design should only occur when
the simulation has parallel components and multiple process/multiple computers are available. When
the host workstation has only one CPU, a simulation with a job running on a child will be much slower
than the same simulation with no children. There are exceptions to this rule, like running asynchronous
background modules on a child that only runs the child during the wait cycle of a simulation set up for
real-time operations.
Child IDs start at 1 and may skip any integer values. The %Trick Executive will spawn enough threads
to accomodate the highest Child ID specified in the S_define file. Jobs without a child specification
will be executed by the parent process. Jobs with a C1 child specification will be executed by the
first child thread; jobs with a C2 specification will be executed by the second child thread; and so on.
Child Threads have three different scheduling choices. See Section XYZ for child thread scheduling
details.
@section LEVEL5 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
modified in the same manner. For example, if jobA and jobB are tagged BLUE, the input file may
have a statement:
<tt>trick.add_read(13.0, """trick.exec_set_job_cycle("BLUE" , 0.001)""")</tt>
This will change the frequency of the jobs to 1 millisecond. You might also disable the jobs
tagged BLUE with the following:
<tt>trick.add_read(10.0, """trick.exec_set_job_onoff("BLUE" , False)""")</tt>
@section LEVEL5 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.
Without a specified phase field, the default phase number is 60000. The phase specification may be
used on all class jobs to sequence the execution of jobs in the same class. Jobs tagged with P1
execute first, then P2, etc. Jobs with the same phase number are executed in the order they are
in the S_define.
@section LEVEL5 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
parentheses, e.g. (1.0,0.5,10.0) would execute a module starting at 0.5 seconds, and every 1.0
seconds thereafter until 10.0 seconds was reached (9.5 seconds would be the time of the last
job call). The start and stop fields are optional; e.g. (1.0,0.5) does the same as the previous
example except the module will keep being called after 10.0 seconds. Also, a (1.0) specification
will start the job at 0.0 (the default) and continue calling the job at 1.0 second intervals.
Only the jobs categorized as CYCLIC or also
the freeze_scheduled job class (see Table SD_1 below) require the execution time specification.
All schedule time specifications are in seconds.
All other job classes categorized in Table SD_1 should NOT specify an execution time specification:
- NON-CYCLIC (red color) of course do not require a spec because they run only once.
- FRAME-BOUNDARY (blue color) are tied to each execution frame and not a cycle time.
- INTEGRATOR (cyan color) are specified via the state integration specifications for the simulation (see Section 4.4.7).
- SELF-SCHEDULING (yellow color) are responsible for scheduling themselves.
- 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.
@section LEVEL5 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.
<center>
<b>KEY: Job Class Category Colors used in Table SD_1</b>
<table>
<tr bgcolor="#c0c0c0"><th>Category Color</th><th>The job classes in Table SD_1 are categorized as one of the following:</th></tr>
<tr><td bgcolor="#ff8080">@b NON-CYCLIC</td><td>jobs that run once either at simulation startup or termination</td></tr>
<tr><td bgcolor="#add8e6">@b FRAME-BOUNDARY</td><td>jobs that run cyclically before/after the scheduled job loop</td></tr>
<tr><td bgcolor="#ccffff">@b INTEGRATOR</td><td>jobs that run first in the scheduled job loop for %Trick state integration</td></tr>
<tr><td bgcolor="#ffff99">@b SELF-SCHEDULING</td><td>jobs in the scheduled job loop that must schedule themselves when to run</td></tr>
<tr><td bgcolor="#ccffcc">@b CYCLIC</td><td>jobs in the scheduled job loop that run cyclically according to their specified cycle time</td></tr>
<tr><td bgcolor="#e6ceff">@b FREEZE</td><td>jobs that are run during the freeze execution mode</td></tr>
<tr><td bgcolor="#ffc285">@b CHECKPOINT</td><td>jobs that are run when a checkpoint is dumpded or loaded</td></tr>
</table>
<b>Table SD_1 %Trick-Provided Job Classes</b>
<table>
<tr bgcolor="#c0c0c0"><th>Job Class Name</th><th>Description</th></tr>
<tr><td bgcolor="#ff8080">@b default_data</td><td>Module executes only once at simulation time = zero.
Called @e before input file is read.</td></tr>
<tr><td bgcolor="#ff8080">@b initialization</td><td>Module executes only once at simulation time = zero.
Called @e after input file is read.</td></tr>
<tr bgcolor="add8e6"><td colspan="2" align="center">\<BEGIN EXECUTION FRAME\></td></tr>
<tr><td bgcolor="add8e6">@b top_of_frame</td><td>Module runs at the beginning of every execution frame, before the scheduled job loop,
even before any child threads are started for the frame.</td></tr>
<tr bgcolor="ccffcc"><td colspan="2" align="center">\<BEGIN SCHEDULED JOB LOOP\></td></tr>
<tr><td bgcolor="#ccffff">@b pre_integration</td><td>Runs only once before the integration loop.
For example, in the case of a Runge Kutta 4, the derivative and integration jobs will be called
four times during the integration steps. A pre_integration job will execute a
single time before this four step integration process has occurred.</td></tr>
<tr bgcolor="ccffff"><td colspan="2" align="center">\<BEGIN INTEGRATION LOOP\></td></tr>
<tr><td bgcolor="#ccffff">@b derivative</td><td>Equations of motion (EOM) derivative function.</td></tr>
<tr><td bgcolor="#ccffff">@b integration</td><td>Equations of motion state integration function.</td></tr>
<tr bgcolor="ccffff"><td colspan="2" align="center">\<END INTEGRATION LOOP\></td></tr>
<tr><td bgcolor="#ccffff">@b post_integration</td><td>Runs only once after the integration loop.</td></tr>
<tr><td bgcolor="#ccffff">@b dynamic_event</td><td>Runs after the integration loop
(after any post_integration jobs). Provides a continuous time dependent equation whose root
defines a discontinuous event in the system EOM, evaluation of function returns an
estimated delta time to reach the root.</td></tr>
<tr><td bgcolor="ffff99">@b automatic</td><td>Module which reschedules its own next call time, and will run before other CYCLIC jobs in the frame.</td></tr>
<tr><td bgcolor="#ccffcc">@b environment</td><td>Time dependent boundary conditions (mother nature).</td></tr>
<tr><td bgcolor="#ccffcc">@b sensor</td><td> Simulated interface between dynamics and control simulation components.</td></tr>
<tr><td bgcolor="#ccffcc">@b sensor_emitter</td><td>Same as sensor, but for the emitter portion of an integrated
multi-component sensor system.</td></tr>
<tr><td bgcolor="#ccffcc">@b sensor_reflector</td><td>Same as sensor, but for the reflector portion of an
integrated multi-component sensor system.</td></tr>
<tr><td bgcolor="#ccffcc">@b sensor_receiver</td><td>Same as sensor, but for the receiver portion of an
integrated multi-component sensor system.</td></tr>
<tr><td bgcolor="#ccffcc">@b scheduled</td><td>Typical flight software and hardware subsystems.</td></tr>
<tr><td bgcolor="#ccffcc">@b effector</td><td>Simulated interface between control and force generator
simulation components.</td></tr>
<tr><td bgcolor="#ccffcc">@b effector_emitter</td><td>Same as effector, but for the ’action’ portion of an
action-reaction effector system.</td></tr>
<tr><td bgcolor="#ccffcc">@b effector_receiver</td><td>Same as effector, but for the ’reaction’ portion of an
action-reaction effector system.</td></tr>
<tr><td bgcolor="#ccffcc">@b logging</td><td>Simulation data recording or displaying.</td></tr>
<tr><td bgcolor="#ffff99">@b automatic_last</td><td>Module which reschedules its own next call time, and will run after other CYCLIC jobs in the frame.</td></tr>
<tr bgcolor="ccffcc"><td colspan="2" align="center">\<END SCHEDULED JOB LOOP\></td></tr>
<tr><td bgcolor="add8e6">@b end_of_frame</td><td>Module runs at the end of every execution frame, after the scheduled job loop completes.</td></tr>
<tr bgcolor="add8e6"><td colspan="2" align="center">\<END EXECUTION FRAME\></td></tr>
<tr><td bgcolor="#e6ceff">@b freeze_init</td><td>Module executes only once upon entering FREEZE mode.</td></tr>
<tr bgcolor="e6ceff"><td colspan="2" align="center">\<BEGIN FREEZE FRAME\></td></tr>
<tr bgcolor="e6ceff"><td colspan="2" align="center">\<BEGIN FREEZE LOOP\></td></tr>
<tr><td bgcolor="#e6ceff">@b freeze_scheduled</td><td>Module executes cyclically during simulation FREEZE mode according to its specified cycle time.</td></tr>
<tr bgcolor="e6ceff"><td colspan="2" align="center">\<END FREEZE LOOP\></td></tr>
<tr><td bgcolor="#e6ceff">@b freeze</td><td>Module runs at end of every freeze frame, after the freeze loop completes.</td></tr>
<tr bgcolor="e6ceff"><td colspan="2" align="center">\<END FREEZE FRAME\></td></tr>
<tr><td bgcolor="#e6ceff">@b unfreeze</td><td>Module executes only once upon leaving FREEZE mode before returning to RUN mode.</td></tr>
<tr><td bgcolor="#ffc285">@b checkpoint</td><td>Module executes only once @e before a checkpoint is @e dumped.</td></tr>
<tr><td bgcolor="#ffc285">@b post_checkpoint</td><td>Module executes only once @e after a checkpoint is @e dumped.</td></tr>
<tr><td bgcolor="#ffc285">@b preload_checkpoint</td><td>Module executes only once @e before a checkpoint is @e loaded.</td></tr>
<tr><td bgcolor="#ffc285">@b restart</td><td>Module executes only once @e after a checkpoint is @e loaded.</td></tr>
<tr><td bgcolor="#ff8080">@b shutdown</td><td>Module executes only once at simulation termination to allow a
graceful shutdown.</td></tr>
</table>
</center>
@section LEVEL5 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.
All dynamic_event class jobs must return a double precision value representing the estimated time
to go to the defined event, in seconds.
All other jobs managed by the %Trick executive, not integration or dynamic_event, may return any
type. If a function is declared with an integer return value, the job must return a non-negative
integer or else the executive will assume an error occurred an immediately terminate the simulation.
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.
@section LEVEL5 Job Name
This field specifies the job name of the job as defined in the job’s source code.
C function and C++ member functions can be called as a jobs. Here is a quick example of a C and C++
calls.
@verbatim
%{
extern "C" {
c_function() ;
}
%}
class MySimObject() : public Trick::SimObject {
public:
Ball my_ball ;
MySimObject() {
(1.0 , "scheduled") c_function() ;
(1.0 , "scheduled") my_ball.print_state() ;
}
}
@endverbatim
@section LEVEL5 Job Calling Arguments
Job calling arguments adhere to C++ calling argument standards.
@section LEVEL4 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.
@section LEVEL3 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
can specify a new set of scheduled loop job classes. Job classes that are eligible for reassignment
are listed in Table SD_1 between automatic and automatic_last inclusive. The order they are shown
in the table is the default ordering.
@code
job_class_order {
my_job_class_1 ;
my_job_class_2 ;
scheduled ;
my_job_class_3 ;
}
@endcode
@section LEVEL3 Simulation Object C++ properties
Sim objects are C++ objects. They posess all of the capabilities of C++ objects. This section
describes how to use some C++ features with sim objects.
@section LEVEL4 Simulation Object Instantiations
@section LEVEL5 Multiple Instantiations
Sim objects are instatiated 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
works with both C and C++ models contained within the sim object.
@code
class ballSimObject : public Trick::SimObject {
public:
Ball obj ;
ballSimObject() {
("initialization") obj.state_init() ;
("derivative") obj.force_field() ;
("derivative") obj.state_deriv() ;
("integration", &my_integ) trick_ret = obj.state_integ() ;
(10.0, "scheduled") trick_ret = obj.state_print() ;
}
}
// Make 2 balls
ballSimObject ball ;
ballSimObject ball2 ;
@endcode
@section LEVEL5 Sim Object Constructor Arguments and Initializer Lists
Sim objects instantiations may take arguments. These arguments may be used in the sim object's
initialzation list. An initialization list constructs member variables of the class. They
are listed as a comma separated list after the declaration of a constructor. Arguments passed
to the sim object constructor may be passed onto member variable constructors.
@note
C structures may be zeroed out when included in the sim object's initialization list.
@code
class ballSimObject : public Trick::SimObject {
public:
Ball obj ;
C_STRUCT c_struct ;
// passes int argument to obj constructor. Zeros out c_struct.
ballSimObject(int num) : obj(num) , c_struct() {
} ;
}
// Sim object constructor requires an integer argument.
ballSimObject ball(5) ;
@endcode
@section LEVEL5 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.
@code
class ballSimObject : public Trick::SimObject {
public:
Ball obj ;
ballSimObject(int phase, double cycle , const char * job_class) {
(job_class) obj.state_init() ;
Pphase ("derivative") obj.force_field() ;
("derivative") obj.state_deriv() ;
("integration", &my_integ) trick_ret = obj.state_integ() ;
(cycle, "scheduled") trick_ret = obj.state_print() ;
}
}
ballSimObject ball(1 , 10.0 , “initialization”) ;
// This ball has different job properties than the first ball.
ballSimObject ball2( 2 , 5.0 , “default_data” ) ;
@endcode
@section LEVEL4 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
instantiation determine which sim object constructor and which jobs are run.
@code
class ballSimObject : public Trick::SimObject {
public:
Ball obj ;
ballSimObject(int phase, double cycle , const char * job_class) {
(job_class) obj.state_init() ;
Pphase ("derivative") obj.force_field() ;
("derivative") obj.state_deriv() ;
("integration", &my_integ) trick_ret = obj.state_integ() ;
(cycle, "scheduled") trick_ret = obj.state_print() ;
}
ballSimObject(const char * job_class) {
(job_class) obj.state_init() ;
}
}
ballSimObject ball(1 , 10.0 , “initialization”) ;
ballSimObject ball2( “default_data” ) ;
@endcode
@section LEVEL4 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.
@code
class ballSimObject : public Trick::SimObject {
public:
Ball obj ;
ballSimObject() {
(10.0, "scheduled") trick_ret = obj.state_print() ;
}
}
class anotherBallSimObject : public ballSimObject {
public:
anotherBallSimObject() {
// This job will run after the above state_print()
(10.0, "scheduled") another_print() ;
}
}
anotherBallSimObject ball() ;
@endcode
@section LEVEL4 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:
@code
class Ball {
public:
virtual void print_type() = 0 ;
} ;
class Baseball : public Ball {
public:
virtual void print_type() ;
} ;
class Soccerball : public Ball {
public:
virtual void print_type() ;
} ;
@endcode
We may use a Ball base pointer in the S_define.
@code
class ballSimObject : public Trick::SimObject {
public:
Ball * ball_ptr ;
ballSimObject() {
(1.0 , "scheduled") ball_ptr->print_type() ;
}
} ;
ballSimObject ball ;
@endcode
ball_ptr is not instantiated when the simulation is compiled. If nothing is assigned to ball_ptr
before the first scheduled call of ball_ptr->print_type() then the call will fail and the sim
will core. We can allocate ball_ptr in the input file. We can even change ball_ptr in the
middle of the simulation.
@verbatim
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]")""")
@endverbatim
@section LEVEL3 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
(for any combination of sim objects) for state integration using a particular integrator and
state integration time step. Some simulations will have several different sets of state
parameters, each set requiring a unique state integration scheme and integration time step.
Likewise, other simulations will require all the derivative class modules from a group of
sim objects to be executed before the integration class modules of the same sim object group.
The integration specification provides this capability.
The integration specification is of the following form:
<tt>integrate <integrator_name> (<integration_dt>) <sim_object_name> [,<sim_object_name_n>] ;</tt>
An alternative instantiation syntax which is pure C++ is of the form:
<tt>IntegLoopSimObject <integrator_name> (<integration_dt>, <sim_object_name> [,<sim_object_name_n>], NULL ) ;</tt>
This form must have NULL as the final argument to the instantiation.
The integrate tag is a reserved word for the CP. The <integration_dt> is a state integration
cycle time in seconds. At least one sim object name must be specified followed by any number
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.
@section LEVEL3 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
‘n’ number (either a known or unknown ‘n’) of parameters of the same type. The parameter
collection mechanism is an alternative for a variable calling argument list The collection
mechanism syntax in the S_define file is as follows:
<tt>collect <reference> = { } ;</tt>
or
<tt>collect <reference> = { <reference_1> [,<reference_n>] } ;</tt>
There is also a C code equivalent to adding collect references one at a time that may
be put in a create_connections section of the S_define file. The advantage of this
method is that not all of the collects must be listed in a single collect statement.
This function call syntax may also be used in the input file to add collects at runtime.
@code
void create_connections() {
reference = add_collect( reference , reference_1 ) ;
reference = add_collect( reference , reference_2 ) ;
}
@endcode
The collect capability allows the developer to build a job which accesses an unknown number
of independent simulation parameters. For example, if designed correctly, a derivative class
module should be capable of incorporating any number of known and unknown (future capabilities)
external forces and torques without any code changes to the derivative module. The collection
mechanism stores the addresses of, and number of, any number of independent parameters in a
single pointer array. The derivative module can use this array to access each parameter in the
collection list. See Section 10.0 for programming requirements for this capability.
The collect statements in the S_define file must be supported by source code implemented by
the math model developer. This collect support code can reside in any function in the simulation,
including functions that are not listed in the S_define file. In general, for every collect
statement in the S_define file, there are two places where source code must be developed: a
data structure definition file (*.h) and a function source file (*.c).
As a real world example, orbital dynamics can include a large number of environmental effects
for high precision state propagation, or a small number of effects for general purpose state
propagation. A spacecraft EOM derivative module should be designed to include any number and
combination of known and unknown (future) effects. A low fidelity parameter collection for
external torques on the spacecraft might look like:
@code
collect shuttle.orbital.rotation.external_torque[0] = {
shuttle.aero.out.torque[0] } ;
@endcode
A higher fidelity parameter collection might look like:
@code
collect shuttle.orbital.rotation.external_torque[0] = {
shuttle.aero.out.torque[0] ,
shuttle.grav.out.gravity_gradient_torque[0] ,
shuttle.solar_pressure.out.torque[0] } ;
@endcode
For those cases when there are no parameters to collect:
@code
collect shuttle.orbital.rotation.external_torque[0] = { } ;
@endcode
The key here is that if a new external torque for the spacecraft is added to the simulation,
that torque can be accessed by the existing derivative module without code modification to the
derivative module. Note that all parameters listed must be of the same type and array dimension.
To use the parameter collection mechanism of the S_define file, the developer must perform three tasks:
-# from the example above, the external_torque parameter must be declared in its data structure
definition file as a two dimensional void pointer, i.e. void ** external_torque ;,
-# a loop must be placed in the derivative module which accesses the collected parameters, and
-# the parameter collection statement must be added to the S_define.
The external_torque parameter must be declared as a two dimensional void pointer for two reasons.
First, the void type is not processed by the ICG. This means that this parameter cannot be recorded
for output or assigned data for input. If the type was any other type than void, the ICG would
assume the parameter required dynamic memory allocation and the resulting ICG generated code would
cause a fatal runtime error (usually accompanied by a core dump). Second, from an automatic code
generation viewpoint, the external_torque parameter is actually an unconstrained array of pointers,
where the pointers in the unconstrained array could be of any type (including data structure pointers);
i.e. the first pointer (*) of the declaration is the array dimension, the second is the address to
each of the collected parameters.
To make the collection mechanism work, the developer must add specific collection mechanism code to
their module. For the above example, the derivative module code might look like the following; the
text in bold indicates code which will be unchanged regardless of the parameters being collected:
@code
#include “dynamics/v2/dynamics.h”
#include “sim_services/include/collect_macros.h”
int derivative_job( DYN_ROT * R ) {
int i ;
double **collect ;
double total_torque[3] ;
total_torque[0] = total_torque[1] = total_torque[2] = 0.0 ;
/* typecast the void ** as a usable double** */
collect = (double**)R->external_torque ;
/*
Loop on the number of collected items
from the above collect statement example:
collect[0] -> shuttle.aero.out.torque
collect[1] -> shuttle.grav.out.gravity_gradient_torque
collect[2] -> shuttle.solar_pressure.out.torque
*/
for( i = 0 ; i < NUM_COLLECT(collect) ; i++ ) {
total_torque[0] += collect[i][0] ;
total_torque[1] += collect[i][1] ;
total_torque[2] += collect[i][2] ;
}
return( 0 ) ;
}
@endcode
Several aspects of this example code which need mentioning are listed below.
-# A local pointer parameter must be declared of the same type as the parameters being
collected, in this case the parameters being collected are double precision; hence,
double **collect ;.
-# The shuttle.orbital.rotation.external_torque (actually a void**) is typecast as a
double** and assigned to the local variable: collect = (double**)R->external_torque ;.
-# The number of parameters collected is saved in the first eight bytes before the
address to the external_torque parameter. The conditional statement of the for loop
demonstrates how the number of collected parameters is retrieved: NUM_COLLECT(collect).
-# This example, and all other collection mechanism code implementations, assume the
developer knows the type and array size of the parameters being collected. In this
example, the parameters collected were single dimensioned double precision arrays with
three elements per array.
@section LEVEL3 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.
The intended use of this section is to glue the sim objects together. Sim objects that
need pointers to other sim objects may be assigned in the create_connections routine.
Default parameters may also be set such as defining a default simulation stop time. Any
arbitrary code may be added to the create_connections section.
There may be multiple create_connection sections in the S_define file. They will be
concatenated together in the order they appear in the S_define file.
@code
class AsimObject : public Trick::SimObject {
public:
modelA a ;
// This pointer points to a different sim object
modelB * b_ptr ;
AsimObject() {
// This job requires type modelB from a different sim object
(1.0 , "scheduled") a.job(b_ptr) ;
}
} ;
class BsimObject: public Trick::SimObject {
public:
modelB b ;
}
AsimObject A ;
BsimObject B ;
void create_connections() {
// Connects the AsimObject and BsimObject together.
A.b_ptr = &B.b
// Sets a default stop time for the simulation.
exec_set_terminate_time(300.0) ;
}
@endcode
*/

71
doxygen/users_guide/S_main.dox_in
View File

@ -1,71 +0,0 @@
/**
@page LEVEL1 S_main_${TRICK_HOST_CPU}.exe
S_main_${TRICK_HOST_CPU}.exe is generated by the CP and is the simulation main executable
program.
The runtime configuration of the executive and its associated support utilities may be
manipulated through entries in the simulation input file. The input file is described
in detail in @ref Input_File.
The command line for the runtime executive is:
@verbatim
S_main_<TRICK_HOST_CPU>.exe [trick_version] [sie]
RUN_<name>/<input_file_name> [-d]
[-O <output_file_path>]
[-OO <output_file_path>]
[-u <user_defined_arguments>]
@endverbatim
- <TRICK_HOST_CPU> is the same as the ${TRICK_HOST_CPU} gte variable
- The first argument in the command line must be the simulation input file name. The
input file name can be in the form of a full path name but MUST have a RUN_<name>
directory immediately above the input file name. By default, all the simulation
output is directed to this RUN_<name> directory. The standard <input_file_name> is
input; however, a simulation could be started from a checkpoint file by substituting
chkpnt_<time> in for <input_file_name> for non-Master/Slave and non-Import/Export
simulations. For Master/Slave and Import/Export simulations you must have the
simulation running, and the simulation must be in a freeze state before reloading a
checkpoint.
- The trick_version option will tell what version of Trick built the S_main executable.
- The sie option will generate the smart input editor (SIE) resource file (CP will by
default invoke the S_main executable with the sie option to generate this file).
- The ‘-d’ argument is optional and, if specified, starts the simulation in an input
file verification mode. In this mode the entire input file is read, echoed to
standard out, and then the simulation exits without calling any jobs listed in the
S_define file. This mode helps debug input file syntax errors.
- The ‘-O <output_file_path>‘ option allows the user to specify the directory to which
simulation data log files will be written. If this option is omitted, the RUN_<name>
directory is used.
- The ‘-OO <output_file_path>’ option allows the user to specify the directory to
which ALL simulation output files will be written. If this option is omitted, the
RUN_<name> directory is used.
- The ‘-u’ option specifies that all remaining arguments are meant to be used by
user supplied jobs. All arguments after the -u can be accessed internal to the
simulation jobs by calling the get_cmnd_args() function of the executive as
illustrated below. In a master/slave simulation, the master’s -u args will be passed
to the slave.
The following code example shows how a function can access the command line
arguments during execution.
@code
#include “sim_services/CommandLineArguments/include/command_line_protos.h”
void test_job( void )
{
int num_args ;
char **args ;
int ii ;
num_args = command_line_args_get_argc() ;
args = command_line_args_get_argv() ;
for( ii = 0 ; ii < num_args ; ii++ )
printf( “argument #%d = %s\n” , ii , args[ii] ) ;
return ;
}
@endcode
*/

186
doxygen/users_guide/appendix_a.dox_in
View File

@ -1,186 +0,0 @@
/**
@page LEVEL1 Converting From Trick 7 To Trick 10
Listed here are the main differences you'll have to handle if you have a Trick version 7 simulation
that you want to convert to Trick version 10.
@section LEVEL2 S_define File
The Trick 7 S_define file syntax for a sim object looks more or less like a C Structure containing model job specifications. The Trick 10 S_define file
syntax for a sim object looks like a C++ Class containing model job specifications within the Class constructor. There are other features of the S_define file
that may or may not look different.<br><br>
See the
@htmlonly
<a href="appendix_a_sdefine_table.html"> Table of S_define File Differences</a>
@endhtmlonly
for Trick 7 vs. Trick 10 S_define File syntax.
@section LEVEL2 Input File
The Trick 7 input syntax is a C-like language created and maintained just for Trick. The Trick 10
input syntax is Python. In addition to the obvious differences due to using a new input file language,
many things have been implemented differently in Trick 10 resulting in changes to the way
Trick data is configured or referenced in the input file.<br><br>
See the
@htmlonly
<a href="appendix_a_input_table.html"> Table of Input File Differences</a>
@endhtmlonly
for Trick 7 vs. Trick 10 Input File syntax.
@section LEVEL2 Memory Initialization
Trick 10 does not automatically initialize C structures to zero (while Trick 7 does). Trick 10 uses the C++ "new" command to allocate memory for both C and C++ data,
which relies on user code (C: an init function, C++: constructor) to do the initializing.
However, you can use a feature of C++ to initialize your C structures to zero (see the S_define example below). This method is also implemented in Trick's generated io_src code
so that when you dynamically allocate a C structure using Trick's memory manager, e.g. TMM_declare_var, it will be zeroed as well.
This way Trick 10 can act like Trick 7 with regards to initializing memory.
@code
class mySimObject : public Trick::SimObject {
public:
STRUCT1 my_c_struct1;
STRUCT2 my_c_struct2;
// you can put C structs with empty parens as initializers on the constructor to zero them out:
mySimObject() : my_c_struct1(), my_c_struct2() {
(0.1, "scheduled") state_update(&my_c_struct1) ;
(0.1, "scheduled") state_update(&my_c_struct2) ;
}
}
mySimObject dyn ;@endcode
@section LEVEL2 Memory Allocation
See @subpage convert_07_to_10.
@section LEVEL2 Default Data Files
Trick 7 default data files should be converted to default_data class jobs in Trick 10. See below for more background on
the default data capabilities in Trick 7 vs. Trick 10. There is a convenience script called dd_convert
that can automatically convert your existing Trick 7 default data files to source code so they can be used as default_data jobs.
See the dd_convert help screen for its usage:
<tt><b>UNIX Prompt></b> dd_convert -h</tt>
<b>Trick 7 default data capability:</b><br>
Using syntax that the Trick input processor can understand, the user can code assignment statements to set the initial ("default") value for variables. These assignment statements are stored in a file with a ".d" extension. When a variable is declared in the S_define file, an optional .d file (or files) may be specified on the declaration statement so that the data is initialized with values from the .d file.
S_define syntax:@code
<rel_path1>: <type> <instance> [(<rel_path2>/<filename>.d)] ;@endcode
S_define example:@code
sim_object {
mymodels: MYSTRUCT var (mymodels/data/mystruct.d) ;
} examp ;@endcode
The <rel_path1> is the path (relative to TRICK_CFLAGS path) to the C or C++ header file where <type> is defined. The <rel_path2> is the relative path to where the .d file is located. The difference between a default data assignment statement and a regular input file statement is that the <type> is specified instead of the declared variable name. Trick will process the .d file and substitute the variable name for each <type>. This way a .d file can be used for one or more variable declarations.
.d file syntax: @code
<type>.<member>[[<dim>]] [{<units>}] = <value> [, <value>#] ;@endcode
.d file example:<br>
Assume there is a mystruct.h file that looks like this:@code
typedef struct {
int dist ; /* km my distance */
} MYSTRUCT ;@endcode
The .d file assignment statement may look like this:@code
MYSTRUCT.dist = 100 ;@endcode
Trick instantiates the .d statement to this:@code
examp.var.dist = 100 ;@endcode
All Trick instantiated .d files are stored in the Default_data directory. Trick also generates an S_default.dat file that includes all of the .d files from the Default_data directory. The 1st statement in the input file should be to #include the S_default.dat file so that the default data assignment statements are processed first by the Trick input processor, guaranteeing that all variables that had default data specified are initialized.
Pros:
- User can change a .d file and not have to recompile (CP -d)
Cons:
- Slower execution at simulation startup
- User can add other input statements (for/if/then/else/etc.) that Trick's default data processor may ignore, which can be error prone
<b>Trick 10 default data capability:</b><br>
A new default_data Trick job class was created so that source code can do the data assignments instead of .d files, mainly because of the two Cons listed above. So the Trick 7 example above can be done using C or C++ source code in Trick 10.
S_define syntax (C):@code
<type> <instance> ;
("default_data") <function>(&<simobj>.<instance>) ;@endcode
S_define example (C):@code
/* LIBRARY DEPENDENCIES: ((mymodels/src/my_ddata.c)) */
class exampSimObject : public Trick::SimObject {
public:
MYSTRUCT var ;
exampSimObject() {
("default_data") my_ddata(MYSTRUCT *ptr = &examp.var) ;
}
};
exampSimObject examp ;@endcode
Source file syntax (C):@code
void <function>(<type> *<param>) {
(*<type>).<member>[[<dim>]] = <value> ;
}@endcode
Source file example (C):@code
void my_ddata(MYSTRUCT *t) {
(*t).dist = 100 ;
}@endcode
S_define syntax (C++):@code
<type> <instance> ;
("default_data") <instance>.<function>() ;@endcode
S_define example (C++):@code
##include "mymodels/include/mystruct.h"
class exampSimObject : public Trick::SimObject {
public:
MYSTRUCT var ;
exampSimObject() {
("default_data") var.my_ddata() ;
}
};
exampSimObject examp ;@endcode
Source file syntax (C++):@code
void <type>::<function>() {
<member>[[<dim>]] = <value> ;
}@endcode
Source file example (C++):@code
void MYSTRUCT::my_ddata() {
dist = 100 ;
}@endcode
Of course because your default data is now done in source code, if you want to change default data values from sim to sim, you would have to run "make" to pick up your changes.
<b>Trick 10 Another way to do it:</b><br>
Don't wanna mess with default_data jobs? You can just assign default values in the sim object constructor. The Trick 10 sim object is a C++ Class, so you can write code in its constructor to assign data values. Note that if you are going to change your default data from sim to sim, you will have to re-CP every time you change values. Otherwise this is a fine method if you don't plan to change your default data values much or at all. (It's pertinent to note that class constructors execute before default_data jobs, in case you use both methods.) So the S_define example from above would look like the example below, with no default_data job needed.
S_define example:@code
##include "mymodels/include/mystruct.h"
class exampSimObject : public Trick::SimObject {
public:
MYSTRUCT var ;
exampSimObject() {
var.dist = 100 ;
}
};
exampSimObject examp ;@endcode
@section LEVEL2 Variable Server Commands
The Variable Server sends any commands it receives to the Trick input processor for parsing, so essentially you can send any valid input syntax
to the Variable Server. In addition to general input statements, there are special commands that only the Variable Server understands
in order to send back variable data to the client. <br><br>
See the
@htmlonly
<a href="appendix_a_varserver_table.html"> Table of Variable Server Command Differences</a>
@endhtmlonly
for Trick 7 vs. Trick 10 Variable Server Command syntax.
@section LEVEL2 Data Product Files
TODO.
*/

2466
doxygen/users_guide/appendix_a_input_table.html
View File

File diff suppressed because it is too large Load Diff

BIN
doxygen/users_guide/appendix_a_input_table.xlsx
View File

Binary file not shown.

897
doxygen/users_guide/appendix_a_sdefine_table.html
View File

@ -1,897 +0,0 @@
<html>
<head>
<meta name=Title content="">
<meta name=Keywords content="">
<meta http-equiv=Content-Type content="text/html; charset=macintosh">
<meta name=ProgId content=Excel.Sheet>
<meta name=Generator content="Microsoft Excel 2008">
<style>
<!--table {}
.font0
{color:windowtext;
font-size:10.0pt;
font-weight:400;
font-style:normal;
text-decoration:none;
font-family:Verdana;}
.font12
{color:#006411;
font-size:10.0pt;
font-weight:400;
font-style:normal;
text-decoration:none;
font-family:Verdana;}
.font15
{color:#FF6600;
font-size:10.0pt;
font-weight:400;
font-style:normal;
text-decoration:none;
font-family:Verdana;}
.style0
{text-align:general;
vertical-align:bottom;
white-space:nowrap;
color:windowtext;
font-size:10.0pt;
font-weight:400;
font-style:normal;
text-decoration:none;
font-family:Verdana;
border:none;}
td
{padding-top:1px;
padding-right:1px;
padding-left:1px;
color:windowtext;
font-size:10.0pt;
font-weight:400;
font-style:normal;
text-decoration:none;
font-family:Verdana;
text-align:general;
vertical-align:bottom;
border:none;
white-space:nowrap;}
.xl24
{white-space:normal;}
.xl25
{background:silver;
white-space:normal;}
.xl26
{font-weight:700;
border-top:none;
border-right:.5pt solid windowtext;
border-bottom:none;
border-left:.5pt solid windowtext;
white-space:normal;}
.xl27
{color:#006411;
border-top:none;
border-right:.5pt solid windowtext;
border-bottom:none;
border-left:.5pt solid windowtext;
white-space:normal;}
.xl28
{color:#0000D4;
border-top:none;
border-right:.5pt solid windowtext;
border-bottom:none;
border-left:.5pt solid windowtext;
white-space:normal;}
.xl29
{color:#DD0806;
font-weight:700;
border-top:none;
border-right:.5pt solid windowtext;
border-bottom:.5pt solid windowtext;
border-left:.5pt solid windowtext;
white-space:normal;}
.xl30
{color:#DD0806;
font-weight:700;
white-space:normal;}
.xl31
{border-top:.5pt solid windowtext;
border-right:.5pt solid windowtext;
border-bottom:none;
border-left:.5pt solid windowtext;
background:silver;
white-space:normal;}
.xl32
{color:#FF6600;
border-top:none;
border-right:.5pt solid windowtext;
border-bottom:none;
border-left:.5pt solid windowtext;
white-space:normal;}
.xl33
{font-weight:700;
white-space:normal;}
.xl34
{color:#006411;
white-space:normal;}
.xl35
{text-align:left;
white-space:normal;
padding-left:24px;}
.xl36
{text-align:left;
white-space:normal;
padding-left:48px;}
.xl37
{color:#006411;
text-align:left;
white-space:normal;
padding-left:24px;}
.xl38
{color:#FF6600;
text-align:left;
white-space:normal;}
.xl39
{color:#006411;
text-align:left;
white-space:normal;
padding-left:48px;}
ruby
{ruby-align:left;}
rt
{color:windowtext;
font-size:8.0pt;
font-weight:400;
font-style:normal;
text-decoration:none;
font-family:Verdana;
display:none;}
-->
</style>
</head>
<body link="#0000d4" vlink="#993366" class=xl24>
<table border=0 cellpadding=0 cellspacing=0 width=3348 style='border-collapse:
collapse;table-layout:fixed'>
<col class=xl24 width=417>
<col class=xl24 width=413>
<col class=xl24 width=529>
<col class=xl24 width=144>
<col class=xl24 width=369 span=5>
<tr height=26>
<td height=26 class=xl24 width=417></td>
<td class=xl31 width=413>TRICK 7 TO TRICK 10 S_DEFINE FILE DIFFERENCES<br>
KEY :</td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl26 width=413 style='background:#E8F9FF'>Bold<font class=font0> =
Default behavior</font></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl27 width=413>Green<font class=font0> = New Trick 10 feature or
implementation is different than Trick 7</font></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl28 width=413 style='background:#E8F9FF'>Blue<font class=font0> =
Need a Trick 10 interface routine</font></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl32 width=413>Orange <font class=font0>= Not implemented in Trick
10 / presumably not needed</font></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl29 width=413 style='background:#E8F9FF'>Red Bold <font
class=font0>= Not implemented in Trick 10 / needs to be fixed</font></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl30 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl24 width=413 style='background:#E8F9FF'></td>
<td class=xl30 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr class=xl25 height=26>
<td height=26 class=xl25 width=417><br>
TRICK 7</td>
<td class=xl25 width=413>TRICK 10</td>
<td class=xl25 width=529>DESCRIPTION</td>
<td class=xl25 width=144>&nbsp;</td>
<td class=xl25 width=369>&nbsp;</td>
<td class=xl25 width=369>&nbsp;</td>
<td class=xl25 width=369>&nbsp;</td>
<td class=xl25 width=369>&nbsp;</td>
<td class=xl25 width=369>&nbsp;</td>
</tr>
<tr height=117>
<td height=117 class=xl24 width=417 style='background:#E8F9FF'>[/* PURPOSE:
(&lt;purpose_statement&gt;) */]</td>
<td class=xl24 width=413 style='background:#E8F9FF'>[/* PURPOSE:
(&lt;purpose_statement&gt;)<font class=font12><br>
[DEFAULT_DATA: (<br>
[ (&lt;type&gt; &lt;variable&gt;
&lt;rel_path&gt;/&lt;default_data_file&gt;) ]<br>
)]<br>
[LIBRARY DEPENDENCIES: (<br>
[ (&lt;rel_path&gt;/&lt;model_source.c|cc|cpp&gt;)
]<br>
])<br>
</font><font class=font0>*/]</font></td>
<td class=xl24 width=529 style='background:#E8F9FF'>OPTIONAL TRICK COMMENT
HEADER<br>
TRICK10:<br>
DEFAULT DATA FILES CONTAINING ASSIGNMENT STATEMENTS ONLY ARE STILL
SUPPORTED. YOU CAN SPECIFY THEM IN THE HEADER (BUT USING DEFAULT DATA JOBS IS
THE RECOMMENDED METHOD).<br>
IF THERE ARE ANY FUNCTION CALLS IN THE
S_DEFINE THAT ONLY OCCUR IN THE S_DEFINE, SPECIFY A LIBRARY DEPENDENCY TO THE
SOURCE SO THAT IT IS BUILT.</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=26>
<td height=26 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl34 width=413 style='background:#E8F9FF'>##include
&quot;&lt;rel_path&gt;/&lt;model_header_file.h|hh&gt;&quot;</td>
<td class=xl24 width=529 style='background:#E8F9FF'>TRICK10: ANY DATA
DECLARED IN THE S_DEFINE MUST HAVE AN ASSOCIATED HEADER FILE INCLUDED WITH
THE SPECIAL ## SYNTAX.</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl33 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=39>
<td height=39 class=xl24 width=417 style='background:#E8F9FF'>%{<br>
&lt;user_code_block&gt;<br>
%}</td>
<td class=xl24 width=413 style='background:#E8F9FF'>%{<br>
&lt;user_code_block&gt;<br>
%}</td>
<td class=xl24 width=529 style='background:#E8F9FF'>ADD ANY USER GLOBAL C/C++
CODE HERE<br>
TRICK10: IF YOU HAVE A LIB DEPENDENCY TO A C FUNCTION, DECLARE ITS PROTOTYPE
HERE AS extern &quot;C&quot; &lt;type&gt; &lt;myfunction&gt;(&lt;args&gt;);</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'>#define
&lt;label&gt; &lt;value&gt;</td>
<td class=xl24 width=413 style='background:#E8F9FF'>#define &lt;label&gt;
&lt;value&gt;</td>
<td class=xl24 width=529 style='background:#E8F9FF'>DEFINE A C PREPROCESSOR
MACRO</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'>#include
&lt;another_s_define_module&gt;</td>
<td class=xl24 width=413 style='background:#E8F9FF'>#include
&lt;another_s_define_module&gt;</td>
<td class=xl24 width=529 style='background:#E8F9FF'>INLINE INCLUDE OTHER
FILES CONTAINING S_DEFINE SYNTAX</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417>sim_object {</td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl35 width=417>sim_services/include: EXECUTIVE exec
(sim_services/include/executive.d);</td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl35 width=417>(automatic) sim_services/input_processor:</td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl36 width=417>input_processor(INPUT_PROCESSOR* IP =
&amp;sys.exec.ip);</td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl35 width=417>[(automatic_last) sim_services/exec:</td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl36 width=417>var_server_sync(EXECUTIVE * E =
&amp;sys.exec ) ;]</td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417>} sys ;</td>
<td class=xl34 width=413>#include
&quot;sim_objects/default_trick_sys.sm&quot;</td>
<td class=xl24 width=529>DECLARE THE NECESSARY TRICK SIM OBJECTS</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl24 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417>sim_object {</td>
<td class=xl34 width=413>class &lt;my_sim_object_type&gt; : public
Trick::SimObject {</td>
<td class=xl24 width=529>START OF A USER SIM OBJECT DECLARATION</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl35 width=417 style='background:#E8F9FF'></td>
<td class=xl37 width=413 style='background:#E8F9FF'>
[public:|protected:|private:]</td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=39>
<td height=39 class=xl35 width=417> &lt;rel_path&gt;:&lt;type&gt;
&lt;variable&gt;[&lt;dim&gt;] <br>
[(&lt;default_data_file&gt;)
[,&lt;default_data_file&gt;])] ;</td>
<td class=xl35 width=413>&lt;type&gt; &lt;variable&gt;[&lt;dim&gt;] ;</td>
<td class=xl24 width=529>DECLARE MODEL DATA (TRICK7: FINDS DATA VIA REL_PATH,
AND OPTIONAL DEFAULT DATA SPECIFIED HERE;<br>
TRICK10: FINDS DATA VIA ##INCLUDE, DEFAULT DATA DONE IN JOB OR IN HEADER
ABOVE)</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl35 width=417 style='background:#E8F9FF'></td>
<td class=xl35 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl35 width=417></td>
<td class=xl37 width=413>&lt;my_sim_object_type&gt; ([&lt;args&gt;]) [:
&lt;initializer_list&gt;] {</td>
<td class=xl24 width=529>TRICK10: START OF SIM OBJECT CONSTRUCTOR</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl35 width=417 style='background:#E8F9FF'></td>
<td class=xl35 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=26>
<td height=26 class=xl35 width=417> [import &lt;import_tag&gt;
&lt;sim_object&gt;.&lt;variable&gt; ;]</td>
<td class=xl38 width=413>NOT IMPLEMENTED</td>
<td class=xl24 width=529>SYNCED DATA IMPORT FROM MASTER/SLAVE; TRICK10:
RARELY USED FEATURE HAS BEEN DEPRECATED</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=39 style='page-break-before:always'>
<td height=39 class=xl35 width=417 style='background:#E8F9FF'>[C&lt;#&gt;]
[{&lt;job_tag&gt;}] [P&lt;#&gt;] [I&lt;sim_object&gt;]<br>
([&lt;cycle_time&gt;, [&lt;start_time&gt;, [&lt;stop_time&gt;]]]
&lt;job_class&gt;)<br>
&lt;rel_path&gt;:&lt;module&gt; ([&lt;param_type&gt; &lt;param&gt; =
&lt;arg&gt; [, É]) ;</td>
<td class=xl36 width=413 style='background:#E8F9FF'>[C&lt;#&gt;]
[{&lt;job_tag&gt;}] [P&lt;#&gt;]<font class=font15>[I&lt;sim_object&gt; NOT
IMPLEMENTED]</font><font class=font12><br>
</font><font class=font0>([&lt;cycle_time&gt;,
[&lt;start_time&gt;, [&lt;stop_time&gt;]]] </font><font class=font12>&quot;</font><font
class=font0>&lt;job_class&gt;</font><font class=font12>&quot;</font><font
class=font0>)</font><font class=font12><br>
[&lt;return_val&gt; =] </font><font
class=font0>&lt;module&gt; (</font><font class=font12>[&lt;arg&gt;][, É]</font><font
class=font0>) ;</font></td>
<td class=xl24 width=529 style='background:#E8F9FF'>SPECIFY A JOB TO BE
MANAGED BY TRICK EXECUTIVE</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl35 width=417>[export &lt;export_tag&gt;
&lt;sim_object&gt;.&lt;variable&gt; ;]</td>
<td class=xl38 width=413>NOT IMPLEMENTED</td>
<td class=xl24 width=529>SYNCED DATA EXPORT TO MASTER/SLAVE; TRICK10: RARELY
USED FEATURE HAS BEEN DEPRECATED</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl35 width=417 style='background:#E8F9FF'></td>
<td class=xl35 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl35 width=417></td>
<td class=xl39 width=413>[&lt;user_code_block&gt;]</td>
<td class=xl24 width=529>TRICK10: C/C++ USER CODE IN CONSTRUCTOR: ASSIGN
VARIABLES, CALL FUNCTIONS, ETC.</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl35 width=417 style='background:#E8F9FF'></td>
<td class=xl37 width=413 style='background:#E8F9FF'>}</td>
<td class=xl24 width=529 style='background:#E8F9FF'>TRICK10: END OF SIM
OBJECT CONSTRUCTOR</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417>} &lt;sim_object&gt; ;</td>
<td class=xl24 width=413>} ;</td>
<td class=xl24 width=529>END OF A USER SIM OBJECT DECLARATION (TRICK7: ALSO
INSTANTIATE THE SIM OBJECT)</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl34 width=413 style='background:#E8F9FF'>[&lt;my_sim_object_type&gt;
&lt;sim_object&gt;[(&lt;args&gt;)] ;]</td>
<td class=xl24 width=529 style='background:#E8F9FF'>TRICK10: INSTANTIATE THE
SIM OBJECT AND PASS CONSTRUCTOR ARGUMENTS</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=65>
<td height=65 class=xl24 width=417 style='background:#E8F9FF'>[job_class_order
{<br>
&lt;job_class_1&gt;,<br>
&lt;job_class_2&gt;,<br>
...<br>
} ;]</td>
<td class=xl24 width=413 style='background:#E8F9FF'>[job_class_order {<br>
<font
class=font12>&quot;</font><font class=font0>&lt;job_class_1&gt;</font><font
class=font12>&quot;</font><font class=font0>,<br>
</font><font
class=font12>&quot;</font><font class=font0>&lt;job_class_2&gt;</font><font
class=font12>&quot;</font><font class=font0>,<br>
...<br>
} ;]</font></td>
<td class=xl24 width=529 style='background:#E8F9FF'>SPECIFY A JOB CLASS ORDER
DIFFERENT THAN THE TRICK DEFAULT ORDER</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'>[integrate
(&lt;integration_dt&gt;) &lt;sim_object&gt; [, É] ;]</td>
<td class=xl34 width=413 style='background:#E8F9FF'>[IntegLoop
&lt;my_integ_loop&gt; <font class=font0>(&lt;integration_dt&gt;)
&lt;sim_object&gt; [, É] ;]</font></td>
<td class=xl24 width=529 style='background:#E8F9FF'>SPECIFY STATE INTEGRATION</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'>[collect
&lt;reference&gt; = {[&lt;reference2&gt; [, É]]} ;]</td>
<td class=xl24 width=413 style='background:#E8F9FF'>[collect
&lt;reference&gt; = {[&lt;reference2&gt; [, É]]} ;]</td>
<td class=xl24 width=529 style='background:#E8F9FF'>CREATE A COLLECTION
(ARRAY) OF SAME TYPED VARIABLES</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl34 width=413 style='background:#E8F9FF'>[void
create_connections() {</td>
<td class=xl24 width=529 style='background:#E8F9FF'>TRICK10: C/C++ USER CODE
THAT IS RUN AFTER ALL DATA IS INSTANTIATED BUT BEFORE DEFAULT DATA</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417>[freeze (&lt;cycle_time&gt;) ;]</td>
<td class=xl37 width=413>[trick_sys.sched.set_freeze_frame(&lt;cycle_time&gt;);]</td>
<td class=xl24 width=529>SET FREEZE CYCLE TIME</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl37 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417>[&lt;sim_object&gt;:&lt;module_after&gt;([dup_id])
depends on</td>
<td class=xl37 width=413>[trick_sys.sched.add_depends_on_job(</td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl35 width=417>&lt;sim_object&gt;:&lt;module_before&gt;([dup_id])</td>
<td class=xl39 width=413>&quot;&lt;sim_object.module_after&gt;&quot;,
&lt;dup_id&gt;,</td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl35 width=417>[and
&lt;sim_object&gt;:&lt;module_before&gt;([dup_id])]]</td>
<td class=xl39 width=413>&quot;&lt;sim_object.module_before&gt;&quot;,
&lt;dup_id&gt;);]</td>
<td class=xl24 width=529>SPECIFY EXECUTION ORDER FOR CHILD THREADS</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl37 width=413 style='background:#E8F9FF'>[&lt;user_code_block&gt;]</td>
<td class=xl24 width=529 style='background:#E8F9FF'>TRICK10: C/C++ OTHER MISC
USER CODE: ASSIGN VARIABLES, CALL FUNCTIONS, ETC.</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl34 width=413>}]</td>
<td class=xl24 width=529>TRICK10: END OF CREATE_CONNECTIONS USER CODE</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl24 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
</table>
</body>
</html>

BIN
doxygen/users_guide/appendix_a_sdefine_table.xlsx
View File

Binary file not shown.

679
doxygen/users_guide/appendix_a_varserver_table.html
View File

@ -1,679 +0,0 @@
<html>
<head>
<meta http-equiv=Content-Type content="text/html; charset=macintosh">
<meta name=ProgId content=Excel.Sheet>
<meta name=Generator content="Microsoft Excel 2008">
<style>
<!--table {}
.font0
{color:windowtext;
font-size:10.0pt;
font-weight:400;
font-style:normal;
text-decoration:none;
font-family:Verdana;}
.font1
{color:windowtext;
font-size:10.0pt;
font-weight:700;
font-style:normal;
text-decoration:none;
font-family:Verdana;}
.font9
{color:#006411;
font-size:10.0pt;
font-weight:400;
font-style:normal;
text-decoration:none;
font-family:Verdana;}
.font10
{color:#006411;
font-size:10.0pt;
font-weight:700;
font-style:normal;
text-decoration:none;
font-family:Verdana;}
.style0
{text-align:general;
vertical-align:bottom;
white-space:nowrap;
color:windowtext;
font-size:10.0pt;
font-weight:400;
font-style:normal;
text-decoration:none;
font-family:Verdana;
border:none;}
td
{padding-top:1px;
padding-right:1px;
padding-left:1px;
color:windowtext;
font-size:10.0pt;
font-weight:400;
font-style:normal;
text-decoration:none;
font-family:Verdana;
text-align:general;
vertical-align:bottom;
border:none;
white-space:nowrap;}
.xl24
{white-space:normal;}
.xl25
{background:silver;
white-space:normal;}
.xl26
{color:#006411;
white-space:normal;}
.xl27
{font-weight:700;
border-top:none;
border-right:.5pt solid windowtext;
border-bottom:none;
border-left:.5pt solid windowtext;
white-space:normal;}
.xl28
{color:#006411;
border-top:none;
border-right:.5pt solid windowtext;
border-bottom:none;
border-left:.5pt solid windowtext;
white-space:normal;}
.xl29
{color:#0000D4;
border-top:none;
border-right:.5pt solid windowtext;
border-bottom:none;
border-left:.5pt solid windowtext;
white-space:normal;}
.xl30
{color:#DD0806;
font-weight:700;
border-top:none;
border-right:.5pt solid windowtext;
border-bottom:.5pt solid windowtext;
border-left:.5pt solid windowtext;
white-space:normal;}
.xl31
{color:#DD0806;
font-weight:700;
white-space:normal;}
.xl32
{border-top:.5pt solid windowtext;
border-right:.5pt solid windowtext;
border-bottom:none;
border-left:.5pt solid windowtext;
background:silver;
white-space:normal;}
.xl33
{color:#FF6600;
border-top:none;
border-right:.5pt solid windowtext;
border-bottom:none;
border-left:.5pt solid windowtext;
white-space:normal;}
.xl34
{font-weight:700;
white-space:normal;}
ruby
{ruby-align:left;}
rt
{color:windowtext;
font-size:8.0pt;
font-weight:400;
font-style:normal;
text-decoration:none;
font-family:Verdana;
display:none;}
-->
</style>
</head>
<body link="#0000d4" vlink="#993366" class=xl24>
<table border=0 cellpadding=0 cellspacing=0 width=3717 style='border-collapse:
collapse;table-layout:fixed'>
<col class=xl24 width=417>
<col class=xl24 width=413>
<col class=xl24 width=529>
<col class=xl24 width=144>
<col class=xl24 width=369 span=6>
<tr height=26>
<td height=26 class=xl24 width=417></td>
<td class=xl32 width=413>TRICK 7 TO TRICK 10 VARIABLE SERVER COMMAND
DIFFERENCES<br>
KEY :</td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl27 width=413 style='background:#E8F9FF'>Bold<font class=font0> =
Default behavior</font></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl28 width=413>Green<font class=font0> = New Trick 10 feature or
implementation is different than Trick 7</font></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl29 width=413 style='background:#E8F9FF'>Blue<font class=font0> =
Need a Trick 10 interface routine</font></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl33 width=413>Orange <font class=font0>= Not implemented in Trick
10 / presumably not needed</font></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl30 width=413 style='background:#E8F9FF'>Red Bold <font
class=font0>= Not implemented in Trick 10 / needs to be fixed</font></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl31 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl24 width=413 style='background:#E8F9FF'></td>
<td class=xl31 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr class=xl25 height=26>
<td height=26 class=xl25 width=417><br>
TRICK 7</td>
<td class=xl25 width=413>TRICK 10</td>
<td class=xl25 width=529>DESCRIPTION</td>
<td class=xl25 width=144>&nbsp;</td>
<td class=xl25 width=369>&nbsp;</td>
<td class=xl25 width=369>&nbsp;</td>
<td class=xl25 width=369>&nbsp;</td>
<td class=xl25 width=369>&nbsp;</td>
<td class=xl25 width=369>&nbsp;</td>
<td class=xl25 width=369>&nbsp;</td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'>var_add
&lt;variable_name&gt; ;</td>
<td class=xl24 width=413 style='background:#E8F9FF'>trick.var_add(&quot;&lt;variable_name&gt;&quot;)</td>
<td class=xl24 width=529 style='background:#E8F9FF'>ADD A VARIABLE TO LIST OF
REGISTERED VARIABLES FOR VALUE RETRIEVAL</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417>var_add &lt;variable_name&gt;
{&lt;units&gt;} ;</td>
<td class=xl24 width=413>trick.var_add(&quot;&lt;variable_name&gt;&quot;,
&quot;&lt;units&gt;&quot;)</td>
<td class=xl24 width=529>A VAR_ADD THAT CAUSES THE RETURNED VALUE TO BE IN
SPECIFIED UNITS</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl34 width=417 style='background:#E8F9FF'>var_ascii<font
class=font0> ; OR var_binary ; OR var_binary_nonames ;</font></td>
<td class=xl24 width=413 style='background:#E8F9FF'>trick.<font class=font1>var_ascii()</font><font
class=font0> OR trick.var_binary() OR trick.var_binary_nonames()</font></td>
<td class=xl24 width=529 style='background:#E8F9FF'>RETURN VARIABLE VALUES IN
ASCII OR BINARY FORMAT</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=26>
<td height=26 class=xl24 width=417></td>
<td class=xl26 width=413>trick.var_byteswap(True|<font class=font10>False</font><font
class=font9>)</font></td>
<td class=xl24 width=529>WHEN VAR SERVER AND CLIENT ARE ON DIFFERENT MACHINE
ARCHITECTURES WITH<br>
DIFFERENT INTERNAL NUMBER REPRESENATION (ENDIANNESS), BYTESWAP RETURNED
VALUES*</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'>var_clear ;</td>
<td class=xl24 width=413 style='background:#E8F9FF'>trick.var_clear()</td>
<td class=xl24 width=529 style='background:#E8F9FF'>REMOVE ALL VARIABLES FROM
LIST OF REGISTERED VARIABLES FOR VALUE RETRIEVAL</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417>var_cycle = <font class=font1>0.1</font><font
class=font0>|&lt;sec&gt; ;</font></td>
<td class=xl24 width=413>trick.var_cycle(<font class=font1>0.1</font><font
class=font0>|&lt;sec&gt;)</font></td>
<td class=xl24 width=529>SET FREQUENCY AT WHICH REGISTERED VARIABLE VALUES
ARE RETURNED</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'>var_debug =
&lt;<font class=font1>0</font><font class=font0>|1|2|3&gt; ;</font></td>
<td class=xl24 width=413 style='background:#E8F9FF'>trick.var_debug(<font
class=font1>0</font><font class=font0>|1|2|3)</font></td>
<td class=xl24 width=529 style='background:#E8F9FF'>PRINT TO TERMINAL
INCREASING AMOUNTS OF DEBUGGING INFORMATION</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417>var_exists &lt;variable_name&gt; ;</td>
<td class=xl24 width=413>trick.var_exists(&quot;&lt;variable_name&gt;&quot;)</td>
<td class=xl24 width=529>RETURN BOOLEAN 0 OR 1 AS TO WHETHER THE SPECIFIED
VARIABLE EXISTS</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'>var_exit ;</td>
<td class=xl24 width=413 style='background:#E8F9FF'>trick.var_exit()</td>
<td class=xl24 width=529 style='background:#E8F9FF'>EXIT THE VARIABLE SERVER
FOR THIS CLIENT</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417>var_mcast &lt;multicast_address&gt;
&lt;port&gt; ;</td>
<td class=xl31 width=413>NOT IMPLEMENTED</td>
<td class=xl24 width=529>CAUSES RETURNED VALUES TO BE DIVERTED TO MULTIPLE
CLIENTS AT SPECIFIED ADDRESS/PORT</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'>var_pause ;</td>
<td class=xl24 width=413 style='background:#E8F9FF'>trick.var_pause()</td>
<td class=xl24 width=529 style='background:#E8F9FF'>PAUSE THE CYCLIC
RETRIEVAL OF REGISTERED VARIABLE VALUES</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417>var_remove &lt;variable_name&gt; ;</td>
<td class=xl24 width=413>trick.var_remove(&quot;&lt;variable_name&gt;&quot;)</td>
<td class=xl24 width=529>REMOVE A VARIABLE FROM LIST OF REGISTERED VARIABLES
FOR VALUE RETRIEVAL</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'>var_send;</td>
<td class=xl24 width=413 style='background:#E8F9FF'>trick.var_send()</td>
<td class=xl24 width=529 style='background:#E8F9FF'>REQUEST VALUES TO BE SENT
IMMEDIATELY (USEFUL DURING VAR_PAUSE OR BEFORE VAR_CLEAR)</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=26>
<td height=26 class=xl24 width=417>var_sync = &lt;Yes|<font class=font1>No</font><font
class=font0>&gt; ;</font></td>
<td class=xl24 width=413>trick.var_sync(<font class=font1>0</font><font
class=font0>|1|2)</font></td>
<td class=xl24 width=529>RETURN VARIABLE VALUES IN SYNC WITH SIM EXECUTION
FRAME<br>
(TRICK10: 0 is ASYNCHRONOUS, 1 IS DATA SYNC BUT WRITTEN ASYNC, 2 IS DATA
&amp; WRITE SYNC)</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'>var_units
&lt;variable_name&gt; {&lt;units&gt;} ;</td>
<td class=xl24 width=413 style='background:#E8F9FF'>trick.var_units(&quot;&lt;variable_name&gt;&quot;,
&quot;&lt;units&gt;&quot;)</td>
<td class=xl24 width=529 style='background:#E8F9FF'>CAUSES THE RETURNED VALUE
(OF A PREVIOUS VAR_ADD) TO BE IN SPECIFIED UNITS</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417>var_unpause ;</td>
<td class=xl24 width=413>trick.var_unpause()</td>
<td class=xl24 width=529>CONTINUE (CANCEL PAUSE OF) THE CYCLIC RETRIEVAL OF
REGISTERED VARIABLE VALUES</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl24 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl24 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl25 width=529>* NOTE ABOUT HANDSHAKING</td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=78>
<td height=78 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl24 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'>THE TRICK7 VARIABLE
SERVER USES HANDSHAKING AT CONNECTION TIME IN ORDER TO KNOW<br>
WHETHER THE CLIENT AND SERVER ARE DIFFERENT AND REQUIRE BYTESWAPPING.
BECAUSE <br>
THIS IS RARE, THE TRICK10 VARIABLE SERVER DOES NOT USE HANDSHAKING. SO
REMOVE ANY HANDSHAKING YOUR CODE DOES TO CONNECT TO THE VARIABLE SERVER IN
TRICK10 (E.G., <br>
IF CONNECTING VIA TRICKCOMM (tc_connect) SET THE DEVICE'S
DISABLE_HANDSHAKING <br>
FLAG TO TRUE.)</td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl24 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl24 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl24 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl24 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417></td>
<td class=xl24 width=413></td>
<td class=xl24 width=529></td>
<td class=xl24 width=144></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
<td class=xl24 width=369></td>
</tr>
<tr height=13>
<td height=13 class=xl24 width=417 style='background:#E8F9FF'></td>
<td class=xl24 width=413 style='background:#E8F9FF'></td>
<td class=xl24 width=529 style='background:#E8F9FF'></td>
<td class=xl24 width=144 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
<td class=xl24 width=369 style='background:#E8F9FF'></td>
</tr>
</table>
</body>
</html>

BIN
doxygen/users_guide/appendix_a_varserver_table.xlsx
View File

Binary file not shown.

56
doxygen/users_guide/building_simulation.dox_in
View File

@ -1,56 +0,0 @@
/**
@page LEVEL1 Building a Simulation
Before a simulation developer can begin using the %Trick environment, he or she must first
install a %Trick software release or locate the %Trick installation on a supported platform
and then install themselves as a %Trick user. This process is described in detail in
Section 3.0 “Installing %Trick”.
The following describes a complete end-to-end simulation development and operation scenario.
-# As with any simulation development task, a %Trick simulation development task begins with
a system design. However, with %Trick, the programmer does not have to start from scratch.
%Trick provides a time based cyclic executive, with a limited event capability, which
schedules developer defined jobs (C subroutines) for execution based upon execution cycle
frequencies and a multitude of different job classifications. This step can be viewed as
fitting the developer’s “pieces” into the %Trick “puzzle”. The design time at this level
should be relatively short, since we are talking about big pieces at this step in the
development.
-# The next step involves source code development. The developer must design and implement
the “jobs” which comprise the end-simulation. During source code development, the
developer is required to adhere to stringent job interface (calling argument)
specification guidelines, as well as a few in-code documentation guidelines. Otherwise,
programming style is left to the developer. Math model source code design and
implementation for a specific model is by far the most time consuming procedure in the
entire simulation development scenario (excluding verification and validation). This is
as it should be; i.e., simulations of the past often require abhorrent labor hours, not
for math model development, but for executive and input and output mechanism development.
-# Next the developer must create a simulation definition file. The simulation definition
file defines the source modules (jobs) and data structures used for a particular
simulation. The simulation definition file contains the following information:
- global data structures, including types, versions, source code names, and default
initialization data files,
- math model jobs (source code routines), including scheduled time intervals, version,
calling argument specification (job interface) , and process specifier
(for multi-process sim),
- model delineation (job groupings),
- state integration jobs and time intervals,
- specialized parameter collections,
- job dependencies for distributed process simulations.
-# With a complete simulation definition file, the developer invokes the %Trick simulation
Configuration Processor (CP). CP reads the simulation definition file and generates all
simulation specific source code for the runtime executive, and all ASCII data base files
for the user interface. CP also compiles the simulation specific source code and links
in the object code libraries. %Trick takes care of all executive, I/O, and file management
chores that have traditionally given simulation developers fits in the past.
-# The developer may now create data product specification files, if data analysis is
required. These files specify logged parameters to access, and display data in either
plot or table format.
-# We now move into the simulation user domain (included in the developer’s domain). At
this point the simulation is ready to operate. The user must first generate an input file.
-# The user now may execute one or more simulation runs.
-# During or after simulation execution the user may use the UI to post process simulation
output data in either plot or tabular format.
*/

33
doxygen/users_guide/data_products.dox_in
View File

@ -1,33 +0,0 @@
/**
@anchor DataProducts
@page LEVEL1 Data Products
The Data Products (DP) is a simulation data post processor designed to allow
visualization of data recorded in the Trick simulation.
The data products can plot ASCII, Binary & HDF5 data. HDF5 is
the new data format supported since Trick 10.
Normally, a user will create DP formatted files for viewing by using the trick_dp and quickplot (trick_qp) GUIs
(see @ref DPGUIs "6.4 Data Products GUIs"), and will not have to worry about DP file formats as well as
the underlying Trick applications @c “fxplot” or @c “gxplot”, which do the work of displaying
plots and tables. However, there are times that a user may want to program scripts or
do something command line and need to know the usage of these internal applications.
There are two basic DP programs for displaying data: @c fxplot, and @c gxplot.
@c “fxplot” creates X-Y plots using a 3rd party Fermi-Lab plot widget as well as creates
ASCII tabular data. @c “gxplot” uses gnuplot for generating report quality plots.
The usage for @c fxplot and @c gxplot are seen below:
<tt><b>UNIX Prompt></b> fxplot <session_file></tt><br>
<tt><b>UNIX Prompt></b> gxplot <session_file></tt><br>
This session is arranged as following:
@li @ref DPSessionFileFormat "6.1 DP Session File Format"
@li @ref DPProductFileFormat "6.2 DP Product File Format"
@li @ref DPPlotPrinting "6.3 Plot Printing"
@li @ref DPGUIs "6.4 Data Products GUIs"
*/

1087
doxygen/users_guide/dp_guis.dox_in
View File

File diff suppressed because it is too large Load Diff

23
doxygen/users_guide/dp_printing.dox_in
View File

@ -1,23 +0,0 @@
/**
@anchor DPPlotPrinting
@page LEVEL2 Plot Printing
To print fermi plots, simply bring up the fermi plot, and press either the “Print” (printer icon) button or the individual “Print” (printer icon)
buttons on the plots themselves. In order for this to work you should set two environment variables:
@li <b>UNIX Prompt></b> setenv TRICK_PRINT_CMD <your print command e.g. lpr>
@li <b>UNIX Prompt></b> setenv TRICK_PRINTER_NAME <printer name e.g. xerox>
In all other cased, just choose the device to be "file", then print the file. If the device is set to be "printer" either in a DP <session_file>
(@ref session_device "device" attribute of session element) or through <b>@c -device</b> option of "fxplot" application as following or through "trick_dp" gui,
all plotting will go to the specified printer automatically.
To specify the <b>@c -device</b> option of "fxplot" command for sending the plots to a printer
(<b>@c -device</b> option overrides the device setting in the <session_file>):
@li <b>UNIX Prompt></b> fxplot -device=printer <session_file>
@see @ref DataProducts "Data Products"
*/

439
doxygen/users_guide/dp_product_file.dox_in
View File

@ -1,439 +0,0 @@
/**
@anchor DPProductFileFormat
@page LEVEL2 DP Product File Format
Since Trick 10, the DP Product Specification File Format is changed to XML. The DP Product XML file
DTD is defined as following:
@see @ref DataProducts "Data Products"
<center>@anchor product_dtd @b Product.dtd</center>
@verbatim
<!-- Trick DP Product definition -->
<!-- V 1.0 -->
<!ELEMENT fname (#PCDATA)>
<!ELEMENT title (#PCDATA)>
<!ELEMENT tstart (#PCDATA)>
<!ELEMENT tstop (#PCDATA)>
<!ELEMENT frequency (#PCDATA)>
<!ELEMENT label (#PCDATA)>
<!ELEMENT units (#PCDATA)>
<!ELEMENT measurement (var, units)>
<!ELEMENT var (#PCDATA)>
<!-- A varcase construct is used to indicate that two or variable names mean the same thing.
If the data for a curve can't be found for the first name, try the second and so forth.
-->
<!ELEMENT varcase (var, var, var?)>
<!ELEMENT xaxis (label?, units?)>
<!ELEMENT yaxis (label?, units?)>
<!ELEMENT zaxis (label?, units?)>
<!ELEMENT column (label?, units?, var)>
<!ELEMENT curve ((var, var, var?)|varcase+)>
<!ELEMENT table (title?, tstart?, tstop?, frequency?, column+)>
<!ELEMENT plot (title?, tstart?, tstop?, frequency?, (xaxis|yaxis|zaxis)*, curve+)>
<!ELEMENT page (title?, tstart?, tstop?, frequency?, plot+)>
<!ELEMENT inputs (var+)>
<!ELEMENT outputs (measurement+)>
<!ELEMENT extfn (fname, inputs, outputs)>
<!ELEMENT product (title?, tstart?, tstop?, frequency?, extfn*, (page|table)+)>
<!ATTLIST product version CDATA #REQUIRED>
<!ATTLIST product foreground_color CDATA #IMPLIED>
<!ATTLIST product background_color CDATA #IMPLIED>
<!ATTLIST page foreground_color CDATA #IMPLIED>
<!ATTLIST page background_color CDATA #IMPLIED>
<!ATTLIST page hcells CDATA #IMPLIED>
<!ATTLIST page vcells CDATA #IMPLIED>
<!ATTLIST page presentation CDATA #IMPLIED>
<!ATTLIST page gnuplot_template CDATA #IMPLIED>
<!ATTLIST page gnuplot_object CDATA #IMPLIED>
<!ATTLIST page gnuplot_geom CDATA #IMPLIED>
<!ATTLIST page gnuplot_plot_ratio CDATA #IMPLIED>
<!ATTLIST page gnuplot_page_orientation CDATA #IMPLIED>
<!ATTLIST table foreground_color CDATA #IMPLIED>
<!ATTLIST table background_color CDATA #IMPLIED>
<!ATTLIST plot x_scale CDATA #IMPLIED>
<!ATTLIST plot xmin CDATA #IMPLIED>
<!ATTLIST plot xmax CDATA #IMPLIED>
<!ATTLIST plot y_scale CDATA #IMPLIED>
<!ATTLIST plot ymin CDATA #IMPLIED>
<!ATTLIST plot ymax CDATA #IMPLIED>
<!ATTLIST plot grid CDATA #IMPLIED>
<!ATTLIST plot grid_color CDATA #IMPLIED>
<!ATTLIST plot foreground_color CDATA #IMPLIED>
<!ATTLIST plot background_color CDATA #IMPLIED>
<!ATTLIST plot font CDATA #IMPLIED>
<!-- The format attribute specifies the printf() format string to -->
<!-- be used for printing y variable data. (e.g., "%18.6e") -->
<!ATTLIST yaxis format CDATA #IMPLIED>
<!-- The format attribute specifies the printf() format string to -->
<!-- be used for printing column data. (e.g., "%18.6e") -->
<!ATTLIST column format CDATA #IMPLIED>
<!-- =============================================================== -->
<!-- <var> ATTRIBUTES -->
<!-- =============================================================== -->
<!ATTLIST var label CDATA #IMPLIED>
<!-- <var>'s from_units attribute specifies the units to be assumed -->
<!-- for the recorded data if and only if the recorded data doesn't -->
<!-- contain units information for it's variables. -->
<!-- This attribute is used for data streams that don't supply -->
<!-- actual units. For streams that supply actual units (like .trk -->
<!-- files) this attribute is ignored. -->
<!ATTLIST var from_units CDATA #IMPLIED>
<!-- <var>'s units attribute indicates the units that recorded data -->
<!-- should be converted to, below being displayed. -->
<!ATTLIST var units CDATA #IMPLIED>
<!ATTLIST var bias CDATA #IMPLIED>
<!ATTLIST var scale CDATA #IMPLIED>
<!ATTLIST var max CDATA #IMPLIED>
<!ATTLIST var symbol_style CDATA #IMPLIED>
<!ATTLIST var symbol_size CDATA #IMPLIED>
<!ATTLIST var line_style CDATA #IMPLIED>
<!ATTLIST var line_color CDATA #IMPLIED>
<!ATTLIST var gnuplot_line_style CDATA #IMPLIED>
@endverbatim
The root element of the DP Product XML file is <b>@c product</b>. It contains all other elements.
There are three main elements under @c product element that are: <b>@c page</b>, <b>@c table</b>, and
<b>@c extfn</b>. <b>@c page</b> refers to a page of X-Y-(Z) plots. <b>@c table</b> refers to ASCII
text formats. The product specification file may contain any number of pages and tables, but at least one
page or table. <b>@c 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.
@section LEVEL3 DP Page Element Specifications
A DP product file may have one or more <b>@c page</b> elements. Each <b>@c page</b> element must
have at least one <b>@c plot</b> elment and may have more plots sepcified. All attributes of a
<b>@c page</b> element as stated earlier in @ref product_dtd "Product.dtd" are:
@code foreground_color, background_color, hcells, vcells, presentation, gnuplot_template, gnuplot_object, gnuplot_geom, gnuplot_plot_ratio, gnuplot_page_orientation@endcode
The <b>@c page</b> element will be discussed in following sections: @ref plot_element_specifictions "6.2.1.1 Plot Element Specifications",
@ref general_variable_options "6.2.1.2 General Variable Options",
@ref specific_variable_options "6.2.1.3 DP Specific Y (or Z) Variable Options", and
@ref curves "6.2.1.4 Curves".
@anchor plot_element_specifictions
@section LEVEL4 DP Plot Element Specifications
The <b>@c tstart</b> and <b>@c 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.
Each plot page specification can include up to nine individual plot specifications. The size of each
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.
@anchor general_variable_options
@section LEVEL4 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:
@li The <b>@c label</b> attribte of @c var element allows the user to give the parameter
(or program token) a name to be used in the legend of a plot.
@li The <b>@c units</b> attribute of <b>@c var</b> allows the user to specify the measurement
units in which the specified parameter will be displayed. The measurement units specification
syntax is identical to that used in the input processor and ICG parameter comments.
@li The <b>@c bias</b> attribute of <b>@c var</b> allows the user to shift the plot.
It is applied after the scaling and unit conversion. X or Y or Z may be shifted.
@li The <b>@c max</b> attribute of <b>@c var</b> allows the user to override the max range options
specified at the plot level.
@li The <b>@c scale</b> attribute of <b>@c var</b> allows the user to scale the specified parameter
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.
@anchor specific_variable_options
@section LEVEL4 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>@c var</b> element XML specification doesn't limit a X variable having
all these options, such restriction is implemented at GUI level.
These options are:
@li <b>@c ymbol_style</b>: None|Square|Circle|Star|XX|Triangle|Solid_Square|Solid_Circle|Thick_Square|Thick_Circle
@li <b>@c symbol_size</b>: Tiny|Small|Medium|Large
@li <b>@c line_sytle</b>: Plain|Dash|No_Line|X_Thick_Line|Fine_Dash|Med_Fine_Dash|Long_Dash|X_Long_Dash|Dot_Dash|2_Dot_Dash|3_Dot_Dash|4_Dot_Dash
@li <b>@c line_color</b>: system supported color
@li <b>@c gnuplot_line_sytle</b>: lines|points|linespoints|impulses|dots|steps|fsteps|histeps|boxes
The <b>@c symbol_style</b> attribute of <b>@c var</b> allows the user to mark each data point with a specific symbol.
The default is None.
The <b>@c line_style attribute</b> of <b>@c var</b> allows the user to change the line style which connects the X-Y(-Z) data points.
The default is Plain.
The <b>@c line_color</b> attribute of <b>@c var</b> allows the user to specify a color to be used for the X-Y(-Z) plot line and symbol.
the <b>@c gnuplot_line_sytle</b> attribute of <b>@c 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.
@anchor curves
@section LEVEL4 Curves
Each curve has either specified 2 or 3 variables stated as <b>@c var</b> or has <b>@c
varcase</b> specified. The first <b>@c var</b> element is for X, the second <b>@c var</b>
element is for Y and the third is for Z. A <b>@c curve</b> element can not have both <b>@c var</b>
and <b>@c varcase</b> elements at same time.
If you have specified multiple RUN_ directories that contain the same X, Y, and (Z) variable names, Trick can
generate a curve for each RUN_ directory, or a single comparison plot. However, the only <b>@c var</b>
specification makes it very difficult to compare a parameter with one variable name in RUN_A and a different
variable name in RUN_B. The <b>@c varcase</b> specification, on the other hand, allows multiple X, Y, and (Z),
which are lists of possible XY(Z) variables that define the curve for each RUN_ directory. If <b>@c varcase</b>
elements do not have unique variable names, DP will use the first <b>@c varcase</b> that it finds in the logged
data and ignores the other <b>@c varcase</b> elements.
As shown in the following DP specification example, it compares @c sys.exec.out.time (X) and
@c ball.obj.state.output.acceleration[1] (Y) variables from RUN_A and @c my_other_data.time (X)
and @c my_other_data.acceleration[1] (Y) variables from RUN_B. It also generates curves for
@c sys.exec.out.time (X) and @c ball.obj.state.output.external_force[0] (Y) from
both RUN_A and RUN_B.
@verbatim
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE product PUBLIC "-//Tricklab//DTD Product V1.0//EN" "Product.dtd">
<product background_color="#ede9e3" foreground_color="#000000" version="1.0">
<tstart>-1.0E20</tstart>
<tstop>1.0E20</tstop>
<frequency>0.0</frequency>
<page background_color="#ede9e3" foreground_color="#000000">
<title>Page</title>
<plot background_color="#ede9e3" foreground_color="#000000" grid="Yes" grid_color="#ffffff">
<title>Plot</title>
<curve>
<varcase>
<var units="--">sys.exec.out.time</var>
<var units="m/s2">ball.obj.state.output.acceleration[1]</var>
</varcase>
<varcase>
<var units="--">my_other_data.time</var>
<var units="m/s2">my_other_data.acceleration[1]</var>
</varcase>
</curve>
<curve>
<var units="--">sys.exec.out.time</var>
<var units="N">ball.obj.state.output.external_force[0]</var>
</curve>
</plot>
</page>
</product>
@endverbatim
@see @ref product_dtd "Product.dtd"
@section LEVEL3 DP Table Specifications
Each table is comprised of one or more columns and each column is only for one variable. Each <b>@c column</b> element
has an optional <b>@c format</b> attribute that allows the user to specify the text format for the variable's data. The
syntax of <b>@c format</b> is the same as that for a C language @p printf format field. Each variable element of
<b>@c column</b> element has those general variable options as stated in
Section @ref general_variable_options "6.2.1.2 GeneralVariable Options".
As shown in the following product example XML file, it has one <b>@c table</b> defined. This <b>@c table</b> has
4 different columns and each column is corresponding to a specific <b>@c var</b>.
@verbatim
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE product PUBLIC "-//Tricklab//DTD Product V1.0//EN" "Product.dtd">
<product background_color="#ede9e3" foreground_color="#000000" version="1.0">
<tstart>-1.0E20</tstart>
<tstop>1.0E20</tstop>
<frequency>0.0</frequency>
<table>
<title>Table</title>
<column>
<units>--</units>
<var units="m/s2">ball.obj.state.output.acceleration[0]</var>
</column>
<column>
<units>--</units>
<var units="m/s2">ball.obj.state.output.acceleration[1]</var>
</column>
<column>
<units>--</units>
<var units="N">ball.obj.state.output.external_force[0]</var>
</column>
<column>
<units>--</units>
<var units="N">ball.obj.state.output.external_force[1]</var>
</column>
</table>
</product>
@endverbatim
An example data of the specified table:
@verbatim
------------------------------------------------------------------------
acceleration[0] acceleration[1] external_force[0] external_force[1]
-- -- -- --
------------------------------------------------------------------------
-6.859943e-01 -4.115966e-01 -6.859943e+00 -4.115966e+00
-6.853979e-01 -4.125891e-01 -6.853979e+00 -4.125891e+00
-6.848069e-01 -4.135693e-01 -6.848069e+00 -4.135693e+00
-6.842212e-01 -4.145375e-01 -6.842212e+00 -4.145375e+00
-6.836408e-01 -4.154939e-01 -6.836408e+00 -4.154939e+00
-6.830657e-01 -4.164388e-01 -6.830657e+00 -4.164388e+00
-6.824956e-01 -4.173724e-01 -6.824956e+00 -4.173724e+00
-6.819306e-01 -4.182949e-01 -6.819306e+00 -4.182949e+00
-6.813706e-01 -4.192065e-01 -6.813706e+00 -4.192065e+00
-6.808155e-01 -4.201075e-01 -6.808155e+00 -4.201075e+00
-6.802652e-01 -4.209980e-01 -6.802652e+00 -4.209980e+00
-6.797196e-01 -4.218782e-01 -6.797196e+00 -4.218782e+00
-6.791788e-01 -4.227484e-01 -6.791788e+00 -4.227484e+00
-6.786426e-01 -4.236086e-01 -6.786426e+00 -4.236086e+00
-6.781109e-01 -4.244592e-01 -6.781109e+00 -4.244592e+00
-6.775837e-01 -4.253003e-01 -6.775837e+00 -4.253003e+00
-6.770610e-01 -4.261320e-01 -6.770610e+00 -4.261320e+00
-6.765426e-01 -4.269545e-01 -6.765426e+00 -4.269545e+00
-6.760285e-01 -4.277680e-01 -6.760285e+00 -4.277680e+00
-6.755186e-01 -4.285727e-01 -6.755186e+00 -4.285727e+00
-6.750130e-01 -4.293687e-01 -6.750130e+00 -4.293687e+00
-6.745114e-01 -4.301562e-01 -6.745114e+00 -4.301562e+00
-6.740139e-01 -4.309353e-01 -6.740139e+00 -4.309353e+00
@endverbatim
@see @ref product_dtd "Product.dtd"
@anchor DPExternalPrograms
@section LEVEL3 DP External Programs
The <b>@c 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".
@section LEVEL4 Element extfn Specifications
The <b>@c extfn</b> needs to have 3 element specifications associated with it. These elements are <b>@c fname</b>, <b>@c inputs</b>, and <b>@c outputs</b>.
The <b>@c 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,
which implies it must be built under specific guidelines. Only ONE <b>@c extfn</b> may be defined per DP XML file.
The <b>@c inputs</b> are specified as a list of simulation variable names or <b>@c var</b> elements. The <b>@c outputs</b> is a user defined name list which
provides a unique variable name for each of the external program output arguments. These outputs variables may be used throughout
the product XML specification file wherever a simulation variable name or <b>@c var</b> element is required.
Inputs will be cast to doubles going to the external program, and outputs must be doubles as well.
The following example shows an external program that takes 3 double inputs and return the addition of these 3 inputs.
The product specification file (DP_* file) might look like this:
@verbatim
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE product PUBLIC "-//Tricklab//DTD Product V1.0//EN" "Product.dtd">
<product background_color="#edeceb" foreground_color="#1a1a1a" version="1.0">
<tstart>-1.0E20</tstart>
<tstop>1.0E20</tstop>
<frequency>0.0</frequency>
<extfn>
<fname>/users/hchen3/trick_test/myextfn/dp_test.so</fname>
<inputs>
<var units="m">ball.obj.state.output.position[0]</var>
<var units="m">ball.obj.state.output.position[1]</var>
<var units="m">ball.obj.state.output.position[0]</var>
</inputs>
<outputs>
<measurement>
<var>out</var>
<units>--</units>
</measurement>
</outputs>
</extfn>
<page background_color="#edeceb" foreground_color="#1a1a1a" hcells="0" vcells="0">
<title>Page</title>
<plot background_color="#edeceb" foreground_color="#1a1a1a" grid="Yes" grid_color="#ffffff">
<title>Plot</title>
<curve>
<var units="s">sys.exec.out.time</var>
<var units="--">out</var>
</curve>
</plot>
</page>
</product>
@endverbatim
@section LEVEL4 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.
The following is an example external program source file which reads the three inputs and generates one output as
specified above. The code example below contains comments which explain the function of the code segments.
@code
/* Used for dp test */
// This line should not change from program to program. The content of this function is application specific and up to user to define.
int extGetNextRecord(double *in, int numIn, double *out, int numOut) ;
// This line should not change from program to program. The content of this function is application specific and up to user to define.
int extGetNextRecord(double *in, int numIn __attribute__ ((unused)), double *out, int numOut __attribute__ ((unused)))
{
out[0] = in[0] + in[1] + in[2];
return (0);
}
@endcode
@section LEVEL4 Building The External Program
@section LEVEL5 Linux & IRIX
@li Step 1. cc -c <myprogram1>.c (compile all individual object this way)
@li Step 2. ld -shared -o <myprogram>.so <myfunction1>.o <myfunction2>.o ... <myfunctionN>.o <myLib>.a -lc
@section LEVEL5 MacOS X
@li Step 1. cc -c <myprogram1>.c (compile all individual object this way)
@li Step 2. cc -bundle -o <myprogram>.so <myfunction1>.o <myfunction2>.o ... <myfunctionN>.o <myLib>.a -lc
In the above example, <myprogram>.so is the name that needs to be specified in the DP specification file.
If LD_LIBRARY_PATH doesn't point to the location of your shared object, then you just need to sepcify the full path
of the shared object in the DP sepcification file.
The example above links in <myLib>.a too. It’s that simple.
Do the following to see if your newly created shared object has unresolved dependencies:
@li @b UNIX @b Prompt> nm <myprogram>.so
@section LEVEL4 External Program Summary
To use an external program:
@li Step 1. Build a DP spec file with the program name, inputs and outputs.
@li Step 2. Write an external program (or scam one off a friend).
@li Step 3. Build the external program.
@li Step 4. Run the data products, and hopefully the results you expect will be there.
@section LEVEL4 External Program Proglems And Caveats
@li 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.
@li Make sure you specify the full path of the shared object if LD_LIBRARY_PATH is not defined or doesn't point to the location of the shared object.
@li You cannot scale or bias X values with external programs.
@li External programs convert everything to doubles, and only accept and output doubles.
@li External programs have no notion of unit conversion.
@section LEVEL3 A general DP Product XML File Example
@verbatim
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE product PUBLIC "-//Tricklab//DTD Product V1.0//EN" "Product.dtd">
<product background_color="#ede9e3" foreground_color="#000000" version="1.0">
<tstart>-1.0E20</tstart>
<tstop>1.0E20</tstop>
<frequency>0.0</frequency>
<page background_color="#ede9e3" foreground_color="#000000">
<title>Page</title>
<plot background_color="#ede9e3" foreground_color="#000000" grid="Yes" grid_color="#ffffff">
<title>Plot</title>
<curve>
<var units="--">sys.exec.out.time</var>
<var units="N">ball.obj.state.output.external_force[0]</var>
</curve>
</plot>
<plot background_color="#ede9e3" foreground_color="#000000" grid="Yes" grid_color="#ffffff">
<title>Plot</title>
<curve>
<var units="--">sys.exec.out.time</var>
<var units="N">ball.obj.state.output.external_force[1]</var>
</curve>
</plot>
</page>
</product>
@endverbatim
@see @ref product_dtd "Product.dtd"
*/

130
doxygen/users_guide/dp_session_file.dox_in
View File

@ -1,130 +0,0 @@
/**
@anchor DPSessionFileFormat
@page LEVEL2 DP Session File Format
Since Trick 10, the DP Session file is changed to XML format. The Session XML Document
Type Definitions(DTD) is defined as following:
@see @ref DataProducts "Data Products"
<center>@anchor session_dtd @b Session.dtd</center>
@verbatim
<!-- Trick DP Session definition -->
<!-- V 1.0 -->
<!ELEMENT tstart (#PCDATA)>
<!ELEMENT tstop (#PCDATA)>
<!ELEMENT frequency (#PCDATA)>
<!ELEMENT file (#PCDATA)>
<!ELEMENT dir (#PCDATA)>
<!ELEMENT timename (#PCDATA)>
<!ELEMENT run (dir)>
<!ELEMENT product_files (file+)>
<!ELEMENT session ((tstart|tstop|frequency)*, run+, product_files)>
<!ATTLIST run timename CDATA #IMPLIED>
<!ATTLIST session version CDATA #REQUIRED>
<!-- session@presentation attribute
"simple" - One curve per plot. #plots = #runs x #plot_specifications
"comparison" - Multiple runs per plot.
"delta" - difference of two runs.
"contrast" - some weird thing Danny dreamed up.
-->
<!ATTLIST session presentation CDATA #REQUIRED>
<!-- session@mode attribute
Indicates a restriction on what in a DP file.
"plot" - means that only the plots described in a DP file may be created.
"table" - means that only tables described in a DP file may be created.
default - all plots and tables in the DP may be created.
-->
<!ATTLIST session mode CDATA #IMPLIED>
<!ATTLIST session device CDATA #IMPLIED>
<!ATTLIST session gnuplot_terminal CDATA #IMPLIED>
<!ATTLIST session machine CDATA #IMPLIED>
<!ATTLIST session port CDATA #IMPLIED>
@endverbatim\n
The <b>@c session</b> element is required and is the root element of the Session XML file.
It encloses all the other elements.
The optional <b>@c tstart, @c tstop</b> child elements of <b>@c session</b> specify the data
within this range gets plotted.
The optional <b>@c frequency </b> child element of <b>@c session</b> specifies the delta time
between data points for display purposes. If it is smaller than the delta time of the recorded data
or if it is not defined, then the recorded data frequency is used. If it is greater than the recorded
data delta time, then it is used. It is specified in seconds.
The required <b>@c run</b> child element of @c session can occur once or more times.
It specifies a simulation RUN_ directory as <b>@c dir</b> stated from which to retrieve data.
By default, the time name for each run is @c sys.exec.out.time, however, an optional attribute of each
<b>@c run - @c timename</b> can be specified if a different name other than
the default one is desired.
The required <b>@c product_files</b> child element of <b>@c session</b> can only occur once.
It specifies product specification file(s) to use for this session. Any number (but at least one)
of product specification files may be specified through its <b>@c file</b> element. In other words,
it can have one or more <b>@c file</b> elements. In general the product specification files specify
the type of product parameters to display for the product, and the display attributes for each parameter.
Product specification files are discussed in greater detail in Section @ref DPProductFileFormat "6.2 DP Product File Format".
The required <b>@c version</b> attribute of <b>@c session</b> specifies the version of this file.
The required <b>@c presentation</b> attribute of <b>@c session</b> is only useful when more than
one data set is specified. It can be <b>@c Simple|Comparison|Delta|Contrast</b>. The <b>@c Simple</b>
option will display the data products independently for all data sets specified. The <b>@c Comparison</b> option
will display the data from all data sets in the same display. The <b>@c Delta</b> option subtracts
the nth data set data from the first data set data and presents the result for data sets 2 through n in
the same display. <b>@c Simple</b> is the default option.
@anchor session_device The <b>@c device</b> attribute of <b>@c session</b> specifies the visualization device
for data output. By default, the output data is displayed on the user's current login terminal screen.
Device types are currently <b>@c Terminal (default), @c Printer, and @c File</b>.
@li In order for Printer to work, you need to set your system variables as stated in @ref DPPlotPrinting "6.3 Plot Printing".
The <b>@c gnuplot_terminal</b> attribute of <b>@c session</b> instructs gnuplot to use the given
terminal device for output. The terminals supported are <b>@c X11, @c postscript @c color, @c postscript, @c png, @c eps, and @c aqua
(@c X11 is the default)</b>. The “postscript” terminal yields black-n-white printable files. The @c png will create
an image in Portable Network Graphics format. The @c aqua terminal is for Macintosh and uses native Aqua for plot display.
The optional <b>@c machine, @c port</b> attributes of <b>@c session</b> specify the name of a machine and the port
number for plotting.
@section LEVEL3 DP Session File Example
@verbatim
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE session PUBLIC "-//Tricklab//DTD Session V1.0//EN" "Session.dtd">
<session device="Terminal" gnuplot_terminal="" mode="Plot" presentation="Simple" version="1.0">
<tstart>-1.0E20</tstart>
<tstop>1.0E20</tstop>
<frequency>0.0</frequency>
<run>
<dir>/users/hchen/trick_sims/trunk/SIM_Ball++_L1/RUN_realtime</dir>
</run>
<run>
<dir>/users/hchen/trick_sims/trunk/SIM_Ball++_L1/RUN_test</dir>
</run>
<product_files>
<file>/users/hchen/trick_sims/trunk/SIM_Ball++_L1/DP_Product/DP_test_4.xml</file>
<file>/users/hchen/trick_sims/trunk/SIM_Ball++_L1/DP_Product/DP_test_5.xml</file>
</product_files>
</session>
@endverbatim
@see @ref session_dtd "Session.dtd"
*/

BIN
doxygen/users_guide/figure_1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 81 KiB

BIN
doxygen/users_guide/figure_2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 32 KiB

655
doxygen/users_guide/input_file.dox_in
View File

@ -1,655 +0,0 @@
/**
@anchor Input_File
@page LEVEL2 Input File
The primary interface between the simulation executable and the user is the runstream
input file. The %Trick simulation input file syntax is Python. All Python syntax rules
apply
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.
@section LEVEL3 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 :
ball.obj.state.output.position[0] = 1.0 ;
In this example, ball is the sim object name in the S_define file for a sim object
which contains the data structure named obj, where the obj data structure declaration
is as follows:
@code
class BallSimObject : Trick::SimObject {
...
Ball obj ;
...
}
BallSimObject ball ;
@endcode
<tt>state</tt> is a class found in the Ball class.
@code
class Ball {
...
public:
BallState state; /**< -- Ball state object. */
...
};
@endcode
<tt>output</tt> is a member of the BallState class, and finally <tt>position</tt> is
a member of the BallStateOutput class.
@code
class BallState {
...
public:
BallStateOutput output; /**< trick_units(--) User outputs. */
...
};
class BallStateOutput {
...
public:
double position[2]; /**< trick_units(m) X(horizontal), Y(vertical) position. */
...
};
@endcode
Arrays of simulation parameters may be read and written to with one Python statement.
@verbatim
"""
These variables are declared in the ball structure.
double da[3] ;
double daa[3][3] ;
"""
# Python lists are the equivalent of the C/C++ arrays.
ball.da = [ 1.0 , 2.0 , 3.0 ]
print ball.da
# [ 1.0 , 2.0 , 3.0 ] is printed
ball.daa = [[ 1.0 , 0.0 , 0.0 ] , [ 0.0 , 1.0 , 0.0 ] , [0.0 , 0.0 , 1.0]]
print ball.daa
# [[ 1.0 , 0.0 , 0.0 ] ,
# [ 0.0 , 1.0 , 0.0 ] ,
# [0.0 , 0.0 , 1.0]]
# is printed
@endverbatim
@section LEVEL3 Accessing Simulation Enumerated Types
Global Enumerations are available through the "trick" module.
@verbatim
# from sim_services/include/Flag.h
print trick.True trick.False trick.Yes trick.No
1 0 1 0
@endverbatim
@section LEVEL3 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
%Trick simulation services routines are available later in this chapter.
@verbatim
# Trick simulation services routines are called by "trick.<function>".
trick.exec_get_sim_time()
trick.checkpoint(100.0)
trick.stop(300.0)
# C User model functions are also called by "trick.<function>".
trick.ball_print(ball.state)
# C++ User model class methods are called by referencing the full object path just like in C++
ball.obj.state.print_position()
@endverbatim
When calling functions, intrinsic typed simulation variables, e.g. int or double, will not work directly
as intrisic typed arguments.
@verbatim
// If we have a c function
void foo( double d) ;
// And a structure with a variable declared as this
double length ; /* (m) length */
@endverbatim
This call in the input will not work
@verbatim
# Will not work
foo(length)
@endverbatim
The reason is that in python space the variable length is an object that contains both the value of length
and the units. The built in python command float() will strip the units off leaving a double that can be
used in the function call.
@verbatim
# Works
foo(float(length))
@endverbatim
Structure and class variables do not carry around units, and therefore the units do not have to be removed.
@section LEVEL3 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.
The first method is to call the Trick::MemoryManager routines to allocate memory. This is the preferred method.
There are 3 Trick::MemoryManager calls with varying arguments that can be used to allocate memory
@code
trick.TMM_declare_var_s("declaration")
trick.TMM_declare_var_1d("enh_type_spec", e_elems)
trick.alloc_type(e_elems , "enh_type_spec")
# Some examples using a c++ declaration
# double * foo ;
# All 3 of the following statments allocates the same amount of memory
foo = trick.TMM_declare_var_s("double[6]")
foo = trick.TMM_declare_var_1d("double", 6)
foo = trick.alloc_type(6 , "double")
# Some examples using a c++ declaration
# double ** food ;
# All 3 of the following statments allocates the same amount of memory
food = trick.TMM_declare_var_s("double *[3]")
food[0] = trick.TMM_declare_var_s("double [4]")
food[1] = trick.TMM_declare_var_s("double [5]")
food[2] = trick.TMM_declare_var_s("double [6]")
food = trick.TMM_declare_var_1d("double *", 3)
food[0] = trick.TMM_declare_var_1d("double", 4)
food[1] = trick.TMM_declare_var_1d("double", 5)
food[2] = trick.TMM_declare_var_1d("double", 6)
food = trick.alloc_type(3, "double *")
food[0] = trick.alloc_type(4, "double")
food[1] = trick.alloc_type(5, "double")
food[2] = trick.alloc_type(6, "double")
@endcode
Memory allocated using the above routines are tracked by the memory manager and is checkpointable and data recordable.
The second method is to call the wrapped constructor of the class directly. This is analogous to declaring local
variables in C/C++ routines. And like local variables in C/C++ if the python variable goes out of scope in the
input file, then python will try and free the memory associated with the local object. Memory allocated this
way is not checkpointable or data recordable.
For example if we are trying to instantiate a new C++ "Ball" object in the input file.
@verbatim
# The new_ball_1 instantiation is at the top level, new_ball_1 will not be freed.
new_ball_1 = trick.Ball() ;
# The new_ball_2 instantiation is in the function foo.
# When foo returns new_ball_2 will be freed by python
def foo():
new_ball_2 = trick.Ball() ;
@endverbatim
To stop python from freeing this memory we must tell python that it does not own the memory.
This can be done in two ways. 1) Tell Python it does not own the memory by modifying the
<tt>thisown</tt> flag. 2) Use a non-constructor routine that allocates memory and returns that
to the Python variable.
@verbatim
# In the above example, we can avoid new_ball_2 from being freed
# when foo returns by setting the thisown flag to 0 in the new_ball_2 object.
def foo():
new_ball_2 = trick.Ball() ;
new_ball_2.thisown = 0 ;
# Alternatively we could call a non-constructor C/C++ routine that returns a new Ball
# object to python. The python interpreter does not sense it allocated anything and
# will not free it.
"""
C++ code for get_new_ball_obj()
Ball * get_new_ball_obj() {
return(new Ball) ;
}
"""
def foo():
new_ball_2 = trick.get_new_ball_obj() ;
@endverbatim
@section LEVEL3 Comments
Comments in Python come in two forms.
@verbatim
# A single line comment starts with a '#' sign
"""
Multi line comments are enclosed in
three sets of double quotes.
"""
@endverbatim
@section LEVEL3 Nested File Inclusion
There are several ways to include files in Python.
@verbatim
# One way is to use the execfile command
execfile("Modified_data/data_record.py")
# Another way is to make the included file a module and import it.
# Import search paths may be added using the sys.path.append command.
sys.path.append("/my/python/dir") ;
import my_new_module
@endverbatim
@section LEVEL3 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.
@verbatim
my_position = ball.obj.state.output.position
my_position[0] = 4.5
my_postion [1] = 6.7
print ball.obj.state.output_position
# printout would read "4.5, 6.7"
@endverbatim
@section LEVEL3 Environment Variables
Environment Variables are available through the Python <tt>os.getenv</tt> call
@verbatim
print os.getenv("TRICK_CFLAGS")
@endverbatim
@section LEVEL3 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
use for that parameter. However, %Trick users also have certain control over units specification
from the input file.
trick.attach_units() attaches a unit to a value or some Python objects.
@verbatim
"""
This variables is declared in the ball structure.
double position[3] ; /* (m) X,Y,Z postion */
"""
# Assign X position to 2m
ball.position[0] = trick.attach_units( "m" , 2.0 )
# Automatic units conversion is done if the attached unit is compatible with the variable.
# Assign Y position to 2ft
ball.position[1] = trick.attach_units( "ft" , 2.0 )
# Error is raised.
ball.position[2] = trick.attach_units( "ft/s" , 3.0 )
# Units may be attached to python lists and assigned to the array with one statement
# Automatic units conversion is done on the entire list.
ball.position = trick.attach_units( "ft" , [1.0 , 2.0, 3.0] )
# Lists may even include values of different units. Automatic units conversion is
# done element by element.
ball.position = [trick.attach_units( "ft" , 1.0 ) , trick.attach_units( "m" , 2.0 , trick.attach_units( "cm" , 3.0)] )
@endverbatim
Printing parameters in the Python script will include the attached units.
@verbatim
print ball.position
[1.0m , 2.0m , 3.0m]
@endverbatim
@section LEVEL3 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>").
@verbatim
# simple statement
trick.add_read(1.0 , "ball.obj.state.out.postion[0] = 4.0") ;
# Use triple quotes for multi line input or code segments that include quotes.
trick.add_read(2.0 , """
ball.obj.state.out.postion[0] = 4.0
print "This is a quoted string inside the triple quotes"
"""
# Use a local python variable called read to get an appearance similar previous %Trick input files
read = 4.0
trick.add_read(read , ... )
read += 0.2
trick.add_read(read , ... )
read = 5.0
trick.add_read(read , ... )
@endverbatim
@section LEVEL3 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
in the future.
@verbatim
# Freezes immediately
trick.freeze()
# Freezes at an absolute time
trick.freeze(100.0)
# Freezes 5 seconds relative from the current sim_time
trick.freeze(trick.exec_get_sim_time() + 5.0)
@endverbatim
@section LEVEL3 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
in the future.
@verbatim
# Checkpoints immediately
trick.checkpoint()
# Checkpoints at an absolute time
trick.checkpoint(100.0)
# Checkpoints 5 seconds relative from the current sim_time
trick.checkpoint(trick.exec_get_sim_time() + 5.0)
@endverbatim
@section LEVEL3 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
in the future.
@verbatim
# Stop immediately
trick.stop()
# Stop at an absolute time
trick.stop(100.0)
# Stop 5 seconds relative from the current sim_time
trick.stop(trick.exec_get_sim_time() + 5.0)
@endverbatim
@anchor Input_File_Events
@section LEVEL3 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 automatically 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 @ref Event_Processing "Event Processing".
@section LEVEL4 Basic Event Usage
@verbatim
# Create an event that can be viewed and manipulated in MTV, and can be checkpointed
<event name> = trick.new_event("<event name>")
# Alternatively, you can create an unnamed event (hidden in MTV and not checkpointable)
<event name> = trick.new_event()
# Set the event condition
# (note that because there can be multiple conditions, you must specify a condition index starting at 0)
# The number of conditions an event can have is unlimited 0...n
# When an (enabled) event condition is true, we say it has "fired"
<event name>.condition(<index>, "<input text string>" [,"<optional comment displayed in mtv>"])
# Set the condition evaluation such that ANY fired condition will cause all of this event's (enabled) actions to run
# (conditions are ORed -- this is the default)
<event name>.condition_any()
# Set the condition evaluation such that ALL (enabled) conditions must fire to cause all of event's (enabled) actions to run
# (conditions are ANDed)
<event name>.condition_all()
# Set the frequency that the event condition(s) will be evaluated at
<event name>.set_cycle(<cycle time in seconds>)
# Set the event action to occur when any/all condition(s) have fired
# (again specify an index because there can be multiple actions)
# The number of actions an event can have is unlimited 0...n
<event name>.action(<index>, "<input text string>", [,"<optional comment displayed in mtv>"])
# Set the event active so that it is processed (default is not active, and event is also deactivated when fired)
<event name>.activate() # the opposite would be <event name>.deactivate()
# Note that your event will be a one-time thing unless you put the activate statement in your action
# This behavior can be overridden using "manual mode" described below
# Add the event to the input processor's list of events (it will be processed at top of frame before scheduled jobs)
trick.add_event(<event name>)
@endverbatim
@section LEVEL4 Advanced Event (Malfunction) Usage
@verbatim
# Insert the event before/after a "target" job so that it is evaluated then (as opposed to top of frame)
# Note that the event cycle is ignored in this case, the event takes on the cycle time of the target job
# Also note that an event can be inserted before/after multiple target jobs,
# in which case it will be evaluated multiple times per frame
# The job name string is the "sim_object.job_name" from the S_define file.
# The job instance is used to specify which instance of the job to use if identically named jobs are
# multiply defined in a sim object. If the argument is not specified, the first instance of the is the default.
trick.add_event_before(<event name>, "<job name string>" [, <job instance> = 1])
trick.add_event_after(<event name>, "<job name string>" [, <job instance> = 1])
# Remove an event from everywhere it's been added (you can then subsequently add the event again if you want)
trick.remove_event(<event_name>)
# Delete an event permanently from the sim so that you can no longer add it again
trick.delete_event(<event_name>)
# Use a model variable or job as a condition
# It is more optimal to use model code as a condition, because of the python parsing involved in a normal condition()
# Variable (the variable's value will be taken as the condition boolean) :
<event name>.condition_var(<index>, "<variable name>" [,"<optional comment displayed in mtv>"])
# Job (the job's return value will be taken as the condition boolean) :
<event name>.condition_job(<index>, "<job name>" [,"<optional comment displayed in mtv>"])
# Any combination of condition(), condition_var(), or condition_job() can be used for your malfunction condition(s).
# NOTE: If the job is something you created just for use in malfunctions (e.g. it is not a scheduled job),
then it must be specified once and only once in the S_define file as a "malfunction" class job.
# Set an event condition's "hold" on so that when it fires, it stays in the fired state, causing actions to run every cycle
# (the default is hold off so fire only once)
<event name>.condtion_hold_on(<index>) # the opposite would be <event name>.condition_hold_off(<index>)
# Note that you would still need "activate" in your action otherwise hold_on won't have any effect.
# Disable a condition from being evaluated (default is enabled)
<event name>.condition_disable(<index>) # the opposite would be <event name>.condition_enable(<index>)
# Use a model job as an action
# It is more optimal to use model code as an action, because of the python parsing involved in a normal action()
<event name>.action_job(<index>, "<job name>" [,"<optional comment displayed in mtv>"])
# Turn a model job ON/OFF as an action
<event name>.action_job_on(<index>, "<job name>" [,"<optional comment displayed in mtv>"])
<event name>.action_job_off(<index>, "<job name>" [,"<optional comment displayed in mtv>"])
# Any combination of action(), action_job(), action_job_on(), or action_job_off() can be used for your malfunction action(s).
# NOTE: If the job is something you created just for use in malfunctions (e.g. it is not a scheduled job),
then it must be specified once and only once in the S_define file as a "malfunction" class job.
# Disable an action from being run (default is enabled)
<event name>.action_disable(<index>) # the opposite would be <event name>.action_enable(<index>)
# Manually fire the event once now, so that its actions will run once now
# (this event is now in "manual mode" and its conditions will not be evaluated until manual_done commanded)
<event name>.manual_fire()
# Manually set an event as fired and hold on, so that its actions will run each cycle
# (this event is now in "manual mode" and its conditions will not be evaluated until manual_done commanded)
<event name>.manual_on()
# Manually set an event as not fired, so that its actions will not run
# (this event is now in "manual mode" and its conditions will not be evaluated until manual_done commanded)
<event name>.manual_off()
# Exit "manual mode" for this event and return to normal processing of its conditions
<event name>.manual_done()
@endverbatim
@section LEVEL4 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 @ref real_time_injector "Real Time Variable Injector".
@section LEVEL4 Accessing the current Event state
@verbatim
<event name>.condtion_fired(<index>) # boolean: test if a particular event condition fired this cycle
<event name>.condition_fired_count(<index>) # integer: number of times a particular event condition has fired
<event name>.condtion_fired_time(<index>) # double: last sim time a particular event condition has fired
<event name>.action_ran(<index>) # boolean: test if a particular event action ran this cycle
<event name>.action_ran_count(<index>) # integer: number of times a particular event action has run
<event name>.action_ran_time(<index>) # double: last sim time a particular event action has run
<event name>.fired # boolean: test if the event conditions setup evaluated to true this cycle
<event name>.fired_count # integer: number of times this event has fired
<event name>.fired_time # double: last sim time this event has fired
<event name>.ran # boolean: test if any event action ran this cycle
<event name>.ran_count # integer: number of times this event has run an action
<event name>.ran_time # double: last sim time this event has run an action
<event name>.manual # boolean: test if this event is in "manual mode"
<event name>.manual_fired # boolean: test if this event was fired manually this cycle
@endverbatim
@section LEVEL4 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.
@verbatim
# In this event example:
# evaluate velocity before integration...
# if it is over 50, print a message
# if it is over 100, reset the velocity to 0 after data recording is done for this frame
# if our sim has gone past 500 seconds, do not reset velocity when it goes over 100,
# but instead shutdown when velocity goes over 200
vel_event = trick.new_event("vel_event")
vel_event.condition(0, "trick.as_pyfloat(ball.obj.state.output.velocity) > 50.0")
vel_event.condition(1, "trick.as_pyfloat(ball.obj.state.output.velocity) > 100.0")
vel_event.action(0, """
print "VELOCITY = ", ball.obj.state.ouput.velocity
vel_event.activate()
""")
vel_event.activate()
over100_event = trick.new_event("over100_event")
over100_event.condition(0, "vel_event.condition_fired(1)")
over100_event.action(0, "trick.as_pyfloat(ball.obj.state.output.velocity) = 0.0")
over100_event.action(1, "trick.stop()")
over100_event.action(2, "over100_event.activate()")
over100_event.action_disable(1)
over100_event.activate()
change_event = trick.new_event("change_event")
change_event.condition(0, "trick.exec_get_sim_time() > 500.0")
change_event.action(0, """
over100_event.action_disable(0)
over100_event.action_enable(1)
vel_event.condition(1, "trick.as_pyfloat(ball.obj.state.output.velocity) > 200.0")
""")
change_event.activate()
trick.add_event_before(vel_event, "ball.obj.state_integ")
trick.add_event_before(change_event, "ball.obj.state_integ")
trick.add_event_after(over100_event, "data_record_group1.Ball")
@endverbatim
@section LEVEL3 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.
@userdesc Look for a %Trick flag icon like this beside each user callable function for details in the Class pages listed below.\n\n
@par Checkpointing:
Trick::MemoryManagerWrapper
@par Data Recording setup and control:
Trick::DRAscii\n
Trick::DRBinary\n
Trick::DRHDF5\n
Trick::DataRecordDispatcher\n
Trick::DataRecordGroup
@par Debugging:
Trick::EchoJobs\n
Trick::FrameLog
@par Dynamic Data declaration and management:
Trick::MemoryManager
@par Event/Malfunction creation, simulation mode control:
Trick::IPPython\n
@par Event/Malfunction configuration and access:
Trick::IPPythonEvent
@par Executive control:
Trick::Executive
@par Master/Slave setup:
Trick::Master\n
Trick::SlaveInfo\n
Trick::Slave\n
Trick::MSSocket
@par Messaging setup:
Trick::MessagePublisher\n
Trick::MessageSubscriber\n
@par Monte Carlo setup:
Trick::MonteCarlo
@par Real-time control:
Trick::RealtimeSync
@par Timer (itimer) control:
Trick::Timer
@par Variable Server control and commands:
Trick::VariableServer\n
Trick::VariableServerThread
@section LEVEL3 I Just Want to Know How Do I Set this Value...
This @htmlonly
<a href="appendix_a_input_table.html"> Table of Input File Differences</a>
@endhtmlonly
was originally put together to help Trick 07 users convert to Trick 10. But it is also a concise
list of commands available to the user.
*/

361
doxygen/users_guide/installing_trick.dox_in
View File

@ -1,361 +0,0 @@
/**
@page LEVEL1 Installing Trick
This section discusses the %Trick system hardware and software requirements and preparations
necessary for a %Trick installation. It also goes into a step-by-step explanation of how to install
trick. To obtain a %Trick software release, login as a %Trick user on the %Trick website:
http://trick.jsc.nasa.gov, and download an installer.
@section LEVEL2 Trick System Hardware and Software Requirements
%Trick runs on PCs running Linux and Macs running OSX. In
general any System V/POSIX compatible UNIX workstation with Motif X Windows should accept the
%Trick software with very little source code porting because %Trick C++ source code is written for
ANSI (function prototyping required) UNIX compilers.
@section LEVEL2 Disk Space and Run-Time Memory Requirements
The current %Trick Release with the "Ball" tutorial requires approximately 350 MB.
External simulation packages may require several gigabytes. When users
are developing simulations, their additional disk requirements will vary based on the size of
the simulation.
Simulation run-time memory or Random Access Memory (RAM) requirements depend greatly on the
models within the simulation. As of this writing in 2010, we recommend systems with 4Gb of RAM.
@section LEVEL2 Prerequisite Packages
%Trick makes use of some free third party utilities. All the following products are used by %Trick
and may installed as part of your OS distribution or can be downloaded from the internet.
<center>
<table>
<tr><th>Product</th><th>Version</th><th>Description</th></tr>
<tr><td>gcc and g++</td><td>4.0+</td><td>Compiler</td>
<tr><td>java</td><td>1.6</td><td>Java virtual machine used for %Trick GUIs</td>
<tr><td>make</td><td>3.78+</td><td>Handles all makes within %Trick</td>
<tr><td>openmotif</td><td>2.2.0</td><td>X Window stuff</td>
<tr><td>perl</td><td>5.6+</td><td>Used for CP, ICG, MIS and various utilities</td>
<tr><td>python</td><td>2.2.3+</td><td>Used for input processor</td>
<tr><td>swig</td><td>1.3.29+</td><td>Used for input processor interface</td>
</table>
<b>Table 2. Third Party Dependencies</b>
</center>
@section LEVEL3 Installing Linux Prerequisites
Each Linux distribution has their own method for installing packages.
RedHat/Centos/Scientific distributions use <b>yum</b>. Most of the prerequisite packages are
included in the development libraries and tools. These packages may already be installed
on your machine. If not, they may be installed with the following two commands (as root).
@section LEVEL4 Development Tools
For RedHat/Centos/Scientific 6.x installations
<tt><b>UNIX Prompt></b>yum groupinstall "Development Tools"</tt><br>
For RedHat/Centos/Scientific 5.x installations
<tt><b>UNIX Prompt></b>yum groupinstall "Development Libraries"</tt><br>
<tt><b>UNIX Prompt></b>yum groupinstall "Development Tools"</tt><br>
@section LEVEL4 Clang/LLVM
Clang is require to build the Interface Code Generator (ICG).
RHEL/CentOS/Scientific Linux pre-built packages are provided on the
<a href="https://trick.jsc.nasa.gov/download/gnu/download_gnu.php"> freeware page.</a>
These binary packages are based on LLVM 3.1.
@section LEVEL4 OpenMotif
Use yum to install openmotif and the openmotif development libraries.
<tt><b>UNIX Prompt></b>yum install openmotif openmotif-devel</tt><br>
Other linux distributions may require additional packages to be installed and may not use
<b>yum</b> to install them.
@section LEVEL4 Java
To compile Trick from source the Java Development Kit is required. At the time of this writing Trick
requires JDK 1.6 or greater.
For machines not needing to build Trick from source, download and install
<a href="http://java.com/en/download/index.jsp">Java Runtine Environment (JRE)</a>.
@section LEVEL3 Installing MacOSX 10.8 and 10.9 Prerequisites
Macs require several additional development tools to build %Trick. All of these are freely available
off the web. Websites and installation procedures may change over time. These instructions are
current as of December 12, 2013.
@section LEVEL4 XCode
Install Xcode from the AppStore. Xcode contains many of the the compiler and related tools
to compile %Trick. %Trick requires the command line tools within Xcode to be installed. After Xcode is installed,
the command line tools may be installed under Preferences...->Downloads.
@section LEVEL4 Clang/LLVM
Clang is require to build the Interface Code Generator (ICG).
The Mac binary package may be found on the <a href="http://llvm.org/releases/download.html">LLVM website.</a>
As of this writing ICG compiles using either clang/llvm version 3.1 or 3.3.
@section LEVEL4 XQuartz
X11 is no longer included with Mac OSX. Download <a href="http://xquartz.macosforge.org">XQuartz</a> that
provides X11 capabilities for MacOSX.
@section LEVEL4 Java
To compile %Trick from source the Java Development Kit is required. At the time of this writing %Trick
requires JDK 1.6 or greater.
For machines not needing to build %Trick from source, download and install
<a href="http://java.com/en/download/index.jsp">Java Runtine Environment (JRE)</a>.
@section LEVEL4 Fink
Fink provides a collection of open source software to MacOSX. Several development tools required
by %Trick may be installed through <a href="http://www.finkproject.org">Fink</a>.
Fink uses rsync as part of it's update process. If you are behind a firewall, rsync may be disabled.
Fink may use CVS as an alternative to rsync. To switch to CVS try this.
<tt><b>UNIX Prompt></b>fink selfupdate-cvs</tt><br>
MacPorts is another project similar to Fink and may provide equivalent packages.
Using MacPorts or compiling OpenMotif from source may require editting %Trick Makefiles to add
the directories to the OpenMotif header files and libraries.
@section LEVEL4 SWIG
SWIG may be installed through fink.
<tt><b>UNIX Prompt></b>fink install swig</tt><br>
@section LEVEL4 OpenMotif
OpenMotif may be installed multiple ways, but Fink is the preferred way for %Trick. %Trick searches for
the Openmotif header files and libraries in the locations where Fink installs files.
Install Openmotif using fink.
<tt><b>UNIX Prompt></b>fink install openmotif4</tt><br>
<tt><b>UNIX Prompt></b>fink install openmotif4-shlib</tt><br>
@section LEVEL4 Gnuplot
Gnuplot is not a requirement to run %Trick. It is an optional alternative plotting package. Installing
gnuplot through fink will include a very large number of depenent packages.
<tt><b>UNIX Prompt></b>fink install gnuplot</tt><br>
@section LEVEL2 Trick Installation
This section describes how to install the *.exe self-inflating executable.
@par Get the %Trick self inflating executable off of the %Trick website.
-# Go to <a href="http://trick.jsc.nasa.gov">http://trick.jsc.nasa.gov</a> and login. Register for
a user account if you are not a %Trick user.
-# Click on the “Download” tab and then the link to “%Trick”.
-# The latest release and documentation is maintained there. The installer should look something
like “trick_<version>.exe”.
-# Download the installer.
@par Run the %Trick self inflating install package
-# <tt><b>UNIX Prompt></b> chmod +x trick_<version>.exe</tt>
-# <tt><b>UNIX Prompt></b> ./trick_<version>.exe</tt>
-# Answer the questions that it asks you.
-# Answer "n" to the question, "Do you want this script to compile after extraction?" if you want
to modify the configuration options of the installation. See the next section for configuration
options.
-# %Trick will be expanded into the ${TRICK_HOME} directory that you specify.
@section LEVEL2 Changing Configuration Options for Trick Installations.
To change the configuration options start in the ${TRICK_HOME} directory.
@code
# The options are listed below
UNIX Prompt> ./configure [OPTIONS]
# Run confiugre with the help argument to see all available options.
UNIX Prompt> ./configure --help
@endcode
The configuration script allows the user to specify the location of many of the compilation tools
and libraries that Trick uses. Here are the current options in alphabetical order.
@section LEVEL3 Binary File Descriptor Library
--bfd=/path/to/bfd/home [/usr]
The Binary File Descriptor (BFD) library translates addresses to function and file names. It is used
with the sim_services/UnbalanceMem class. This option is a Linux only feature.
The BFD library is found in the binutils-devel rpm on RHEL systems.
@section LEVEL3 Bison
--bison=/path/to/bison [/usr/bin/bison]
Bison is parser generator. Bison is only required for Trick developers.
@section LEVEL3 C compiler
--cc=/path/to/cc [/usr/bin/cc]
The C compiler. This specifies the default C compiler. The TRICK_CC environment variable overrides
this value.
@section LEVEL3 C++ compiler
--cxx=/path/to/cxx [/usr/bin/c++]
The C++ compiler. This specifies the default C++ compiler. The TRICK_CPPC environment variable overrides
this value.
@section LEVEL3 Distributed MultiThreaded Checkpointing
--dmtcp=/path/to/dmtcp []
The Distributed MultiThreaded Checkpointing (DMTCP) feature is an optional checkpoining tool used by Trick.
@section LEVEL3 Flex
--flex=/path/to/flex [/usr/bin/flex]
Flex is the fast lexical analyser generator. Flex is only required for Trick developers.
@section LEVEL3 GNU Scientific Library
--gsl=/path/to/gsl []
The GNU scientific library provides random number generators used by the Trick math library. It is an optional
package.
@section LEVEL3 Google Test
--gtest=/path/to/gtest []
The Google Test application is used in Trick unit testing. Gtest is only required for Trick developers.
@section LEVEL3 Linker
--ld=/path/to/ld [/usr/bin/c++]
The linker defaults to the same as the C++ compiler.
@section LEVEL3 Motif
--motif=/path/to/motif [/usr or /sw]
The openmotif home location. Motif is a required package for Trick compiles.
@section LEVEL3 Perl
--perl=/path/to/perl [/usr/bin/perl]
Specify an alternative perl Interpreter.
@section LEVEL3 Python
--python=/path/to/python [/usr/bin/python]
Specify an alternative python Interpreter.
@section LEVEL3 SWIG
--swig=/path/to/swig [/usr/bin/swig]
The location of the SWIG executable. SWIG 1.3.29 or greater is required for Trick to compile.
@section LEVEL3 TPRO Central Timing Equipment
--tprocte=/path/to/tprocte []
The location of the TPRO Central Timing Equipment (CTE) home directory. The TPRO software is an
optional package to use with Trick.
@section LEVEL2 Recompiling Trick After Installing
To re-compile %Trick post-install:
<tt><b>UNIX Prompt></b> cd ${TRICK_HOME}</tt><br>
<tt><b>UNIX Prompt></b> make clean</tt><br>
<tt><b>UNIX Prompt></b> make</tt>
@section LEVEL2 Trick Environment Variables
Now that %Trick has been extracted and built into the desired location, the user must set
his/her environment to run %Trick. %Trick runs with [t]csh and bash
@section LEVEL3 Required Environment Variables
TRICK_HOME is the only required environment variable. TRICK_HOME is set to the root of
the %Trick distribution. Setting TRICK_HOME may be done in any number of startup files read
by your shell of choice.
@verbatim
# bash
export TRICK_HOME=/path/to/trick
# [t]csh
setenv TRICK_HOME "/path/to/trick"
@endverbatim
@section LEVEL3 Optional Environment Variables
There are many environment variables that control the compilation and running of %Trick. These
environment varaibles may be set in your login startup file of choice. The most important
environment variablse are listed below. See section @ref Trick_Environment for more information
on other environment varaibles.
@section LEVEL4 Adding ${TRICK_HOME}/bin to PATH
${TRICK_HOME}/bin can be added to the PATH environment variable for convenience. It is not necessary
for compiling or running sims.
@verbatim
# bash
PATH="${PATH}:/path/to/trick"
# [t]csh
setenv PATH "${PATH}:/path/to/trick"
@endverbatim
@section LEVEL4 TRICK_CFLAGS
TRICK_CFLAGS includes header file search directories, macro define variables, and compiler flags.
TRICK_CFLAGS is used with each C file compilation.
@verbatim
# sets debug symbols on and activate lots of compiler warnings and a model include path
# bash
export TRICK_CFLAGS="-g -Wall -Wextra -I/path/to/my/models"
# [t]csh
setenv TRICK_CFLAGS "-g -Wall -Wextra -I/path/to/my/models"
@endverbatim
@section LEVEL4 TRICK_CXXFLAGS
TRICK_CXXFLAGS includes header file search directories, macro define variables, and compiler flags.
TRICK_CXXFLAGS is used with each C++ file compilation.
@verbatim
# sets debug symbols on and activate lots of compiler warnings
# bash
export TRICK_CXXFLAGS="-g -Wall -Wextra -I/path/to/my/models"
# [t]csh
setenv TRICK_CXXFLAGS "-g -Wall -Wextra -I/path/to/my/models"
@endverbatim
*/

16
doxygen/users_guide/introduction.dox_in
View File

@ -1,16 +0,0 @@
/**
@page LEVEL1 Introduction
The responsibility for this document lies with the Simulation and Graphics Branch (ER7) of the
Automation, Robotics and Simulation Division of the NASA JSC Engineering Directorate.
The purpose of this document is to provide %Trick simulation developers and users with a detailed
user’s reference guide on how to install %Trick, use %Trick processors and utilities, and how to
operate a simulation from execution to data post processing.
To see how to build a simulation from scratch, refer to the %Trick Tutorial document. For details
about the high level design of %Trick, refer to the %Trick Design document. Details of specific
NASA programmatic math models and simulations will not be addressed in this document.
*/

127
doxygen/users_guide/main_page.dox_in
View File

@ -1,127 +0,0 @@
/**
@page users_guide Trick User's Guide
@subpage u01 "1 Introduction"<br>
@subpage u02 "2 Overview and Purpose of Functions"<br>
@subpage u03 "3 Installing Trick"<br>
@subpage u04 "4 Building a Simulation"<br>
@subpage u0401 "4.1 Model Source Code"<br>
@subpage u0402 "4.2 Trick Environment"<br>
@subpage u0403 "4.3 Simulation Definition File (S_define)"<br>
@subpage u0404 "4.4 Making the Simulation"<br>
@subpage u05 "5 Running a Simulation (S_main_${TRICK_HOST_CPU}.exe)"<br>
@subpage u0501 "5.1 Input File"<br>
@subpage u0502 "5.2 Runtime GUIs"<br>
@subpage u0503 "5.3 Runtime Output"<br>
@subpage u06 "6 Data Products (DP)"<br>
@subpage u0601 "6.1 DP Session File Format"<br>
@subpage u0602 "6.2 DP Product File Format"<br>
@subpage u0603 "6.3 Plot Printing"<br>
@subpage u0604 "6.4 Data Products GUIs"<br>
@subpage u07 "7 Simulation Capabilities"<br>
@subpage u0701 "7.1 Executive Scheduler"<br>
@subpage u0702 "7.2 Input Processor"<br>
@subpage u0703 "7.3 Event Manager"<br>
@subpage u0704 "7.4 Real-time"<br>
@subpage u0705 "7.5 Real-time Clock"<br>
@subpage u0706 "7.6 Real-time Sleep Timer"<br>
@subpage u0707 "7.7 Real-time Injector"<br>
@subpage u0708 "7.8 Monte Carlo"<br>
@subpage u0709 "7.9 Master Slave"<br>
@subpage u0710 "7.10 Data Record"<br>
@subpage u0711 "7.11 Checkpoints"<br>
@subpage u0712 "7.12 MemoryManager"<br>
@subpage u0713 "7.13 Integrator"<br>
@subpage u0714 "7.14 Frame Logging"<br>
@subpage u0715 "7.15 Debug Pause"<br>
@subpage u0716 "7.16 Echo Jobs"<br>
@subpage u0717 "7.17 Variable Server"<br>
@subpage u0718 "7.18 Status Message System"<br>
@subpage u0719 "7.19 Command Line Arguments"<br>
@subpage u0720 "7.20 Environment (Unix Shell)"<br>
@subpage u0721 "7.21 Standard Template Library checkpointing"<br>
@subpage u08 "8 Simulation Utilities"<br>
@subpage u0801 "8.1 Trickcomm"<br>
@subpage u0802 "8.2 Units Conversion"<br>
@subpage u0803 "8.3 Math Utilities"<br>
@subpage u0804 "8.4 Abstract Data Types"<br>
@subpage u09 "9 Miscellaneous Trick Tools"<br>
@subpage u10 "10 Converting From Trick 7 To Trick 10"<br>
*/
// section 1
#include "introduction.dox_in"
// section 2
#include "overview.dox_in"
// section 3
#include "installing_trick.dox_in"
// section 4
#include "building_simulation.dox_in"
#include "model_source_code.dox_in"
#include "trick_env.dox_in"
#include "S_define.dox_in"
#include "CP.dox_in"
// section 5
#include "S_main.dox_in"
#include "input_file.dox_in"
#include "sim_services/ExternalApplications/docs/main_page.dox_in"
#include "runtime_output.dox_in"
// section 6
#include "data_products.dox_in"
#include "dp_session_file.dox_in"
#include "dp_product_file.dox_in"
#include "dp_printing.dox_in"
#include "dp_guis.dox_in"
// section 7
#include "simulation_capabilities.dox_in"
#include "sim_services/Executive/docs/main_page.dox_in"
#include "sim_services/InputProcessor/docs/main_page.dox_in"
#include "sim_services/EventManager/docs/main_page.dox_in"
#include "sim_services/RealtimeSync/docs/main_page.dox_in"
#include "sim_services/Clock/docs/main_page.dox_in"
#include "sim_services/Timer/docs/main_page.dox_in"
#include "sim_services/RealtimeInjector/docs/main_page.dox_in"
#include "sim_services/MonteCarlo/docs/main_page.dox_in"
#include "sim_services/MasterSlave/docs/main_page.dox_in"
#include "sim_services/DataRecord/docs/main_page.dox_in"
//#include "sim_services/CheckPointRestart/docs/main_page.dox_in"
#include "sim_services/MemoryManager/docs/main_page.dox_in"
#include "sim_services/Integrator/main_page.dox_in"
#include "sim_services/FrameLog/docs/main_page.dox_in"
#include "sim_services/DebugPause/main_page.dox_in"
#include "sim_services/EchoJobs/docs/main_page.dox_in"
#include "sim_services/VariableServer/docs/main_page.dox_in"
#include "sim_services/Message/docs/main_page.dox_in"
#include "sim_services/CommandLineArguments/docs/main_page.dox_in"
#include "sim_services/Environment/docs/main_page.dox_in"
#include "sim_services/STL/docs/main_page.dox_in"
// section 8
#include "simulation_utilities.dox_in"
#include "trick_utils/comm/main_page.dox_in"
#include "trick_utils/units/main_page.dox_in"
#include "trick_utils/math/main_page.dox_in"
#include "trick_utils/trick_adt/main_page.dox_in"
// section 9
#include "misc_utils.dox_in"
// section 10
#include "appendix_a.dox_in"

164
doxygen/users_guide/misc_utils.dox_in
View File

@ -1,164 +0,0 @@
/**
@page LEVEL1 Other Trick Tools
@section LEVEL3 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
developers.
@par
The ICG parses developer created data structure definition files and generates
runtime executive input/output source code. The source code generated is compiled
into a simulation which uses the types parsed.
@par
The command syntax for the ICG is as follows (with restrictions outlined afterward):
@par
<tt><b>UNIX Prompt></b> ICG [-d] [-D <define>] [-U <undefine>] <filename>.h</tt><br>
<tt><b>UNIX Prompt></b> ICG -u</tt>
@par
The ICG can process multiple files at a
time and does accept UNIX wild card character designations (*.h) in the filename. The
optional ‘-d’ (for debug) argument tells the ICG to echo every character successfully
parsed from the file; if a syntax error occurs in the file, the user will know the exact
character which caused the problem. The optional ‘-D’ and ‘-U’ arguments are compiler
directives, used in concert with #defines, #undefs etc. and work like their CFLAGS
counterparts. The optional ‘-u’ argument tells ICG to display the current measurement
units primitives allowed in the parameter comment fields of the data structure definition
files.
@par
The ICG generates one source code file for each data structure definition file it
processes, with a file name in the form of io_src/io_<file_name>.c; where “io_” is a
standard prefix for all ICG generated files, and <file_name> is the original data
structure definition file name.
@par
Any characters or statements the ICG recognizes as valid syntax, but does not process,
will be echoed to the screen with an informative message on why it did not process the
parameter.
@par
In general, the following items are not processed by the ICG:
-# global parameters decalred outside of a struct, union, or enum typedef,
-# all parameter declarations of a type other than the basic C types listed in the
Parameter Data Types section or the types contained within the data structure and
enumerated type databases (structure and enumerated types previously processed by the ICG),
-# all parameters that have a ‘**’ in the measurement units field of the parameter comment, and
-# all function declarations.
@par
The ICG will always give the “ICG complete.” message upon successful completion of processing.
@section LEVEL3 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
directory. Or the developer may want to build a library from a model directory of
source and include files. %Trick’s make_build and UNIX’s make may be used for these
purposes.
@section LEVEL4 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
in the same directory or for src and include subdirectories. make_build generates a
complete dependency list for the source and header files processed. make_build should
only be run after the ICG processor has been run on all appropriate data structure
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:
<tt><b>UNIX Prompt></b> make_build [lib <lib_name>]</tt>
The lib argument causes make_build to generate Makefile syntax for building an
archived (UNIX ar) library for the object files and give the library the name <lib_name>.
The make_build command is rarely used.
@section LEVEL4 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
result, hopefully, in a simulation. Running make in a model directory with a
Makefile generated by make_build will result in either object code for the model
source local to that directory or a library.
Makefile options may be found by typing in:
<tt><b>UNIX Prompt></b> make help</tt>
Additional documentation for make can be found in UNIX manuals for your workstation.
@section LEVEL2 Pickling And Unpickling A Simulation
Ever wanted to go to a sim directory and type in a command to get a tar-zipped file
of all simulation source necessary to run/build a simulation?
Welcome to pickle.
“pickle” is a script that does just that.
Here is an example of how to pickle a previously built simulation:
-# Build your simulation
-# cd ${HOME}/trick_sims
-# pickle SIM_ball_L2
This will create a file called SIM_ball_L2.tgz.
To “unpickle” your SIM_ball_L2.tgz and build it somewhere else, you take the following steps.
-# Untar and decompress the *.tgz file
-# source SIM_ball_L2_includes.csh (to get your TRICK_CFLAGS set)
-# cd SIM_ball_L2
-# CP
Caveat: Pickle will not search your input file for #includes on the system.
As long as you have all dependent input parameters in the SIM directory, it will
grab that.
@section LEVEL2 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.
<tt><b>UNIX Prompt></b> sie [-nocase] <search string></tt>
As an example, if you know the parameter name contains clock but don’t know
anything else, try:
<tt><b>UNIX Prompt></b> sie clock</tt>
The search returns each %Trick processed variable (including %Trick’s “sys” variables)
from your simulation that contains the search string. Beneath each variable returned
is information from its header file definition: user supplied description, type,
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.
@section LEVEL2 kill_sim
The following command will kill all simulations and their children that you own.
<tt><b>UNIX Prompt></b> kill_sim</tt>
@section LEVEL2 Current Trick Version
The following command echoes the installed %Trick version release:
<tt><b>UNIX Prompt></b> trick_version</tt>
@section LEVEL2 Checksumming
%Trick comes with a file that contains checksums for the %Trick package. You may run:
<tt><b>UNIX Prompt></b> trick_verify_checksums</tt>
at any time to see what, if any, files have changed from the original package. The checksum is
done on source files, not object code.
*/

757
doxygen/users_guide/model_source_code.dox_in
View File

@ -1,757 +0,0 @@
/**
@page LEVEL2 Model Source Code
This section details the syntax for creating headers and source code that %Trick can process.
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.
@section LEVEL3 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.
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.
@section LEVEL3 C 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.
@verbatim
/* [TRICK_HEADER]
PURPOSE:
(Purpose statement.)
[LANGUAGE: (CPP|C++)]
[LIBRARY DEPENDENCY:
(
(object.o|model.c|lib.a|lib.so|<relative_path>/lib.a)
[(object_n.o|lib_n.a|lib_n.so|<relative_path>/lib_n.a)]
)]
[ICG IGNORE TYPES:
((Type #1) (Type #n)])]
[PYTHON_MODULE: (module_name)]
[REFERENCES:
((Reference #1) (Reference #n)])]
[ASSUMPTIONS AND LIMITATIONS:
((Assumption #1) (Assumption #n)])]
[PROGRAMMERS:
(((Name) (Company) (Date) [(other info)])
[((Name) (Company) (Date) [(other info)])]]
[ICG: (No|Nocomment)]
*/
typedef enum {
enum_lable [=enum_value],
last_enum_label [= enum_value]
} 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]]* ;
/* [**|*i|*o|*io] trick_io([**|*i|*o|*io]) trick_chkpnt_io([**|*i|*o|*io])
measurement_units [<min_val..max_val]] description */
any_other_type [*]* param_name [[dim]]* ;
/* [**|*i|*o|*io] trick_io([**|*i|*o|*io]) trick_chkpnt_io([**|*i|*o|*io])
measurement_units [<min_val..max_val]] description */
} struct_name ;
class <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]]* ;
/* [**|*i|*o|*io] measurement_units [<min_val..max_val]] description */
any_other_type [*]* param_name [[dim]]* ;
/* [**|*i|*o|*io] measurement_units [<min_val..max_val]] description */
} ;
@endverbatim
@section LEVEL4 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.
@par 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.
@par 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.
@anchor Library_Dependencies
@par Library Dependencies
@verbatim
LIBRARY DEPENDENCY:
((relative_path/model_1.c)
(relative_path/model_2.cpp))
@endverbatim
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 dependendencies 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 prefered library dependeny 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:
@verbatim
LIBRARY DEPENDENCY:
((this.o)
(that.o)
(my_library/libdog.a)
(libcow.so)
(${FOO_ENV_VAR}/foo.o))
@endverbatim
For references to objects outside the current source directory, the directory paths
must be specified relative to the bin_${TRICK_HOST_CPU} directory. In this example,
the that.c function might also have its own library dependency list, but the that.c
dependencies do not need to appear in the this.c dependency list. The CP will
automatically search and sort all the object code dependencies; the developer just has
to make sure all dependencies are listed in the appropriate files.
There are two ways to specify dependencies to actual libraries, i.e. lib*.a files:
-# <relative path>/<libraryname>.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
- 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.
You may also have %Trick link in a shared (lib*.so) library. You must supply the *.so
extension. %Trick will not automatically build a shared library, but it is smart enough
to use it during link time.
The LIBRARY DEPENDENCY field also handles the #ifdef, #else and #endif statements
such that different object files and libraries may be linked for different cases.
The previous example might look like this:
@verbatim
LIBRARY DEPENDENCY:
((this.o)
(that.o)
#ifdef __animals
(my_library/libdog.a)
(libcow.so)
#else
(my_library/lib.a)
#endif
(${FOO_ENV_VAR}/foo.o))
@endverbatim
It is good practice to add library dependencies for source code files for prototypes
listed in the header.
@par 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 only valid for
the current file. It does not extend to included header files.
@par 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.
@section LEVEL4 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.
@section LEVEL4 Enumerated Type Definitions
%Trick provides complete support for enumerated types. Simple mathematical
expressions using enumerated types are supported as well.
An example follows:
a.h
@verbatim
typedef enum {
FIRST_ENUM = 45
} A_ENUM ;
@endverbatim
b.h
@verbatim
#include "a.h"
typedef enum {
ME_TOO = 2
} OTHER_ENUM;
typedef enum {
SECOND_ENUM = FIRST_ENUM,
THIRD_ENUM = FIRST_ENUM * 3,
FOURTH_ENUM = SECOND_ENUM * 4,
FIFTH_ENUM = ME_TOO * 6
} B_ENUM ;
@endverbatim
c.h
@verbatim
#include "b.h"
typedef struct {
int dummy; /* No comment necessary */
A_ENUM ae; /* No comment necessary */
B_ENUM be; /* No comment necessary */
int ia1[FIRST_ENUM]; /* No comment necessary */
int ia2[SECOND_ENUM]; /* No comment necessary */
int ia3[FIFTH_ENUM]; /* No comment necessary */
} DATA ;
@endverbatim
@section LEVEL4 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.
@section LEVEL4 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:
-# int,
-# short,
-# long,
-# long long
-# char,
-# (un)signed int,
-# (un)signed short,
-# (un)signed long,
-# (un)signed char,
-# (un)singed long long,
-# (un)signed short int,
-# (un)signed long int,
-# float,
-# double,
-# wchar_t,
-# FILE *
-# Bit fields (signed and unsigned) and
-# previously processed structure, union, enumerated types and typedefs.
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).
@section LEVEL4 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. For a code example, see Section
4.4.11.
@section LEVEL4 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:
@verbatim
typedef unsigned char my_uchar;
typedef char my_char;
typedef wchar_t my_wchar;
typedef short int my_shortint;
typedef short my_short;
typedef unsigned short int my_ushortint;
typedef unsigned short my_ushort;
typedef int my_int;
typedef unsigned int my_uint;
typedef long int my_longint;
typedef long my_long;
typedef unsigned long int my_ulongint;
typedef unsigned long my_ulong;
typedef float my_float;
typedef double my_double;
typedef my_short my_short2;
struct Animal_Sound {
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 ;
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 ;
@endverbatim
@section LEVEL4 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.
@par 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.
To set all permissions for general variable access start the comment with one of the
following fields, [**|*i|*o|*io]. trick_io([**|*i|*o|*io]) is an equivalent form to
set general variable access.
- ** indicates that %Trick will not allow input or output for this parameter; i.e.
the user can not input this parameter,record this parameter, or view its value.
- *i indicates that only input is allowed for the parameter. Parameter may be input
through the checkpoint file or ref_assignment, but the parameter will not be
recordable or written to a checkpoint file.
- *o indicates only output is allowed for the parameter. Parameter may be
checkpointed or logged only. They are not reloaded during a checkpoint reload.
- *io specifies that both input and output are allowed for the parameter. This
is the default condition if the field is omitted from the comment. Parameter may
be in input file, may be checkpointed and logged.
Checkpoint I/O may be set separately by adding trick_chkpnt_io([**|*i|*o|*io]) to
the comment. If this optional field is not present the general I/O access field
is used to determine checkpoint permissions.
- ** indicates that %Trick will not allow checkpoint input or output. General
variable access may still be available.
- *i indicates only checkpoint input is allowed for the parameter. Parameters
will not be written to the checkpoint.
- *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.
@par The Measurement Units Specification
The second field 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.
The following sections describe the new and the previous units specifications in
header files, respectively.
Measurement units may be any combination of the below units. Prefixes are allowed
only for Metric units.
@verbatim
Trick Measurement Units Summary
-------------------------------
Time: s min hr day
Angular Displacement: r d as am rev
Voltage: v
Amperage: amp
Resistance: ohm
Sound: dB
Unitless: -- cnt one mol
English System Units
--------------------
Linear Displacement: ft in yd mi n.m.
Mass: sl lbm
Force: oz lbf
Temperature: R F
Energy: BTU
Power: hp
Pressure: psi
Metric System Units
-------------------
Linear Displacement: m
Mass: g mt
Force: N
Temperature: C K
Energy: J TNT
Power: W
Pressure: Pa atm
Frequency: Hz
Prefixes for Multiples and Submultiples
(Not valid for English system units)
---------------------------------------
10**-1 d 10 da
10**-2 c 10**2 h
10**-3 m 10**3 k
10**-6 u 10**6 M
10**-9 n 10**9 G
10**-12 p 10**12 T
10**-15 f 10**15 P
10**-18 a 10**18 E
10**-21 z 10**21 Z
10**-24 y 10**24 Y
@endverbatim
@par 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.
@par 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.
@section LEVEL3 C++ Header Files
C++ headers may include constructs and concepts not found in C header files. In addtion
to all C syntax, %Trick parses and understandes many C++ features.
@section LEVEL4 Public, Protected, and Private Access
%Trick is able to access a class's public data and methods for input processing, data
recording, ASCII checkpoinint and the variable server. Protected and private variables
are not accessible by default. %Trick is able to access this data if two friends
are declared in the class.
@code
friend class InputProcessor ;
friend void init_attr<class_name>() ;
@endcode
These friends should appear at the top of the class. If the friends are not declared
with a class %Trick will ignore private and protected data.
@section LEVEL4 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.
- Public and protected inherited variables are avalable for access.
- Protected and private inheritance is ignored.
- Multiple inheritance is processed but not well tested.
- Template inheritance is not currently supported.
@section LEVEL4 Namespaces
Currently one level of namespace is supported. Addtional levels of namespaces are
ignored. Simliarly classes and enumerations embedded in other classes are ignored.
@code
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 {
...
} ;
} ;
@endcode
@section LEVEL4 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.
@section LEVEL4 Templates and the Standard Template Libraries (STL)
%Trick attempts to process user defined templates. Simple templates are handled. We do not
have a good definintion 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 tempaltes
should be excldued 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. STL
variables may be checkpointed with user help. %Trick provides function templates to
checkpoint and restore STLs. The user needs to call 3 functions, a checkpoint, post_checkpoint,
and restart class jobs.
@code
// A class with STLs to be checkpointed. 3 methods are defined to help Trick checkpoint the STLs
class STLCheckpoint {
public:
std::map< int , double > my_double_map ;
std::vector < double > my_double_vec ;
int checkpoint(string object_name);
int post_checkpoint(string object_name);
int restart(string object_name);
} ;
// The checkpoint job converts STLs to array data.
int STLCheckpoint::checkpoint(string object_name) {
/* checkpoint_stl is a templated function that takes an STL,
a sim_object name, and a variable name (usually the same
as the STL name) as arguments. It outputs memory_manager
arrays named object_name.<variable_name> that contain the
data in the STLs.
*/
checkpoint_stl(my_double_map, object_name , “my_double_map”) ;
checkpoint_stl(my_double_vec , object_name ,“my_double_vec”) ;
}
// The post_checkpoint job frees memory allocated in checkpoint job
int STLCheckpoint::post_checkpoint(string object_name) {
//delete_stl takes the same arguments as checkpoint_stl
checkpoint_stl(my_double_map, object_name , “my_double_map”) ;
checkpoint_stl(my_double_vec , object_name ,“my_double_vec”) ;
}
// The restart job restores STLs from a checkpoint file.
int STLCheckpoint::restart(string object_name) {
//restore_stl takes the same arguments as checkpoint_stl
restore_stl(my_double_map, object_name , “my_double_map”) ;
resotre_stl(my_double_vec , object_name ,“my_double_vec”) ;
}
@endcode
Calls to checkpoint the STLs in the S_define.
@code
class theSimObject : public Trick::SimObject {
public:
STLCheckpoint stls ;
theSimObject() {
/*
"name" is the string that is the sim_object
instance name. It is present in all sim objects
and automatically set by Trick.
*/
("checkpoint") stls.checkpoint(name) ;
("post_checkpoint") stls.post_checkpoint(name) ;
("restart") stls.restart(name) ;
} ;
@endcode
@section LEVEL4 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.
@code
class CantCopyMe {
private:
CantCopyMe( const CantCopyMe & ) ;
CantCopyMe & operator = ( const CantCopyMe ) ;
}
@endcode
When using such classes in %Trick, xlasses that include non copyable classes must also
declare themselves not copyable. this extendds all the way up to sim objects in the
S_define.
@code
class MysimObject : public Trick::SimObject {
public:
CantCopyMe ccm ;
private:
MysimObject( const MysimObject & ) ;
MysimObject& operator = ( const MysimObject) ;
}
@endcode
@section LEVEL4 Source Code in Header Files
%Trick attempts to skip over class code in header files while searching for class
varaibles and method declarations. However, code can sometimes confuse %Trick and
cause it to abort processing of header files. It is recommened to keep code out
of the header file..
@section LEVEL4 Library Dependencies
It is good practice to list all the source code files that define class methods
in the class header file.
@section LEVEL3 Excluding Header File Code
There are several ways to exclude code from processing.
@par Excluding Directories
Add paths to exclude to the TRICK_ICG_EXCLDUE environment variable or makefile
variable. This works for both C and C++ headers.
@par Excluding File
Add "ICG: (No)" to tht %Trick comment header.
@par 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.
@code
#ifndef TRICK_ICG
code that cannot be processed by ICG
#ifndef SWIG
code that cannot be processed by ICG or SWIG
#endif
#endif
@endcode
@section LEVEL3 Source Files
By source files, in this context, we mean functional model source code, i.e. *.c files.
@verbatim
/* [TRICK_HEADER]
PURPOSE:
(Purpose statement.)
[REFERENCES:
((Reference #1) (Reference #n)])]
[ASSUMPTIONS AND LIMITATIONS:
((Assumption #1) (Assumption #n)])]
[LIBRARY DEPENDENCY:
(
(object.o|lib.a|lib.so|<relative_path>/lib.a)
[(object_n.o|lib_n.a|lib_n.so|<relative_path>/lib_n.a)]
)]
[PROGRAMMERS:
(((Name) (Company) (Date) [(other info)])
[((Name) (Company) (Date) [(other info)])]]
*/
// source code...
@endverbatim
@section LEVEL4 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).
@par 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.
- The ASSUMPTIONS AND LIMITATIONS field may contain any number of assumptions and limitations delimited by parentheses.
- The LIBRARY DEPENDENCIES. See @ref Library_Dependencies secion 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.
@section LEVEL4 Source Code
%Trickis only interested in the header comment if one is present in source code files. Anything
goes for the rest of the source code file.
@section LEVEL3 Trick Version Compatibility
%Trick is always changing. The interface to %Trick functions may change with
each major version. Sometimes even monor 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.
*/

55
doxygen/users_guide/overview.dox_in
View File

@ -1,55 +0,0 @@
/**
@page LEVEL1 Overview and Purpose of Functions
The %Trick processors and utilities covered in this document are listed in Table 1. All functions
listed in Table 1, can be started at the UNIX command prompt by entering the function’s name and
associated arguments followed by a return. For help with CP, ICG and MIS, use the -h option. Man
pages are available for CP, ICG and MIS too. Specific startup and termination characteristics for
each function are discussed in the later subsections. Most of these functions can also be
executed through the Graphical User Interfaces.
<center>
<table>
<tr><th>Name</th><th>Description</th></tr>
<tr><td>CP</td><td>Configuration Processor - builds simulation executable</td></tr>
<tr><td>fxplot</td><td>Data Products plots, tables, and displays generation</td></tr>
<tr><td>trick_dp</td><td>Data Products user interface</td></tr>
<tr><td>trick_ui</td><td>%Trick developer’s interface</td></tr>
<tr><td>ICG</td><td>Interface Code Generator - parses header files and builds %Trick data structure interfaces</td></tr>
<tr><td>install_user</td><td>Installs user for current %Trick environment</td></tr>
<tr><td>kill_sim</td><td>Kills runaways simulations</td></tr>
<tr><td>make</td><td>Standard UNIX make command</td></tr>
<tr><td>make_build</td><td>Makefile builder</td></tr>
<tr><td>MIS</td><td>Module Interface Specification processor - parses modules and builds %Trick function call interfaces</td></tr>
<tr><td>S_main_${TRICK_HOST_CPU}.exe</td><td>Specific %Trick Simulation</td></tr>
<tr><td>trick_version</td><td>Displays the currently installed %Trick Release Version</td></tr>
</table>
<b>Table 1. %Trick Processor and Utility Functions</b>
</center>
Figure 1 is a high-level picture of how a model developer interacts with %Trick to produce a
simulation executable. The developer creates math model source code, default data for the models,
and a simulation definition file. The developer may optionally use external libraries he/she has
already created. Once these tasks are complete, the developer runs the Configuration Processor (CP)
on the simulation definition file (S_define). The Configuration Processor (CP) then does its magic.
Using the S_define as a blue print, CP gathers the default math model data, auto generates IO code
from source headers, parses math model source code to find object dependencies, job specifications
etc., and then creates a master makefile. With this master makefile in hand, CP calls UNIX make,
which creates the simulation executable. CP (and other utilities) also creates a database that
contains data structure information and model job info. The “catalog” utility provides a means
to view the database.
@image html users_guide/figure_1.png "Figure 1 Trick Simulation Development Processor Interactions"
@image rtf users_guide/figure_1.png "Figure 1 Trick Simulation Development Processor Interactions"
Figure 2 is a high-level picture of how a simulation user operates the simulation. The simulation
developer/user is responsible for creating an “input” file for the simulation and data recording
specification files (if needed). Once these are created, the simulation is ready to execute. The
simulation will output data if the user has designated variables for logging. Data may be analyzed
by creating a Data Products specification file.
@image html users_guide/figure_2.png "Figure 2 Trick Simulation Operation"
@image rtf users_guide/figure_2.png "Figure 2 Trick Simulation Operation"
*/

23
doxygen/users_guide/runtime_output.dox_in
View File

@ -1,23 +0,0 @@
/**
@page LEVEL2 Runtime Output
Executing the simulation main executable S_main_${TRICK_HOST_CPU}.exe generates a handful
of log files that document a simulation run. The log files are written to the RUN_<name>
directory by default. The destination can be redirected by specifying the -O or -OO
option for the runtime executive. Two of the log files are described below.
<tt>S_job_execution</tt> lists the jobs executed by name, the job types, the arguments, and
start and stop times.
<tt>S_run_summary</tt> documents the name and path of the executable and the input file, the
build time of the executable, and the Trick version. It also contains the list of
environment variables used when the executable was built and the model versions.
<tt>log_<group_name>.*</tt> log files and log header files. These files are created by
the Data Recording capabilities in Trick. They contain cyclic recorded parameters from
within the simulation.
<tt>send_hs</tt> all messages written by <tt>send_hs</tt> or <tt>message_publish</tt> will
be saved to the send_hs file.
*/

8
doxygen/users_guide/simulation_capabilities.dox_in
View File

@ -1,8 +0,0 @@
/**
@page LEVEL1 Simulation Capabilities
This section details the runtime capabilities of Trick. All capabilities described are
available both through calls in model code or through the input processor. See Section
XYZ for details to the input processor.
*/

8
doxygen/users_guide/simulation_utilities.dox_in
View File

@ -1,8 +0,0 @@
/**
@page LEVEL1 Simulation Capabilities
This section details the simulation utilities of Trick. Simulation utilities provide a service to
user models. These included a socket communication library, Trickcomm, as well as math routines,
units conversion routines, and some abstract data types written in C.
*/

157
doxygen/users_guide/trick_env.dox_in
View File

@ -1,157 +0,0 @@
/**
@page LEVEL2 Trick Environment
@anchor Trick_Environment
A very important part of building %Trick simulations is understanding the environment and
how to manipulate it. %Trick maintains a list of variables. Each variable has a default
value that may be overridden by setting the value in the environment. %Trick resolves these
variables by a call to a function called "gte". You can type in "${TRICK_HOME}/bin/gte"
on the command line to see what the "Trick environment" is.
A %Trick simulation may run with no UNIX environment. However, for simulation development,
there is a set of UNIX variables that may be in your UNIX environment. For instance, you
may have TRICK_CFLAGS defined.
The user’s environment is very important to building a correct simulation and it can be
complex at times. If you have questions, please contact a %Trick representative.
@section LEVEL3 TRICK_CFLAGS and TRICK_CXXFLAGS
The contents of TRICK_CFLAGS is included on the command line with each C file compilation.
Similiarly, TRICK_CXXFLAGS is included for each C++ file. Each contain header file search
directories, macro define variables, and compiler flags.
For building a simulation, a user must be proficient at tweaking TRICK_CFLAGS and TRICK_CXXFLAGS.
There are a several ways to do this.
TRICK_CXXFLAGS works exactly like TRICK_CFLAGS.
<b>Example 1:</b> Add "-I/user/mooo/trick_models" to the environment variable.
TRICK_CFLAGS is currently...
<tt><b>UNIX Prompt></b> echo $TRICK_CFLAGS</tt><br>
<tt>-Wall</tt>
Now we need to edit the shell startup file where TRICK_CFLAGS is defined.
Add the following line for bash.
<tt>TRICK_CFLAGS="$TRICK_CFLAGS -I/user/mooo/trick_models"</tt>
Add the following line for [t]csh.
<tt>setenv TRICK_CFLAGS "$TRICK_CFLAGS -I/user/mooo/trick_models"</tt>
Now source your shell startup file and voila!...
For bash:<br>
<tt><b>UNIX Prompt></b> . ~/.bash_profile</tt><br>
<tt><b>UNIX Prompt></b> echo $TRICK_CFLAGS</tt><br>
-Wall -I/user/mooo/trick_models
For [t]csh:<br>
<tt><b>UNIX Prompt></b> source ~/.cshrc</tt><br>
<tt><b>UNIX Prompt></b> echo $TRICK_CFLAGS</tt><br>
-Wall -I/user/mooo/trick_models
<b>Example 2:</b> Add "-I/user/mooo/trick_models" through the simulation S_overrides.mk file
~e need to edit the S_overrides.mk file in the simulation to be built.
Add the following line.
<tt>TRICK_CFLAGS="$TRICK_CFLAGS -I/user/mooo/trick_models"</tt>
This will not show up in the current shell environment, but will be set for each command that
the makefile executtes.
@section LEVEL3 TRICK_CONVERT_SWIG_FLAGS
TRICK_CONVERT_SWIG_FLAGS contains flags sent to the convert_swig utility. Currently the flags only
support "-s" which allows convert_swig to process STLs.
@section LEVEL3 TRICK_EDITOR
TRICK_EDITOR defaults to an empty string. With TRICK_EDITOR is set, when CP encounters an error it
brings up the S_define file automatically using the TRICK_EDITOR command.
@section LEVEL3 TRICK_EXCLUDE
A colon separated list of directories to skip when processing files.
It is possible to instruct all CP functions to skip entire directories using the environment variable
TRICK_EXCLUDE. Set this variable to a colon separated list of directories which you
wish CP to bypass. All header files found in TRICK_EXCLUDE will not be processed. All source code
files found in TRICK_EXCLDUE will not be compiled or linked into the simulation.
This feature is useful to bring in packages as a library.
@section LEVEL3 TRICK_FORCE_32BIT
To force %Trick to compile in 32-bit on 64-bit systems, set the TRICK_FORCE_32BIT environment
variable to 1. Setting this variable appends "-m32" automatically to TRICK_CFLAGS and TRICK_CXXFLAGS.
@section LEVEL3 TRICK_HOST_CPU
%Trick determines a system specific suffix to append to object code directory names. By default
this is determined automatically by %Trick. The user may override this by setting the TRICK_HOST_CPU
environment variable.
@section LEVEL3 TRICK_HOST_TYPE
%Trick determines the current OS type. The user may override this by setting the TRICK_HOST_TYPE.
It is rare to set this variable.
@section LEVEL3 TRICK_ICG_EXCLUDE
A colon separated list of directories to skip when processing header files.
It is possible to instruct ICG to skip entire directories using the environment variable
TRICK_ICG_EXCLUDE. Set this variable to a colon separated list of directories which you
wish ICG to bypass. This is useful when there is code which you do not wish %Trick to have
any knowledge of (i.e. you don’t need any of the parameters recorded or input processable).
@section LEVEL3 TRICK_LDFLAGS
TRICK_LDFLAGS include linker flags. TRICK_LDFLAGS is used when linking the simulation executable.
It is rare to set this variable.
@section LEVEL3 TRICK_MAKE
This variable has been deprecated.
@section LEVEL3 TRICK_SFLAGS
TRICK_SFLAGS includes header file search directories and macro define variables.
TRICK_SFLAGS is used when parsing the S_define file.
@section LEVEL3 TRICK_USER_LINK_LIBS
Additional library and library directories to include when linking a simulation.
An example of adding a library search path, a library to be searched for, and a full
path library.
bash<br>
<tt>export TRICK_USER_LINK_LIBS="-L/full/path/to/libs -lfile1 /another/path/to/a/libfile2.a"</tt>
[t]csh<br>
<tt>setenv TRICK_USER_LINK_LIBS "-L/full/path/to/libs -lfile1 /another/path/to/a/libfile2.a"</tt>
@section LEVEL3 MAKEFLAGS
MAKEFLAGS is not a %Trick environment variable. It is used with the GNU make utility.
Invoking make with the -j flag allows make to compile more than one file simultaneously.
Dramatic speedups in compiling can be achieved when using multiple processors.
<tt><b>UNIX Prompt></b> setenv MAKEFLAGS –j10</tt>
(circa 2007?) We have used the parallel make to build %Trick on an 8 core system in a
gee-whiz time of only 25 seconds! In the year 2016, or thereabouts, %Trick will be compiled
in 1 second. Imagine that!!! Of course, we are assuming that there will be such a thing
as %Trick... By then, hopefully, %Trick will be written in a language that needs no compilation.
So really, make will be a thing of the past... And this section will not exist in the
User’s Guide! Assuming of course that the editor, at that time, actually reads the thing.
*/

9
trick_source/sim_services/CheckPointAgent/docs/main_page.dox_in
View File

@ -1,9 +0,0 @@
/**
@page LEVEL2 Trick Checkpoint Writer
The Trick CheckPointWriter is a C++ Class that implements checkpointing.
See Also:
- Trick::CheckPointAgent
- Trick::ClassicCheckPointAgent
*/

176
trick_source/sim_services/Clock/docs/main_page.dox_in
View File

@ -1,176 +0,0 @@
/**
@page LEVEL2 Trick Realtime Clock
A realtime clock is an optional feature for %Trick simulations.
The Trick::Clock base class provides %Trick with a consistent interface to different
realtime clocks. The base class provides a common set of routines called by
Trick::RealtimeSync to get and reset the realtime clock.
%Trick provides built in support for using the system clock (Trick::GetTimeOfDayClock).
%Trick also provides built in support for using Spectracom's TPRO IRIG-B clock board,
also referred as a Central Timing Equipment (CTE) board. TPRO CTE support is off
by default. To enable TPRO CTE support %Trick must be built with TPRO driver support.
Go to http://www.spectracomcorp.com for driver support for your particular board.
To enable TPRO CTE support, run ${TRICK_HOME/configure --tprocte=/paht/to/tpropci.
Recompile %Trick after the configure script.
@section LEVEL3 Creating a User Defined Real-Time Clock
Clocks may be created by users. To create a new clock, the class must inherit from
the Trick::Clock. Trick::Clock is an abstract class with several methods for the user
to implement. These methods provide the hardware specific code to initalize, access, and
shutdown clock hardware. See ${TRICK_HOME}/trick_source/sim_services/Clock for examples
to how we implemented the GettimeofDay and the TPRO_CTE clock. This is the list of
routines that must be implemented by the user:
@par Trick::Clock::clock_init()
Opens the clock hardware, initializes the clock, etc.
@par Trick::Clock::wall_clock_time()
Gets the wall clock time. Returns the time in integer number of tics of 1us.
@par Trick::Clock::clock_spin(long long req_time)
Waits for real-time to catch up to the requested simulation time. Polling or waiting
for an interrupt are typical methods for spinning.
@par Trick::Clock::clock_stop()
Shuts down clock hardware, closes devices, etc.
@section LEVEL3 Specifying the Real-Time Clock
%Trick instantiates an instance of the Trick::GetTimeOfDayClock and Trick::TPROCTEClock
clocks by default. The Trick::TPROCTEClock will be empty if TPRO CTE support is not
enabled.
%Trick defaults to the Trick::GetTimeOfDay clock. To switch to the TPRO CTE clock
or a user defined clock use the following line in the Python input file.
@code
# Changes to the TPRO CTE clock
trick.real_time_change_clock(real_time.tpro_cte)
# Changes to a user defined clock
trick.real_time_change_clock(<user defined clock>)
@endcode
@section LEVEL3 Accessing the Real-Time Clock
Typically, users will not have to access the real-time clock directly, the
Trick::RealtimeSync uses the real time clock to synchronize to real time. However
there are several user accessible routines to control the clock and get the status.
#include "trick_source/sim_services/Clock/include/clock_proto.h" for these routines
@section LEVEL4 Clock Time
@code
long long clock_time() ;
@endcode
@code
# Python access
trick.clock_time()
@endcode
Gives you real-time referenced from simulation start. The returned value is in tics.
A tic is set amount of time, set by the Trick::Executive, usually 1us.
@section LEVEL4 Wall Clock Time
@code
long long wall_clock_time() ;
@endcode
@code
# Python access
trick.wall_clock_time()
@endcode
Gives you the actual time from the clock. The returned value is in tics
A tic is set amount of time, set by the Trick::Executive, usually 1us.
@section LEVEL4 Clock Spin
@code
int clock_spin(long long ref) ;
@endcode
@code
# Python access
trick.clock_spin(<ref_time>)
@endcode
Calling clock spin will cause the simulation to enter a loop and wait until
realtime catches up to simulation time. This is not typically called by
users.
@section LEVEL4 Reset Clock Reference
@code
long long clock_reset(long long ref) ;
@endcode
@code
# Python access
trick.clock_reset(<ref_time>)
@endcode
Resetting the clock synchronizes the "reference" time to the real-time clock.
The reference time is typically the current simulation time.
@section LEVEL4 Manually Setting Clock Reference
@code
int clock_set_reference(long long wall_clock_time) ;
@endcode
@code
# Python access
trick.clock_set_reference(<wall_clock_time>)
@endcode
This manually synchronizes the clock's reference to the incoming wall clock time.
This routine is used internally to synchronize the simulation time to a whole
second multiple of the real time clock.
@section LEVEL4 Getting the Clock Ratio
@code
double clock_get_rt_clock_ratio() ;
@endcode
@code
# Python access
trick.clock_get_rt_clock_ratio()
@endcode
The realtime clock has the ability to run at a ratio to realtime. This routine
gets the current set ratio.
@section LEVEL4 Setting the Clock Ratio
@code
int clock_set_rt_clock_ratio(double in_rt_clock_ratio) ;
@endcode
@code
# Python access
trick.clock_set_rt_clock_ratio()
@endcode
The realtime clock has the ability to run at a ratio to realtime. This routine
sets the current set ratio. A simulation may not be able to run fast enough to
honor the set ratio. In this case the simulation will run as fast as possible.
@section LEVEL3 Realtime Clock Related Pages
Realtime Clock Requirements\n
Realtime Clock Design
*/

50
trick_source/sim_services/CommandLineArguments/docs/main_page.dox_in
View File

@ -1,50 +0,0 @@
/**
@page LEVEL2 Command Line Arguments
The Trick::CommandLineArguments class stores the command line arguments specified
by the user when starting the simulation. The class provides routines to
access the arguments.
@section LEVEL3 Accessing the Command Line Arguments
The command line arguments are available to user classes through the following two calls.
@li int command_line_args_get_argc() ;
@li char ** command_line_args_get_argv() ;
Specific directories and file names may be accessed by the following calls.
@li const char * command_line_args_get_output_dir() ;
@li const char * command_line_args_get_input_file() ;
@li const char * command_line_args_get_default_dir() ;
@li const char * command_line_args_get_cmdline_name() ;
@section LEVEL3 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.
@verbatim
S_main_${TRICK_HOST_CPU}.exe RUN_dir/input.py -O <output_dir>
@endverbatim
All Trick core output files will be written to the specified <output_dir>.
@section LEVEL3 TimeStamping the Output Directory
The user may also specify a time stamped output directory in the input file.
@code
trick.output_dir_timestamped_on()
@endcode
This will create a dated subdirectory in the current output directory. All of the Trick
core output files will be written to the output directory. This option may be used in
conjunction with the <tt>-O</tt> or the <tt>-OO</tt> command line arguments.
@section LEVEL3 Command Line Arguments Related Pages
Requirements\n
Design
*/

222
trick_source/sim_services/DataRecord/docs/main_page.dox_in
View File

@ -1,222 +0,0 @@
/**
@page LEVEL2 Data Recording
Data Recording provides the capability to specify any number of data recording groups,
each with an unlimited number of parameter references, and with each group recording
at different frequencies to different files in different formats.
All data is written to the simulation output directory. @see @ref output_dir "Output Directory"
@section LEVEL3 Format of Recording Groups
Trick allows recording in three different formats. Each recording group is readable by
different external tools outside of Trick.
- @e DRAscii - Human readable and compatible with Excel.\n
- @e DRBinary - Readable by previous Trick data products.\n
- @e DRHDF5 - Readable by Matlab.
DRHDF5 recording support is off by default. To enable DRHDF5 support Trick must be built with HDF5 support.
Go to http://www.hdf5group.org and download the latest pre-built hdf5 package for your system. Source packages are
available as well. We recomment getting the static library packages above the shared. Static packages make
your executable larger, but you will not have to deal with LD_LIBRARY issues. The HDF5 package may be installed
anywhere on your system. To tell Trick you have HDF5 run ${TRICK_HOME}/configure --hdf5=/path/to/hdf5.
Re-compile Trick to enable HDF5 support.
@section LEVEL3 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>
For example:
@code
drg = trick.DRBinary() ;
@endcode
Note: drg is just an example name. Any name may be used.
@anchor S_7_8_3
@section LEVEL3 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:
@code
drg.add_variable("ball.obj.state.output.position[0]")
drg.add_variable("ball.obj.state.output.position[1]")
@endcode
An optional alias may also be specified in the method as <tt>drg.add_variable("<string_of_variable_name"> [, "<alias>"])</tt>.
If an alias is present as a second argument, the alias name will be used in the data recording file instead of the actual variable name.
For example:
@code
drg.add_variable("ball.obj.state.output.position[0]", "x_pos")
drg.add_variable("ball.obj.state.output.position[1]", "y_pos")
@endcode
@section LEVEL3 Changing the Recording Rate
To change the recording rate call the <tt>set_cycle()</tt> method of the recording group.
@code
drg.set_cycle(0.01)
@endcode
@section LEVEL3 Buffering Techniques
Data recording groups have three buffering options:
- @e DR_Buffer - the group will save recorded data to a buffer and use a separate thread to write recorded
data to disk. This will have little impact to the performance of the simulation. The downside
is that if the simulation crashes, the most recent recorded points may not be written to disk in time.
DR_Buffer is the default buffering technique. (For backwards compatibility, DR_Buffer can also be called DR_Thread_Buffer).
- @e DR_No_Buffer - the group will write recorded data straight to disk. All data is guaranteed to be written
to disk at simulation termination time. The downside of this method is that it is performed in
the main thread of the simulation and could impact real-time performance.
- @e DR_Ring_Buffer - the group will save a set number of records in memory and write this data to disk during
a graceful simulation termination. The advantage of this method is that there is only a set, usually
small, number of records written. The downside of this method is that if the simulation terminates
ungracefully, all recorded data may be lost.
To set the buffering technique call the <tt>set_buffer_type(trick.<buffering_option>)</tt> method of the recording group.
For example:
@code
drg.set_buffer_type(trick.DR_Buffer)
@endcode
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.
@section LEVEL3 Recording Frequency: Always or Only When Data Changes
Data recording groups have three recording frequency options:
- @e DR_Always - the group will record the variable value(s) at every recording cycle. (This is the default).
- @e DR_Changes - the group will record the variable value(s) only when a particular watched parameter (or parameters) value changes.
- @e DR_Changes_Step - like DR_Changes, except that a before and after value will be recorded for each variable,
creating a stair step effect (instead of point-to-point) when plotted.
To set the recording frequency call the <tt>set_freq(trick.<frequency_option>)</tt> method of the recording group. For example:
@code
drg.set_freq(trick.DR_Changes)
@endcode
For DR_Changes or DR_Changes_Step, to specify parameter(s) to watch that will control when the variables added with <tt>add_variable</tt> are recorded,
call the <tt>add_change_variable(string)</tt> method of the recording group. For example:
@code
drg.add_change_variable("ball.obj.state.output.velocity[0]")
@endcode
So if we assume the <tt>add_variable</tt> statements from the example in @ref S_7_8_3 "7.8.3" combined with the above <tt>add_change_variable</tt> statement,
then <tt>ball.obj.state.output.position[0]</tt> and <tt>ball.obj.state.output.position[1]</tt> will be recorded only when
<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.
@section LEVEL3 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.
@code
/* C code */
dr_enable_group("<group_name">) ;
dr_disable_group("<group_name">) ;
dr_record_now_group("<group_name">) ;
@endcode
This is the Python input file version:
@code
# Python code
trick.dr_enable_group("<group_name">) ; # same as <group_name>.enable()
trick.dr_disable_group("<group_name">) ; # same as <group_name>.disable()
trick.dr_record_now_group("<group_name">) ;
@endcode
@section LEVEL3 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.
This must be done before the add_data_record_group function is called. Trick does not
provide data locks for data record groups. It is up to the user to ensure that the data
recorded on *any* thread (including the master) is ready in order for data recording to
record a time homogeneous set of data.
@code
drg.set_thread(<thread_number>)
@endcode
@section LEVEL3 Example Data Recording Group
This is an example of a data recording group in the input file
@code
# Data recording HDF5 test
drg0 = trick.DRHDF5("Ball")
drg0.add_variable("ball.obj.state.output.position[0]")
drg0.add_variable("ball.obj.state.output.position[1]")
drg0.add_variable("ball.obj.state.output.velocity[0]")
drg0.add_variable("ball.obj.state.output.velocity[1]")
drg0.add_variable("ball.obj.state.output.acceleration[0]")
drg0.add_variable("ball.obj.state.output.acceleration[1]")
drg0.set_cycle(0.01)
drg0.freq = trick.DR_Always
trick.add_data_record_group(drg0, trick.DR_Buffer)
# This line is to tell python not to free this memory when drg0 goes out of scope
drg0.thisown = 0
@endcode
@section LEVEL3 User accessible routines
Create a new data recording group:
@li Trick::DRAscii::DRAscii(string in_name)
@li Trick::DRBinary::DRBinary(string in_name)
@li Trick::DRHDF5::DRHDF5(string in_name)
This list of routines is for all recording formats:
@li int dr_disable_group( const char * in_name )
@li int dr_enable_group( const char * in_name )
@li int dr_record_now_group( const char * in_name )
@li int Trick::DataRecordGroup::add_variable
@li int Trick::DataRecordGroup::add_change_variable
@li int Trick::DataRecordGroup::disable
@li int Trick::DataRecordGroup::enable
@li int Trick::DataRecordGroup::set_cycle
@li int Trick::DataRecordGroup::set_freq
@li int Trick::DataRecordGroup::set_job_class
@li int Trick::DataRecordGroup::set_max_buffer_size
This list of routines provide some additional configuration for DR_Ascii format only:
@li int Trick::DRAscii::set_ascii_double_format
@li int Trick::DRAscii::set_ascii_float_format
@li int Trick::DRAscii::set_delimiter
@li int Trick::DataRecordGroup::set_single_prec_only
@section LEVEL3 DRAscii Recording Format
@copydoc Trick::DRAscii
@section LEVEL3 DRBinary Recording Format
@copydoc Trick::DRBinary
@section LEVEL3 DRHDF5 Recording Format
@copydoc Trick::DRHDF5
@section LEVEL3 Related Pages
Requirements\n
Design
*/

26
trick_source/sim_services/DebugPause/main_page.dox_in
View File

@ -1,26 +0,0 @@
/**
@page LEVEL2 Debug Pause
Debug Pause is a debugging feature provided by Trick. When turned on, Debug Pause will print the current simulation time and
the name of the current job, and pause the simulation @e before the job is executed. Debug Pause provides a way for the user to step
through a simulation run job by job. The Simulation Control Panel (see @ref SimControlPanel "Sim Control Panel") is the means by which the user does this.
When a simulation is in Freeze mode, clicking the Step button will turn on Debug Pause. Each subsequent Step click will then execute the current job and pause at the next job.
Clicking Freeze will turn Debug Pause off and return to Freeze mode.
All jobs (user jobs and Trick jobs) of the following job class will be paused at:
@li initialization
@li integration
@li scheduled
@li end_of_frame
@li shutdown
Debug Pause 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").
@section LEVEL3 Related Pages
Requirements\n
Design
*/

29
trick_source/sim_services/EchoJobs/docs/main_page.dox_in
View File

@ -1,29 +0,0 @@
/**
@page LEVEL2 Echo Jobs
Echo Jobs is a handy debugging toggle provided by Trick. When turned on, Echo Jobs will print the current simulation time and
the name of the current job being executed. Echo Jobs is a convenient way to see the order of job execution and narrow down when
and where something occurs during a simulation run.
All jobs (user jobs and Trick jobs) of the following job class will be echoed:
@li initialization
@li integration
@li scheduled
@li end_of_frame
@li shutdown
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").
@section LEVEL3 User accessible routines
@li int echo_jobs_on() ;
@li int echo_jobs_off() ;
@section LEVEL3 EchoJobs Related Pages
Requirements\n
Design
*/

16
trick_source/sim_services/Environment/docs/main_page.dox_in
View File

@ -1,16 +0,0 @@
/**
@page LEVEL2 Environment (UNIX shell)
This class saves the Trick environment variables at compile-time. The variables
are saved inside the S_main executable. These variables are read-only after they
are compiled into the sim.
@li const char * get_trick_env( char * variable_name )
@section LEVEL3 Related Pages
Requirements\n
Design
*/

29
trick_source/sim_services/EventManager/docs/main_page.dox_in
View File

@ -1,29 +0,0 @@
/**
@anchor Event_Manager
@page LEVEL2 Event Manager
This page describes the methods available in the Trick::EventManager and Trick::EventProcessor class.
@note <b>See @ref Input_File "Input File" for detailed information on the syntax of the input processor file. </b>
@section LEVEL3 User accessible routines
These commands are for adding and removing events from the Event Manager
@li Event * @link Trick::EventManager::get_event() get_event() @endlink
@li int @link Trick::EventManager::add_event( Trick::Event * in_event) add_event( Trick::Event * in_event ) @endlink
@li int @link Trick::EventManager::add_event_before( Trick::Event * in_event) add_event_after( Trick::Event * in_event, std::string target_name, unsigned int target_inst ) @endlink
@li int @link Trick::EventManager::add_event_after( Trick::Event * in_event) add_event_before( Trick::Event * in_event, std::string target_name, unsigned int target_inst ) @endlink
@li int @link Trick::EventManager::remove_event( Trick::Event * in_event) remove_event( Trick::Event * in_event ) @endlink
@anchor Event_Processing
@section LEVEL3 Event Processing Flow
The next set of flowcharts details how the %Trick Event Processor processes events.
@image html ../../../doxygen/images/event_flowchart/event_processing.jpg
@image rtf ../../../doxygen/images/event_flowchart/event_processing.jpg
<center><b>Figure IP_1 Input Processor Event Processing</b></center>
Each thread in the simulation has an event processing job.
*/

506
trick_source/sim_services/Executive/docs/main_page.dox_in
View File

@ -1,506 +0,0 @@
/**
@page LEVEL2 Executive Scheduler
This scheduler or derivative of this class is required for Trick simulations to run.
The scheduler is in charge of simulation execution. The scheduler maintains simulation
elapsed time. The scheduler has 4 modes of operation, Initialization, Run, Freeze,
and Shutdown. The scheduler maintains the simulation mode. Within each mode of operation
the executive/scheduler calls different sets of user and system jobs.
The scheduler is implemented by the Trick::Executive class.
@section LEVEL3 Executive Flow
The next set of flowcharts details how the Trick main executable runs.
@image html ../../../doxygen/images/executive_flowchart/initialization.png
@image rtf ../../../doxygen/images/executive_flowchart/initialization.png
<center><b>Figure Exec_1 Executive Initialization</b></center>
During the Initialization phase three job classes are called, default data, input_processor, and
initialization. All jobs of these classes are executed in the main thread. Not shown in the
picture is any job returning a non-zero value to "trick_ret" will cause the simulation immediately
to go to shutdown. Execution continues to the Scheduled loop.
@image html ../../../doxygen/images/executive_flowchart/scheduled_loop.png
@image rtf ../../../doxygen/images/executive_flowchart/scheduled_loop.png
<center><b>Figure Exec_2 Scheduled Loop</b></center>
Run mode is also called the Scheduled loop. The Scheduled loop calls the top_of_frame, the scheduled
jobs, and the end_of_frame jobs. Both the top_of_frame and end_of_frame
jobs are called at the software_frame cycle rate. The scheduled jobs include these job classes:
- integ_loop. The integ_loop includes derivative, integration, dynamic_event, and post_integration.
- automatic
- environment
- sensor
- sensor_receiver
- scheduled, effector
- effector_emitter
- effector_receiver
- automatic_last
- logging
- advance_sim_time
Receiving a freeze command diverts execution to the Freeze loop. Execution is resumed in the
scheduled loop when returing to run mode.
The loop is run until an exit condition is met. The exit conditions include receiving
an exit command, reaching the termination time, or a job returning a non-zero value to
"trick_ret". Upon meeting an exit condition, execution continues to the Shutdown phase.
@image html ../../../doxygen/images/executive_flowchart/freeze_loop.png
@image rtf ../../../doxygen/images/executive_flowchart/freeze_loop.png
<center><b>Figure Exec_3 Freeze Loop</b></center>
Execution is diverted to the Freeze loop when the Freeze command is set in the Scheduled
loop. When entering freeze the freeze_init jobs are called. The freeze loop cyclically
calls the freeze scheduled jobs, freeze_automatic, and freeze jobs. Elapsed freeze time
is kept and cycle times for the freeze_scheduled jobs are followed. freeze_automatic
jobs are assumed to set their own next call time. Freeze jobs are called at the end of
the freeze_software_frame. The loop is run until a run command is received or an exit
condtion is met. Upon receiving a run command, execution is returned to the Scheduled loop.
The exit conditions include receiving an exit command or a job returning a non-zero
value to "trick_ret". Upon meeting an exit condition, execution continues to the Shutdown phase.
@image html ../../../doxygen/images/executive_flowchart/shutdown.png
@image rtf ../../../doxygen/images/executive_flowchart/shutdown.png
<center><b>Figure Exec_4 Shutdown</b></center>
The shutdown phase calls the shutdown phase jobs and exits. Easy peasy.
@section LEVEL3 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.
@section LEVEL4 Reading the Time
The executive provides 2 calls to get the simulation time.
@code
double exec_get_sim_time() ;
long long exec_get_time_tics() ;
@endcode
exec_get_sim_time() is a returns a double representing simulation elapsed seconds.
@note exec_get_sim_time() will not return an exact value when time values are large due to roundoff error.
exec_get_time_tics() returns the number of elapsed time tics. The time tic is explained below.
@section LEVEL4 Setting the Time
Trick provides 2 calls to set the simulation time.
@code
int exec_set_time( double in_time ) ;
int exec_set_time_tics( long long in_time_tics ) ;
@endcode
exec_set_time() sets the current simulation time to the incoming value. This should normally be done
at initialization. Doing this while running is not defined.
exec_set_time_tics() sets the simulation time based on time tics. The time tic is explained below.
@section LEVEL4 Time tic
@code
int exec_get_time_tic_value( void ) ;
int exec_set_time_tic_value( int num_of_tics_per_second ) ;
@endcode
A time tic is a fraction of a second equal to 1s/<number_of_tics_per_second>. The time tic default is 1us.
Scheduled job cycles are converted to numbers of tics. For instance a 1ms cycle job will be run every
1000 tics. All job cycles should be a multiple of the time tic value. If they are not the number of
time tics is rounded down to the nearest number of tics. The time tic value can be changed with the
exec_set_time_tic_value() call.
Example 1: A job is set to run at 128Hz or at 0.0078125 seconds. This is converted to 7812.5 tics using
the default tic value. The job will end up running incorrectly every 7812 tics. To correct this we
call exec_set_time_tic_value(10000000) to set the time tic value to 100ns. With a 100ns time tic value
the job will be called every 78125 tics, which is (10000000/78125) = 128Hz.
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.
@section LEVEL3 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.
@code
int exec_set_software_frame(double) ;
double exec_get_software_frame() ;
long long exec_get_software_frame_tics() ;
int exec_set_freeze_frame(double) ;
double exec_get_freeze_frame() ;
long long exec_get_freeze_frame_tics() ;
@endcode
exec_set_software_frame(double) and exec_set_freeze_frame(double) both take frame values in seconds.
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.
@section LEVEL3 User Mode Control
User's may toggle the Executive mode between Freeze and Run as well as command simulation Shutdown.
@section LEVEL4 Getting the current mode
@code
# Python code
SIM_MODE trick.exec_get_mode()
@endcode
exec_get_mode returns the current mode of the simulation. See the SIM_MODE definition for the
enumeration values.
@section LEVEL4 Commanding to Freeze
@code
// C/C++ code
#include "sim_services/Executive/include/exec_proto.h"
exec_freeze()
@endcode
@code
# Python code
trick.freeze()
trick.freeze(<double freeze_time>)
@endcode
Users may command freeze in model code by calling exec_freeze(). Inside the input file user's
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.
@code
# Python code
trick.exec_set_freeze_command(int on_off)
@endcode
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.
@code
# Python code
trick.exec_set_freeze_on_frame_boundary(int on_off)
@endcode
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 avaialbe frame boundary.
@code
# Python code
trick.exec_set_enable_freeze( int on_off )
int trick.exec_get_enable_freeze() ;
@endcode
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.
@section LEVEL4 Commanding to Run
@code
exec_run()
@endcode
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.
@section LEVEL4 Commanding to Shutdown
@code
# Python code
trick.exec_set_terminate_time(double time_value)
double trick.exec_get_terminate_time() ;
@endcode
The most common way to shutdown a simulation is setting a terminate time. When simulation elapsed
time reaches the terminate time, the shutdown jobs are executed and the program terminates.
@code
exec_terminate(const char *file_name, const char *error)
exec_terminate_with_return(int ret_code, const char *file_name, int line, const char *error)
@endcode
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.
@section LEVEL3 Job Control
The executive provides routines to control job execution.
@section LEVEL4 Turning Jobs On/Off
@code
# Python code
trick.exec_set_job_onoff(char * job_name , int instance_num , int on) ;
@endcode
The exec_set_job_onoff() routine allows users to turn individual jobs on and off. The job name is
the concatenation of the sim_object name and the job name. The instance_num argument is used
when jobs have the same name. Jobs with unique names are always instance_num 1. Jobs with
identical names start at instance_num 1 and increment for each job as they appear in the
sim object.
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.
@code
# Python code
trick.exec_set_sim_object_onoff(char * job_name , int on) ;
@endcode
The exec_set_sim_object_onoff routine allows users to turn individual whole sim_objects on and off.
@section LEVEL4 Job Cycle Time
@code
# 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)
@endcode
Each job cycle time is availabe to read and to set. Some job classes ignore cycle times, i.e. initialization
and shutdown. The user may change the cycle time set in the S_define file with the exec_set_job_cycle() call.
The instance_num argument is used when jobs have the same name (see exec_set_job_onoff above).
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.
@section LEVEL3 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.
@code
# Python code
trick.exec_set_thread_process_type( unsigned int thread_id , int process_type )
@endcode
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.
@section LEVEL4 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.
@section LEVEL4 PROCESS_TYPE_ASYNC_CHILD Threads
Asynchronous threads have 2 modes of operation depending on if a synchronization time is specified. A cycle
syncrhonization time is set through the exec_set_thread_async_cycle_time call.
@code
# Python code
trick.exec_set_thread_async_cycle_time( unsigned int thread_id , double cycle_time ) ;
@endcode
If the synchronization cycle time is set to zero, then the asynchronous threads do not synchronize to the main thread.
Asynchronous jobs are often infinite loops. If all jobs in an asynchronous thread finish, the thread is
immediately restarted. Execution frequencies for jobs in asynchronous threads are ignored. All jobs are run
each time an asynchronous thread is executed. Asynchronous thread simulation time is set to the thread start
time and is not updated while the thread is executing.
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 syncrhonization 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.
@section LEVEL4 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.
@code
# Python code
trick.exec_set_thread_amf_cycle_time( unsigned int thread_id , double cycle_time ) ;
@endcode
exec_set_thread_amf_cycle_time sets the synchronization cycle rate with the main thread.
@section LEVEL4 Main Thread CPU release.
@code
# Python code
trick.exec_set_rt_nap(int on_off)
trick.exec_get_rt_nap()
@endcode
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.
@section LEVEL4 Asynchronous Threads at Shutdown
@code
# Python code
trick.exec_set_thread_async_wait( unsigned int thread_id , int yes_no ) ;
@endcode
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.
@section LEVEL4 Thread Priorities
@code
# Python code
trick.exec_set_thread_priority(unsigned int thread_id , unsigned int req_priority)
@endcode
exec_set_thread_priority() will set the thread's priority. The main thread is thread_id=0, 1-n are the
child threads. for req_priority, 1 is the highest priority. This number is converted internally
to the highest priority of the system automatically.
@note Setting a simulation to run as priority 1 may lock out keyboard and mouse processing.
@code
# Python code
trick.exec_set_thread_cpu_affinity(unsigned int thread_id , int cpu_num) ;
@endcode
exec_set_thread_cpu_affinity assigns a thread to a specific CPU. The main thread is thread_id=0. 1-n are
the child threads. Setting a thread to run on a specific CPU does not exclude other processes to
continue to run on the same CPU.
@section LEVEL4 Thread Priorities
@code
# Python code
trick.exec_set_lock_memory(int yes_no) ;
@endcode
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.
@section LEVEL4 Thread Job Dependencies
@code
# Python code
trick.exec_add_depends_on_job(char * target_job_string , unsigned int t_instance ,
char * depend_job_string , unsigned int d_instance )
@endcode
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.
@section LEVEL4 Getting Thread ID
@code
unsigned int exec_get_process_id() ;
unsigned int exec_get_num_threads() ;
@endcode
exec_get_process_id() will return the current thread the caller is on. 0 = main thread, 1-n
are the child threads. If this call is issued through a variable server client, or a thread
that was not spawned by the executive, a -1 error code is returned.
exec_get_num_threads() returns the number of child threads spawned by the main thread.
@section LEVEL3 Debugging Help
The Executive provides several parameters that can help a model developer debug a simulation.
@section LEVEL4 Trapping signals
@code
# Python code
trick.exec_set_trap_sigbus(int on_off)
trick.exec_set_trap_sigfpe(int on_off)
trick.exec_set_trap_sigsegv(int on_off)
trick.exec_get_trap_sigbus()
trick.exec_get_trap_sigfpe()
trick.exec_get_trap_sigsegv()
@endcode
The set_trap routines listed above set a signal handler for the SIGBUS, SIGFPE, and SIGSEGV
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 exitting execution. Turning off the traps will revert
signal handling to the default system signal handler. By default the traps for SIGBUS and
SIGSEGV are true. SIGFPE is not trapped by default.
@section LEVEL4 Printing a Stack (Call) Trace on Signal
@code
# Python code
trick.exec_set_stack_trace(int on_off)
@endcode
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.
@section LEVEL4 Attaching a debugger on Signal
@code
# Python code
trick.exec_set_attach_debugger(int on_off)
@endcode
This is a Linux only option. By default, this option is off. If enabled, when a signal
is trapped a debugger is automatically connected to the running simulation and an interactive
debugging session is presented to the user.
The debugger executable may be set with the following. The default is "/usr/bin/gdb".
@code
# Python code
trick.exec_set_debugger_command(char * command)
char * trick.exec_get_debugger_command()
@endcode
@section LEVEL4 Getting Build Information
@code
# Python code
char * trick.exec_get_current_version()
@endcode
The executive stores the Trick version that was used to build the executable. Use
exec_get_current_version() to return the version string.
@section LEVEL3 Executive Scheduler Related Pages
@subpage scheduler_requirements "Scheduler Requirements"\n
@subpage scheduler_design "Scheduler Design"
*/
#include "requirements.dox"
#include "design.dox"

194
trick_source/sim_services/ExternalApplications/docs/main_page.dox_in
View File

@ -1,194 +0,0 @@
/**
* @anchor ExternalApplications
* @page LEVEL2 Runtime GUIs
*
* Trick provides the following graphical user interfaces:
*/
#include "sim_services/ExternalApplications/docs/scp.dox_in"
/**
* @page LEVEL2cont
* - @subpage SimControlPanelPage "LEVEL3cont Sim Control Panel" <br>
* Send control commands to and view the status of a simulation.
*/
#include "sim_services/ExternalApplications/docs/tv.dox_in"
/**
* @page LEVEL2cont
* - @subpage TrickViewPage "LEVEL3cont Trick View" <br>
* Browse and modify a simulation's variables while it's running. Launch integrated strip charts.
*/
#include "sim_services/ExternalApplications/docs/mtv.dox_in"
/**
* @page LEVEL2cont
* - @subpage MalfunctionsTrickViewPage "LEVEL3cont Events/Malfunctions Trick View" <br>
* Manage the events and malfunctions of a simulation.
*/
#include "sim_services/ExternalApplications/docs/mm.dox_in"
/**
* @page LEVEL2cont
* - @subpage MonteMonitorPage "LEVEL3cont Monte Monitor" <br>
* Monitor the status of a Monte Carlo simulation; create, start, and stop slaves.
*
* @section LEVEL3 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:
*
* @code trickView = trick.TrickView() @endcode
*
* You now have an instance of the %Trick View launcher class on which you can invoke calls to modify the actual %Trick View
* application's behavior at launch. For instance, you could set the host and port:
*
* @code
* trickView.set_host("localhost")
* trickView.set_port(7000)
* @endcode
*
* And then add it for automatic launching:
*
* @code trick.add_external_application(trickView) @endcode
*
* 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).
*
* @anchor ExternalApplicationsAutomaticLaunching
* @section LEVEL3 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.
*
* @section LEVEL3 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.
*
* @section LEVEL3 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.
*
* @section LEVEL3 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.
*
* @code
* customApplication = trick.ExternalApplication()
* customApplication.set_startup_command("echo Hello World!")
* customApplication.set_arguments("")
* trick.add_external_application(customApplication)
* @endcode
*
* Note that ExternalApplication automatically appends the host and port argument unless you set the arguments by calling
* Trick::ExternalApplication::set_arguments.
*
* 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!
*
* @section LEVEL3 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.
*
* @section LEVEL4 Host
*
* The host of the Variable Server to which the application will connect at launch can be specified via one of:
*
* - From the command line, use the <code>\-\-host</code> option.
*
* - From the input file or user model code, use Trick::ExternalApplication::set_host
*
* If no host is specified, it will automatically be set to that of the simulation which is launching this application.
*
* @section LEVEL4 Port
*
* The port of the Variable Server to which the application will connect at launch can be specified via one of:
*
* - From the command line, use the <code>\-\-port</code> option.
*
* - From the input file or user model code, use Trick::ExternalApplication::set_port
*
* If no port is specified, it will automatically be set to that of the simulation which is launching this application.
*
* @section LEVEL4 Automatically Reconnect
*
* The application can be configured to automatically reestablish lost connections via one of:
*
* - From the command line, use the <code>\-\-autoReconnect</code> option.
*
* - From the input file or user model code, use Trick::ExternalApplication::set_auto_reconnect
*
* - From the application, use the <code>File->Settings</code> menu.
*
* The default value is <code>false</code>.
*
* @section LEVEL4 Window Size and Placement
*
* The window's coordinates and dimensions at launch can be set via one of:
*
* - From the command line, use the <code>\-\-x</code>, <code>\-\-y</code>, <code>\-\-width</code>, or <code>\-\-height</code>
* 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.
*
* @section LEVEL4 Cycle Period
*
* The period (in seconds) at which the Variable Server sends information to the application can be specified via one of:
*
* - From the command line, use the <code>\-\-cycle</code> option.
*
* - From the input file or user model code, use Trick::ExternalApplication::set_cycle_period.
*
* - From the application, use the <code>File->Settings</code> menu.
*
* The cycle period must be a non-negative number. Specify <code>0</code> to recieve updates at the maximum rate. Values
* below the minimum cycle period will be set to the minimum cycle period.
*
* @section LEVEL4 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:
*
* - From the command line, use the <code>\-\-minCycle</code> option.
*
* - From the input file or user model code, use Trick::ExternalApplication::set_minimum_cycle_period.
*
* The minimum cycle period must be a non-negative number. The recommended and default value is <code>0.1</code>. Values
* below this may cause instability in %Trick GUIs.
*
* @section LEVEL4 Application Behavior
*
* The application can take one of several actions when it loses the connection with the simulation:
*
* - <b>Close</b><br>
* Terminate and close.
*
* - <b>Notify</b><br>
* Present a notification dialog describing the failure.
*
* - <b>Nothing</b><br>
* Do nothing.
*
* This behavior can be specified via one of:
*
* - From the command line, use the <code>\-\-disconnectBehavior</code> option.
*
* - From the input file or user model code, use Trick::ExternalApplication::set_disconnect_behavior.
*
* - From the application, use the <code>File->Settings</code> menu.
*/

103
trick_source/sim_services/ExternalApplications/docs/mm.dox_in
View File

@ -1,103 +0,0 @@
/**
* @page MonteMonitorPage
* @section LEVEL3 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.
*
* @section LEVEL4 Launching
*
* MM can be launched from the command line via:
*
* @code ${TRICK_HOME}/bin/mm [options] @endcode
*
* Pass <code>--help</code> for a description of available options. For additional launching options, see
* @ref ExternalApplicationsAutomaticLaunching "Automatically Launching Applications".
*
* @section LEVEL4 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.
*
* @image html ../../../doxygen/images/MonteMonitor.jpg
* @image rtf ../../../doxygen/images/MonteMonitor.jpg
*
* @section LEVEL5 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>.
*
* @section LEVEL5 Slave Table
*
* The slave table displays information on each of the slaves. From left to right, this information is:
*
* <ul><li><b>ID</b><br>
* The unique ID of the slave.
*
* <li><b>Status</b><br>
* The current status of the slave. It can be one of:
*
* <ul><li><b>Unitialized</b><br>
* The slave has yet to be spawned.
*
* <li><b>Initializing</b><br>
* The slave has been spawned, and the master is waiting for initialization information from it. Once initialized, the
* slave will be in the <code>Ready</code> state. Since Monte Carlo cannot determine if slaves spawn correctly, slaves
* that fail to spawn will remain in this state for the duration of the Monte Carlo.
*
* <li><b>Ready</b><br>
* The slave is awaiting a dispatch.
*
* <li><b>Running</b><br>
* The slave is processing a run. Once completed, the slave will be in the <code>Ready</code> state.
*
* <li><b>Stopping</b><br>
* The slave is processing a run. Once completed, the slave will be in the <code>Stopped</code> state.
*
* <li><b>Stopped</b><br>
* The slave is not accepting dispatches.
*
* <li><b>Finished</b><br>
* No runs remain to dispatch to the slave.
*
* <li><b>Unresponsive - Running</b><br>
* The slave has timed out and is also in the <code>Running</code> state.
*
* <li><b>Unresponsive - Stopping</b><br>
* The slave has timed out and is also in the <code>Stopping</code> state.
*
* <li><b>Disconnected</b><br>
* The connection to the slave has been lost.
*
* <li><b>Unknown</b><br>
* MM could not interpret the state of the slave as reported by the Monte Carlo simulation.
*
* </ul><li><b>Machine Name</b><br>
* The name of the machine on which the slave is running.
*
* <li><b>Current Run</b><br>
* The ID of the run the slave is currently processing.
*
* <li><b>Total Runs</b><br>
* The number of runs the slave has completed.
*
* @section LEVEL5 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>.
*
* @section LEVEL5 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.
*
* @section LEVEL4 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
* command from the <code>Slaves</code> menu to all slaves in the slave table. Stopping a slave will prevent any further
* runs from being dispatched to it after its current dispatch completes. Starting a slave will resume dispatches to it.
*
* @see Trick::MonteMonitor
*/

210
trick_source/sim_services/ExternalApplications/docs/mtv.dox_in
View File

@ -1,210 +0,0 @@
/**
@page MalfunctionsTrickViewPage
@section LEVEL3 Events/Malfunctions Trick View
Events/Malfunctions %Trick View (hereafter referred to as MTV) is a graphical user interface that has two main functions:
-# to view/control Trick-managed event activity while the simulation is running, and
-# to create/edit Trick-managed events for saving to a file or for sending directly to a running simulation.
"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".\n
@see @ref Input_File_Events "Input File Events" and @ref Input_Processor "Input Processor"
@section LEVEL4 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:\n\n
@image html ../../../doxygen/images/mtv_launch.jpg
@image rtf ../../../doxygen/images/mtv_launch.jpg
\n If you want MTV to launch every time you run a simulation, you can automatically launch MTV each run by coding the following in your Run input file:
@code trick.malfunctions_trick_view_set_enabled(1) @endcode
\n MTV can also be launched from the command line via:
@code mtv <hostname> <port> @endcode
The mtv launch script is located in $TRICK_HOME/bin. If you only want to use MTV to create/edit a new event, you can simply type: @code mtv @endcode
on the command line in your simulation directory (without the <hostname> or <port> arguments). You can save your newly created event to a file but
you of course can't send it to a running simulation in this mode (See @ref MTV_send_to_sim "Send To Sim Button" below).
\n\n For additional launching options, see @ref ExternalApplicationsAutomaticLaunching "Automatically Launching Applications".
@anchor MTV_GUI_picture
@section LEVEL4 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 @b View @b 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.\n\n
@image html ../../../doxygen/images/mtv_view.jpg
@image rtf ../../../doxygen/images/mtv_view.jpg
@section LEVEL5 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).
@anchor MTV_background_on_event_processing
@section LEVEL5 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.
@section LEVEL5 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.
@section LEVEL5 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 @c 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
@c condition() or @c 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 @c conidtion() or @c action() command.
@section LEVEL5 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. An event 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 @c manual_fire() or @c manual_on(). An event action runs if it is Active and the event fires. An event runs when at least one of its actions runs.
@section LEVEL5 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.
@section LEVEL5 Event Mode
The 8th column in View Mode is the Event Mode selector:
@li @b Normal The default, event conditions are evaluated to determine when the event fires (issues a @c manual_done() command).
@li @b Manual @b FIRE Fire the event once now, remain in manual OFF mode (issues a @c manual_fire() command).
@li @b Manual @b ON Fire the event every time it is evaluated, remain in manual ON mode (issues a @c manual_on() command).
@li @b Manual @b OFF Do not fire the event, remain in manual OFF mode (issues a @c manual_off() command).
When in one of the Manual modes, the event's conditions are not evaluated, the manual command issued determines if the event fires.
@note The @c 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 @c 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.
@section LEVEL5 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 (@c manual_fire()) command. When you click on the Added toggle
to uncheck it, a @c remove_event() command is issued.
@note Instead of adding an event (via @c 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 @c add_event_before() or @c 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 @c add_event_before() or @c 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 @c add_event(), @c add_event_before(), or @c add_event_after().
@section LEVEL5 Colors Used in MTV
@li @b Black @b font An event in Normal mode that is both Active and Added, having been added using the @c add_event() command.
@li @b Brown @b font An event in Normal mode that is both Active and Added, having been added using the @c add_event_before() or @c add_event_after() command.
@li @b Gray @b 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).
@li @b Blue @b font An event in Manual mode (this color overrides the previous three colors, except that actions can be inactive in Manual mode, so inactive actions will be gray).
@li @b Red @b background An event's Fired Time column is highlighted in red when it fires.
@li @b Green @b background An event's Ran Time column is highlighted in green when it runs.
@section LEVEL5 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.
@section LEVEL5 View Menu
@section LEVEL6 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.
@section LEVEL6 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 less 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 @c mygroup.this_event and @c mygroup.that_event shown in @ref MTV_GUI_picture "the MTV GUI picture above" were defined like this :
@code
class MyGroup:
this_event = trick.new_event("mygroup.this_event")
this_event.condition(0, "test.obj.run_status<1")
this_event.action(0, "trick.freeze()")
this_event.action(1, "test.obj.run_status=1")
this_event.activate()
trick.add_event(this_event)
that_event = trick.new_event("mygroup.that_event")
that_event.condition(0, "test.obj.run_status>1")
that_event.action(0, "trick.run()")
that_event.activate()
trick.add_event(that_event)
mygroup = MyGroup()
@endcode
The Customize Event Display popup will recognize such event groups and allow you to select / deselect events by group name. It will contain a Tab for each
event group labeled with the group name; events that do not belong to any group will be in a Tab labeled "Events".\n\n
@image html ../../../doxygen/images/mtv_customize.jpg
@image rtf ../../../doxygen/images/mtv_customize.jpg
\n You may notice some events named "no_name_specified". These are either events created for @c add_read() statements in the Run input file, or events created
by the @c 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.
@section LEVEL5 Cycle Menu
The Cycle Menu allows you to set how fast the MTV GUI receives udpates 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).
@section LEVEL5 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.
Thre 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 @ref SimControlPanel "Simulation Control Panel" if it is up.)
@section LEVEL4 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 @b Edit @b Mode.\n\n
@image html ../../../doxygen/images/mtv_edit.jpg
@image rtf ../../../doxygen/images/mtv_edit.jpg
@section LEVEL5 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).
@section LEVEL5 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.
@section LEVEL5 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 @ref MTV_edit_menu "Edit Menu" described below.
@section LEVEL5 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:
@code
File "<string>", line 1
trick_ip.ip.return_val = XXX
SyntaxError: unexpected EOF while parsing@endcode
Where "XXX" is the offending string from your event command.
@anchor MTV_send_to_sim
@section LEVEL5 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.
@section LEVEL5 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.
Currenty there is no way to Load Event(s) from a file into the MTV editor. It is strictly for creating new events from scratch.
@anchor MTV_edit_menu
@section LEVEL5 Edit Menu
@section LEVEL6 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.
@section LEVEL6 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.
@section LEVEL6 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.
@section LEVEL6 Add Statement
You can add more event commands to the event you are editing by selecting Add Statement from the Edit Menu. All of the valid event commands are then
popped up for you to select.
*/

7
trick_source/sim_services/ExternalApplications/docs/scp.dox_in
View File

@ -1,7 +0,0 @@
/**
* @page SimControlPanelPage
* @anchor SimControlPanel
* @section LEVEL3 Sim Control Panel
*
* @see Trick::SimControlPanel
*/

399
trick_source/sim_services/ExternalApplications/docs/tv.dox_in
View File

@ -1,399 +0,0 @@
/**
* @page TrickViewPage
* @section LEVEL3 Trick View
*
* %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.
*
* @see @ref ExternalApplications "Runtime GUIs"
*
* @section LEVEL4 Launching
* TV can be launched via one of:
*
* - From the @ref SimControlPanel "Simulation Control Panel", under the <code>Actions</code> menu.
*
* @image html ../../../doxygen/images/tv_launch.jpg
* @image rtf ../../../doxygen/images/tv_launch.jpg
*
* - From the command line:
* @code tv [options] @endcode
* The TV launch script is located in <code>$TRICK_HOME/bin</code>. Pass <code>\-\-help</code> for a description of
* available options.
*
* For additional launching options, see @ref ExternalApplicationsAutomaticLaunching "Automatically Launching Applications".
*
* @section LEVEL4 Automatically Opening Files
*
* Files that are to be automatically opened when TV launches can be specified via one of:
*
* - From the command line, use the <code>\-\-open</code> option.
* File paths are relative to the directory from which TV launches.
*
* - From the input file or user model code, use Trick::TrickView::set_auto_open_file.
* File paths are relative to the directory containing the S_main executable.
*
* Opening a TV file will overwrite the current cycle period or any argument to <code>\-\-cycle</code> with the value from
* the file, subject to the minimum cycle period.
*
* @section LEVEL4 Automatically Opening and Setting Files
*
* Files that are to be automatically opened and set when TV launches can be specified via one of:
*
* - From the command line, use the <code>\-\-openSet</code> option.
* File paths are relative to the directory from which TV launches.
*
* - From the input file or user model code, use Trick::TrickView::set_auto_open_and_set_file.
* File paths are relative to the directory containing the S_main executable.
*
* Opening a TV file will overwrite the current cycle period or any argument to <code>\-\-cycle</code> with the value from
* the file, subject to the minimum cycle period.
*
* @section LEVEL4 Automatically Setting Files
*
* Files that are to be automatically set when TV launches can be specified via one of:
*
* - From the command line, use the <code>\-\-set</code> option.
* File paths are relative to the directory from which TV launches.
*
* - 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.
*
* @section LEVEL4 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:
*
* - From the command line, use the <code>\-\-stripChartsOnly</code> option.
*
* - From the input file or user model code, use Trick::TrickView::set_strip_charts_only.
*
* Note that you must provide a TV file to be automatically opened as described above when launching in strip-chart-only
* mode.
*
* @section LEVEL4 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.
*
* @image html ../../../doxygen/images/TrickView.jpg
* @image rtf ../../../doxygen/images/TrickView.jpg
*
* @section LEVEL5 File Buttons
*
* The file buttons provide for persistent storage of lists of variables of interest. From left to right, they are:
*
* - <b>New</b><br>
* Clears the variable table.
*
* - <b>Open</b><br>
* Opens a dialog allowing the user to select a TV file. The variable table will be cleared and replaced by
* the variables from the file. The saved cycle period and any strip charts will be restored.
*
* - <b>Open And Set</b><br>
* Opens a dialog allowing the user to select a TV file. The variable table will be cleared and replaced by
* the variables from the file. Additionally, the variables will be set to their corresponding values in the file.
* The saved cycle period and any strip charts will be restored.
*
* - <b>Set</b><br>
* Opens a dialog allowing the user to select a TV file. The variables listed in the file will be set to
* their corresponding values in the file. The variable table, cycle period, and any strip charts will be unaffected.
*
* - <b>Save</b><br>
* 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.
*
* @section LEVEL5 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.
*
* @section LEVEL5 Variable Buttons
*
* The variable buttons affect variables in the variable table. From left to right, they are:
*
* - <b>Strip Chart</b><br>
* Launches a strip chart that will plot all selected variables on the same graph while the simulation is running.
*
* - <b>Delete</b><br>
* Removes the selected variables from the variable table and all strip charts.
*
* @section LEVEL5 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 <code>Add Selection</code> 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 extremely unresponsive.
*
* @section LEVEL5 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 simulation objects. In subsequent
* searches, a quantitative value of progress is displayed.
*
* @section LEVEL5 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.
*
* @image html ../../../doxygen/images/TVSpecifyIndices.jpg
* @image rtf ../../../doxygen/images/TVSpecifyIndices.jpg
*
* Each array displays a combo box over its allowable range. Each pointer has a single text box that accepts values in the
* form <code>minimum-maximum</code>. 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.
*
* @section LEVEL5 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 <code>Delete</code> key while the variable table has focus is equivalent to clicking the delete variable button.
*
* While you cannot actually change a variable's name, you can quickly add another variable of a similar name by
* double-clicking the name cell of a variable and modifying it. The original variable will remain unchanged, and a variable
* of the new name will be added.
*
* Each variable's value is displayed according to its type and format. Booleans are represented by check boxes; enumerated
* types, by combo boxes; and all other types, by a string. Modifying a variable's value is achieved by clicking the check
* box, selecting a value from the combo box, or directly entering a new value. Inputs are validated against the variable's
* type before being submitted to the Variable Server. Note that the displayed value will not change until the
* Variable Server reflects the change.
*
* Variable units are displayed via a combo box containing all of the supported units. To change a variable's units, click
* its units cell and select a new value. Note that the displayed units will not change until the Variable Server reflects
* the change.
*
* Variable formats are displayed via a combo box containing all of the supported formats for the variable's type. To change
* a variable's format, click its format cell and select a new value. The displayed value will be updated immediately.
*
* 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.
*
* @subsection LEVEL6 Invalid References
*
* Variables that the Variable Server failed to resolve display values of <code>\<Invalid Reference\></code> 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.
*
* @section LEVEL5 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:
*
* @code ball.obj.state.output.position[0-1] @endcode
*
* Note that pointers cannot be dereferenced using the pointer dereference operator (<code>*</code>) in TV. Instead, the user
* should treat the pointer as a single-element array and append the variable's name with <code>[0]</code>.
*
* @section LEVEL5 Purge Button
*
* The purge button removes all variables from the variable table that have a value of <code>\<Invalid Reference\></code>.
*
* @section LEVEL5 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.
*
* @section LEVEL5 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 <code>host:port</code>.
*
* @section LEVEL5 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 <code>Action</code> menu of either TV or any strip chart. Note that this will erase any data currently
* being displayed on any strip charts.
*
* @section LEVEL5 Settings
*
* The Settings dialog can be accessed via the <code>File</code> menu and allows the user to alter the behavior of TV.
* See @ref ExternalApplications "Runtime GUIs" for a detailed description of Application Behavior and Cycle Period options.
*
* @image html ../../../doxygen/images/TVSettings.jpg
* @image rtf ../../../doxygen/images/TVSettings.jpg
*
* @subsection LEVEL6 Variable Tree Order
*
* The order in which the variable hierarchy is displayed has two options:
*
* - <b>Alphabetic</b><br>
* Variables are sorted alphabetically.
*
* - <b>Declared</b><br>
* Variables are sorted according to their order of declaration within the simulation.
*
* @subsection LEVEL6 Variable Addition
*
* The placement of newly added variables within the variable table is specified via the Position combo box. The available
* options are <code>Top</code>, <code>Before</code>, <code>After</code>, and <code>Bottom</code>. The <code>Before</code>
* and <code>After</code> options are relative to the currently selected row.
*
* Character pointers and arrays can be treated as strings by default by checking the <code>char[] as string</code> check
* box. When added as such, arrays will be collapsed into single string entries. Otherwise, they will be displayed element
* by element.
*
* @subsection LEVEL6 Font Size
*
* This setting affects the variable hierarchy tree, search panel, and variable table text size.
*
* @subsection LEVEL6 Default Units
*
* Default units for each unit type can be specified via its corresponding combo box, which lists all of its available
* units. Selecting <code>xx</code> results in units as specified in the model code. The <code>Default All</code> check box,
* when selected, is equivalent to selecting <code>xx</code> for all unit types.
*
* @subsection LEVEL6 Default Formats
*
* Default formats for each variable type can be specified via its corresponding combo box.
*
* @section LEVEL4 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.
*
* @image html ../../../doxygen/images/Stripchart.jpg
* @image rtf ../../../doxygen/images/Stripchart.jpg
*
* @section LEVEL5 Domain Axis Panel
*
* The domain axis panel allows the user to affect the range of the domain axis.
*
* - <b>All</b><br>
* The domain axis will continuously adjust to contain the entirety of all plotted variables' domain values.
*
* - <b>Strip</b><br>
* The domain axis will continuously scroll such that the latest sub-set (as set by the adjacent text box) of domain values
* is contained.
*
* - <b>Fixed</b><br>
* The domain axis will not automatically change.
*
* @section LEVEL5 Display Panel
*
* The display panel allows the user to specify whether or not the chart should display certain features.
*
* - <b>Lines</b><br>
* When enabled, lines will be drawn between the data points.
*
* - <b>Points</b><br>
* When enabled, the data points themselves will be drawn.
*
* - <b>Legend</b><br>
* When enabled, the chart's legend will be shown.
*
* @section LEVEL5 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 <code>Add</code> button. To remove a dependent
* variable, select it from the adjacent combo box and click the <code>Remove</code> button. To change the independent
* variable, select it from the adjacent combo box.
*
* @section LEVEL5 Right-Click Menu
*
* Right-clicking the plot area will display a context menu with the following options:
*
* - <b>Properties</b><br>
* Opens a dialog allowing the user to customize the plot as described below.
*
* - <b>Copy</b><br>
* Copies the plot to the clipboard, allowing the user to paste the content into other applications.
*
* - <b>Save As...</b><br>
* Opens a dialog allowing the user to save the plot as a PNG file.
*
* - <b>Print...</b><br>
* Opens a dialog allowing the user to print the plot.
*
* - <b>Zoom In</b><br>
* Zooms in either or both axes. This can also be achieved by left-click-dragging a box from its top-left to bottom-right
* corner.
*
* - <b>Zoom Out</b><br>
* Zooms out either or both axes. This can also be achieved by left-click-dragging any other way than described above.
*
* - <b>Auto Range</b><br>
* Automatically adjusts one or both axes.
*
* @section LEVE5 Chart Properties Dialog
* The Chart Properties dialog can be opened by selecting <code>Properties</code> 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.
*
* @image html ../../../doxygen/images/TVChartPropertiesTitleTab.jpg
* @image rtf ../../../doxygen/images/TVChartPropertiesTitleTab.jpg
*
* The <code>Title</code> tab allows the user to toggle visibility of the title and to set the title's text, font, size,
* and color.
*
* @image html ../../../doxygen/images/TVChartPropertiesPlotTab.jpg
* @image rtf ../../../doxygen/images/TVChartPropertiesPlotTab.jpg
*
* The <code>Plot</code> tab allows the user to set the label text, font, size, and color for the domain and range axes.
* It also provides for toggling the visibility of each axis' tick labels and marks, for setting each axis' label font
* and size, and for adjusting the range of each axis.
*
* @image html ../../../doxygen/images/TVChartPropertiesAppearanceTab.jpg
* @image rtf ../../../doxygen/images/TVChartPropertiesAppearanceTab.jpg
*
* The <code>Appearance</code> tab within the <code>Plot</code> tab allows the user to set the plot's border's width and
* color and the plot's background color. It also provides for inverting the axes.
*
* @image html ../../../doxygen/images/TVChartPropertiesOtherTab.jpg
* @image rtf ../../../doxygen/images/TVChartPropertiesOtherTab.jpg
*
* The <code>Other</code> 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.
*
* @section LEVEL4 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.
*
* TV files have changed format a number of times since the release of %Trick 10. Originally, they were simple custom text
* files. This evolved into a custom XML format (%Trick 10.4) which provided for better verification under a formal language.
* As the amount and types of data to be saved to persistent memory between sessions increased, it became obvious that the
* creating and parsing of custom-defined XML elements was not maintainable in the long run. Thus, the persistent storage
* mechanism was changed to Java's serialization protocol (%Trick 10.7), which stores data in binary. This delegated nearly
* all of the work to Java, reducing the code related to saving and restoring state to a few lines. However, users that had
* come to rely on the capability to manually modify TV files found the new format unacceptable, since it was no longer
* human-readable. Therefor, the storage mechanism has changed once again to an XML format. This time the marshaling and
* unmarshaling is delegated entirely to Java's JAXB library, which encodes Java classes that follow the JavaBean design
* pattern, to which much of TV's package has been modified to adhere. This achieves most of the best of both of the previous
* formats while incurring code overhead somewhere between the two. TV is backwards-compatible with the two previous formats
* (to %Trick 10.4) but will always save in the current (JAXB) format. The XML schema, which is automatically created by
* JAXB, can be found at <a href="../../bin/java/src/trick/tv/resources/trickView.xsd">trickView.xsd</a>.
*
* There is one special case in which backwards-compatibility is not maintained. TV files from %Trick 10.4 to 10.6 rely on
* the variable hierarchy tree being parsed before the file is loaded so that enumeration descriptions are available.
* However, the variable hierarchy tree is now populated in the background so that the GUI is immediately responsive upon
* launch. Therefor, if an old-format TV file containing enumeration variables is specified to be automatically loaded on
* launch and the variable hierarchy tree is slow to load, the enumeration variables will fail to resolve to valid values
* and will display <code><error, reload me></code>. Simply reload the TV file to resolve the issue. After saving the file
* in the new format, this error will not occur again.
*
* @see Trick::TrickView
*/

31
trick_source/sim_services/FrameLog/docs/main_page.dox_in
View File

@ -1,31 +0,0 @@
/**
@page LEVEL2 Trick Frame Logging
Trick provides a means to gather simulation performance data and view it using Data Products (see @ref DataProducts "Data Products").
When the user turns on the Frame Logging feature, Trick will use its Data Recording mechanism to track the following:
- execution time of each Trick and User job, view in Data Products using DP_rt_trickjobs.xml and DP_rt_userjobs.xml
- a timeline showing when each job runs during each job frame, view in Data Products using DP_rt_timeline_init.xml and DP_rt_timeline.xml
- total execution time of all jobs for each frame showing underrruns/overruns, view in Data Products using DP_rt_frame.xml
You can turn frame logging on and off whenever you want to toggle frame logging during execution.\n
Caveat:\n
You must always turn frame_log_on() first (i.e., in the input file) because it has to create data recording groups at initialization time.
If you don't want to begin frame logging at time 0, then you can simply make your next statement frame_log_off(). After that you can turn it on/off at will.
The following input file example will only frame log from simulation time 500-600 and from 1500 to end of run:
@code
trick.frame_log_on()
trick.frame_log_off()
trick.add_read(500.0, "trick.frame_log_on()")
trick.add_read(600.0, "trick.frame_log_off()")
trick.add_read(1500.0, "trick.frame_log_on()")
@endcode
@section LEVEL3 User accessible routines
@li int frame_log_on() ;
@li int frame_log_off() ;
@li int frame_log_set_max_samples(int num) ;
@note The Frame Logging feature is only valid when the simulation is run in real-time (see @ref RealTime "Real-Time").
*/

52
trick_source/sim_services/InputProcessor/docs/main_page.dox_in
View File

@ -1,52 +0,0 @@
/**
@anchor Input_Processor
@page LEVEL2 Input Processor
This page describes the methods available in the Trick::InputProcessor class.
@note <b>See @ref Input_File "Input File" for detailed information on the syntax of the input processor file. </b>
@section LEVEL3 User accessible routines
@li int @link Trick::IPPython::shutdown() shutdown() @endlink
These commands are for creating python events and manipulating them.
@li IPPythonEvent * @link ippython_new_event() new_event() @endlink
@li int @link ippython_add_read(double in_time , char * in_string) add_read(double in_time , char * in_string) @endlink
@li int @link ippython_add_read(unsigned int thread_id , double in_time , char * in_string) add_read(double in_time , char * in_string) @endlink
@li int @link ippython_delete_event(IPPythonEvent * in_event) delete_event(IPPythonEvent * in_event) @endlink
@li int @link ippython_manual_on(std::string * name) manual_on(std::string name) @endlink
@li int @link ippython_manual_fire(std::string * name) manual_fire(std::string name) @endlink
@li int @link ippython_manual_off(std::string * name) manual_off(std::string name) @endlink
@li int @link ippython_manual_done(std::string * name) manual_done(std::string name) @endlink
The commands for setting up each event are described in
Trick::IPPythonEvent
An event is in Normal mode by default, meaning its condition(s) are used to determine when to fire. Issuing one of the manual commands (@c manual_fire,
@c manual_on, @c manual_off) puts an event in Manual mode, meaning its conditions are ignored and the type of manual command determines if the event fires.
Any event can be fired once immediately with the @c manual_fire command; the @e only way to fire non-"Added" events is with @c manual_fire().
An event will NOT fire when the @c manual_off() command is issued. An event returns to Normal mode by issuing the @c manual_done() command.
The commands described above can be done in the Run input file, and/or via the variable server, and/or via MTV (see @ref MalfunctionsTrickViewPage "MTV").
@image html ../../../doxygen/images/event_flowchart/event_loop.jpg
@image rtf ../../../doxygen/images/event_flowchart/event_loop.jpg
<center><b>Figure IP_2 Input Processor Event Loop</b></center>
The %Trick process_event() job will execute the Event Loop for all events that were added with the @c add_event() command. For events that were added with
@c add_event_before() or @c add_event_after(), the Event Loop is effectively executed once for the event immediately before/after the event target job.
@image html ../../../doxygen/images/event_flowchart/check_conditions.jpg
@image rtf ../../../doxygen/images/event_flowchart/check_conditions.jpg
<center><b>Figure IP_3 Input Processor Event Check Conditions Loop</b></center>
The Check Conditions Loop is called from the Event Loop to determine if the event should fire. Notice that no checking is necessary in Manual mode, the event
simply fires.
@image html ../../../doxygen/images/event_flowchart/fire_event.jpg
@image rtf ../../../doxygen/images/event_flowchart/fire_event.jpg
<center><b>Figure IP_4 Input Processor Event Fire Event Loop</b></center>
The Fire Event Loop is called from the Check Conditions Loop or directly by the @c manual_fire() command, causing all of the event's enabled actions to run.
*/

244
trick_source/sim_services/Integrator/main_page.dox_in
View File

@ -1,244 +0,0 @@
/**
@anchor IntegratorPage
@page LEVEL2 Integrator
Trick provides a state integration capability described by the inputs below.
To use these options a developer must develop application code which interfaces the application states with
the Trick integration services.
The integration job class is designed to accommodate the application state to Trick integration service interface.
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.
The code below represents a simple integration job implementation.
@code
/*********** TRICK HEADER **************
PURPOSE: (State Integration Job)
...
CLASS: (integration)
...
*/
#include "ip_state.h"
#include "sim_services/Integrator/include/integrator_c_intf.h"
int integration_test( IP_STATE* s)
{
int ipass;
/* LOAD THE POSITION AND VELOCITY STATES */
load_state(
&s->pos[0],
&s->pos[1],
&s->vel[0],
&s->vel[1],
NULL
);
/* LOAD THE POSITION AND VELOCITY STATE DERIVATIVES */
load_deriv(
&s->vel[0],
&s->vel[1],
&s->acc[0],
&s->acc[1],
NULL
);
/* CALL THE TRICK INTEGRATION SERVICE */
ipass = integrate();
/* UNLOAD THE NEW POSITION AND VELOCITY STATES */
unload_state(
&s->pos[0],
&s->pos[1],
&s->vel[0],
&s->vel[1],
NULL
);
/* RETURN */
return(ipass);
}
@endcode
The <i> integrate() </i> function, declared externally, is the function which physically integrates the states.
This function uses the input parameters defined in Table 18 and 19 to integrate any set of states and derivatives.
First, the states must be loaded,<i> load_state() </i>.
Notice in the example code that both position and velocity are loaded into the state array.
This is because the integrators are primarily 1st order differential equation integrators, which means that
velocities are integrated to positions independently from the accelerations being integrated to velocities.
Hence, the velocity is a state and the acceleration is its derivative,
just as the position is a state and velocity is its derivative.
From the 2 degree of freedom code example, there are four states: two position and two velocity.
Next, the derivative of the position (velocity) and the derivative of the velocity (acceleration) must be loaded,
<i> load_deriv() </i>. The integration job class is designed to be called once for each intermediate
pass of a multi-pass integrator. For example the Runge_Kutta_4 integrator will make 4 separate derivative
evaluations and stores the resulting state from each intermediate pass separately so that they may be
combined and weighted to create a "true" state for the specified time step. The intermediate_step parameter
defines the current intermediate step ID for the integrator. This parameter is initialized to zero by the
executive and managed by the <i> integrate() </i> function.
With the states and derivatives loaded into the appropriate integrator arrays, the <i> integrate() </i> function
must be called to integrate the states through a single intermediate step of the selected integration scheme.
The integrated states must then be unloaded, <i> unload_state() </i>.
If a developer wishes to use their own integration scheme, then the <i> integrate() </i> function source code
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.
@section LEVEL3 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> INTEGRATOR </i> data structure declaration.
The available inputs for state integration control are listed in Table 18.
<center>
Table 18 State Integration Control Inputs
<table>
<tr>
<th width=375>Name</th>
<th>Default</th>
<th>Description</th>
</tr>
<tr>
<td>getIntegrator(Integrator_type, unsigned int, double)</td>
<td>No default value</td>
<td>Tell Trick the Integrator scheme and the number of state variables.
A call to this function is required otherwise a runtime error is generated.</td>
</tr>
<tr>
<td>set_first_step_deriv(bool)</td>
<td>True</td>
<td>True=perform derivative evaluation for the first pass of the integrator;
False=use the derivative evaluation from the last pass of the previous integration cycle.</td>
</tr>
<tr>
<td>set_last_step_deriv(bool)</td>
<td>False</td>
<td>True=perform derivative evaluation for the last pass of the integrator;
False=do not perform derivative evaluation for the last pass of the integrator.</td>
</tr>
</table>
</center>
- <b> getIntegrator(Alg, State_size, Dt) </b>: The <b> Alg </b> parameter is an enumerated type which currently
has nine possible values. These values and information about the associated integrator is shown in Table 19.
The <b> State_size </b> parameter is the number of states that are to be integrated. This includes position
<i> and </i> velocity states; e.g. for a three axis translational simulation, there would be three position
states and three velocity states, hence the second parameter would equal 6 states.
The <b> Dt </b> parameter is the integration frequency; however, this parameter is ignored unless using the
<i> Integration </i> class stand-alone. The frequency is defined in the S_define when using integration within Trick.
- <b> set_first_step_deriv(first_step) </b>: The <b> first_step </b> parameter is a boolean. If <b> True </b> then
Trick will run the derivative jobs for the first integration step. If <b> False </b> then Trick will run only
the integration jobs for the first integration step.
- <b> set_last_step_deriv(last_step) </b>: The <b> last_step </b> parameter is a boolean. If <b> True </b> then
Trick will run the derivative jobs after the last integration step. If <b> False </b> then Trick will not run
the derivative jobs after the last integration step.
<center>
Table 19 State Integration Options
<table>
<tr>
<th>Option</th>
<th>Accuracy</th>
<th>DiffEQ</th>
<th># Deriv</th>
<th>Comments</th>
</tr>
<tr>
<td>Euler</td>
<td>1st Order</td>
<td>1st Order</td>
<td>1</td>
<td>yn + 1 = yn + y'n*dt</td>
</tr>
<tr>
<td>Euler_Cromer</td>
<td>2nd Order</td>
<td>2nd Order</td>
<td>2</td>
<td>yn + 1 = yn + y'n + 1*dt</td>
</tr>
<tr>
<td>ABM_Method</td>
<td></td>
<td> </td>
<td> </td>
<td>Adams-Bashforth-Moulton Predictor Corrector</td>
</tr>
<tr>
<td>Nystrom_Lear_2</td>
<td>2nd Order</td>
<td>2nd Order </td>
<td>1</td>
<td>4th order accuracy for orbital state propagation, circular motion</td>
</tr>
<tr>
<td>Runge_Kutta_2</td>
<td>2nd Order</td>
<td>2nd Order </td>
<td>2</td>
<td>Good general purpose integrator</td>
</tr>
<tr>
<td>Modified_Midpoint_4</td>
<td>4th Order</td>
<td>2nd Order </td>
<td>3</td>
<td>Good accuracy with less derivative evaluations, be careful with high frequency statesr</td>
</tr>
<tr>
<td>Runge_Kutta_4</td>
<td>4th Order</td>
<td>1st Order </td>
<td>4</td>
<td>Good general purpose integrator, although a little time consuming</td>
</tr>
<tr>
<td>Runge_Kutta_Gill_4</td>
<td>4th Order</td>
<td>1st Order </td>
<td>4</td>
<td>Good general purpose integrator, although a little time consuming</td>
</tr>
<tr>
<td>Runge_Kutta_Fehlberg_45</td>
<td>5th Order</td>
<td>1st Order </td>
<td>6</td>
<td>Designed for larger time steps and smooth states, orbital state propagator</td>
</tr>
<tr>
<td>Runge_Kutta_Fehlberg_78</td>
<td>8th Order</td>
<td>1st Order </td>
<td>12</td>
<td>Designed for larger time steps and smooth states, orbital state propagator</td>
</tr>
<tr>
<td>User_Defined</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
<td>Used to bypass trick integration utilities</td>
</tr>
</table>
</center>
The <b> Option </b> column are the integration algorithm options.
The <b> Accuracy </b> column gives the order of accuracy for the integrator.
The <b> DiffEQ </b> column gives the order of teh differential equation set the integrator formulation assumes.
For example, a 1st order DiffEQ integrator integrates accelerations to velocities independently of the velocity
to position integration. However, a 2nd order DiffEQ integrator integrates the velocity to position states
dependent on the acceleration to velocity state integration. The # <b> Deriv </b> column specifies the number
of derivative evaluations performed to integrate across a full time step (also known as the number of
integration passes). The <b> Comments </b> column gives some special notes for the usage of each integrator.
@section LEVEL3 Related Pages
Requirements\n
Design
*/

106
trick_source/sim_services/JITInputFile/docs/main_page.dox_in
View File

@ -1,106 +0,0 @@
/**
@page LEVEL2 Just-In-Time (JIT) Input File
This capability executes C++ code as an input file. It is implemented by the
Trick::JITInputFile class.
This class provides a method for injecting code that is not possible to
do through the python input processor or for code that is required to execute
at maximum speed.
@section LEVEL3 Basic Usage
@note When using this capability the simulation is not recompiled.
Here is an example C++ input file to use with the Trick example ball simulation.
@code
// Include S_source.hh to get the sim object definitions and instantiations.
#include "../S_source.hh"
// By default the input processor looks for the run_me function with the following call signature
extern "C" int run_me() {
// All of the top level sim objects are available by including S_source.hh
ball.obj.state.input.position[0] = 6.0 ;
ball.obj.state.input.position[1] = 4.0 ;
// trick.stop(<time>) in python maps to exec_set_terminate_time in C++
exec_set_terminate_time(200.0) ;
}
@endcode
There are two ways to use C++ input files. The first is to use the C++ input file
in place of the normal pyton input file on the command line. When the input file
is specified on the command line, the input file is compiled and linked into a
shared library during simulation initialization (input_processor phase 50000 job).
The shared library is opened via dlopen and the 'extern "C" int run_me()' is run.
@verbatim
> S_main_Linux_4.4_x86_64.exe RUN_test/input.cpp
@endverbatim
The second method to call C++ input files is to compile and run them within python
input files.
@code
# compile and run a C++ input file. This call will search for the function "run_me"
trick.jit_compile_and_run("RUN_cpp_input/input.cpp")
# Separately compile and run a C++ input file.
trick.jit_compile("RUN_cpp_input/input.cpp")
trick.jit_run("RUN_cpp_input/input.cpp", "run_event_1")
# compile and run the function run_event_1 from the C++ input file.
trick.jit_compile_and_run("RUN_cpp_input/input.cpp", "run_event_1")
@endcode
@section LEVEL3 Events
Events may be specified through the C++ input file. Events may be cyclic or tied to a job.
Cyclic events may be one-time events. All events must be a function call that has the following
call signature "int <event_function>()".
The following examples show the ways to add the different types of events from a C++ input file.
@code
//This event only prints a message
int run_event_1() {
message_publish(1, "event 1 fired!\n") ;
return 0 ;
}
int remove_events() {
jit_remove_event("event_1") ;
return 0 ;
}
// In this example, we can create independent events that call the same function. They
// are differentiated by the event name.
extern "C" int run_me() {
// add read events
jit_add_read_event( 90.0 , run_event_1 ) ;
jit_add_read_event( 80.0 , run_event_1 ) ;
// add cyclic event
jit_add_cyclic_event( "event_1" , 100.0 , run_event_1 ) ;
// add another cyclic event
Trick::JITCyclicEvent * jce = new Trick::JITCyclicEvent("event_2", exec_get_time_tics(),
(long long)(50.0*exec_get_time_tic_value()), run_event_1 ) ;
jit_add_cyclic_event( jce ) ;
// events tied to jobs
jit_add_event_before( "event_before", run_event_1 , "ball.obj.state_print" ) ;
jit_add_event_after( "event_after", run_event_1 , "ball.obj.state_print" ) ;
// another way to tie event to job.
Trick::JITInstrumentEvent * jie = new Trick::JITInstrumentEvent( "event_before2" , run_event_1 ) ;
jit_add_event_before( jie , "ball.obj.state_print" ) ;
// add a read event that removes event 1
jit_add_read_event( 150.0 , remove_events ) ;
}
@endcode
*/

125
trick_source/sim_services/MasterSlave/docs/main_page.dox_in
View File

@ -1,125 +0,0 @@
/**
@page LEVEL2 Trick Master/Slave Synchronization
Master/Slave is a way to do distributed processing in Trick using multiple simulations.
Master/Slave synchronization synchronizes a master simulation to one or more slave
simulations. The slaves may be run on a different computer or computers, independent of
the computer running the master simulation.
While synchronized, the master controls the overall simulation time for all simulations. Slaves
will use the same real-time software frame as the master and will sync with the master's time at the end of each frame.
The master also controls the overall simulation execution mode for all simulations. However, a slave that goes into freeze
mode will cause the master to go into freeze mode (which will propagate freeze mode to all slaves). Also,
a slave that loses sync or terminates unexpectedly can affect the master's mode (see sync_error_terminate below).
Trick provides a connection class for synchronization that uses sockets (MSSocket derived from MSConnect) for master/slave
connection and communication. The user may also provide their own way of synchronization if desired, in which
case you must provide your own class derived from MSConnect.
@see Trick::MSSocket\n Trick::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.
@section LEVEL3 User accessible routines
The following routine is used to create a socket connection for either Master or Slave:
@li Trick::MSSocket::MSSocket() ;
In order for Master/Slave synchronization to take place, it must be enabled:
@li int Trick::Master::enable() ;
@li int Trick::Master::disable() ;
The following are routines and attributes for configuring the Master's interface to each Slave:
@li Trick::SlaveInfo::SlaveInfo() ;
@li int Trick::SlaveInfo::set_connection_type(Trick::MSConnect * in_connection) ;
@li Trick::SlaveInfo * Trick::Master::add_slave(Trick::SlaveInfo * new_slave) ;
@li Trick::SlaveInfo::machine_name
@li Trick::SlaveInfo::machine_display
@li Trick::SlaveInfo::other_args
@li Trick::SlaveInfo::remote_shell
@li Trick::SlaveInfo::remote_shell_args
@li Trick::SlaveInfo::run_input_file
@li Trick::SlaveInfo::S_main_name
@li Trick::SlaveInfo::sim_path
@li Trick::SlaveInfo::sync_error_terminate
@li Trick::SlaveInfo::sync_wait_limit
@li Trick::SlaveInfo::user_remote_shell
The following are routines and attributes for configuring a Slave's interface to the Master:
@li int Trick::Slave::set_connection_type(Trick::MSConnect * in_connection) ;
@li Trick::Slave::sync_error_terminate
@section LEVEL3 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.
@section LEVEL4 Master Input File Example
@verbatim
new_connection = trick.MSSocket()
new_slave = trick.SlaveInfo()
new_slave.set_connection_type(new_connection)
new_slave.sim_path = "/users/bob/trick_sims/SIM_myslave"
new_slave.run_input_file = "RUN_test/slave.py"
new_slave.sync_error_terminate = 1
new_slave.sync_wait_limit = 0.2
master_slave.master.add_slave(new_slave)
master_slave.master.enable()
@endverbatim
@section LEVEL4 Slave Input File Example
@verbatim
new_connection = trick.MSSocket()
master_slave.slave.set_connection_type(new_connection)
master_slave.slave.sync_error_terminate = 1
@endverbatim
@section LEVEL4 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
its own RUN_ directory).
The following are attributes for configuring the Master's checkpointing interface to each Slave:
@li Trick::SlaveInfo::chkpnt_dump_auto
@li Trick::SlaveInfo::chkpnt_load_auto
@li Trick::SlaveInfo::chkpnt_binary
@li Trick::SlaveInfo::reconnect_wait_limit
If you do not want the Slave to dump/load a checkpoint when the Master does, you can turn off either feature in the
Master input file like so:
@verbatim
new_slave.chkpnt_dump_auto = 0
new_slave.chkpnt_load_auto = 0
@endverbatim
in which case your Slave would have to have its own model code to perform a checkpoint dump/load.
If the Slave simulation was built with DMTCP enabled (for more information see TBD DMTCP Section), you can set the following variable
in the Master input file, causing the Slave to dump/load a binary DMTCP checkpoint when the Master commands:
@verbatim
new_slave.chkpnt_binary = 1
@endverbatim
Note that when loading a binary DMTCP checkpoint, the checkpoint is a new executable file that must be run. When the
Master commands a checkpoint (and chkpnt_load_auto=1), the Slave will send the Master its checkpoint file name path
and then terminate itself. The Master will then automatically restart the Slave by executing that checkpoint file.
If chkpnt_load_auto=0, the user is responsible for terminating and restarting the Slave.
To run the Slave with DMTCP enabled, you'll have to modify some of the Slave's attributes in the Master input file.
@li S_main_name normally defaults to your Slave's executable, which Trick fills in for you. But you will set it to instead run the dmtcp_checkpoint command.
@li run_input_file should not change from what your Slave would normally run, but it needs the keyword "dmtcp" specified after it.
@li sync_error_terminate needs to be 0 because the Slave must be terminated before the Master restarts it, and we don't want Master to also terminate.
@li reconnect_wait_limit is the time the Master will then wait for the Slave to be restarted and get reconnected with the Master. If the Slave does not
reconnect within this time, the Master will deactivate the Slave for the rest of the simulation.
Here's an example:
@verbatim
new_slave.S_main_name = "/users/bob/dmtcp-1.2.7/bin/dmtcp_checkpoint --quiet --new-coordinator --checkpoint-open-files --ckptdir ./dmtcp_checkpoints ./S_main_Linux_4.4_x86_64.exe"
new_slave.run_input_file = "RUN_test/slave.py dmtcp"
new_slave.sync_error_terminate = 0
new_slave.reconnect_wait_limit = 10.0
@endverbatim
When chkpnt_load_auto=1, the Slave restarting and reconnecting should occur within a second or two. If chkpnt_load_auto=0, the user has
to restart the slave himself (and may even be typing in the checkpoint executable on the command line), so reconnect_wait_limit should be
set accordingly.
*/

1417
trick_source/sim_services/MemoryManager/docs/MM.doxygen
View File

File diff suppressed because it is too large Load Diff

37
trick_source/sim_services/MemoryManager/docs/main_page.dox_in
View File

@ -1,37 +0,0 @@
/**
@page LEVEL2 Trick Memory Manager
The Trick MemoryManager is a C++ Class that provides memory tracking,
allocation, checkpointing and various other memory-resource administration
services. It is a "keeper of knowledge" about variables (chunks of memory).
It manages variables that a user has asked it to allocate as well as
user-allocated variables that the user tells it about.
Variables whose memory is allocated by the memory manager are called
\b TRICK_LOCAL variables. Those allocated by the user are \b TRICK_EXTERN
variables. Variables can also optionally be named.
TRICK_LOCAL variables are declared using \b Trick::MemoryManager::declare_var.
This function allocates memory according to a user-provided declaration.
Information about the allocation, and it's declared type are retained.
TRICK_EXTERN variables are declared using: \b Trick::MemoryManager::declare_extern_var
This function stores information about a chunk of memory that the user
has allocated and has declared to be of a given type.
By tracking allocation and type information, the Memory Manager can, on
request, write human-readable representations of memory resources to a
file. To write the value(s) of a single variable to a file, use \b Trick::MemoryManager::write_var.
To write a checkpoint, consisting of declarations and values of all variables
known to the memory manager, use \b Trick::MemoryManager::write_checkpoint.
These memory resources can later be restored from this checkpoint file using
\b Trick::MemoryManager::read_checkpoint or \b Trick::MemoryManager::init_from_checkpoint.
See Also:
- Trick::MemoryManager
- @subpage defsMemoryManager "Memory Manager Definitions"
- @subpage ADEF_Syntax "Allocation Declaration Syntax"
- @subpage examples_declare_var
- @subpage convert_07_to_10
- @subpage placement_new_init
*/

60
trick_source/sim_services/Message/docs/main_page.dox_in
View File

@ -1,60 +0,0 @@
/**
@anchor StatusMessageSystem
@page LEVEL2 Trick Message Publisher/Subscriber
The Message Publisher publishes executive and/or model messages. A Message Subscriber gets the messages published by the Publisher.
@section LEVEL3 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
::message_subscribe routine (and conversely can be removed from the publisher by calling ::message_unsubscribe).
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.
@section LEVEL3 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
- Trick::MessageFile - outputs messages to a file named "send_hs" in the RUN directory
- Trick::MessageTCDevice - outputs messages to a socket at port 7200, used by the Simulation Control Panel for its Status Messages display
So by default, when you publish a message, it will be output by the three subscribers above.
A subscriber can be enabled / disabled at any time during simulation execution to output / ignore messages as desired.
The user may also add their own subscriber by creating a derived class from Trick::MessageSubscriber.
@section LEVEL3 User accessible routines
To publish a message:
@li int ::message_publish(int level, const char * format_msg, ...) ;
@li int ::send_hs(FILE * fp, const char * format_msg, ...) ;
The level number can be any integer from 0 to 99. Trick has a few predefined levels (Trick::MessagePublisher::MESSAGE_TYPE) that it uses for publishing messages.
If the message subscriber's color is enabled (see below), then a particular colored message will be displayed for each of these levels:
- @e 0 - normal message, default color
- @e 1 - informational message, green
- @e 2 - warning message, yellow
- @e 3 - error message, red
- @e 10 - debug message, cyan
To subscribe / unsubscribe Trick's default subscribers (these call ::message_subscribe / ::message_unsubscribe mentioned above):\n
By default these are all subscribed. You can use subscribe/unsubscribe throughout a simulation to turn on/off messages at will.
@li int message_cout_subscribe() ;
@li int message_cout_unsubscribe() ;
@li int message_file_subscribe() ;
@li int message_file_unsubscribe() ;
@li int message_device_subscribe() ;
@li int message_device_unsubscribe() ;
To enable / disable Trick's default subscribers:\n
By default these are all enabled. If you disable file at startup, the send_hs file will not be created/opened. If you disable device at startup, its connection will not be established.
That means you cannot then later try to enable and subscribe to file/device.
@li int message_cout_set_enabled(int yes_no) ;
@li int message_file_set_enabled(int yes_no) ;
@li int message_device_set_enabled(int yes_no) ;
To enable / disable showing colored messages in Trick's default subscribers:\n
By default color is enabled for cout and device. Color is achieved by adding ANSI escape codes around the message.
@li int message_cout_set_color(int yes_no) ;
@li int message_file_set_color(int yes_no) ;
@li int message_device_set_color(int yes_no) ;
*/

437
trick_source/sim_services/MonteCarlo/docs/main_page.dox_in
View File

@ -1,437 +0,0 @@
/**
*
* @anchor MonteCarloPage
* @page LEVEL2 Monte Carlo Simulation
*
* Trick offers a convenient method for repeatedly running a simulation with varying inputs. We call this capability
* "Monte Carlo". Monte Carlo is a well-known technique where mathematical problems are solved using random numbers
* and probability statistics. By "Monte Carlo", we mean running the simulation repeatedly over a varying input space.
* How the inputs vary is up to you, the developer. How the input space is varied may not fall into the strict definition
* of Monte Carlo, i.e. using bell curves, linear distributions, etc.
*
* Use this section as a reference. Refer to the tutorial for a full blown example.
*
* @section LEVEL3 Monte Carlo Tutorial
* The tutorial has an example of how to use Trick-based Monte Carlo. The example shows how to use Monte Carlo to optimize
* the ground distance of a jet-propelled ball. The ball has a jet which yields upward force. The jet may only fire four
* times. The firing times are set in the input file. The Monte Carlo technique is used to run the simulation repeatedly
* with varying jet-firing sequences. The tutorial shows how to use predetermined (hard-coded) sequences, as well as how
* to use random sequences. The tutorial also shows how to use data products to analyze the multitudinous curves that a
* Monte Carlo simulation produces.
*
* @section LEVEL3 Structure
* The curious will want to know the internal design of Monte Carlo. In the case of optimization, or when feeding new inputs
* to the simulation based on past results, the design becomes prerequisite. That said, here are a few brief points about
* the design:
*
* - Monte Carlo is designed to be distributed. You must have ssh or rsh setup to run Monte Carlo. Runs may occur in parallel
* across a network. In fact, all Monte Carlo runs are distributed, even when running with one machine.
* - There is no wrapper or script around S_main*.exe. Monte Carlo is a child class of the Executive class.
* - GNU's standard library is used to generate "random" data.
* - The simulation input file is only processed once (by each distributed "slave").
* - fork() is used to keep simulation runs in their own address space.
* - Optimization is possible through special developer-written jobs that wrap the simulation run. These special jobs make
* it possible to change run inputs based on past simulation results.
* - To run Monte Carlo, you run the S_main*.exe as usual. All configuration is done with input files.
* - All data is saved for each and every run. Data is saved in a MONTE_* directory. The MONTE_* directory will hold a
* RUN_* directory for each simulation run.
* - stderr, stdout, and send_hs from distributed "slaves" are saved to files.
* - Post-processing is in place to view 1000+ curves simultaneously.
* - A master which oversees the creation and management of slaves and the dispatching of runs.
* - One or more slaves that process the runs and return results to the master.
*
* @subsection LEVEL4 The Master
* The master is the command center of a Monte Carlo simulation. It does not process runs directly. Rather, it delegates them
* to one or more slaves which perform the actual execution. The master is responsible for spawning and managing the state of
* these slaves, dispatching and tracking the progress of each run, and handling the retrying of failed and timed out runs.
* Its life cycle consists of the following:
*
* - Initialize
* - While there are unresolved runs:
* - Spawn any uninitialized slaves.
* - Dispatch runs to ready slaves.
* - Receive results from finished slaves.
* - Check for timeouts.
* - Shutdown the slaves and terminate.
*
* @see Trick::MonteCarlo
*
* @anchor MonteCarloSlaves
* @subsection LEVEL4 Slaves
*
* Slaves are the workhorses of a Monte Carlo simulation. They are responsible for the actual execution of runs and the
* reporting of results back to the master. Slaves are robust enough to handle runs that fail abnormally and will continue
* executing until explicitly killed or disconnected. A slave's life cycle consists of the following:
*
* - Initialize
* - Connect to and inform the master of the port over which the slave is listening for dispatches.
* - Until the connection to the master is lost or the master commands a shutdown:
* - Wait for a new dispatch.
* - Process the dispatch.
* - Write the exit status to the master.
* - Run the shutdown jobs and terminate.
*
* @see Trick::MonteSlave
*
* @section LEVEL3 Setting Up a Monte Carlo Simulation
*
* It is important to note that the only initialization jobs the master runs are those with phase zero. As such, if one
* wishes to use the functions in the following discussion in user model code, a few will have effect only in phase zero
* initialization jobs. These jobs are explicitly noted below.
*
* @subsection LEVEL4 Monte Carlo Remote Shell
*
* To start Monte Carlo slaves you must have either rsh or ssh installed. It is best to setup the remote shell so that it
* doesn't prompt for a password every time you run it. See tutorial for a tiny ssh test.
*
* @subsection LEVEL4 Activating Monte Carlo
*
* A Monte Carlo simulation is enabled via one of:
*
* <b>C++:</b> Trick::MonteCarlo::set_enabled <br>
* <b>C:</b> ::mc_set_enabled
*
* @anchor MonteCarloRuns
* @subsection LEVEL4 Specifying the Number of Runs
*
* This tells Monte Carlo how many simulation runs to execute. For a series of random runs, Monte Carlo will execute the
* simulation the number of runs specified. When MonteVarFile is specified as the input variable's type, Trick will execute
* the number of runs specified, not exceeding the number of values contained in the input variable's data file. For multiple
* MonteVarFile variables, Trick will execute the least number of runs specified, not exceeding the least number of values
* contained in the input variable's data file.
*
* The number of runs to be dispatched is specified via one of:
*
* <b>C++:</b> Trick::MonteCarlo::set_num_runs<br>
* <b>C:</b> ::mc_set_num_runs
*
* @anchor MonteCarloRanges
* @subsection LEVEL4 Ranges
*
* This optional section tells Monte Carlo which runs to execute.
*
* A subset of runs to be dispatched can be achieved via one of:
*
* <b>C++:</b> Trick::MonteCarlo::add_range<br>
* <b>C:</b> ::mc_add_range
*
* All ranges will be combined, and runs falling in any of the specified ranges will be dispatched. If no ranges are
* specified, all runs will be dispatched. For example, the following lines in the input file result in runs 100 through
* 200, 250, and 300 through 500 being dispatched:
*
* @code
* trick.mc_add_range(100, 200)
* trick.mc_add_range(250)
* trick.mc_add_range(300, 500)
* @endcode
*
* @anchor MonteCarloVariables
* @subsection LEVEL4 Monte Carlo Input Variables
*
* The following classes (which are derived from the Trick::MonteVar abstract base class) are used to specify
* which input variables are available for changing from run to run. The type of class tells Trick how to
* generate the value for the variable from run to run.
*
* - Trick::MonteVarCalculated
* - The user feeds Monte Carlo with calculated values. The values are calculated in user-created Monte Carlo
* jobs. The primary purpose of the MonteVarCalculated type formula is for optimization (see the Optimization section) <br>
* Parameter Descriptions:
* - name - the fully qualified name of the simulation variable
* - unit - the variable's units.
* - Trick::MonteVarFile
* - Pull values from an input file. Use MonteVarFile when you want to hard-code various values. <br>
* Note: Below represents an example of an input file. The data should be in tabular format with each column
* containing the data for a variable and each row is for a different run.
* @code
* #this is a comment
* 0 1.00000 1.50000
* 1 1.50000 2.00000
* 2 2.00000 2.50000
* 3 2.50000 3.00000
* @endcode
* Column 1 contains the run number (optional, the values can begin in column 1).<br>
* Column 2 contains the values for 4 runs.<br>
* Column 3 contains the values for 4 runs.<br>
*
* Parameter Descriptions:
* - name - the fully qualified name of the simulation variable
* - file_name - the name of the file containing the values to use
* - column - the column in the data file containing the values for this variable
* - unit - the variable's units.
* - Trick::MonteVarFixed
* - Use this class type to specify a constant value. <br>
* Parameter Descriptions:
* - name - the fully qualified name of the simulation variable
* - value - the constant value to use for the variable
* - unit - the variable's units.
* - Trick::MonteVarRandom
* - Use this class type to auto-generate the input values using a distribution formula. <br>
* Parameter Descriptions:
* - name - the fully qualified name of the simulation variable
* - unit - the variable's units
* - distribution - the random distribution method (GAUSSIAN, FLAT, or POISSON)
* - <b> GAUSSIAN </b>: This specifies the following probability density function to be used for the variable: <br>
* <i>P(x)= 0.0, if x < min <br>
* Or: 0.0, if x > max <br>
* Or: 0.0, if x < rel_min +\f$\mu\f$ <br>
* Or: 0.0, if x > rel_max +\f$\mu\f$ <br>
* Otherwise: \f${\displaystyle\frac{1}{\sigma\sqrt{2 \pi}} \; exp\biggr(-\frac{(x-\mu)^2}{2\mu^2}\biggr)}\f$ </i> <br>
* Gaussian Parameter Descriptions:
* - Seed - the randomization seed. (use Trick::MonteVarRandom::set_seed))
* - Sigma - the standard deviation. The larger the value, the broader the bell curve. (use Trick::MonteVarRandom::set_sigma))
* - Mu - specifies the center of the bell curve. (use Trick::MonteVarRandom::set_mu)
* - Min, Max - absolute cutoff limits. Any values ouside of these bounds are discarded. (use Trick::MonteVarRandom::set_min, Trick::MonteVarRandom::set_max)
* - Rel_min, Rel_max - cutoff limits relative to mu \f$(\mu)\f$. Any values ouside of these bounds are discarded.
* (use Trick::MonteVarRandom::set_min_is_relative, Trick::MonteVarRandom::set_max_is_relative)
* - <b> POISSON </b>: This specifies the following probability density function to be used for the variable:\n
* <i> P(n)= \f${\displaystyle\frac{\mu^ne^{-\mu}}{n!}}\f$ </i> <br>
* Poisson Parameter Descriptions:
* - Seed - the randomization seed. (use Trick::MonteVarRandom::set_seed)
* - Mu\f$(\mu)\f$ - non-negative, real-valued number that specifies the mean of the distribution. (use Trick::MonteVarRandom::set_mu)
* - Min, Max - absolute, non-negative, cutoff limits. Any values outside of these bounds are discarded.
* (use Trick::MonteVarRandom::set_min, Trick::MonteVarRandom::set_max)
* - Rel_min, Rel_max - cutoff limits relative to mu \f$(\mu)\f$. Any values outside of these bounds are discarded.
* (use Trick::MonteVarRandom::set_min_is_relative, Trick::MonteVarRandom::set_max_is_relative)
* - <b> FLAT</b>: Uniform distribution. No bell. Returns uniform random values between (-\f$\infty\f$, +\f$\infty\f$) bracketed
* optionally by [min, max]. (use Trick::MonteVarRandom::set_min, Trick::MonteVarRandom::set_max)
* - engine - the C++11 predefined pseudo-random engine type. NO_ENGINE is the default (results in Trick coded random number engine).
* Other options using the C++11 <random> facilities of the Standard Template Library:
* (Requires --std=c++0x or --std=c++11 on Trick configure command line when building Trick.)
* - TRICK_DEFAULT_ENGINE - <b>SUGGESTED FOR USE</b>. std::ranlux_base_01 for c++0x, std::mt19937 for c++11
* - C++ TR1 options: (pre-C++11 compiler, GCC versions 4.4 through 4.6).
* (Requires --std=c++0x on Trick configure command line when building Trick.)
* - RANLUX_BASE_01_ENGINE - std::ranlux_base_01 Engine
* - RANLUX_64_BASE_01_ENGINE - std::ranlux64_base_01 Engine
* - (others such as std::mt19937 not provided, because they return
* outside the canonical 0 <= x < 1 range in some GCC versions,
* which can cause infinite loops in distributions.)
* - C++11 options: (C++11 compiler, versions 4.7, 4.8).
* (Requires --std=c++11 on Trick configure command line when building Trick.)
* - MINSTD_RAND_ENGINE - std::minstd_rand Minimal Standard Linear Congruential Engine
* - MT19937_ENGINE - std::mt19937 Mersenne Twister Engine. Said to provide better behavior than Linear Congruential Engines.
* - MT19937_64_ENGINE - std::mt19937_64 64 bit Mersenne Twister Engine.
* - RANLUX_24_BASE_ENGINE - std::ranlux24_base Engine
* - RANLUX_44_BASE_ENGINE - std::ranlux48_base Engine
* - RANLUX_24_ENGINE - std::ranlux24 Engine
* - RANLUX_44_ENGINE - std::ranlux48 Engine
* - KNUTH_B_ENGINE - std::knuth_b Engine
*
* After constructing such a variable, it can be added via:
*
* <b>C++:</b> Trick::MonteCarlo::add_variable
*
* C wrapper functions are not available for creating and adding variables. As such, C simulations can add variables
* <i>only</i> through the input file. To create a variable in the input file, prepend the constructor with
* \"<code>trick.</code>\". For example:
*
* @code
* variable0 = trick.MonteVarCalculated("ball.obj.state.input.mass")
* variable1 = trick.MonteVarFile("ball.obj.state.input.position[0]", "RUN_monte/values.txt", 2)
* variable2 = trick.MonteVarFixed("ball.obj.state.input.position[1]", 5)
* variable3 = trick.MonteVarRandom("ball.obj.state.input.velocity[0]", trick.MonteVarRandom.GAUSSIAN, "", trick.MonteVarRandom.NO_ENGINE)
* variable3.set_seed(1)
* variable3.set_sigma(0.6667)
* variable3.set_mu(4.0)
* variable3.set_min(-4.0)
* variable3.set_max(4.0)
* variable3.set_sigma_range(0) # integer argument, default is 1. 0 turns limit feature off.
* variable3.set_min_is_relative(True) # default true. When True, set_min value is relative to mean mu
* variable3.set_max_is_relative(True) # default true. When True, set_max value is relative to mean mu
* @endcode
*
* Calling a C++ function in the input file is not as simple as prepending it with \"<code>trick.</code>\". To add a variable
* in the input file, use the following syntax:
*
* @code
* trick_mc.mc.add_variable(variable0)
* trick_mc.mc.add_variable(variable1)
* trick_mc.mc.add_variable(variable2)
* variable3.set_seed(0)
* trick_mc.mc.add_variable(variable3)
* @endcode
*
* Note that it is necessary to assign the result of the constructor to a local variable in the input file. While it may
* be tempting to combine the calls into one line such as:
*
* @code trick_mc.mc.add_variable(trick.MonteVarFixed("ball.obj.state.input.position[1]", 5) @endcode
*
* this will generally result in a run-time error since the Python input processor will free the memory allocated for the
* variable after leaving the scope of the constructor if it is not locally assigned.
*
* Variables can also be added from jobs of type <code>"monte_master_pre"</code> or <code>"monte_master_post"</code> while
* the Monte Carlo is running. Note that new variables will effect only runs that have yet to be dispatched.
*
* @subsection LEVEL3 Distributed Monte Carlo
*
* To run Monte Carlo distributed across a network, you simply need to add_slave to the input file for each slave.
*
* <b>C++:</b> Trick::MonteCarlo::add_slave<br>
* <b>C++:</b> Trick::MonteCarlo::add_slave <br>
* <b>C:</b> ::mc_add_slave
*
* @code
* slave0 = trick.MonteSlave("WonderWoman")
* trick_mc.mc.add_slave(slave0)
* slave1 = trick.MonteSlave("CatWoman")
* trick_mc.mc.add_slave(slave1)
* slave2 = trick.MonteSlave("LoisLane")
* trick_mc.mc.add_slave(slave2)
* @endcode
*
* It is really that easy. But the following bullets need to be remembered:
* - ssh is used to launch simulations across the network.
* - Each slave machine will work in parallel with other machines.
* - Each slave will do as much work as it can. The faster the machine, the more work it will do.
* - If a slave dies, the "master" is smart enough to redistribute the missing work.
* - Communication between master and slave(s) will be done with socket communication (handshaking_disabled)
* - There is no way to be "nice" to other users on a machine. The Monte Carlo is going to hog the CPU.
* - Monte Carlo runs distributed even when there are NO slaves. If no slaves are added, Trick will add a single slave on "localhost".
* Slaves can also be added from jobs of type <code>"monte_master_pre"</code> or <code>"monte_master_post"</code>
* while the Monte Carlo is running.
*
* @section LEVEL3 Output
* Data logged for each run is stored in a <code>RUN_<run number></code> directory within a
* <code>MONTE_<run directory></code> directory on the machine that processed the run. Existing directories and files will be
* overwritten. These directories are not cleaned out by subsequent Monte Carlos. So, for instance, if the user runs a Monte
* Carlo with 1000 runs, and then reruns the same Monte Carlo with 500 runs, the first 500 <code>RUN_*</code> directories
* will contain data from the second Monte Carlo, while the last 500 will still exist and contain data from the first Monte
* Carlo. The following files are Monte Carlo specific:
*
* - <b>MONTE_<run directory>/monte_header</b><br>
* This file contains the input file lines that configured the initial state of the Monte Carlo, such as information on the
* number of runs and variables. This file is also created during a dry_run.
*
* - <b>MONTE_<run directory>/monte_runs</b><br>
* This file lists the values used for each variable for each run. This file is also created during a dry_run.
*
* - <b>MONTE_<run directory>/run_summary</b><br>
* This file contains the summary statistical information that is printed out to the screen after a Monte Carlo completes.
*
* - <b>MONTE_<run directory>/RUN_\<run number\>/monte_input</b><br>
* This file contains the input file commands necessary to rerun a single run as a stand alone simulation.
*
* @anchor MonteCarloDryRun
* @section LEVEL3 Dry Run
* A dry run generates only the monte_header and monte_runs files without actually processing any runs. It is useful for
* verifying input values before running a full Monte Carlo. A dry run is specified via one of:
*
* <b>C++:</b> Trick::MonteCarlo::set_dry_run<br>
* <b>C:</b> ::mc_set_dry_run
*
* @anchor MonteCarloVerbose
* @section LEVEL3 Making Monte Carlo Less Verbose
*
* By default, Monte Carlo is fairly verbose. If you need to suppress the messages from a Monte Carlo run:
*
* <b>C++:</b> Trick::MonteCarlo::set_verbosity <br>
* <b>C:</b> ::mc_set_verbosity
*
* Possible values for the verbosity argument are:
* - NONE (0) - report no messages
* - ERROR (1) - report error messages
* - INFORMATIONAL (2) - report error and informational messages
* - ALL (3) - report all messages
*
* @section LEVEL3 Optimization
* Monte Carlo has no decision making capability. It runs a predetermined set of inputs or a random set. In order to optimize,
* it is usually necessary to base current inputs from past results. Intelligence must be involved for the decision making.
* Currently, Trick has no built-in "intelligence" for optimization. It offers a framework for you, the brains, to
* optimize the simulation. The framework allows on-the-fly input modification based on past simulation results.
*
* The framework is a set of monte jobs which run at critical times for analyzing results and building new inputs. The
* jobs are written by the developer. The job's class determines what role the job plays (i.e. where it is run) in the
* optimization process. The Monte Carlo classed job is specified in the S_define like any other job.
*
* In order to get a handle on how to plug in to the optimization framework, it helps to have a better understanding of the
* roles the master and slave play in the master/slave design.
*
* The below table contains a description of the Monte Carlo specific Trick jobs:
*
* <center>
* <table>
* <tr><th>Trick Job </th> <th>Description </th>
* <tr><td><b>monte_master_init</b><br>
* <td>This class job runs within the master. It is run before tasking any slaves to run. This class job only runs once.</td></tr>
* <tr><td><b>monte_master_pre</b><br></td>
* <td>This class job runs within the master. These jobs run right before dispatching a simulation run to a slave. Within
* this job, you may modify inputs before the slave receives them. This is one area where you may place intelligence.
* This class job runs cyclically before each and every run.</td></tr>
* <tr><td><b>monte_master_post</b><br></td>
* <td>This class job runs within the master. These jobs run right after a slave reports back that it has completed running
* the simulation. This type job is the place to receive results from the slave simulation. Results from slave to master
* are sent via a Trick communication device (socket). The connection to the slave is already in place, you only need to
* tc_read() the results. These results are used by the master_post and master_pre jobs for intelligently deciding the
* next set of inputs for the slave. This class job runs cyclically after each and every slave run.</td></tr>
* <tr><td><b>monte_master_shutdown</b><br></td>
* <td>This class job runs within the master. Once all slaves have cranked through all inputs desired by the master, the master's
* shutdown class jobs are run. These are run only once at the very end.</td></tr>
* <tr><td><b>monte_slave_init</b><br></td>
* <td>This class job runs within the slave. These jobs are run before the slave fork()s off the simulation with the inputs
* passed in by the master and before the RUN directories are created. These jobs run once.</td></tr>
* <tr><td><b>monte_slave_pre</b><br></td>
* <td>This class job runs within the slave's child. These jobs run after the slave fork()s off the simulation with the inputs
* passed in by the master. These jobs run every time the slave runs the simulation.</td></tr>
* <tr><td><b>monte_slave_post</b><br></td>
* <td>This class job runs within the slave's child. It is responsible for passing simulation results back to the master. Trick will
* automatically create a connection from the slave to the master. You only need to tc_write() the results. These jobs run
* every time the child runs the simulation (during shutdown).</td></tr>
* <tr><td><b>monte_slave_shutdown</b><br></td>
* <td>This class jobs runs within the slave. After the master cuts off communication with the slave, the slave realizes it is
* no longer needed for any service. It then runs its shutdown class jobs. Then terminates itself.</td></tr>
* </table>
* </center>
*
* @section LEVEL4 The Post-Run Connection
*
* Post-run communication can be done via the Trick comm package in the post-run jobs. The underlying sockets are already
* connected at the time the post-run jobs are executed, so the user can simply use the C wrapper functions
* ::mc_read and ::mc_write to pass additional data between the master and slave.
*
* @section LEVEL4 Where To Put Optimization Code
*
* Since the master is in charge of dispatching, the optimization code will reside in the master. It is debatable whether
* to put the actual decision making in the monte_master_pre or monte_master_post jobs. In the tutorial, the
* optimization code was put in a monte_master_prerun class job. This may seem less intuitive, since the monte_master_postrun
* is the one receiving the results. It turned out that the decision making for that particular algorithm was easier before
* the run rather than after. This is not a hard and fast rule. Wherever it makes sense for the problem at hand is where the
* decision making should go.
*
* @section LEVEL3 User Accessible Routines
*
* - ::mc_set_enabled
* - ::mc_get_enabled
* - ::mc_set_dry_run
* - ::mc_get_dry_run
* - ::mc_set_localhost_as_remote
* - ::mc_get_localhost_as_remote
* - ::mc_set_custom_slave_dispatch
* - ::mc_get_custom_slave_dispatch
* - ::mc_set_timeout
* - ::mc_get_timeout
* - ::mc_set_max_tries
* - ::mc_get_max_tries
* - ::mc_set_user_cmd_string
* - ::mc_get_user_cmd_string
* - ::mc_set_custom_pre_text
* - ::mc_get_custom_pre_text
* - ::mc_set_custom_post_text
* - ::mc_get_custom_post_text
* - ::mc_set_verbosity
* - ::mc_get_verbosity
* - ::mc_set_num_runs
* - ::mc_get_num_runs
* - ::mc_set_run_directory
* - ::mc_get_run_directory
* - ::mc_get_slave_id
* - ::mc_add_range
* - ::mc_add_slave
* - ::mc_start_slave
* - ::mc_stop_slave
* - ::mc_set_output_directory
* - ::mc_disable_slave_GUIs
* - ::mc_write
* - ::mc_read
* - ::mc_get_connection_device
* - ::mc_set_current_run
* - ::mc_get_current_run
*/

59
trick_source/sim_services/RealtimeInjector/docs/main_page.dox_in
View File

@ -1,59 +0,0 @@
/**
@page LEVEL2 Real Time Injector
@anchor real_time_injector
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.
@section LEVEL3 Adding and Injecting Variables
@code
trick.rti_add( char * var_name , long long value)
trick.rti_fire( unsigned int thread_id)
@endcode
The rti_add call is typically executed in the input file or variable server,
rti_add requires a variable name and a value (the value may also be a variable name, expression, etc.).
The rti_add call invokes an overloaded function that currently allows either a 64bit integer or double
precision float value to be inputted as the value. The RTI will down cast the
value to the variable type pointed to by var_name. If the value is a variable name, the value of the
variable is determined at the time of the rti_add call, NOT when the injection (rti_fire call) is done.
Multiple variables are allowed to be injected at the same time with separate
rti_add statements. Trick keeps an internal queue of all pending variable injections.
The injection occurs at the top of the next real-time frame only after the rti_fire() call is commanded.
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.
@section LEVEL3 Adjusting Firing Frame
A frame multiple and offset may be set to only allow injections to occur on a frame multiple boundary
and offset.
@code
trick.rti_set_frame_multiple( unsigned int thread_id , unsigned int mult )
trick.rti_set_frame_offset( unsigned int thread_id , unsigned int offset )
@endcode
@section LEVEL3 Listing Scheduled Injections
@code
trick.rti_list()
@endcode
rti_list prints the list of pending injections to the screen.
Listing the injections is not a real-time friendly operation.
@section LEVEL3 Debugging Injections
@code
trick.rti_set_debug( True | False )
@endcode
Debug statements are printed if the rti debug flag is true. But we don't need them
because there aren't any bugs. :D Debug statements are normally set to Off.
*/

91
trick_source/sim_services/RealtimeSync/docs/main_page.dox_in
View File

@ -1,91 +0,0 @@
/**
@anchor RealTime
@page LEVEL2 Real-Time Simulation Processing
Trick provides a real-time processing capability which is different from many real-time
simulation capabilities. The Trick executive is a “time based” executive and can run in
a non-real-time mode just as easily as a real-time mode. This is because Trick guarantees
job execution orders and allows the developer to design guaranteed interfaces which are
not affected by the execution time required for any one or more jobs. Frame based
scheduling executives typically have problems handling real-time overruns because the
frame pulse is the scheduling cue. The frame-pulse in Trick is a mechanism to monitor
and maintain the real-time status of the simulation, not a scheduling mechanism.
An executive for a real-time simulation must guarantee that the simulated time matches
the real-world time at specified intervals (real-time frame length). If the simulated
execution time is greater than the real-world time, an overrun has occurred and must be
dealt with. The parent executive process does all job scheduling and real-time frame
processing. Real-time frame processing is guaranteed by synchronizing with a clock.
Trick provides a clock based on the operating system gettimeofday system call. Users
may provide a different clock my extending the Trick::Clock class.
The software time checks are performed at the end of each real-time
frame by getting the time from the Trick::Clock class, and then
comparing the real-world time to the simulated time.
The gettimeofday clock alone cannot guarantee that an overrun will be detected when
the real-time frame has elapsed; e.g. the software check will never stop an infinite loop.
When the executive has reached the end of frame it burns a CPU (while loop waiting
for the clock to reach the end of the real-time frame) during an under-run.
Trick provides a sleep timer to pause simulation execution and wait for real-time to
catch up. Trick provides an abstract Trick::Timer class and a Trick::ITimer (SIGALARM)
class. The itimer uses signals to “wake up” the simulation when real-time has caught
up to simulation time. Users may provide their own wait mechanisms by extending the
Trick::Timer class.
If overruns occur which exceed the maximum overrun amount or the
maximum number of overruns, the parent initiates a quick and graceful shutdown. Note
that the executive does not know of the overrun condition until it has finished its
regularly scheduled real-time frame processing. This means that the overrun detection
is not instantaneous
Through the input file, the user can set overrun limits, use software time checks and
itimers, and use real-time process control features (locking the process in memory,
assigning and locking a process to a processor, setting the process priority, etc.).
By default, a Trick simulation is run non-real-time, that is all jobs will be run as
fast as possible. The frequency of a job specified in the S_define tells Trick when
to run the job within @e simulation @e time. Trick keeps track of simulation time by
running each job in order according to its frequency, and accumulating time by adding
each unique frequency to simulation time after all jobs of that frequency have run.
But in non-real-time, Trick simulation time does not correspond to real "wall clock"
time (simulation time is normally much faster than real-time).
Real-time can only occur if you tell Trick to synchronize the simulation time with some
real-time clock. To do this, you first choose a frequency at which Trick should synchronize
to a real-time clock. This frequency is referred to as the @e real-time @e frame. Trick
will run all jobs whose frequency \<= real-time frame as fast as possible (this set of
jobs is referred to as an @e execution @e frame), then sync to the real-time clock. If,
at this sync point, Trick has to wait because it has finished its execution frame before
the real-time frame, an @e underrun has occurred, which is the desired behavior. If, at
this sync point, the time to run the execution frame \> real-time frame, an @e overrun has
occurred, meaning the simulation is running slower than real-time. Trick will immediately
start the next execution frame in an attempt to catch up after an overrun.
Trick provides real-time synchronization using the system clock.
It is also possible to use an external time source instead of the system clock. To do so
you must provide your specific external clock functionality by deriving from Trick's
Clock class. (Trick provides the GetTimeOfDayClock class as a derivative of Clock).
@see Trick::Clock\n Trick::GetTimeOfDayClock
A timer may also be used when syncing to real-time during an underrun. Trick provides
this functionality by using a system interval timer or @e itimer. It is possible to use
an external timer instead of an itimer. To do so you must provide your specific external
timer functionality by deriving from Trick's Timer class. (Trick provides the ITimer class
as a derivative of Timer). @see Trick::Timer\n Trick::ITimer
@section LEVEL3 User accessible routines
@li int real_time_enable() ;
@li int real_time_disable() ;
@li int real_time_restart(long long ref_time) ;
@li int is_real_time() ;
@section LEVEL3 RealTime Related Pages
@subpage realtime_requirements "Realtime Requirements"\n
@subpage scheduler_design "Realtime Design"
*/
#include "requirements.dox"

42
trick_source/sim_services/STL/docs/main_page.dox_in
View File

@ -1,42 +0,0 @@
/**
@page LEVEL2 Trick STLs
%Trick provides checkpointable versions of std::STLs.
The list of Trick::STLs are
- deque
- list
- map
- multimap
- multiset
- pair
- priority_queue
- queue
- set
- stack
- vector
The Trick STLs require a C++11 compliant compiler. As of this writing
gcc 4.4+ on Linux systems meets these requirements using the "-std=c++0x"
command line argument.
To use Trick STLs include the proper header file from sim_services/STL/include
and use Trick::STL_name instead of std::STL_name. Trick STLs must be public,
or the proper init_attr friends must be present for checkpointing to work. A
Trick comment with "**" has not effect, Trick STLs will always be checkpointed.
If checkpointing is not desired use the std::STL_name instead.
Example:
@code
#include "sim_services/STL/include/trick_vector.hh"
class A {
public:
Trick::vector< int > my_vector ; // -- trick_comment
}
@endcode
*/

26
trick_source/sim_services/Timer/docs/main_page.dox_in
View File

@ -1,26 +0,0 @@
/**
@page LEVEL2 Realtime Sleep Timer
A realtime sleep timer is an optional class for Trick simulations.
The Realtime Sleep Timer allows the simulation to sleep in case of an frame underrun.
This is desireable to allow other processes to use the CPU during times where the
simulation would not be doing anything.
%Trick provides a Sleep Timer based on the system itimer to sleep during
simulation inactivity.
The user has the ability to enable and disable the sleep timer from the input file.
@code
trick.itimer_enable
trick.itimer_disable
@endcode
@section LEVEL3 Realtime Sleep Timer Related Pages
Realtime Realtime Sleep Timer Requirements\n
Realtime Realtime Sleep Timer Design
*/

499
trick_source/sim_services/VariableServer/docs/main_page.dox_in
View File

@ -1,499 +0,0 @@
/**
@page LEVEL2 Variable Server
When running a %Trick simulation, unless specifically turned off, a server called the
"variable server" is always up and listening in a separate thread of execution. The
variable server is privy to simulation parameters and their values since it resides
in an asynchronous simulation thread. Threads share the same address space as their
siblings and parent. Clients connect to the variable server in order to set/get
values of %Trick processed variables. You may already be familiar with the %Trick
applications that use the variable server: the simulation control panel, %Trick
View (TV) , Event/Malfunction %Trick View (MTV) , and the stripchart.
The variable server is a convenient way for external applications to interact with
the simulation. Any application that needs to set or get simulation parameters may
do so through the variable server. The external application need not be on the same
machine since the connection to the variable server is via a %Trick communication
TCP/IP socket.
@section LEVEL3 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
applications the best way to find a varible server port is to listen to the variable
server broadcast channel. Every simulation variable server will broadcast the host and port
number to the broadcast channel. The channel is address 224.3.14.15 port 9265. All simulations
on your network sends it's information to this address and port so there may be multiple
messages with variable server information available here. Here is some
C code that reads all messages on the variable server channel.
@code
#include <stdio.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
int main() {
int mcast_socket ;
char buf1[1024] ;
ssize_t num_bytes ;
int value = 1;
struct sockaddr_in sockin ;
struct ip_mreq mreq;
if ((mcast_socket = socket(AF_INET, SOCK_DGRAM, 0)) < 0) {
perror("init socket");
}
if (setsockopt(mcast_socket, SOL_SOCKET, SO_REUSEADDR, (char *) &value, (socklen_t) sizeof(value)) < 0) {
perror("setsockopt: reuseaddr");
}
#ifdef SO_REUSEPORT
if (setsockopt(mcast_socket, SOL_SOCKET, SO_REUSEPORT, (char *) &value, sizeof(value)) < 0) {
perror("setsockopt: reuseport");
}
#endif
// Use setsockopt() to request that the kernel join a multicast group
mreq.imr_multiaddr.s_addr = inet_addr("224.3.14.15");
mreq.imr_interface.s_addr = htonl(INADDR_ANY);
if (setsockopt(mcast_socket, IPPROTO_IP, IP_ADD_MEMBERSHIP, (char *) &mreq, (socklen_t) sizeof(mreq)) < 0) {
perror("setsockopt: ip_add_membership");
}
// Set up destination address
sockin.sin_family = AF_INET;
sockin.sin_addr.s_addr = htonl(INADDR_ANY);
sockin.sin_port = htons(9265);
if ( bind(mcast_socket, (struct sockaddr *) &sockin, (socklen_t) sizeof(sockin)) < 0 ) {
perror("bind");
}
do {
num_bytes = recvfrom(mcast_socket, buf1, 1024, 0 , NULL, NULL) ;
if ( num_bytes > 0 ) {
buf1[num_bytes] = '\0' ;
printf("%s\n" , buf1) ;
}
} while ( num_bytes > 0 ) ;
return 0 ;
}
@endcode
The information sent by each variable server is a tab delimited list of strings
-# Hostname
-# Port
-# User
-# Process ID (PID)
-# Simulation directory
-# S_main command line name
-# Input file
-# %Trick version of simulation
-# User defined tag
-# Port (duplicate field for backwards compatibility)
@section LEVEL3 User accessible routines
These commands are for enabling/disabling the variable server, and for getting its status.
The variable server is enabled by default.
@li int var_server_set_enabled(int on_off)
@li int var_server_get_enabled()
@note <b>Disabling the variable server will disable all %Trick runtime GUIs: simulation
control panel, TV, MTV, and stripchart.</b>
These commands are for toggling information messages from the variable server (i.e., commands received from <i>ALL</i> clients).
The messages go to the terminal, the simulation control panel, and the "send_hs" file in the RUN directory.
The variable server information message capability is off by default.
@li int @link Trick::VariableServer::set_var_server_info_msg_off() set_var_server_info_msg_off() @endlink
@li int @link Trick::VariableServer::set_var_server_info_msg_on() set_var_server_info_msg_on() @endlink
These commands are also for toggling information messages from the variable server (i.e., commands received from <i>ALL</i> clients).
The messages only go to a dedicated "varserver_log" file in the RUN directory.
The variable server log capability is off by default.
@li int @link Trick::VariableServer::set_var_server_log_off() set_var_server_log_off() @endlink
@li int @link Trick::VariableServer::set_var_server_log_on() set_var_server_log_on() @endlink
@section LEVEL4 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()
@code trick.var_server_set_port( unsigned int port ) @endcode
To get the variable server host and port information in the input file use var_server_get_hostname() and
var_server_get_port().
@code
trick.var_server_get_hostname()
trick.var_server_get_port()
@endcode
@section LEVEL3 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
is acceptable to the variable server. This section lists the commands that are specific
for the variable server. Commands are sent over a %Trick communication TCP/IP socket to
the variable server. Multiple commands (newline separated) can be sent in the string
over the socket. The variable server will send back information to the requesting client.
If the command contains a syntax error, Python will print an error message to the screen,
but nothing will be returned to the client.
@section LEVEL4 Adding a Variable
@code trick.var_add( string var_name ) @endcode
or
@code trick.var_add( string var_name , string units ) @endcode
Adding a variable will tell the variable server to send the variable's value back to the
client at a specified frequency. An optional units parameter may be attached to the
variable as the desired return units. Multiple variables may be added to the list to be sent
back to the client. The format of the returned values are described below, Ascii Format
or binary format.
@section LEVEL4 Time Homogeneous or Synchronous Data
@section LEVEL5 Copying Data Out of Simulation.
@code trick.var_set_copy_mode(int mode) @endcode
There are 3 options to when the variable server will copy data out from the simulation.
Each option has unique capabilites.
@par 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.
@par 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
at that time step both in run and freeze mode. All variables solely calculated in the
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.
@par 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
of the freeze frame. With careful planning, all variables from all threads can be
guaranteed to be time homogenous. Copying data may very slightly affect the main thread
real-time performance.
To set the frame multiplier and frame offset between copies use the following commands.
The frame refers to the software frame in the Executive. In freeze mode a different
multiplier and offset are used.
@code
trick.var_set_frame_multiplier(int mult)
trick.var_set_frame_offset(int offset)
trick.var_set_freeze_frame_multiplier(int mult)
trick.var_set_freeze_frame_offset(int offset)
@endcode
@section LEVEL5 Writing Data Out of Simulation.
@code trick.var_set_write_mode(int mode) @endcode
There are 2 options when the variable server writes the data.
@par 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.
@par 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.
@section LEVEL5 Old Style var_sync() Command
@code trick.var_sync(bool mode) @endcode
var_sync() was previously used to control the copies and writes from the simulation.
The number of options has outgrown what a single var_sync command can configure. It
may still be used to configure a subset of the copy/write combinations.
@code
trick.var_sync(0) # asynchronous copy and asynchronous write.
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.
@endcode
@section LEVEL4 Sending the Return Values Immediately
@code trick.var_send() @endcode
The var_send command forces the variable server to return the list of values to the
client immediately.
@section LEVEL4 Changing the Units
@code trick.var_units( string var_name , string units ) @endcode
The returned values can be converted to other units of measurments. The var_units command
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.
@section LEVEL4 Removing a Variable
@code trick.var_remove( string var_name ) @endcode
Removing a variable removes the variable from the list returned to the client.
@section LEVEL4 Clearing the List of Variables
@code trick.var_clear() @endcode
To clear the whole list of variables sent to the client.
@section LEVEL4 Exiting the Variable Server
@code trick.var_exit() @endcode
Disconnects the current client from the variable server.
@section LEVEL4 Checking for existence of a variable
@code trick.var_exists( string var_name ) @endcode
To test if a variable name exists. A special return message is sent to the client when
this command is processed.
The return message is in this format:
@code1<1 byte binary 0 or 1>@endcode
@section LEVEL4 Changing the Return Value Cycle Rate
@code trick.var_cycle( double cycle_rate ) @endcode
Changes the rate of the return messages to the client. This rate is estimated and may not
perfectly match the requested rate.
@section LEVEL4 Pause the Variable Server
@code trick.var_pause() @endcode
Pauses the return values sent to the client. Even when paused, the variable server will
accept new commands.
@section LEVEL4 Unpause the Variable Server
@code trick.var_unpause() @endcode
Resumes sending the return values to the client.
@section LEVEL4 Setting Ascii Return Format
@code trick.var_ascii() @endcode
Sets the return message format to ASCII. See below for the format of the message.
@section LEVEL4 Setting Binary Return Format
@code trick.var_binary() @endcode
Sets the return message format to Binary. See below for the format of the message.
@code trick.var_binary_nonames() @endcode
This variation of the binary format reduces the amount of data that is sent to the client.
See below for the exact format.
@section LEVEL4 Sending stdout and stderr to client
@code trick.var_set_send_stdio(bool on_off) @endcode
If var_set_send_stdio is called with a true value, then all python stdout and stderr
output will be redirected to the client instead of printing to the simulation stdout/stderr
location. Note: output from C/C++ code called from python will direct it's output to
the simulation stdout/stderr location. See the return message format for Stdio.
This is useful to get output from the simulation such as the return values of a function.
@code
# Example in a variable server client to get the Trick version used to compile a sim
# The C prototype is "const char *exec_get_current_version(void) ;"
trick.var_set_send_stdio(True)
sys.stdout.write(trick.exec_get_current_version())
# The returned text will look like this. See the return message format below
4 1 10
10.7.dev-1
# If a "print" is used instead of sys.stdout.write, a second message is sent containing
# a single newline.
print "trick.exec_get_current_version()"
4 1 10
10.7.dev-14 1 1
<- a single newline is the second message
@endcode
@section LEVEL4 Debugging Variable Server Messages
@code trick.var_debug(int level) @endcode
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).
@section LEVEL4 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.
The variable server log capability is off by default. (See the global variable server commands
@link Trick::VariableServer::set_var_server_log_on() set_var_server_log_on() @endlink and
@link Trick::VariableServer::set_var_server_log_off() set_var_server_log_off() @endlink for toggling
the logging capability for <i>ALL</i> clients.)
@code
trick.var_server_log_on()
trick.var_server_log_off()
@endcode
@section LEVEL4 Setting Variable Server Client Tag
@code trick.var_set_client_tag(string name) @endcode
This sets an identifying name tag to be associated with the current client that will be printed with each information message
displayed. Information messages are displayed as a result of
@link Trick::VariableServer::set_var_server_info_msg_on() set_var_server_info_msg_on() @endlink,
@c var_server_log_on() or
@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.).
@section LEVEL4 Byteswapping
@code trick.var_byteswap(bool on_off) @endcode
@section LEVEL3 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
guarantee synchronization from the same simulation execution frames unless the var_sync
command is used. Values will be returned to the client in the same order that they were
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).
@subsection LEVEL3 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:
@code 0\t<variable1 value>[\t<variable2 value>. . .\t<variableN value>]\n @endcode
where N is the number of variables registered via the var_add command(s). The "\t" represents
a tab character, and the "\n" is the newline character that always ends the string. Note
that if a value being returned is itself a character string data type, any tab (or other
unprintable character) that occurs within the character string value will appear as an
escaped character, i.e. preceded by a backslash.
The 1st value returned in the list will always be a message indicator. The possible
values of the message indicator are:
- 0 returned variable value(s) from var_add or var_send
- 1 returned value from var_exists
- 2 returned value from send_sie_resource (special command used by Trick View)
- 3 returned value from send_event_data (special command used by Events/Malfunctions Trick View)
.
If the variable units are also specified along with the variable name in a var_add or
var_units command, then that variable will also have its units specification returned following
its associated value separated by a single blank. For example, if the 2nd of N variables was
specified with {<units>} in either a var_add or var_units command, the returned string would
be in the following format:
@code 0\t<variable1 value>\t<variable2 value> {<variable2 units>}. . .\t<variableN value>\n @endcode
Note that the maximum message size that the variable server sends to the client is 8192 bytes.
If the amount of data requested is larger than that, the ASCII message will be split into
multiple messages. The client is responsible for concatenating the multiple messages back
together. (Hint: look for the "\n" delimter)
If a syntax error occurs when processing the variable server client command, Python will print
an error message to the screen, but nothing will be returned to the client.
If a var_add command was issued for a non-existent variable, there will be a one time %Trick error
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".
@subsection LEVEL3 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:
@code
<message_indicator><message_size><N>
<variable1_namelength><variable1_name><variable1_type><variable1_size><variable1_value>
<variable2_namelength><variable2_name><variable2_type><variable2_size><variable2_value>
. . .
<variableN_namelength><variableN_name><variableN_type><variableN_size><variableN_value>
@endcode
Where the first 12 bytes are the message header:
- @e message_indicator is the same possible values as in var_ascii shown above : a 4 byte integer
- @e message_size is the total size of the message in bytes (NOT including message_indicator) : a 4 byte integer
- @e N is the number of variables registered via the var_add command(s) : a 4 byte integer
.
and the remaining bytes of the message contain the variable data:
- @e variable_namelength is the string length of the variable name : a 4 byte integer (NOT present for var_binary_nonames)
- @e variable_name is the ASCII variable name string : @e variable_namelength bytes of string (NOT present for var_binary_nonames)
- @e variable_type is %Trick data type of the variable : a 4 byte integer (see Trick::MemoryManager::TRICK_TYPE)
- @e variable_size is number of bytes the variable occupies in memory : a 4 byte integer
- @e variable_value is the variable's current value : @e variable_size bytes of @e variable_type
When the client has requested a very large amount of data, it is possible that it may require
more than one message to be returned. The maximum message size is 8192 bytes, so if the data
returned by the variable server requires more space than that (once formatted into the above
message format), then the variable server sends more than one message. This is indicated by
the @e N field. For example, if the client has requested 15 variables, and @e N = 15, then
everything is contained in that one message. However if @e N < 15, then the client should
continue reading messages until all @e N received add up to 15.
If a syntax error occurs when processing the variable server client command, Python will print
an error message to the screen, but nothing will be returned to the client.
If a var_add command was issued for a non-existent variable, there will be a one time %Trick error
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".
@subsection LEVEL3 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.
@code
4 <stream> <size>
<text>
@endcode
- @e message_id Stdio messages are message_id = 4.
- @e stream is the stream the message was written to. 1 = stdout, 2 = stderr
- @e size is the number of bytes in the <text> section. The newline between the <size> and <text>
is not counted in the size.
- @e text is the message
Only output from python is redirected, i.e. "print" or calls to "sys.stdout.write()". C/C++ code
called from python will still direct their stdout/stderr to the simulation output location.
The "print" statement will send 2 messages, the text in the print, and an additional newline.
Calls to sys.stdout.write() only generate 1 message.
@note Error messages printed by python to stderr may be sent in multiple messages.
*/

3
trick_source/trick_utils/comm/main_page.dox_in
View File

@ -1,3 +0,0 @@
/**
@page LEVEL2 Comm
*/

8
trick_source/trick_utils/math/main_page.dox_in
View File

@ -1,8 +0,0 @@
/**
@page LEVEL2 Math Utilities
@subpage VECTOR_MACROS "Vector Macros"<br>
@subpage MATRIX_MACROS "Matrix Macros"<br>
@subpage QUATERNIAN_MACROS "Quaternian Macros"<br>
@ref TRICK_MATH "Trick Math Utilities"<br>
*/

3
trick_source/trick_utils/trick_adt/main_page.dox_in
View File

@ -1,3 +0,0 @@
/**
@page LEVEL2 Abstract Data Types
*/

50
trick_source/trick_utils/units/main_page.dox_in
View File

@ -1,50 +0,0 @@
/**
@page LEVEL2 Units
The measurement units field for each parameter requires the following syntax:
( <units_spec> )
Each units specification may be a units primitive,
or a combination of units primitives.
A units primitive in the Metric system may also be combined with a prefix to
specify decimal multiples and submultiples, such as mm for millimeters, km for
kilometers, etc.
The rules for combining units primitives are as follows:
<units_product>[/<units_product>[/<units_product>...]] where <units_product> is defined as:
<units_primitive>[2|3][ *<units_primitive>[2|3] [ *<units_primitive>[2|3] ...] ]
Where the units primitives are:
- @subpage UNITS_TIME "Units of Time"<br>
- @subpage UNITS_LENGTH "Units of Length"<br>
- @subpage UNITS_ANGLE "Units of Angle"<br>
- @subpage UNITS_MASS "Units of Mass"<br>
- @subpage UNITS_FORCE "Units of Force"<br>
- @subpage UNITS_ELECTRIC_POTENTIAL "Units of Electric Potential"<br>
- @subpage UNITS_ELECTRIC_CURRENT "Units of Electric Current"<br>
- @subpage UNITS_ELECTRIC_RESISTANCE "Units of Electric Resistance"<br>
- @subpage UNITS_TEMPERATURE "Units of Temperature"<br>
- @subpage UNITS_GAIN "Units of Gain"<br>
- @subpage UNITS_ENERGY "Units of Energy"<br>
- @subpage UNITS_POWER "Units of Power"<br>
- @subpage UNITS_PRESSURE "Units of Pressure"<br>
- @subpage UNITS_UNITLESS "Unitless"<br>
@attention Use of \"\--\" is not allowed for any parameter that should have a measurement units specification.
Maximum exponent of 3 is allowed for measurement units.
For example, the following all represent the same units specification:
- m/s2
- m/s*s
- m/s/s
Also, see the following units conversion interfaces:
- @ref Unit "Unit Class"
- @ref UNITS_C_INTF "Units C Interface"
*/