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

Improve tutorial documentation (#1408)

Browse Source
This commit is contained in:
Cody Martin 2022-12-02 13:55:40 -07:00 committed by GitHub
parent 0933228dd5
commit 3870dc73b6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
16 changed files with 83 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
bin/trick-CP
View File

@ -60,7 +60,7 @@ if ( -f $sdefine ) {
system("make -f makefile " . $makefileAddArgs) ;
exit $? >> 8;
} else {
print "S_define does not exist" ;
print "S_define does not exist\n" ;
exit 1 ;
}

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

@ -255,7 +255,7 @@ There are several ways to include files in Python.
```python
# One way is to use the execfile command
execfile("Modified_data/data_record.py")
exec(open("Modified_data/data_record.py").read())
# 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.

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

@ -382,7 +382,7 @@ The following data-types are used in Trick versions >= 10, that is for, *vv* = "
### DRHDF5 Recording Format
HDF5 recording format is an industry conforming HDF5 formatted file. Files written in this format are named
log_<group_name>.hd5. The contents of this file type are readable by the Trick Data Products packages from
log_<group_name>.h5. The contents of this file type are readable by the Trick Data Products packages from
Trick 07 to the current version. The contents of the file are binary and is not included here. The HDF5 layout
of the file follows.

33
docs/tutorial/ATutAnalyticSim.md
View File

@ -479,7 +479,7 @@ our Cannonball simulation is shown in Listing 7, below.
```c++
/************************TRICK HEADER*************************
PURPOSE:
(This S_define works with the RUN_analytic input file)
(S_define file for SIM_cannon_analytic)
LIBRARY DEPENDENCIES:
(
(cannon/src/cannon_init.c)
@ -507,8 +507,6 @@ class CannonSimObject : public Trick::SimObject {
CannonSimObject dyn ;
```
The `S_define` file syntax is C++ with a couple of Trick specific constructs.
Let us dissect this S_define file to see what makes it tick.
@ -647,14 +645,19 @@ In the files that we have created so far, the file paths in `#include` directive
and in the `LIBRARY_DEPENDENCY` sections, are **relative** paths. These paths
are relative to a **base-path**, that we still need to specify.
For example, the `S_define` file listed above, `#includes` the relative path:
`cannon/include/cannon.h`. We intend for this path to be relative to the
`trick_models` directory that we created in our `$HOME` directory. The complete
For example, the `S_define` file listed above `#includes` the relative path:
`cannon/include/cannon_analytic.h`. We intend for this path to be relative to the
`models` directory that we created in our `SIM_cannon_analytic` directory. The complete
path to our cannon.h header file should be:
![Trick Path Construction](images/TrickPaths.png)
```
${HOME}/trick_sims/SIM_cannon_analytic/models/cannon/include/cannon_analytic.h
```
So, we need to specify the base-path(s), to the compilers, and to Trick by adding
We need to specify either the absolute path to the `models` directory, or the
relative location of the `models` directory with respect to the top-level
simulation directory (the location of S_define) as the base-path.
We can specify the base-path(s) to the compilers, and to Trick, by adding
-I*dir* options, that contain the base-paths, to `$TRICK_CFLAGS` and
`$TRICK_CXXFLAGS`.
@ -670,8 +673,8 @@ TRICK_CFLAGS += -Imodels
TRICK_CXXFLAGS += -Imodels
```
When Trick encounters relative paths, these base-paths will be prepended to the
relative paths to create a complete path to the file, thus allowing it to be
When Trick encounters relative paths in an S_define, it prepends these base-path(s)
to the relative paths to create a complete path to the file, thus allowing it to be
located.
#### Additional Compiler Flag Recommendations
@ -708,15 +711,17 @@ If you typed everything perfectly... Trick is installed properly... there are no
bugs in the tutorial... the stars are aligned... and Trick is in a good mood...
You should, ultimately see :
![Simulation Make Complete](images/SimMakeComplete.png)
```
Trick Build Process Complete
```
Now, take a look at the sim directory. Is there an `S_main*.exe` file?? (* is a wildcard, instead of * you will see the name of your platform). If so, cool deal. If not, scream!, then take a look at the next section "Troubleshooting A Bad Build". If all went well, you will notice several other files now resident in the `SIM_cannon_analytic` directory.
```bash
% ls
Modified_data S_overrides.mk makefile
RUN_test S_sie.resource trick.zip
S_define S_source.hh
S_overrides.mk makefile
S_sie.resource trick.zip
S_define S_source.hh
S_main_<your_platform_name_here>.exe build
```

2
docs/tutorial/ATutDynamicEvents.md
View File

@ -211,7 +211,7 @@ Add the [cannon_impact](#listing_cannon_impact) function, listed above, to the b
Add the following job specification, to run our cannon_impact job.
```
("dynamic_event") cannon_impact( &cannon) ;
("dynamic_event") cannon_impact( &cannon ) ;
```
to the end of the list of jobs in the CannonSimObject.

20
docs/tutorial/ATutIntroduction.md
View File

@ -68,24 +68,30 @@ its capabilities.
If Trick is not already installed on your machine, then you will need to do that
first, by following the directions at: [Install Guide](/trick/documentation/install_guide/Install-Guide).
Once Trick is installed on your machine, you will need add the Trick **bin**
directory to your execution path. For the sake of example, let us assume that
The rest of the tutorial is written as if the Trick **bin** directory is
available on your execution path. This isn't strictly necessary, but allows
you to call `trick-CP` instead of `/full/path/to/trick/bin/trick-CP`. Follow
the steps below if you would like to add the **bin** directory to your PATH.
For the sake of example, let us assume that
you installed Trick in your home directory, and you used the default name for
the repository, which is **trick**. If you named it something different, then
use that name instead in the scripts below.
If you are using **bash or ksh**, then add the following lines to the file that is automatically sourced by your terminal. Based on your platform this could be **.profile, .bash_profile, .bashrc, .zshrc** or others. Google "How to edit PATH variable" on google to find a wealth of information on this subject.
If you are using **bash or ksh**, then add the following lines to the file
that is automatically sourced by your terminal. Based on your platform this
could be **.profile, .bash_profile, .bashrc, .zshrc** or others. Google "How
to edit PATH variable" on google to find a wealth of information on this
subject.
```bash
export TRICK_HOME="${HOME}/trick"
export PATH=${PATH}:${TRICK_HOME}/bin
export PATH=${PATH}:${HOME}/trick/bin
```
If you are using **csh** or **tcsh**, then add the following lines to your **.cshrc** file.
```csh
setenv TRICK_HOME ${HOME}/trick
setenv PATH ${PATH}:${TRICK_HOME}/bin
setenv PATH ${PATH}:${HOME}/trick/bin
```
Close and then re-open your terminal window.

8
docs/tutorial/ATutMonteCarlo.md
View File

@ -184,7 +184,7 @@ trick-dre &
Create a sub-directory called *RUN_test* in your simulation directory. In this new directory create an input file named *test.py*. This input file executes the data recording file you saved above and stops the simulation after 10 seconds of simulation time.
```python
execfile("monte_cannon.dr")
exec(open("monte_cannon.dr").read())
trick.stop(10)
```
@ -253,7 +253,7 @@ Create a new directory called RUN_file and place the following python script in
```python
# -*- coding: UTF-8 -*-
execfile("monte_cannon.dr")
exec(open("monte_cannon.dr").read())
# Enable Monte Carlo.
trick.mc_set_enabled(1)
@ -282,7 +282,7 @@ Random Input Generation provides users with the ability to statistically generat
### Script
```python
# -*- coding: UTF-8 -*-
execfile("data/monte_cannon.dr")
exec(open("data/monte_cannon.dr").read())
# Enable Monte Carlo.
trick.mc_set_enabled(1)
@ -398,7 +398,7 @@ int cannon_master_post(CANNON *C)
```python
# -*- coding: UTF-8 -*-
execfile("data/monte_cannon.dr")
exec(open("data/monte_cannon.dr").read())
# Enable Monte Carlo.
trick.mc_set_enabled(1)

33
docs/tutorial/ATutNumericSim.md
View File

@ -27,7 +27,7 @@
<a id=how-trick-does-numerical-integration></a>
## How Trick Does Numerical Integration
The type of model that we created in the last section relied on the fact that
the cannon ball problem has an closed-form solution from which we can
the cannon ball problem has a closed-form solution from which we can
immediately calculate the cannon ball state [position, velocity] at any
arbitrary time. In real-world simulation problems, this will almost never
be the case.
@ -140,11 +140,8 @@ Producing simulation states by numerical integration requires that the derivativ
and integration jobs be called at the appropriate rate and times. This requires
a properly configured integration scheduler.
First,an integration scheduler has to be instantiated in the S_define. Then, in
the input files
1. In the S_define file, define the integration with a declaration of the
following form:
First, instantiate an integration scheduler in the S_define with a declaration
of the following form:
```c++
IntegLoop integLoopName ( integrationTimeStep ) listOfSimObjectNames ;
@ -153,16 +150,18 @@ IntegLoop integLoopName ( integrationTimeStep ) listOfSimObjectNames ;
* Jobs within a simObject that are tagged "derivative" or "integration" will be
dispatched to the associated integration scheduler.
In the input file, call the IntegLoop **getIntegrator()** method to specify
Then, in the input file, call the IntegLoop **getIntegrator()** method to specify
the integration algorithm of choice and the number of state variables to be
integrated.
*integLoopName*.getIntegrator( *algorithm*, *N* );
```py
integLoopName.getIntegrator( algorithm, N );
```
* *algorithm* is a enumeration value that indicates the numerical integration
algorithm to be used, such as: `trick.Euler`, `trick.Runge_Kutta_2`,
`trick.Runge_Kutta_4`. A complete list can be seen Integrator.hh, in
`${TRICK_HOME}/include/trick/Integrator.hh` .
`trick.Runge_Kutta_4`. A complete list is visible in Integrator.hh, in
`${TRICK_HOME}/include/trick/Integrator.hh`.
* N is the number of state variables to be integrated.
@ -192,7 +191,7 @@ And then copy the sim directory.
### Create **cannon_numeric.h.**
In this new simulation, we're going to create two new functions, 1)
`cannon_deriv()` [our derivative job], 2) `cannon_integ ()` [our integration job].
`cannon_deriv()` [our derivative job], and 2) `cannon_integ ()` [our integration job].
We'll put prototypes for each these functions into `cannon_numeric.h`. This new
header file which will replace `cannon_analytic.h`.
@ -357,8 +356,8 @@ Replace:
with:
```c++
("derivative") cannon_deriv( &cannon) ;
("integration") trick_ret= cannon_integ( & cannon);
("derivative") cannon_deriv( &cannon ) ;
("integration") trick_ret= cannon_integ( & cannon ) ;
```
### Add Integration Scheduler and Integrator
@ -385,7 +384,7 @@ The updated S_define is:
```c++
/****************************************************************
PURPOSE: (S_define File for SIM_cannon_numeric.)
PURPOSE: (S_define file for SIM_cannon_numeric)
LIBRARY_DEPENDENCY: ((cannon/src/cannon_init.c)
(cannon/src/cannon_numeric.c)
(cannon/src/cannon_shutdown.c))
@ -399,9 +398,9 @@ class CannonSimObject : public Trick::SimObject {
CannonSimObject() {
("initialization") cannon_init( &cannon ) ;
("default_data") cannon_default_data( &cannon ) ;
("derivative") cannon_deriv( &cannon) ;
("integration") trick_ret= cannon_integ( &cannon);
("shutdown") cannon_shutdown( &cannon);
("derivative") cannon_deriv( &cannon ) ;
("integration") trick_ret= cannon_integ( &cannon ) ;
("shutdown") cannon_shutdown( &cannon ) ;
}
};

4
docs/tutorial/ATutRecordingData.md
View File

@ -26,7 +26,7 @@ recording editor --- aka Dr. Dre) or you may create it manually.
* **Step 1.** In the "DR Name" entry box, enter my_cannon.
* **Step 2.** In the "DR Cycle" entry box, change 0.1 to 0.01.
* **Step 3.** In the "Variables" pane, double-click dyn, then double-click cannon.
* **Step 4.** Double-click pos[2]. The result should result in dyn.cannon.pos[0]
* **Step 4.** Double-click pos[2] and click OK. The result should result in dyn.cannon.pos[0]
and dyn.cannon.pos[1] appearing in the "Selected Variables" pane.
* **Step 5.** Choose File->Save. In the "Save" dialog, enter the file name
cannon.dr. Save cannon.dr in the Modified_data directory.
@ -40,7 +40,7 @@ text file.
#### Running The Simulation And Recording Data
The simulation must know about the data recording file created in the last
section. This is accomplished by adding execfile to the simulation input file.
section. This is accomplished by adding exec to the simulation input file.
```bash
% cd $HOME/trick_sims/SIM_cannon_analytic/RUN_test

12
docs/tutorial/ATutRunningRealtime.md
View File

@ -48,15 +48,15 @@ is beating the system clock, it pauses. If it is falling behind, it registers
waiting for the beginning of the next software frame to start the simulation
jobs. If interval timers are not used, Trick will spin waiting for the next beat.
`trick.exec_set_freeze_command()` - brings up the simulation in a frozen
(non-running) state.
`trick.exec_set_enable_freeze()` - allows the user to toggle the simulation
from a frozen state to a running state at will.
`trick.exec_set_freeze_command()` - brings up the simulation in a frozen
(non-running) state.
`trick.sim_control_panel_set_enabled(True)` or
`simControlPanel = trick.SimControlPanel() & trick.add_external_application(simControlPanel)`
- brings up the simulation control panel GUI.
`simControlPanel = trick.SimControlPanel() & trick.add_external_application(simControlPanel)` -
brings up the simulation control panel GUI.
The `realtime.py` file must be included in the RUN_test/input.py file. When
finished, the latest version of the input file should look like the following:
@ -100,7 +100,7 @@ Some items to note about the simulation control panel for your future use:
(does not complete all jobs during the software frame) and display them in
the tiny box next to the simulation name. If the simulation overruns, the
sim will run as fast as it can "to catch up" to where it should be.
* Using the File menu at the top, you may set a freeze point in the future.
* Using the Actions menu at the top, you may set a freeze point in the future.
---

14
docs/tutorial/ATutTrickView.md
View File

@ -60,13 +60,15 @@ to 10 meters.
1. Notice that dyn.cannon.vel[0] is 43.30... meters per second. To
view it in feet per second:
* Left Click on the variable dyn.cannon.vel[0] on the Variable table.
* Left Click on the "m/s" in the Unit column to bring up a drop-down list.
* Select **ft/s**. Notice that the value of dyn.cannon.vel[0] changes to
* Double Click on the "m/s" in the Unit column to edit the field.
* Type **ft/s**. Notice that the value of dyn.cannon.vel[0] changes to
142.06... ft/s.
1. Resume the simulation run by clicking the **Start** button on the
sim control panel. Notice that the trajectory assumes its predetermined path.
This is because we are giving the cannonball a position as a function of time.
This is because we are analytically calculating the cannonball position as a
function of time, rather than calculating it from the previous frame data.
#### TV With An Input File
If this simulation were run over and over, it would be laborious to
@ -107,8 +109,8 @@ Again, we need to incorporate the TV input file into our ever expanding
simulation input file.
```python
execfile("Modified_data/realtime.py")
execfile("Modified_data/cannon.dr")
exec(open("Modified_data/realtime.py").read())
exec(open("Modified_data/cannon.dr").read())
trick.trick_view_add_auto_load_file("TV_cannon.tv")
trick.stop(5.2)
@ -122,6 +124,4 @@ trick.stop(5.2)
You may now run the sim and verify that TV pops up automatically.
Congratulations, you have finished the basic Trick tutorial!
[Next Page](ATutNumericSim)

20
docs/tutorial/TutVariableServer.md
View File

@ -124,12 +124,13 @@ To run the variable server client :
* Execute, but don't "Start" the cannonball simulation.
* Find the variable server port number in the bottom left hand corner of the Sim
Control Panel, as shown below.
* Execute the script with the port number as an argument. Example:
```$ ~/CannonDisplay_Rev1.py 50774 &```
![Cannon](images/SimControlPanel.png)
* Execute the script with the port number as an argument.
Example: ```$ ~/CannonDisplay_Rev1.py 50774 &```
* "Start" the cannonball simulation.
The output of the script will display three columns of numbers. The left most
number is the [variable server message type](#variable-server-message-types).
Here, a message type of 0 indicates that the message is the (tab delimited) list
@ -147,7 +148,6 @@ that they were specified in the script.
0 68.84901960086293 27.34966950000001
0 73.17914661978513 28.24082950000001
```
<a id=how-the-client-works></a>
@ -179,7 +179,7 @@ and "dyn.cannon.pos[1]" to the session variable list.
⚠️ Please notice that the quotes around the variable names must be
escaped with the '\' (backslash) character.
```
```python
client_socket.send( "trick.var_add(\"dyn.cannon.pos[0]\") \n" +
"trick.var_add(\"dyn.cannon.pos[1]\") \n"
)
@ -260,7 +260,6 @@ Now, when we run the client, we get both the init_angle and the init_speed with
0 0 0
```
Another commonly used pattern to retrieve variables only once is to use the [**var_add**](#api-var-add),
[**var_send**](#api-var-send), and [**var_clear**](#api-var-clear) commands. [**var_send**](#api-var-send) tells
the variable server to send all **session** variables immediately regardless of whether [**var_pause**](#api-var-pause)
@ -277,8 +276,6 @@ print line
client_socket.send( "trick.var_clear()\n" )
```
In this snippet of code, we add ```dyn.cannon.init_angle``` to the session
variable list. Then we call [**var_send**](#api-var-send) to tell the variable
server to send us the value, and wait for the response by calling
@ -289,7 +286,9 @@ two ways. We can 1) call [**var_clear**](#api-var-clear) to clear the the list,
or 2) we can call [**var_remove**](#api-var-remove). Specifically we could do
the following:
```client_socket.send("trick.var_remove(\"dyn.cannon.init_angle\")\n")```
```python
client_socket.send( "trick.var_remove(\"dyn.cannon.init_angle\")\n" )
```
So, when we run the modified client, the first three lines of the output should
look something like the following.
@ -302,7 +301,7 @@ look something like the following.
0 0 0
```
The first line contains the message type ( which is zero), followed by the value
The first line contains the message type (which is zero), followed by the value
of ```dyn.cannon.init_angle```. Subsequent lines contain the position data like
before.
@ -561,7 +560,6 @@ Add this to the bottom of RUN_test/input.py to give it a try.
<a id=the-variable-server-api></a>
### The Variable Server API
``
The following functions are a subset of variable server API functions that are
used in this tutorial:

BIN
docs/tutorial/images/SimMakeComplete.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 8.4 KiB

BIN
docs/tutorial/images/TrickPaths.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 12 KiB

2
include/trick/DRHDF5.hh
View File

@ -48,7 +48,7 @@ namespace Trick {
/**
The DRHDF5 recording format is an industry conforming HDF5 formatted file. Files written in this format are named
log_<group_name>.hd5. The contents of this file type are readable by the Trick Data Products packages from
log_<group_name>.h5. The contents of this file type are readable by the Trick Data Products packages from
Trick 07 to the current version. The contents of the file are binary and is not included here. The HDF5 layout
of the file follows.

2
trick_sims/Cannon/SIM_cannon_analytic/S_define
View File

@ -1,6 +1,6 @@
/************************TRICK HEADER*************************
PURPOSE:
(This S_define works with the RUN_analytic input file)
(S_define file for SIM_cannon_analytic)
LIBRARY DEPENDENCIES:
(
(cannon/gravity/src/cannon_init.c)