|
|
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.
|
|
|
|
|
|
License Requirements
|
|
|
--------------------
|
|
|
|
|
|
All submissions must follow the existing Pulse [LICENSE](https://gitlab.kitware.com/physiology/engine/blob/master/LICENSE) and will be distributed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). See the accompanying [NOTICE](https://gitlab.kitware.com/physiology/engine/blob/master/NOTICE) file for details.
|
|
|
|
|
|
Getting Started
|
|
|
--------------------
|
|
|
|
|
|
Prior attempting to extend Pulse, we highly recommend you review and understand the [Common Data Model](https://pulse.kitware.com/_c_d_m.html) and its [structures](https://pulse.kitware.com/_c_d_m_tables.html), as well as the [Pulse interface](https://pulse.kitware.com/physeng.html).
|
|
|
|
|
|
We also recommend you experiment with the C++ SDK Project!<br> To get a SDK environment up, check out the [Pulse SDK wiki](https://gitlab.kitware.com/physiology/engine/wikis/Using%20the%20pulse%20sdk)<br>
|
|
|
|
|
|
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](https://pulse.kitware.com/_circuit_methodology.html)
|
|
|
- [System Overview](https://pulse.kitware.com/_system_methodology.html)
|
|
|
- The system methodology you are adding functionality to
|
|
|
- Such as the [Cardiovascular System](https://pulse.kitware.com/_cardiovascular_methodology.html)
|
|
|
|
|
|
If you would like help scoping or reviewing your approach you can post to the [discourse channel](https://discourse.kitware.com/c/pulse-physiology-engine) or contact us directly by email at [kitware@kitware.com](mailto:kitware@kitware.com). We are also happy to hear suggestions on how to improve this document or any templates we are providing.
|
|
|
|
|
|
Process:
|
|
|
|
|
|
### 1. Clone the repository
|
|
|
|
|
|
### 2. Branch the repository
|
|
|
|
|
|
### 3. Review Existing Methodology
|
|
|
|
|
|
Review the existing [Pulse methodology documentation](https://pulse.kitware.com/_system_methodology.html) 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](https://pulse.kitware.com/citelist.html).
|
|
|
|
|
|
### 4. Complete the Design using our [Design Template]() as a guide
|
|
|
|
|
|
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 Model](https://pulse.kitware.com/_c_d_m.html)and 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](https://pulse.kitware.com/_respiratory_methodology.html#respiratory-dataflow)) and circuit diagrams ([example respiratory circuit](https://pulse.kitware.com/_respiratory_methodology.html#respiratory-features)). See the [How to update the documentation](https://gitlab.kitware.com/physiology/engine/wikis/Updating%20Documentation) 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](https://pulse.kitware.com/_c_d_m.html) and remain cognizant of how to interface with it through the [API](https://pulse.kitware.com/physeng.html). 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](https://pulse.kitware.com/events.html), [errors](https://pulse.kitware.com/errors.html), and [irreversible states](https://pulse.kitware.com/irreversible.html) 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](https://pulse.kitware.com/_cardiovascular_methodology.html). 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](https://gitlab.kitware.com/physiology/engine/blob/master/test/validation/SystemValidationData.xlsx). You should use empirical data with references wherever possible, with the next best option leveraging subject matter expertise.
|
|
|
|
|
|
If you have any questions about how to answer the questions in the [Design Template](), please reach out to us via the [discourse channel](https://discourse.kitware.com/c/pulse-physiology-engine) or contact us directly by email at [kitware@kitware.com](mailto:kitware@kitware.com).
|
|
|
|
|
|
### 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 modify a system](https://gitlab.kitware.com/physiology/engine/wikis/Modifying%20a%20System)
|
|
|
* [How to create a new action](https://gitlab.kitware.com/physiology/engine/wikis/Creating%20an%20Action)
|
|
|
* [How to create a new condition](https://gitlab.kitware.com/physiology/engine/wikis/Creating%20a%20Condition)
|
|
|
* [How to add a new patient parameter](https://gitlab.kitware.com/physiology/engine/wikis/Adding%20a%20patient%20parameter)
|
|
|
|
|
|
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](https://gitlab.kitware.com/physiology/engine/-/blob/master/src/cpp/cpm/physiology/Nervous.cpp).
|
|
|
|
|
|
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](https://gitlab.kitware.com/physiology/engine/wikis/Creating%20a%20Unit%20Test) 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](https://gitlab.kitware.com/physiology/engine/wikis/Creating%20a%20Scenario) 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](https://gitlab.kitware.com/physiology/engine/wikis/Test%20Suite) and evaluate the results. More details can be found on the [How to perform verification and validation](https://gitlab.kitware.com/physiology/engine/wikis/Verification%20and%20Validation) page. If the scenarios in the test suite do not pass, you will need to reach out to our team via the [discourse channel](https://discourse.kitware.com/c/pulse-physiology-engine) or contact us directly by email at [kitware@kitware.com](mailto:kitware@kitware.com) 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](https://gitlab.kitware.com/physiology/engine/wikis/Updating%20Baselines) to complete this process. Prior to rebaselining, we encourage you to reach out to our team to review your changes.
|
|
|
|
|
|
### 6. Documentation
|
|
|
|
|
|
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](https://gitlab.kitware.com/physiology/engine/wikis/Updating%Documentation) for tips on making these changes.
|
|
|
|
|
|
You should also create a How To in the [Pulse SDK](https://gitlab.kitware.com/physiology/engine/wikis/Using%20the%20pulse%20sdk) 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. |
|
|
\ No newline at end of file |