Improve tutorial documentation (#1408)

bin/trick-CP

@@ -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 ;
 }
 

docs/documentation/running_a_simulation/Input-File.md

@@ -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.

docs/documentation/simulation_capabilities/Data-Record.md

@@ -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.
 

docs/tutorial/ATutAnalyticSim.md

@@ -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,14 +711,16 @@ 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_overrides.mk                        makefile
+S_sie.resource                        trick.zip
 S_define                              S_source.hh
 S_main_<your_platform_name_here>.exe	build
 ```

docs/tutorial/ATutIntroduction.md

@@ -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.

docs/tutorial/ATutMonteCarlo.md

@@ -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)

docs/tutorial/ATutNumericSim.md

@@ -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,15 +150,17 @@ 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.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`.
 
@@ -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))

docs/tutorial/ATutRecordingData.md

@@ -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

docs/tutorial/ATutRunningRealtime.md

@@ -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.
 
 ---
 

docs/tutorial/ATutTrickView.md

@@ -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)

docs/tutorial/TutVariableServer.md

@@ -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.
@@ -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:
 

include/trick/DRHDF5.hh

@@ -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.
 

trick_sims/Cannon/SIM_cannon_analytic/S_define

@@ -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)