Source code documentation
The pyplan application consists of following Python files:
- pydplan_main.py
- pydplan_classes.py
- pydplan_plot.py
- pydplan_profiletools.py
- pydplan_buhlmann.py
- pydplan_bars.py
- pydplan_heat.py
- pydplan_table.py
They have the following purpose:
| file | purpose |
|---|---|
| pydplan_main.py | the PyQt5 GUI defined here, call this module to start the app |
| pydplan_classes.py | major classes used by the app |
| pydplan_plot.py | PyQt5 plotting functions, custom widgets using QPainter() |
| pydplan_profiletools.py | the calculation of dive profile |
| pydplan_buhlmann.py | Buhlmann model |
| pydplan_bars.py | code that implements the tab “Bars” panel |
| pydplan_heat.py | the heat map plotting |
| pydplan_table.py | TABLE view plotting |
modules
pydplan_main.py
class pydplan_main(QMainWindow) implements the main window of the application GUI. All of the UI widgets that are used to configure something are here.
The widgets connect to a few callback handlers, but the most important one is drawNewProfile(), which recalculates the Buhlmann model using the configured dive profile.
The drawNewProfile() calls:
- calculatePlan(divePlan), which executes the dive profile
The object pydplan_main.divePlan of class DivePlan() contains all the data of a dive profile and the Buhlmann model states that are calculated for the profile.
- pydplan_main.divePlan.profileSampled is a Python list that stores the dive profile into objects of
- class DiveProfilePoint()
- pydplan_main.divePlan.model is a Python list that stores the calculated Buhlmann model states throughout this profile into objects of
- class ModelPoint(), with tissue compartment data at each point of the dive profile
pydplan_classes.py
Major classes used by the app.
pydplan_plot.py
PyQt5 plotting functions, custom widgets using QPainter() to plot the graphical views to data.
pydplan_profiletools.py
This module executes the dive itself. It has no dependencies to the user interface, and could be used by any kind of UI, and so is reusable for implementing any kind of UI, even a command line application.
The most important function is the calculatePlan(divePlan), which executes the dive profile and calculates the Buhlmann model using the configured dive profile. This function contains a state machine where the divephase variable contains the current state of the dive.
calculatePlan(divePlan) calls model.calculateAllTissuesDepth(), which calculates the next Buhlmann model state.
pydplan_buhlmann.py
This module contains the Buhlmann model objects, coefficients and methods of calculating the model state. It has no dependencies to any other module, except Python built-in math and copy. It could be reused in other applications as such.
calculateAllTissuesDepth() method calculates the next Buhlmann model state to the initial model state, given:
- modelUsed: the model coefficients list to be used in calculation
- beginDepth: depth in meters at begin of the segment calculated
- endDepth: depth in meters at end of the segment calculated
- intervalMinutes: minutes of exposure of the segment
- heliumFraction: fraction of Helium, 1.0 = 100%, 0.0 = no helium
- nitrogenFraction: fraction of Nitrogen
- gfNow: gradient factor for ceiling calculation
calculateAllTissuesDepth() actually calls calculateAllTissues(), by just converting the depths to pressures. That function then calculates for all tissue compartments the new Nitrogen and Helium pressures by calling compartment.calculateCompartment() for each tissue compartment.
calculateCompartment() method calculates new Nitrogen and Helium pressures during an exposure interval to a single tissue compartment.
- when pressure (depth) is changing during an interval, as in descent or ascent, then newPressureSchreiner() is called, which is an implementation of a Schreiner equation
- when pressure (depth) is constant during an interval, as at bottom or in deco stop, then a simplified Haldane or the instantaneous equation is used. This is basically same as Schreiner but reduced to speed up calculation.
class Buhlmann() contains the coefficients for the Buhlmann decompression models “ZHL16a”, “ZHL16b”, “ZHL16c” The coefficients are generated by a separate Python script from text copied from source literature.
pydplan_bars.py
Code that implements the tab “Bars” panel.
pydplan_heat.py
The heat map plotting widget.
pydplan_table.py
TABLE view plotting functions.