Commit 5f3ee443 authored by Aaron Bray's avatar Aaron Bray
Browse files

Update ReadMe.md

parent 587c6c89
......@@ -102,130 +102,7 @@ make install
cd Pulse
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## Running and Testing
## Using Pulse
The code base provides a few driver programs to execute the physiology libraries built.
<b> !! NOTE : The 'bin' directory being refered to below is the bin directory in your <build directory>/install/bin NOT the src/bin directory !! </b>
As part of running and testing Pulse, you will need to download the testing scenarios and their baseline result files.
These files are not part of the standard build.
If you would like to have these files downloaded during the build, enable the PULSE_DOWNLOAD_BASELINES option when configuring the CMake super build
To download the verificaiton scenarios and baseline results run this command from a bash/cmd prompt from <build directory>/install/bin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
cmake -DTYPE:STRING=updateBaselines -P run.cmake
# There is also .bat and .sh scripts to make this a little easier
# You can type
run updateBaselines
# or, on Linux
./run.sh updateBaselines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This script will download the scenarios and baselines associated with your code version and place them in <build directory>/install/bin/verification
If you would like to manually pull the verification files you can get them <a href="https://data.kitware.com/#collection/59849c788d777f7d33e9c084/folder/598c95d88d777f7d33e9c1fa">here</a>
Note that each folder will be tied to a git hash where it was introduced, you can search a history of the sourc/verificaiton/verification.zip/sha512 to see all baseline commits hashes.
Simply unzip the archive in the <build directory>/install/bin/verification directory
### Scenario Driver
The Scenario Driver is a simple C++ driver that reads a scenario proto text files (*.pba) and creates a CSV file with results.
See <a href="/_scenario_p_b_a_file.html">here</a> for more info.
To run the driver, change directory in your cmd/bash shell to the build/install/bin directory and execute the following :
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
# First ensure the release directory (or debug if that is what you are running) is on your path, so we can see the executable
# Note release will contain 64bit binaries, if you build 32bit, there will be a release32 folder
PATH=%PATH%;./release # for windows
PATH=$PATH:./release # for linux
PulseScenarioDriver verification/scenarios/patient/BasicStandard.pba
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<b> .csv and .log files will be placed in the bin directory </b>
If you are going to run the SceanrioDriver through visual studio follow these steps :
- Right-click the ScenarioDriver project and select 'Set as Startup Project'
- Right-click the Project and select settings
- Make sure you are on the appropriate configuration in the Configuration drop down. The one you intend to run
- You probably want to do this for all configuration in the solution
- Click on 'Configuration Options->Debugging' on the left tree in the properties dialog
- Put the directory to your bin directory as the 'Working Directory'
- Put in the full path (or relative to the bin directory) of the scenario file you wish to run
<b> You will also need to set the working directory for the UnitTestDriver if you want to run that through visual studio as well. </b>
### Java Based Testing Suite
The code base also provides a test harness, written in Java, that will process a ./test/config/*.config file in the source tree by doing the following :
- For each line in the config file :
- Run the ScenarioDriver or UnitTestDriver (depends on the line)
- Compare the generated csv results to a baseline csv file and report any differences
- Generate a plot image file for each data column of the csv file over the time of the scenario
To run the test driver, change directory in your cmd/bash shell to the build/install/bin directory and execute the run.cmake in the following way :
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
cmake -DTYPE:STRING=[option] -P run.cmake
# There is also .bat and .sh scripts to make this a little easier
# You can type
run [option]
# or, on Linux
./run.sh [option]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Where [option] can be one of the following :
- genData - Generate pba files from data in the ../data/Data.xlxs file (Patients, Substances, etc.)
- genStates - Generate state file for every patient at the point where the patient completed stabilization (Simulation time 0s)
- Any of the testing configurations found in ../test/config without the suffix
- For Example : DebugRun, CDMUnitTests, ValidationSystems, VerificationScenarios, etc.
- With exception of the Characterize.config, this is a legacy testing configuration that will not work
- SystemValidation - Will run the ../test/config/ValidationSystems configuration plus create validation tables from comparing results to ../test/validation
- PatientValidation - Will run the ../test/config/ValidationPatients configuration plus create validation tables from comparing results to ../test/validation
<b>Results will be place in the build/install/bin/test_results directory </b>
#### Configuration Files
The configuration files, referenced above, provide the testing suite direction on how to execute the test harness and what to do with the results.
## Generating Documentation
The physiology engine includes functionality to generate html documentation. This including in-code documentation, data model design description, and physiology system methodology reports. The html files are generated using Doxygen and custom Java applications.
To generate the documentation, perform the following steps:
- Install Doxygen, which can be found <a href="http://www.stack.nl/~dimitri/doxygen/download.html">here</a>
- Install Ghostscript, which can be found <a href="https://www.ghostscript.com/download/">here</a>
- Install a LaTeX generator
- For windows, use MiKTeX, which can be found <a href="https://miktex.org/download">here</a>
- Execute SystemValidation and PatientValidation as described above
- Execute the doxygen tool using build/install/bin/run.cmake in your cmd/bash shell in the following way :
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
cmake -DTYPE:STRING=doxygen -P run.cmake
# There is also .bat and .sh scripts to make this a little easier
# You can type
run doxygen
# or, on Linux
./run.sh doxygen
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
## Creating the Software Development Kit (SDK)
In the source code tree is an sdk folder.
This folder provides examples of how to use the physiology engine.
During the build and install, all the header and library files needed to integrate the engine into your application are placed into the build/install folder
External applications only need to reference this directory for headers and libraries for their build.
Note, your application will still need to execute within the build/install/bin directory as it has the binaries and data files in it.
There is a CMakeLists.txt in the sdk folder that you can also run to build and run any of the provided HowTo examples.
You can edit the EngineHowTo.cpp to run a particular example, and even code in the HowToSandbox.cpp to run your own engine!
There is also an example of using a Java based interface with an eclipse project you can explore as well.
See the wiki for more examples using the SDK and building your own application with Pulse.
With the code built, visit our [wiki](https://gitlab.kitware.com/physiology/engine/wikis/home) to learn how to execute Pulase and use our SDK to use Pulse in your own application with Pulse.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment