We welcome updates, modifications, and new functionality to Pulse and hope users will contribute improvements back for the benefit of the community. All code committed to Pulse has to conform to agreed-upon standards and will be rigorously tested on many platforms before it can be merged into the Master and be included in a release. Your contribution will be recognized as part of the release process.
These step-by-step instructions layout the mechanics of submitting work for inclusion into Pulse and having it tested and, eventually, merged into Pulse. We enacted this contribution process to prevent unintended negative consequences to the overall codebase.
We also recommend you experiment with the C++ SDK Project!
To get a SDK environment up, check out the Pulse SDK wiki
Finally, prior to adding a model or modifying an existing model, we recommend you understand the how Pulse works and in particular the system you are proposing to modify. You can do this by reviewing the following pages:
- Circuit Methodology
- System Overview
- The system methodology you are adding functionality to
- Such as the Cardiovascular System
If you would like help scoping or reviewing your approach you can post to the discourse channel or contact us directly by email at email@example.com. We are also happy to hear suggestions on how to improve this document or any templates we are providing.
1. Clone the repository
You can clone the repository and find build instructions for the Pulse Physiology Engine on the main page.
2. Branch the repository
3. Review Existing Methodology
Review the existing Pulse methodology documentation related to your new model to understand how things are currently designed and implemented and how your work fits. You should also perform a literature search to find equations and data. Details from applicable literature these documents will be needed later to add as references for methodology documentation later and will end up in the citations list.
Design Template as a guide4. Complete the Design using our
The design template outlines steps for design, including identifying the needs and requirements of the model, noting existing models, reviewing the models available in Pulse, developing/identifying equations and parameters values required for your model, determining the required interfaces with other systems in Pulse, identifying what parameters should be in the Common Data Modeland which should be in the physiology methodology, identifying validation data, and creating scenarios for testing.
You should take into account fidelity considerations and use realistic mechanistic (causal) pathways whenever possible to maintain Pulse extensibility. Assumptions and limitations should also be documented. As with all well-managed tasks, risks should be taken into account with mitigation strategies.
At this stage, you should generate or update the data flow diagrams (example respiratory diagram) and circuit diagrams (example respiratory circuit). See the How to update the documentation page for details on where to find existing data flow diagrams and circuit diagrams.
In addition to the computational physiology, you will also need to design how your new model fits within the Pulse data model framework and remain cognizant of how to interface with it through the API. Think carefully about how the user will use your model, including specifying the injury, illness, or treatment level. For example, hemorrhage is currently specificied with a location (compartment) and rate, tension pneumothorax is specified with a location (right/left) and a severity. Be sure to think through what events, errors, and irreversible states you will want to include Also, consider whether you are implenting a patient condition, which is implemented before the final patient stabilization, or an action, which is implemented during the simulation (after stabilization).
We recommend creating a validation table or matrix, such as those shown in the Cardiovascular System. It is best to determine your validation data as a target before beginning any implementation. Ask yourself: What are the measurable physiological outcomes (at the spatiotemporal and/or organizational level) relevant to Pulse? You should include any expected healthy homeostatic values (added to the system validation data spreadsheet. You should use empirical data with references wherever possible, with the next best option leveraging subject matter expertise.
5. Implement your model
After you have completed the design template, you should begin implementing your changes. Depending on the type of model you are implemented, review the suggestions in the followng pages.
- How to extend a system
- How to create a new action
- How to create a new condition
- How to add a new CDM parameter
You may also add functionality that is only accessed internally to the engine. This means that the user can not manually trigger the function via the API. Feedback mechanisms are a good example of this. These are standard C++ functions within a system. For an example of this, see the Baroreceptor Implementation.
Before you begin writing new code to add a new model to Pulse, we recommend following the design process below. Most of the results from following this approach will be used later to complete methodology documentation updates.
5. Verification and Validation
After you have implemented you model updates and additions, you should validate the components. We use unit/component tests and scenarios to validate components. Often, creating unit tests for your individual model or components therein will help speed-up development by eliminating other potential sources of error and allowing for targeted calibration of feedback mechanisms. Unit tests should also be added to the codebase for continuous automated testing. See How to create a unit test for tips on how to do this.
If you are creating or modifying a condition, action, or system, you will want to create scenarios to test these components. We use multiple scenarios to test the range of severities, locations, etc. for each condition and action. See How to create a scenario for tips on how to create these scenarios.
Due to the interconnected nature of the Pulse Physiology Engine, you may effect other functionality in the engine. To evaluate these results, you should run our Test Suite and evaluate the results. More details can be found on the How to perform verification and validation page. If the scenarios in the test suite do not pass, you will need to reach out to our team via the discourse channel or contact us directly by email at firstname.lastname@example.org to determine if the changes are acceptable for the master branch of the repository.
Depending on the results of your verification and validation analysis, you may need to update the baselines for the scenarios. This updates all of the scenario data to set a new "gold" standard. See Updating Baselines to complete this process. Prior to rebaselining, we encourage you to reach out to our team to review your changes.
Pulse has extensive documentation on our methodology, validation, and API. You will need to update the documentation for any changes you have made. See Updating Documentation for tips on making these changes.
You should also create a How To in the Pulse SDK to demonstrate your functionality for other users.
7. Submit a Pull Request
Once you have your new code working as desired, you can submit a Merge Request. We will perform a code review and test the functionality.