Repository navigation
DrillPyze 1.0.0
First stable release of DrillPyze, an open-source simulator of coupled axial–torsional drillstring dynamics. It is meant for teaching and for research in drilling dynamics and drilling automation.
The model runs faster than real time. You drill from an interactive driller's display: change the set points and watch the string respond, from the top drive down to the bit.
- Try it in your browser: https://romanshor.github.io/DrillPyze/lite/ (nothing to install; it also runs on a phone)
- Full-screen demo: https://romanshor.github.io/DrillPyze/lite/#demo
- Documentation: https://romanshor.github.io/DrillPyze/ (model derivation, physics specification, API reference)
- Changelog: CHANGELOG.md
What's in 1.0
Coupled drillstring model
- Axial and torsional wave propagation along the full string, solved by the method of characteristics on the drillstring's own sections.
- Soft-string friction along a 3-D well path from a survey, with axial–torsional coupling at the bit and in the along-string friction. The friction coupling can be switched off.
- Three bit models: Coulomb, cutting (Detournay & Defourny), and regenerative (Richard, Germay & Detournay). Rock strength comes from the formation or from Caicedo, Calhoun & Ewy.
- Fluid and material (Kelvin–Voigt) damping, effective up to 10 Hz.
- Top-drive controllers: stiff, SoftTorque, Z-Torque and custom, after Aarsnes, di Meglio & Shor (2018).
- A PI autodriller and ramped set points.
- New: mud motor. A positive-displacement motor between the string and the bit, after Nguyen et al. (2017):
- Speed: set by the motor constant (rev/gal) and the flow, with optional slip and bypass.
- Torque: T = K_T (Δp − Δp₀), with K_T = η / (2π k_n).
- Stall: above the stall differential the bit stops, and the jump shows in the standpipe pressure.
- Reactive torque on the string: in slide drilling the toolface turns left as WOB rises.
- Off by default: cases without a motor give exactly the 1.0.0a1 results.
Hydraulics and temperature
- Steady circulating losses (Introduction to Drilling Engineering, ch. 7).
- A transient drift-flux model for SPP, bottomhole pressure, ECD and flow out (Wang et al. 2023). It includes surge and swab, and the motor differential in series with the bit nozzles.
- A wellbore temperature model for the mud, the string and the formation.
Interactive simulator (drillpyze-ui, or DrillPyze Lite in the browser)
- Driller's display:
- set points you drag on the dials;
- surface and downhole readings, pump and mud-weight/ECD bars;
- a mud-motor flag, a toolface dial with orient buttons and stall warning, and an off-bottom SPP marker.
- Logs and views:
- log tracks with clock time, shared scales and per-curve limits;
- along-string views of RPM, torque, tension and temperature, plus the well path.
- Case editor: SI and field units, case save and load, and CSV export of results.
- New: phone layout. The inputs fold away, the dials sit two to a row, one along-string view shows at a time, and the log shows two tracks per page that you swipe between.
- New: demo mode (button, or a link ending in
#demo). The dials fill the screen, and the plots are pages below and to the right.
DrillPyze Lite
- The same simulator in pure JavaScript, running in a Web Worker in the browser. It runs at about 20–30× real time.
- It is built from the written physics specification (
docs/spec, now revision 3). - The test suite checks that it matches the Python model to round-off, including runs with the mud motor.
- The hosted site counts anonymous visits with GoatCounter, without cookies.
Changes since 1.0.0a1
- Mud motor: physics spec revision 3, derivation §6.4, the Python model, DrillPyze Lite and the UI.
- Phone layout and full-screen demo mode for the simulator.
- Anonymous visit counts on the hosted DrillPyze Lite.
- README references: added Wang et al. (2023), Nguyen et al. (2017), the Introduction to Drilling Engineering hydraulics chapter, Detournay & Defourny (1992), Richard, Germay & Detournay (2007), and Caicedo, Calhoun & Ewy (2005).
- Model derivation: fixed the typesetting of equation (5.2).
- CI: a single Tests check for branch protection.
Compatibility
- New outputs:
Simulation.latest()addsomega_motor,dp_motor,motor_stalledandtoolfacewhen a motor is present. The recorded channels addomega_motor,dp_motorandstator_angle, which are zero without a motor. - Old case files load unchanged; a case without a
motorentry means no motor. - Python: 3.10–3.12.
Install
git clone https://github.com/romanshor/DrillPyze.git
cd DrillPyze
pip install -e ".[ui]"
drillpyze-ui # opens the simulator at http://127.0.0.1:8050Citing
If you use DrillPyze in your work, please cite it; see CITATION.cff or the Cite this repository button on GitHub. This release is archived on Zenodo: https://doi.org/10.5281/zenodo.24289880