Introduction

This software simulation of the Train Thing originated near the beginning of this project. For a longer discussion of the genesis see the introduction in the Documentation tab of the main menu. The simulator is one of a software developer's worst nightmares; A "one-time-use" or tool for personal use, that has a ribbon put on it and then given to the client. The simulator was written for personal amusement, then developmental use, so the GUI (Graphical User Interface) is a little clunky in places.

Depending on your browser when you hold your mouse over any of the options or help icons, a one-line window will open with a short explanation of that option.

Alongside many options is this small icon . Clicking on the icon will open this contextual help document in a new window providing information about that option.

There is a Simulator Section on the Bulletin Board where, registered visitors, can ask questions, make comments, suggestions or report errors regarding the simulator.

Quick Start On the simulator drop-down menu, there is a screenshot video illustrating the following quick start procedure.

• From the Train Thing main menu, hold your mouse over the <Simulator> option and from the drop-down options click on <Run Simulator>.
• You may resize this browser window to take up less screen space. See the illustration at left. Note: If you make the window too narrow, the elements near the bottom will wrap and be hard to read. Reducing this window's width will make room for the simulator display. 
• Click on <Create Second Window> to open a second browser window filled with the Train Thing Display. Resize the new window so both windows are fully visible.
• For now, you can skip over the {Display Labels} section of the Initialize Screen.
• The {Configure Trains} section is where you set up a simulation run. You can configure the trains as described below or let the system randomly configure the trains by pressing the <Random Trains> button at the bottom of this section.
• There are four paths that can be assigned to a "train": a small figure-eight, large figure-eight, small oval and large oval. Each path can be traced CW (Clockwise) or CCW (Counterclockwise).
• To assign a train to a path, select a color from the <Select one> drop-down menu.
• Click on the radio button next to CW or CCW to select a direction.
• You may assign a path to 1 to 4 train(s) by selecting a train color for each path.
• You MUST assign at least one train to a path by selecting a color for a path.
• You MAY NOT assign a color to more than one path.
• When you have finished configuring the simulation click on <Run Train(s)> to start the simulation. Ignore the <Repeat Similar Runs> option for now. (see Repeat Runs)
• You will be switched to the Updating Loop screen. Here there will always be an <ABORT> button which will rudely stop the simulation and return to the Initialize State screen.
• The simulator will progress from Stopped state, to Starting, to Transition, to the Run state. In the Transition state, trains will move from their initial CW figure-eight path to the path you assigned in the previous screen. When the simulator reaches the Run state there will also be an <End Run> button. Pressing <End Run> will change the simulator to the Return state. In this state all trains will migrate to a CCW figure-eight path in preparation for returning to the parking lot. When all trains are following a large or small CCW figure-eight path, the state will switch to the Parking state and in order trains will return to the parking lot. When all trains are parked you will be returned to the Initialize screen where you can start another simulator run or exit the simulator.
• To exit the simulator:
• Click on <End TrainThing> to close the simulator, delete the second window and return to the main menu.
• Click on the appropriate icon in the top right of your browser to expand the browser window to full screen.

Create New Window

After reducing the width of your browser window, click this <Create Second Window> button to open a second browser window filled with the graphics of the Train Thing layout. Adjust the size of the new window so both windows are fully visible.

Originally the thought was that, with a second display attached to my PC the window with the graphics could be moved to the second screen, freeing the laptop screen for the control screen and IDE (Integrated Development Environment) to write the software.

Display Labels

This section of the initialization screen lets you select which labels are displayed on the simulator graphics. Many of the labels were originally displayed for development but they "clutter" the screen now.

With the radio button "Select Above" selected, you can check or un-check individual boxes at the top and then click <Update Labels Displayed>. Alternatively, you can use the radio buttons at the bottom to select "All" or "None" of the labels, then click <Update Labels Displayed>.Changes will immediately take effect in the graphics display window.

Note: The signal labels will not be displayed if the "Display Signals" is not also selected.

Display options are retained until you <End TrainThing>. Choices can be changed any time this screen is displayed.

Configure Trains

There are two ways to configure which of the four paths are followed by trains during a simulation run.

• You can click the <Random Trains> button at the bottom of the {Configure Trains} section. The system will randomly select 1 - 4 trains to run during the simulation. Each train will randomly be assigned to a path and direction (CW or CCW). The {Configure Trains} will be updated to reflect the random assignments. You can click <Random Trains> again for a new random assignment or change the assignment as below before pressing <Run Train(s)> to start the simulation.
• You can select 1 to 4 paths: Small figure-8, Large figure-8, Small oval and/or Large oval. Each path can be run in a CW or CCW direction by clicking the appropriate radio button. To activate a path, select the color of the train you want to follow the path from the drop-down menu. Use a color only once. Logically a train can only follow one path. And of course, it does not make sense to run the simulator without selecting any trains/paths.

When you click <Run Train(s)> colored trains not selected here will be magically removed from the display.

By default, the <Single Run> radio button is selected. In this mode, the colored trains you select will exit the 'Parking Lot' and follow the assigned path. This should run forever or until you end the run by selecting <End Run> or <ABORT> on the next screen.

Select <End Run> and the trains will find their way back to the 'Parking Lot'. <ABORT> will rudely stop the simulation run and place the trains back in their beginning parking locations. In either case the Initialize State screen will again be displayed.

See <Repeat Similar Runs> for details of repeat runs.

Repeat Similar Runs

This was a last-minute addition for testing. Select 1,2,3 or 4 paths/trains above for the simulation run, select the <Repeat Similar Runs> radio button and then click <Run Train(s)>.

1. First the entered simulation configured will be run for a random number of steps (out of the parking lot, random number of run steps, then back to the parking lot).
2. The simulator will randomly select the same number of paths CW/CCW and randomly assign each path to colored trains.
3. This new random simulation will be run for a random number of steps, as in step 1.
4. This will repeat until the simulator is stopped.

During a "Run" the process can be stopped by clicking <End Run> or <ABORT>.

This "feature" was added to help in testing. Keeping in mind there are:

• 384 different runs of 4 trains running 4 of the 8 paths
• 192 runs of 3 trains
• 48 runs of 2 trains
• 8 runs of 1 train

That is 632 tests to run. Booooring. So, I added random testing.

It may look like there are more runs using different colored trains. However, due to the choke point exiting the parking lot into CW figure-eight paths, the order determined by the color of the trains is lost. The color of the train is looked at by the software only when getting back into the parking lot. Obviously, the RED train must be parked first. Otherwise the permutation of paths is accounted for in the numbers above.

In the beginning the order of the paths appeared to be important. If path "A" is assigned to RED (first) or GREEN (last) is different. Anecdotally, both runs seem to fall into a pattern after executing in the 'Run' mode for a while.

Please record any different analysis on the Simulator forum of the Bulletin Board.

Run Train(s)

When a simulation run has been configured and <Single Run> (default) or <Repeat Similar Runs> have been selected, click <Run Train(s)> to start the simulation.

Not selecting at least one "Train Color" or selecting the same "Train Color" more than once will result in an error condition.

End TrainThing

When you are ready to exit the simulator, there are two things you should do to clean up your computer display and return to the Train Thing main menu (part of the clunky GUI):

• Click on <End TrainThing> to close the second browser window, end the simulator and return to the main menu.
• Click on the appropriate icon in the top right of your browser to expand the browser window to full screen.

Updating Loop

This simulator has 7 states. The current state is shown in the upper left corner of the display.

0.        Stopped

1.        Idle

2.        Starting

3.        Transition

4.        Run

5.        Return

6.        Parking

In system states 2, 3, 5 & 6 temporary paths are followed by a train to move from the parking lot, to their assigned path and from their assigned path back to the parking lot. A train is switched from its current path to its next path when the next two sections of track in the current path match two sections of track in the next path. 

0.  The "Stopped" simulator state is entered when the simulator is started, or after the <ABORT> or <End Run> buttons are clicked. See the Introduction for options available in the "Stopped" state. After configuring a simulator run in the Initialization window, clicking <Run Train(s)> will change the simulator to the "Starting" state (2) below and start the Updating Loop program.

1.  The "Idle" state is entered from the "Parking" state (6) when <Repeat Runs> was selected, the random number of run steps were completed in "Run" state (4) and all trains are parked in state 6. The next simulator run is configured similarly to the one selected in "Stopped" state (0). The same number of paths are randomly selected, direction randomly assigned and assigned to a randomly selected colored trains. A random number of steps, between 5 and 20, are selected for the "Run" state. When configured, the state is changed to "Starting" (2). See "Idle" for details of this process. 

2.  In the "Starting" state each train is moved along a path to exit the parking lot and enter a large CW figure-eight loop. If the train's assigned path is a small oval or small figure-eight, at the appropriate time the train then switches from a large to a small CW figure-eight path. Trains assigned to a large path follow a large CW figure-eight path until the parking lot is empty. This avoids a train running into back of the parking lot or blocking the exit from the parking lot. (Ok so this can't happen in the simulator. But remember this tool is a prologue to a hardware implementation.) When all trains are out of the "parking lot" all tracks are available and the simulator goes to the "Transition" state (3). See "Starting" for details of this state.

3.  In the "Transition" state trains are switched from CW figure-eight paths given in state (2) to the path assigned in the "Stopped" or initialization state. This may be a two-step process depending on the final direction assigned. When all trains are following their assigned path, in the desired direction the simulator advances to "Run" state (4). Step wise details are in "Transition".

4.  In the "Run" state each train follows its assigned endless loop until one of three events occur:

• The <ABORT> button is clicked. The simulator goes directly to the "Stopped" state (0) and the Initialization program.
• The <End Run> button is clicked. The simulator goes to the "Return" (5), then "Parking" (6) states and finally returns to the "Stopped" state (0) after all trains are parked..
• If the <Repeat Runs> option was selected and the random number of steps have been completed. As with <End Run> trains are returned to the parking lot. When all trains are parked the simulator changes to the "Idle" state (1) to start another simulator run.

For details of which train goes when see "Run".

5.  In the "Return" state each train is moved from their assigned path to a large or small CCW figure-eight depending on their assigned level. Depending on the assigned direction this may be a two-step process. When all trains are following a CCW figure-eight, the state is changed to "Parking" (6). Details of this state can be seen at "Return".

6.  In the "Parking" state each train is moved, in order, from the temporary CCW figure-eight path into the right-hand end of the parking lot. If all four trains are in use, the RED train is first moved to a large figure-eight path and then into the parking lot. This avoids congestion in the large figure-eight path. When there are three or fewer trains to be parked, all trains are moved to a large figure-eight and in order moved into the parking lot. When all the trains are parked the simulator does one of two things: 

• If the <Repeat Runs> was selected in the beginning and no buttons were pressed in the "Run" state to end the run early, the simulator goes to the "Idle" state (1).
• Otherwise, the <End Run> button was clicked in the "Run" state, and all the trains have been parked, the simulator returns to the "Stopped" state (0) and the "Initialization" screen is displayed.

This process is detailed in the "Parking" section.

End Run

When the simulator is in the "Run" state the <End Run> button is visible. Clicking <End Run> will change the simulator from the "Run" state to the "Return" state 5. In preparation for parking the trains. Trains running small oval or figure-eight will move to a small CCW figure-eight. Similarly trains running a large oval or figure-eight will move to a large CCW figure-eight.

When all trains are following a CCW figure-eight, the simulator will change to the "Parking" state and move the trains, in order, to the parking lot. When all trains are parked, the simulator will return to the initialization or "Stopped" state ready to run another simulation or exit.

ABORT

The <ABORT> option is always visible during updating loop operation. Clicking <ABORT> will rudely end the updating operating loop and return the simulator to the initialization or "Stopped" state. Keep in mind that there are two programs running: the update program and the display graphic program. Clicking <ABORT> will not be detected / take effect except while the update script is running, so click the button "slowly" or it may not be effective.

Idle

The idle state (1) was added to the simulator options to assist in testing all the combinations of paths and number of trains.

From the initialization screen, the "Stopped" state, the update loop is entered in the "Starting" state as normal. The "Run" state is reached as normal. However, in the "Run" state, a predetermined number steps are executed and the state automatically advances to the "Return" state as if the <End Run> button was pressed. When all the trains are parked in the "Parking" state, the simulator comes to this "Idle" state instead of returning to the initialization screen/"Stopped" state.

Each run in the <Similar Runs> mode have the same number of trains as configured on the initialization screen. Each new configuration is randomly selected effectively using two 'hats'. One hat contains the 4 train colors. The second hat contains tokens for the 4 paths, small and large figure-eights, small and large ovals.

A path is selected from one hat and a color from the other. Then a 'coin' is flipped to assign CW or CCW direction to the train path. This process is repeated until the required number of trains have been configured. A new random number of run steps is selected for the next simulation. All simulator status data elements are updated, the simulator state is advanced to the "Starting" state and the new simulator is run as described above.

This process is repeated until the <ABORT> or <End Run> buttons are pressed.

Starting

After a simulation run is configured either in the stopped state or the idle state, running the simulation begins here.

Each train is assigned two initial paths:

1. A short CW path including the 4 blocks of track in the parking lot and the 2 blocks of track at the left end of the large figure-eight.
2. A large CW figure-eight path.

All trains are cycled through and moved forward if it can within the rules. A train may move forward within the current block or move to the next block in its currently assigned path.

Moving within the current block.

Each control block of track has 5 locations representing moving along the block of track. The train can be located at either end of the block, on one of the two IR sensors represented by the black dots on the track, or between the two IR sensors. The exceptions to this are the 4 short "parking places" which have only 1 IR sensor, the only place a train can be located.

A train enters a control block at one end, moved to the first IR sensor, then between the two IR sensors, to the second IR sensor. Sense the end of the current block is the same location at the beginning of the next block the rules for changing blocks are checked (below) and if the rules are met the train moves to the beginning of the next block. Within the parking lot trains move from the IR sensor in the current block to the IR sensor in the next block if the block is not occupied.

Moving to the next block.

There are only two rules controlling whether a train can move forward to the next block in its current path.

1. A train can move to the next block if:

• Any turnouts or the crossover between the current block and the next block are not being used by another train and
• The next block is not occupied

2. If the train is entering the two curved blocks of track at the left or right end of the display or entering the "X" in the middle of the display a train can move to the next block if:

• Rule #1 is met and
• The second block must not be occupied or
• If the second block is occupied the train must be going in the same direction as the train entering the first block.

If a train can move the current block of track is turned on and displayed in green. If the train is moving to a new block, logically we don't know where the train is between the last IR sensor on the current block and the first IR sensor on the next block. So both the current and next block are turned on and displayed in green. If the train is blocked this is indicated by displaying the current block in red.

Change to next path.

When two paths are assigned to a train, a current path and a next path, each time a train is cleared to change block a check is made if the train can change paths. The train changes paths when:

• The train is cleared to move to the next block and
• The next two blocks in the current path matches, in order, two blocks in the next path.

For example, in the "Starting" state each train starts with two paths assigned, see above. As a train is ready to exit the parking lot the next two blocks in its path match two blocks in the large CW figure-eight, so its current path is switched to the large CW figure-eight.

Add a next path

At this same time a check is made if another next path needs to be assigned. In the starting state, if a train was initially assigned either a small figure-eight or a small oval, as soon as the train is out of the parking lot, a small CW figure-eight path is assigned as the next path.

When all configured trains are out of the parking lot, the state is advanced to the Transition state (3).

Transition

In the transition state trains are moved from the large or small CW figure-eight path assigned in the starting state (2) to the path assigned during the stopped (0) or idle (1) state.

Following the rules for changing paths, a train can switch from a CW figure-eight to either a CW or CCW oval. And from an oval back to a CCW figure-eight. In this way all trains are moved to the final assigned path and are ready for the Run state (4).

If there are two trains on a given level, large or small, and the figure-eight train needs to run CCW care must be taken that when both trains are switched to the oval path that they are going in the same direction.

As soon as all trains are following their configured path in the desired direction the simulator state is advanced to the Run state (4).

Run

As soon as the Run state is entered the <End Run> button is displayed along with the <ABORT> button.

In the Run State all trains are following the path and direction assigned by the user in the Stopped State (0) or randomly in the Idle state (1). 

All trains continue looping around the assigned path until one of the two buttons are pressed or if in the "Repeat Run" mode the specified number of steps have been completed. When the steps are completed in the "Repeat Runs" mode or the <End Run> button is pressed the simulator advances to the Return state (5). As in all states pressing the <ABORT> button stops the simulator and returns to the initialization screen.

Return

In the return state, all trains are moved to a CCW figure-eight path in preparation for moving into the parking lot. The return state's function mirrors the function of the Transition state, migrating each train from their assigned path and direction to a CCW figure-eight.

As in the Transition state a CW figure-eight train, if present, can be changed to either a CW or CCW oval. Trains following an oval path can be changed to a CCW figure-eight following the rules defined earlier.

When all trains are following a CCW figure-eight path the simulator advances to the parking state (6).

Parking

In the Parking state, each train is moved, in order, from their current CCW figure-eight path into the right-hand end of the parking lot and stopped in their assigned parking place. When all trains are parked one of two actions is taken:

• In the single run mode (default), the simulator is returned to the Stopped state (0) and the initialization program is started.
• In the Repeat Similar Runs mode, the simulator is switched to the Idle state (1) and a new random simulation is started.

The steps to move all trains from their current large or small figure-eight to the parking space are:

1. If four trains are running in the simulation the red train is:

• If following a small CCW figure-eight, move to a large CCW figure-eight.
• From the large CCW figure-eight path switched to the short ending path and parked.

2. When there are three or fewer trains to be parked, move any train following a small CCW figure-eight path to a large CCW figure-eight path.
3. In color order, red, orange, yellow & green, move trains from a large CCW path to the short ending path to park the train.

Steps 2 and 3 can be followed at the same time depending on the color and location of each train.

When all trains are parked the simulator goes to the Stopped or Idle state as described above.

Errors

There are only two user input errors that are detected:

• You must select at least one train/path to simulate.
• Each train/path you select must have a unique color.

Must Select One

To generate this error, you have clicked <Run Train(s)> without selecting any "Train" colors first.

A simulation running no trains doesn't make much sense.

The error was detected when no trains were found to update. 

By selecting at least one color for a path before clicking <Run Train(s)> will avoid this error.

Select Color Once

The screenshot at left shows an example of how this error could be generated, the "Train Color" for two paths is the same.

When <Run Train(s)> is clicked, the error is detected and the simulator is stopped.

Obviously a train cannot follow two paths.

By selecting a color only once before clicking <Run Train(s)> will avoid this error.

More than you Want to Know

I know I need to write some words for here.

Direction of Path

For the figure-eight paths, CW and CCW are defined on the left end of the figure.

Copyright © September 2019 - 2021 by No One's Business. All Rights Reserved.