Skip to content
Snippets Groups Projects

how to connect to pulse

Last edited by Aaron Bray

The Pulse engine is set of static C++ libraries that are intended to be integrated into an application.

Here we will discuss how setup your application to connect and use Pulse, by walking you though using CMake to setup your application build. While not required for your applications, we encourage you to use CMake for your applications build.

When Pulse is successfully built, it creates an install folder that contains all the necessary files needed to both execute and be integrated into an applications.

Application Execution

When creating a new patient, the Pulse engine requires that the working directory of any application its integrated into contain many of the files and directories from the Pulse install/bin directory. The install/bin directory contains all the necessary data files needed by Pulse. Although some directories and files are listed as optional, it is recommended to have all of the following directories in your application working directory :

  • config : stabilization criteria for conditions
  • ecg : available ecg waveforms
  • environments - Only the standard file is necessary if initializing the engine via a patient file. Other files are optional, but could also be used in a change initial environment condition.
  • nutrition - Only the standard file is necessary if initializing the engine via a patient file. Other files are optional, but could also be used in the consume meal condition.
  • patients - The patient files are provided for you, if you have your own, you do not need these.
  • states - The patient states are provided for you, if you have your own, you do not need these.
  • substances - All files in this directory are necessary for patient creation

When loading a patient state. No files are needed from the disk.

Application Interaction

Pulse is essentially a very dynamic state machine. While you can inject actions at the beginning of any time step, Pulse must calculate the physiological state of our patient at a discrete 1/50 second time step. The integrating application must control simulation time by calling one of the AdvanceSimulationTime methods from their application. Pulse runs much faster than real time, so if your application wants to display data from Pulse in real-time, you need to have a sleep accompany Pulse execution to get timing correct. Also, an instance of Pulse is fully self contained. You can have multiple instances of Pulse in the same process, and on the same thread, and they will not interfere with each other.

Threading

Pulse does have some thread safety, but it is not fully thread safe, but that does not mean you cannot put Pulse in a loop inside a thread.

When using Pulse in a thread inside of your application, you need to follow one simple rule: Do not access Pulse outputs while it is advancing time

This applies to System and Compartments objects. You can get a const pointer to CDM classes that hold the data calculated by Pulse. The data structure being pointed to will be read and written to during advancement of time. For this reason, it is recommended to pull data you need from Pulse, in a method called directly after your application advances simulation time on Pulse. This will also ensure that data you do get from Pulse is consistent with a specific time.

Of course, you may run into issues and thread collisions that we may not have anticipated. If you do, please start a conversation and we will help you out in any way we can.

Application Integration

Pulse provides libraries for integration into the following languages : C++, Java, C, C#, Python

C++

All necessary headers and libraries are provided in the install directory. Headers are copied into the install/include directory, and libraries are located in various directories under the install/lib directory. Debug libraries follow a d postfix naming convention.

C++ applications that use Pulse, will do so by linking to the provided static libs. Simply point your applications build script to these directories. See below on connecting your applications CMake project to Pulse.

Pulse provides a simple CMake configuration file that is used to inform other CMake projects about Pulse and its built components. This file is the PulseConfig.cmake file in the install folder of your Pulse build. By utilizing the find_package command in your projects CMake files, you will be provided CMake variables that specify the location of Pulse headers and libraries (both debug and release).

We will go into more detail into setting up a CMake project using Pulse below.

Java

The Pulse build will generate a install/bin/Pulse.jar that provides many CDM classes as well as a set of classes that allocate, manage and control a native C++ Pulse engine. Simply import this jar into your Java project. The pulse repository also contains a copy of all the 3rd party jars that Pulse is dependent on (Be sure to include those jars to your projects class path). From there simply follow the Java SDK for how to use these classes to manage 1 or more instances of a Pulse engine in your Java application.

There will also be a install/bin/PulseJNI.<dll/so> file. This contains all the JNI needed to bridge the Java/C++ language barrier. The Pulse.jar will automatically load this library. In the future we could make this configurable, but we have not seen an end user need to debug into the code to address shortfalls in the engine. If you do have an issue and the log is not sufficient to solve your problem, we suggest you start a topic on our discourse forum.

See these Java how-to examples using the Pulse Java interface

C

Pulse provides a very basic C interface. This interface is built as a install/bin/PulseC.<dll/so> file. The C methods provided define I/O as string encoded CDM data objects in either JSON or binary protobuf. The primary use of this interface it to provide a thunk layer between our C# and Python API's. It is not intended to be used directly, but it can be as long as you provide valid strigified objects.

C#

Python

Coming Soon

CMake Integration

Pulse is a C++ library that utilizes the CMake build system. We encourage you to use CMake for your application. CMake will provide a consistent system to build and deploy your application on multiple platforms. In the following sections we will discuss and provide CMake configurations and examples for you in writing your own CMake files for a C++ application.

Note that if you have a Java or .NET project you can still utilize CMake as a scripting language to organize files and directories. There is even support to compile and jar Java source code. If you would like to know more about supporting these types of projects with CMake, please start a discussion topic.

CMake Example

Here are the contents of a CMake file that will compile your code and link to Pulse. This does use the find_package method to get information about Pulse. Pulse supports this method by creating a PulseConfig.cmake file that find_package will search for and provide variables associated with Pulse to your CMake files. This file could be used as your sources root CMakeLists.txt file, but in a super build, we will want a different CMakeList.txt file, so we will name this file CustomApplication.cmake in this example

# Create an executable with your code like this:
project(CustomApplication)

set(CMAKE_CXX_STANDARD 17)

set(SOURCE "CustomApplication.cpp"
#          "AnotherFile.cpp"
#          "AndAnotherFile.cpp"
)
add_executable(PulseClient ${SOURCE})

## This is how you connect that executable to Pulse

# Find the Pulse package

# Again, set Pulse_DIR to the install directory with the PulseConfig.cmake file, or make the developer set this when building the code (usually `pulse/install/lib/cmake/pulse`)
find_package(Pulse REQUIRED) # If you don't, CMake will halt here
# You will now have access to all the variables set in the PulseConfig.cmake in the Pulse install directory
# Simply link to the Pulse target defined in the PulseConfig.cmake file
target_link_libraries(PulseClient Pulse::PulseEngine)
# That is it, your program is now using to Pulse!

Superbuilds

Your application is going to have its own code associated with it, in its own repository. At the very least, your project is dependent on Pulse, if not more libraries from different repositories. While you could store specific libraries and binary files of your dependent libraries in your repository, it is inefficient and difficult to maintain various libraries for multiple target platforms. Instead, we will use CMake to connect to the source code of these dependent libraries and build them for each of our target platforms. A superbuild will allow us to organize and build dependent libraries along side your application.

In short, a superbuild operates in 2 phases

  1. Pull and build the code base of any dependent libraries
  2. Build your application code base
    • Since the superbuild build the dependent libraries, it will automatically inform your application project where to get include files and libraries of those dependent libraries.

Note as part of building the dependent libraries, you can use CMake to organize the necessary run-time files (such as dll/so's, configuration and other data files) to be placed into a single working directory for your application so that you can easily package up all files needed for delivery to your end users. This is known as an install, and CMake will create a compiler target to execute the CMake generated install instructions.

More information on superbuilds can be found in the Kitware blog

Example

Here are two files that constitutes a valid superbuild and will leverage the CMake example above that will :

  1. Pull and build code from the Pulse repository * Direct Pulse to install its necessary run-time files into a directory of your choice
  2. Compile your application code * Find the Pulse headers and libraries and inform your project * Build your application code base * Copy any necessary run-time files into the directory of your choice

CMakeLists.txt

This file goes in the root of your source directory and is used to direct the 2 logic flows described above. Note the setting of the variable CMAKE_INSTALL_PREFIX, this variable tells CMake where to put files associated with the install command in both your CMake files, and any depended libraries

cmake_minimum_required(VERSION 3.7)
# Using SOURCE_SUBDIR which was first in introduced in CMake 3.7

# My preference as to where the default install location should be
set(CMAKE_INSTALL_PREFIX ${CMAKE_BINARY_DIR}/install CACHE PATH "Install location")

project(SuperBuild)

# Policy to address @foo@ variable expansion
if(POLICY CMP0053)
  cmake_policy(SET CMP0053 NEW)
endif()
cmake_policy(SET CMP0022 NEW)

# A useful macro to install headers to a specified location
MACRO(install_headers SRC_DIR DEST)
  file(GLOB_RECURSE HEADER_LIST 
    ${SRC_DIR}/*.h 
    ${SRC_DIR}/*.hxx
    ${SRC_DIR}/*.inl)
  foreach(HEADER ${HEADER_LIST})
    #message(STATUS "Header at ${HEADER}")
    STRING(REPLACE ${SRC_DIR}/ "" REL_DIR ${HEADER})
    #message(STATUS "Relative Path ${REL_DIR}")  
    set(FULL_LOC ${CMAKE_INSTALL_PREFIX}/include/${DEST}/${REL_DIR})
    #message(STATUS "File should goto ${FULL_LOC}")
    get_filename_component(DEST_DIR ${FULL_LOC} PATH) 
    #message(STATUS "Going to ${DEST_DIR}")
    install(FILES ${HEADER} DESTINATION ${DEST_DIR})
  endforeach()    
ENDMACRO(install_headers)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_POSITION_INDEPENDENT_CODE ON)

# The following code for configuration is to support building/installing multiple build
# configurations to the same build and install directory, helps to integrate better with
# Visual Studio, XCode, and CLion IDE's that support building multiple configurations
set(CONFIGURATION ${CMAKE_CFG_INTDIR})
set(CMAKE_CONFIGURATION_TYPES Debug Release RelWithDebInfo CACHE TYPE INTERNAL FORCE )
# Set any flag specific to any compiler/IDE
if(MSVC)  
# Using MD as that seems to be what I run into alot, you could change these to /MT and /MTd if you want...
  set(CMAKE_CXX_FLAGS_DEBUG "/D_DEBUG /MDd /Zi /Ob2 /Oi /Od /RTC1" CACHE TYPE INTERNAL FORCE)
  set(CMAKE_CXX_FLAGS_RELEASE "/MD" CACHE TYPE INTERNAL FORCE)
  set(CMAKE_CXX_FLAGS_RELWITHDEBINFO "/MDd /Zi" CACHE TYPE INTERNAL FORCE)
  set(CONFIGURATION "$(Configuration)")
endif()
if(MINGW)
endif()
if(APPLE)
endif()
if(UNIX)
  set(CMAKE_INSTALL_RPATH "${CMAKE_INSTALL_RPATH}:\$ORIGIN")
endif()

# Set up install variables and directories for multiple configurations
message(STATUS "Installing to ${CMAKE_INSTALL_PREFIX}")
set(INSTALL_BIN ${CMAKE_INSTALL_PREFIX}/bin)
set(INSTALL_LIB ${CMAKE_INSTALL_PREFIX}/lib)
file(MAKE_DIRECTORY "${INSTALL_BIN}/debug${EX_CONFIG}")
file(MAKE_DIRECTORY "${INSTALL_BIN}/release${EX_CONFIG}")
file(MAKE_DIRECTORY "${INSTALL_BIN}/relwithdebinfo${EX_CONFIG}")
# A useful flag 
if(UNIX AND NOT APPLE)
  set(LINUX TRUE)
endif()

# Create a variable and mark it with CACHE
# This will allow a user to tell our build to use pre-built Pulse libraries
# For Pulse, set it to the Pulse install directory. 
# CMake will look for the Pulse.Config.cmake file there
# If the user does not provide this, our build will download it and build it
# CMake uses variables ending in _DIR when it looks for packages 
# Since we made it a CACHE variable, it will be displayed in the CMake GUI, and stored in the CMakeCache.txt
set( Pulse_DIR "" CACHE PATH "Path to Pulse" )

# Here we switch our build flow
set (SUPERBUILD ON CACHE BOOL "Initial pull and build of all dependent libraries/executables")
if(SUPERBUILD)# This will tell CMake to download and compile dependent libraries
  include(SuperBuild.cmake)
else()# Build your project code, and now it can find the dependent libs
  include(CustomApplication.cmake)
endif()

SuperBuild.cmake

This file describes the external dependencies (Pulse in this example) and how your code base can pull and build a specific version of Pulse for it to link against. Note how we pass variables set in the calling CMake file into the CMake files of the dependent libraries, such as the CMAKE_INSTALL_PREFIX variable!

include(ExternalProject)
include(CMakeDetermineSystem)
project(OuterBuild)

# Pulse builds static libs, but your project does not have to
set(BUILD_SHARED_LIBS OFF)
if(MSVC OR XCode)
# We want the super build to build Pulse in release by default
# This will allow Pulse to properly configure and generate all data necessary for you application
# Note that once, built, we can build Pulse in Debug so you can step into code if you need to
  set(CMAKE_CONFIGURATION_TYPES Release CACHE TYPE INTERNAL FORCE )
endif()
##################################
## Pulse                        ##
##################################

set( Pulse_FOUND FALSE)
if(Pulse_DIR)# If the user provided us a Pulse_DIR, check that it has what we want
  if ( IS_DIRECTORY ${Pulse_DIR} )
    message(STATUS "Looking for your Pulse...")
    find_package( Pulse NO_MODULE NO_POLICY_SCOPE)
    if ( Pulse_FOUND )
      message(STATUS "I found your Pulse!")
    else()
     message(STATUS "I could not find your Pulse!")
    endif()
  else()
    message(STATUS "I could not find your Pulse!")
    set( Pulse_FOUND FALSE)
  endif()
endif()

if(NOT Pulse_FOUND)
  # Pull it and build it if it was not found
  message( STATUS "I am going to download and build Pulse" )
  set(Pulse_VERSION "1.0.0" )
  set(Pulse_DIR "${CMAKE_BINARY_DIR}/pulse")

  ExternalProject_Add( Pulse
    SOURCE_DIR Pulse
    BINARY_DIR Pulse-build
    GIT_REPOSITORY "https://gitlab.kitware.com/physiology/engine.git"
    GIT_TAG v1.0
    INSTALL_DIR "${CMAKE_INSTALL_PREFIX}"
    CMAKE_ARGS
        -DCMAKE_PREFIX_PATH:STRING=${CMAKE_PREFIX_PATH}
        -DCMAKE_INSTALL_PREFIX:STRING=${CMAKE_INSTALL_PREFIX}
        -DCMAKE_BUILD_TYPE:STRING=${CMAKE_BUILD_TYPE}
        -DCMAKE_CXX_COMPILER:FILEPATH=${CMAKE_CXX_COMPILER}
        -DCMAKE_CXX_FLAGS:STRING=${CMAKE_CXX_FLAGS}
        -DCMAKE_C_COMPILER:FILEPATH=${CMAKE_C_COMPILER}
        -DCMAKE_C_FLAGS:STRING=${CMAKE_C_FLAGS}
        ${CMAKE_CXX_COMPILER_LAUNCHER_FLAG}
        ${CMAKE_C_COMPILER_LAUNCHER_FLAG}
        -DCMAKE_EXE_LINKER_FLAGS:STRING=${CMAKE_EXE_LINKER_FLAGS}
        -DCMAKE_SHARED_LINKER_FLAGS:STRING=${CMAKE_SHARED_LINKER_FLAGS}
        -DMAKECOMMAND:STRING=${MAKECOMMAND}
        -DADDITIONAL_C_FLAGS:STRING=${ADDITIONAL_C_FLAGS}
        -DADDITIONAL_CXX_FLAGS:STRING=${ADDITIONAL_CXX_FLAGS}
  )
  list(APPEND CustomApplication_DEPENDENCIES Pulse)
  message(STATUS "Pulse is here : ${Pulse_DIR}" )

endif()

# Now add ourselves to the Super Build


# ExternalProject_Add doesn't like to work with lists: it keeps only the first element
string(REPLACE ";" "::" CMAKE_PREFIX_PATH "${CMAKE_PREFIX_PATH}")

# Generate the Pulse project after dependencies have been built
ExternalProject_Add( CustomApplication
    PREFIX CustomApplication
    DEPENDS ${CustomApplication_DEPENDENCIES}
    DOWNLOAD_COMMAND ""
    DOWNLOAD_DIR ${CMAKE_SOURCE_DIR}
    SOURCE_DIR ${CMAKE_SOURCE_DIR}
    BINARY_DIR ${CMAKE_BINARY_DIR}/CustomApplication
    CMAKE_GENERATOR ${CMAKE_GENERATOR}
    BUILD_AWAYS 1
    LIST_SEPARATOR ::
    CMAKE_ARGS
      -DSUPERBUILD:BOOL=OFF # Change this so we go down the other path in our main CMakeLists.txt
      -DCMAKE_PREFIX_PATH:STRING=${CMAKE_PREFIX_PATH}
      -DCMAKE_INSTALL_PREFIX:STRING=${CMAKE_INSTALL_PREFIX}
      -DCMAKE_BUILD_TYPE:STRING=${CMAKE_BUILD_TYPE}
      -DCMAKE_CXX_COMPILER:FILEPATH=${CMAKE_CXX_COMPILER}
      -DCMAKE_CXX_FLAGS:STRING=${CMAKE_CXX_FLAGS}
      -DCMAKE_C_COMPILER:FILEPATH=${CMAKE_C_COMPILER}
      -DCMAKE_C_FLAGS:STRING=${CMAKE_C_FLAGS}
      ${CMAKE_CXX_COMPILER_LAUNCHER_FLAG}
      ${CMAKE_C_COMPILER_LAUNCHER_FLAG}
      -DCMAKE_EXE_LINKER_FLAGS:STRING=${CMAKE_EXE_LINKER_FLAGS}
      -DCMAKE_SHARED_LINKER_FLAGS:STRING=${CMAKE_SHARED_LINKER_FLAGS}
      -DMAKECOMMAND:STRING=${MAKECOMMAND}
      -DADDITIONAL_C_FLAGS:STRING=${ADDITIONAL_C_FLAGS}
      -DADDITIONAL_CXX_FLAGS:STRING=${ADDITIONAL_CXX_FLAGS}

      -DBUILD_SHARED_LIBS:BOOL=${shared}
      # Let our build know where Pulse is/or is going to be
      -DPulse_DIR=${Pulse_DIR}
)

Note the use of Pulse_DIR in all of the example files. The find_package command looks for a variable named with a _DIR suffix. In defining the Pulse_DIR variable in the root CMakeLists.txt file as a CACHE variable, this allows a user running CMake to generate build files to specify a pre-built Pulse install. The SuperBuild.cmake checks to see if that variable is set, and if it can find Pulse before it downloads a new copy of Pulse to build. This can save the developer time by not needed to always rebuild the same dependencies when they work on several branches. The developer just needs to set this variable to the install directory containing the PulseConfig.cmake file.

You can download a working set these CMake files and some simple code that uses Pulse from here

If you have any questions of comments on connecting to Pulse, start a conversation at our discourse forum

Comments

    Please register or sign in to add a comment.