ReadMe.md 14.1 KB
Newer Older
Aaron Bray's avatar
Aaron Bray committed
1
<img src="./docs/Images/pulse_logo_512.png" alt="Pulse Physiology Engine" width="256" height="106">
Aaron Bray's avatar
Aaron Bray committed
2

Aaron Bray's avatar
Aaron Bray committed
3
The Pulse Physiology engine is a C++ based simulation engine for human and animal physiology.
Aaron Bray's avatar
Aaron Bray committed
4
It is intended to provide accurate and consistent physiology data to medical education, research, and training technologies. 
Aaron Bray's avatar
Aaron Bray committed
5
The built libraries are static and can be integrated with standalone applications, hardware simulators, sensor interfaces, and other physiology models of all fidelities.
Aaron Bray's avatar
Aaron Bray committed
6

Jeff Webb's avatar
Jeff Webb committed
7
Along with the build instructions below, we provide more technical discussions using Pulse on our <a href="https://gitlab.kitware.com/physiology/engine/wikis/home">wiki</a>
Aaron Bray's avatar
Aaron Bray committed
8
9

For detailed information about our design and methodology read our <a href="https://physiology.kitware.com/">documentation</a>
10

Aaron Bray's avatar
Aaron Bray committed
11
12
13
Use this <a href="https://discourse.kitware.com/c/pulse-physiology-engine">discourse channel</a> 
to ask or share anything and everything about building, using, or understanding the Pulse engine and welcome to our community!!

14
15
## Build Environment

16
17
The code provided utilizes C++17, here is a list of popular compilers and their initial version to implement all of C++17 :

18
19
- GCC 9 and later
  - While GCC 7/8 have C++17 support, it was still experimental and requires different includes/linkages
Aaron Bray's avatar
Aaron Bray committed
20
21
- Clang 5 and later
- MSVC 2017 and later
Aaron Bray's avatar
Aaron Bray committed
22

Aaron Bray's avatar
Aaron Bray committed
23
While the provided cmake superbuild automatically pulls many libraries it needs to compile, 
Aaron Bray's avatar
Aaron Bray committed
24
25
26
you will still need to have the following tools installed (along with your choice of C++ compiler) :

### CMake
Aaron Bray's avatar
Aaron Bray committed
27
Currently, the code requires CMake 3.12 or greater to properly build
Jeff Webb's avatar
Jeff Webb committed
28
Go to the cmake website, <a href="https://cmake.org/download">https://cmake.org/download</a>, and download the appropriate distribution.
Aaron Bray's avatar
Aaron Bray committed
29
Ensure that cmake bin is on your PATH and available in your cmd/bash shell.
Aaron Bray's avatar
Aaron Bray committed
30

Aaron Bray's avatar
Aaron Bray committed
31
#### On Linux
Aaron Bray's avatar
Aaron Bray committed
32

Aaron Bray's avatar
Aaron Bray committed
33
34
If you are on a Debian/Ubuntu system, please install the latest cmake on your system by <a href="https://apt.kitware.com/">following thes instructions</a>.

Aaron Bray's avatar
Aaron Bray committed
35
36
### Java JDK

Aaron Bray's avatar
Aaron Bray committed
37
38
The test suite and data generate tools used are written in Java.
While there is no dependency on Java when integrating with your application, it is currently required to build/develop/contribute to the code base.
Aaron Bray's avatar
Aaron Bray committed
39

Aaron Bray's avatar
Aaron Bray committed
40
A JAVA_HOME environment variable needs to exist pointing to the Java installation.<br>
41
42
43
44
There are many ways to do this.
We recomend using the Amazon Corretto JDK 8

Follow the installation instructions for your operating system <a href="https://docs.aws.amazon.com/corretto/latest/corretto-8-ug/what-is-corretto-8.html">here.</a>
Aaron Bray's avatar
Aaron Bray committed
45
46

#### Windows
47
48

To set a global JAVA_HOME environment variable pointing to the Java installation:
Aaron Bray's avatar
Aaron Bray committed
49

Aaron Bray's avatar
Aaron Bray committed
50
- Download the Windows x64 JDK <a href="https://docs.aws.amazon.com/corretto/latest/corretto-8-ug/downloads-list.html">here.</a>
51
- Run the installer for Win.
Aaron Bray's avatar
Aaron Bray committed
52
53
- Goto your Control Panel->System and click Advanced system settings on the left. <br>
- Click the 'Environment Variables' button and add JAVA_HOME as a new 'System variables'.<br>
Aaron Bray's avatar
Aaron Bray committed
54
- Set the Value to something like: N:/Programming/Tools/jdk1.8.0_212<br>
Aaron Bray's avatar
Aaron Bray committed
55
56
57
    - It's a good idea to add the JDK to the system PATH by adding this to the beginning: %JAVA_HOME%/bin;
- Make sure to start a new cmd window.<br>

58
59
60
61
#### Mac

Use the <a href="https://docs.aws.amazon.com/corretto/latest/corretto-8-ug/macos-install.html"> instructions provided by amazon. </a> 

Aaron Bray's avatar
Aaron Bray committed
62
#### Linux
Aaron Bray's avatar
Aaron Bray committed
63

64
65
66
67
Use the <a href="https://docs.aws.amazon.com/corretto/latest/corretto-8-ug/generic-linux-install.html"> instructions provided by amazon. </a> 

If you would like to use the open jdk, follow these instructions:

Aaron Bray's avatar
Aaron Bray committed
68
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
Aaron Bray's avatar
Aaron Bray committed
69
70
# Check to see if you have the JDK
$ update-alternatives --list java
Jeff Webb's avatar
Jeff Webb committed
71
# Note: Make sure you don't add the jre in the path of the java listed
Aaron Bray's avatar
Aaron Bray committed
72
73
74
75
76
# for example you may see '/usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java'
# you will want the truncated '/usr/lib/jvm/java-8-openjdk-amd64'
# If you do not have the Java SDK
$ sudo apt-get install openjdk-8-jdk
# Set the JAVA_HOME environment variable
Aaron Bray's avatar
Aaron Bray committed
77
78
# NOTE your Java path may vary!
# Use the update-alternatives to find your system's Java path
Aaron Bray's avatar
Aaron Bray committed
79
export JAVA_HOME='/usr/lib/jvm/java-8-openjdk-amd64'
Aaron Bray's avatar
Aaron Bray committed
80
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Aaron Bray's avatar
Aaron Bray committed
81

Jeff Webb's avatar
Jeff Webb committed
82
You can also add it to your ~/.bash_profile, or related file (.bashrc, .zshrc, .cshrc, setenv.sh), to get the path in all shells.
Aaron Bray's avatar
Aaron Bray committed
83

Aaron Bray's avatar
Aaron Bray committed
84
## Building
Aaron Bray's avatar
Aaron Bray committed
85

Aaron Bray's avatar
Aaron Bray committed
86
The build is directed by CMake to ensure it can be built on various platforms. 
Aaron Bray's avatar
Aaron Bray committed
87
The code is build by a CMake 'superbuild', meaning as part of the build, CMake will download any
Aaron Bray's avatar
Aaron Bray committed
88
dependent libraries and compile those before it builds. 
Aaron Bray's avatar
Aaron Bray committed
89
The build is also out of source, meaning the code base is seperated from the build files.
Aaron Bray's avatar
Aaron Bray committed
90
This means you will need two folders, one for the source code and one for the build files.
Aaron Bray's avatar
Aaron Bray committed
91
Generally, I create a single directory to house these two folders.
Aaron Bray's avatar
Aaron Bray committed
92
93
94
95

Visual Studio users, our <a href="https://gitlab.kitware.com/physiology/engine/wikis/Using%20MSVC">wiki provides detailed steps for building with MSVC</a>

Here is the quickest way to pull and build via a bash shell:
Aaron Bray's avatar
Aaron Bray committed
96

Aaron Bray's avatar
Aaron Bray committed
97
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
Aaron Bray's avatar
Aaron Bray committed
98
99
100
$ mkdir Pulse
$ cd Pulse
$ git clone https://gitlab.kitware.com/physiology/engine
101
# This will put the source in an 'engine' folder
Aaron Bray's avatar
Aaron Bray committed
102
103
104
105
$ mkdir builds
$ cd builds
# Feel free to make subfolders here, like debug or release
# Generate a make file solution for the external dependencies
106
# Note you need to provide cmake the source directory at the end (relative or absolute)
Aaron Bray's avatar
Aaron Bray committed
107
# Run CMake (it will use the system default compiler if you don't provide options or use the CMake GUI)
Aaron Bray's avatar
Aaron Bray committed
108
$ cmake -DCMAKE_BUILD_TYPE:STRING=Release ../engine
Daryl.Xu's avatar
Daryl.Xu committed
109
# If you want the build to pull the Verification and Validation (V&V) scenarios and baselines run this (or check the Pulse_DOWNLOAD_BASELINES option in the CMake GUI)
Aaron Bray's avatar
Aaron Bray committed
110
# You can always pull these later if you want (See Running and Testing)
Daryl.Xu's avatar
Daryl.Xu committed
111
$ cmake -DCMAKE_BUILD_TYPE:STRING=Release -DPulse_DOWNLOAD_BASELINES:BOOL=ON ../engine
112
#
113
114
# Build the install target/project
# On Linux/OSX/MinGW 
Aaron Bray's avatar
Aaron Bray committed
115
116
117
118
119
120
121
122
123
124
$ make -j4
# cd into the 'Pulse' directory for building any changes specific to the Pulse code base
# Such as if you pull new Pulse code or make changes, run make from the Pulse directory
# See below for more details in pulling and rebuilding
$ cd Pulse
# To run Pulse, cd to the install/bin directory
$ cd install/bin
# In this example that would be ~/Pulse/builds/install/bin
# Now you can run something
$ ./PulseScenarioDriver VitalsMonitor.json
125
126
127
128
129
130
131
132
133
134
135
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

### Docker Support

Pulse provides a docker file that, by default, builds a linux based docker container with Python support.

To build this docker container, pull the source code and run the docker build command from the source root.
Kitware provides Pulse containers on [dockerhub](https://hub.docker.com/r/kitware/pulse).

Here is an example of building a docker container and pushing it to an organization repository in dockerhub:

Aaron Bray's avatar
Aaron Bray committed
136
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
137
138
139
140
141
142
# From the Pulse source directory
$ docker build -t kitware/pulse:3.0.0 .
$ docker push kitware/pulse:3.0.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

### Single Board Computers Support 
Aaron Bray's avatar
Aaron Bray committed
143

Aaron Bray's avatar
Aaron Bray committed
144
145
146
Note that on small boards, like the Beagle Board Black and DragonBoard 410c, you may need to allocate a <a href="https://www.cyberciti.biz/faq/linux-add-a-swap-file-howto/">temporary swap</a> file if your build runs out of memory

It boils down to:
Jeff Webb's avatar
Jeff Webb committed
147

Aaron Bray's avatar
Aaron Bray committed
148
149
150
151
152
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
su - root
fallocate -l 1G tmpswap
mkswap tmpswap
swapon tmpswap
Aaron Bray's avatar
Aaron Bray committed
153
154
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Aaron Bray's avatar
Aaron Bray committed
155
156

Read the article if you want to make this change permanent, it contains some valuable hints regarding permissions and fstab.
Aaron Bray's avatar
Aaron Bray committed
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
### Cross Compiling

CMake provides the ability to easily cross compile.
In general, when we cross compile, we are doing so to get out a PulseC library.
The PulseC library provides an interface used by our C#/Unity and Python API's to access and control the C++ based engine.
Unity is C# based and any C# managed libraries built on any platform, will automatically run on other platforms.
But the PulseC library is a native library and a specific platform version must be provided for the platform Pulse is being run on.
The following sections will highlight specific build instructions for cross compiling for these target platforms.

#### Native Platform Build

The first thing you will want to do is build Pulse on the host system. I use Visual Studio when building natively.
During the Pulse build, it will build and run the Protobuf protoc compiler to generate C++ classes needed for I/O.
These files are needed to build, but when you cross compile, you will build a protoc executable for your target platform, and it will not run on the native host system.
Doing a native build will ensure these files are generated. The cross compile build will see the files exist and not run the non native protoc compiler.
Once you have a native build, create a new empty build directory for your cross compile build.

#### Dockcross

To generate Pulse libraries for android, linux, and web assembly, we use docker containers provided by [dockcross](https://hub.docker.com/u/dockcross). Dockcross provides both a build environment and a cmake toolchain file that simplifies the cross platform build process. 
Simply pull the target docker container, run cmake, and build.
I am using docker on windows via the WSL 2 based engine, from an [Ubuntu 20](https://www.microsoft.com/en-us/p/ubuntu-2004-lts/9n6svws3rx71?activetab=pivot:overviewtab) terminal.

Here is an example bulding Pulse for Android armv8a.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
# Run this command from a directory that contains both your sourc and your build directories
$ docker run --rm dockcross/android-arm64 > ./armv8a
# This creates a file we will use to invoke our container
# Next, set execution permissions
$ chmod +x ./armv8a  
# Run CMake
# -B is the relative path to my build directory
# -H is the relative path to my Pulse source directory
$ ./armv8a cmake -DPulse_JAVA_API:BOOL=OFF -B./Builds/pulse-engine-armv8a -H./Pulse/engine -GNinja
# Use ninja to build (provided in the docker)
$ ./armv8a ninja -C./Builds/pulse-engine-armv8a
# The PulseC.so for the target platform will be in the pulse-engine-armv8a/install/bin directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#### Magic Leap

Magic Leap provides a Lumin SDK for use in compiling native C++ code for use on the Magic Leap platform.
You will need to download and install this SDK. 
In this example we are building on a windows machine, using the Lumin SDK v0.24.1.
Please follow the [Lumin instructions on generating a cmake toolchain file](https://developer.magicleap.com/en-us/learn/guides/sdk-mabu-ref-build-and-link-libraries#build-libraries-with-cmake) needed for cross compiling.

I had to modify the toolchain file, adding '-llog' for protobuf's use of the android log methods, as well as '-g -std=c++11 -Wall -pedantic' to add C++11 support.
Aaron Bray's avatar
Aaron Bray committed
205
206
207
208
`set(CMAKE_CXX_FLAGS "-g -std=c++1z -Wall -pedantic ` <br>
`set(CMAKE_EXE_LINKER_FLAGS "-llog ` <br>
`set(CMAKE_SHARED_LINKER_FLAGS "-llog ` <br>

Aaron Bray's avatar
Aaron Bray committed
209
210
211
212
213
214
215
Here is a copy of the [modified toolchain file](https://data.kitware.com/api/v1/file/5f29b9489014a6d84e57067a/download)

To generate a Makefile and build, run :

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
# Where -H specifies the Pulse source, and -B is the build directory
cmake -DPulse_JAVA_API:BOOL=OFF -DCMAKE_TOOLCHAIN_FILE:FILEPATH=C:/Programming/magicleap.0.24.1.toolchain.cmake -BC:/Programming/Builds/pulse-engine-lumin -HC:/Programming/Pulse/engine -G "Unix Makefiles"
Aaron Bray's avatar
Aaron Bray committed
216

Aaron Bray's avatar
Aaron Bray committed
217
218
219
220
221
222
# Run make from within your build directory
N:/Tools/MagicLeap/dev/mlsdk/v0.24.1/tools/mabu/tools/MinGW/bin/mingw32-make.exe
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This will provide a PulseC.so in the build/install/bin that works on the Magic Leap platform!

Aaron Bray's avatar
Aaron Bray committed
223

Aaron Bray's avatar
Aaron Bray committed
224
225
## Updating Pulse

Aaron Bray's avatar
Aaron Bray committed
226
The Pulse repository is always changing as we add improvements and features to the code base.
Aaron Bray's avatar
Aaron Bray committed
227
These changes will require that you rebuild the source code when you pull the latest changes.
Jeff Webb's avatar
Jeff Webb committed
228
Here are a few tips for keeping your source code up to date when you pull:
Aaron Bray's avatar
Aaron Bray committed
229

Aaron Bray's avatar
Aaron Bray committed
230
231
<b>Please ensure CMake is on your path!</b>

Aaron Bray's avatar
Aaron Bray committed
232
233
234
235
236
237
238
239
240
### Rebuilding the schema

Pulse uses Google Protocol Buffers for data files and to communicate data between various languages and networking protocols.
After you pull the latest, you will need to run the Protoc compiler to adjust the data model to any changes made to the proto files describing the Pulse Data Model.

From a command/terminal in your pulse/build/install/bin directory : 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
# On Windows
> run protoc
Aaron Bray's avatar
Aaron Bray committed
241
# On Linux/Mac
Aaron Bray's avatar
Aaron Bray committed
242
243
244
245
246
247
$ ./run.sh protoc
# Note you may need to do a 
$ chmod +x run.sh
# To run this script on your machine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Jeff Webb's avatar
Jeff Webb committed
248
Note: If there were no changes to the protobuf files, the proto compile will not run and return this message 
Aaron Bray's avatar
Aaron Bray committed
249
250
251
252
253

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
-- Not generating bindings, nothing has changed since last build
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Jeff Webb's avatar
Jeff Webb committed
254
255
256
If you are getting linking errors about missing protobuf functions,
such as missing something in the cdm:: namespace,
you can force the protoc compiler to run by deleting this timestamp file:
Aaron Bray's avatar
Aaron Bray committed
257
258
259
260
261

<b>pulse/build/Pulse/schema/schema_last_built</b>

### Rebuild the code base

Jeff Webb's avatar
Jeff Webb committed
262
With the Protocol Buffer bindings updated, you can now build the updated code base.
Aaron Bray's avatar
Aaron Bray committed
263
264
265
266

### Regenerate State Data

Any changes to the code base can change various aspects of the data our engine calculates.
Jeff Webb's avatar
Jeff Webb committed
267
268
269
This in-turn has can have an effect on the various state files used in our HowTo examples
(located in the pulse/install/bin/states directory).
If the state files no longer load, or you want to ensure they are up to date with your version of the engine code, regenerate these state files:
Aaron Bray's avatar
Aaron Bray committed
270
271
272
273

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
# On Windows
> run genStates
Aaron Bray's avatar
Aaron Bray committed
274
# On Linux/Mac
Aaron Bray's avatar
Aaron Bray committed
275
276
$ ./run.sh genStates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Aaron Bray's avatar
Aaron Bray committed
277
278
279
280
281
282
283
284
285
286
287
288

### Update Baseline Data

Changes to the code base can also change the Test Suite baseline files.
You will need these new baseline files to pass any tests and ensure any changes do not affect the code base in any negative ways.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~bash
# On Windows
> run updateBaselines
# On Linux/Mac
$ ./run.sh updateBaselines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Aaron Bray's avatar
Aaron Bray committed
289

Aaron Bray's avatar
Aaron Bray committed
290
## Using Pulse
Aaron Bray's avatar
Aaron Bray committed
291

Aaron Bray's avatar
Aaron Bray committed
292
With the code built, visit our [wiki](https://gitlab.kitware.com/physiology/engine/wikis/home) to learn how to execute Pulse and use our SDK to use Pulse in your own application with Pulse.
Aaron Bray's avatar
Aaron Bray committed
293