They Gave Me a Broken Manual. I Gave Them a Working System.

Yan Reysak — Mon, 29 Jun 2026 16:43:00 +0000

In April, I received a 60-page manual and a technical specification. The task was to turn them into diagnostic software for gas turbine units. The deadline was one month. There was a promise of a contract.

I created the software on May 30.

111 unit-tests. 130+ calculated parameters. Three operating systems: Windows, Arch Linux, Alt Linux.

But the manual contained roughly ~57 errors. At least, the ones I managed to find. Not just typos. Systemic errors. Arithmetic, mathematical, physical, chemical, metrological and logical errors.

I documented every finding in my developer's journal. Because I was searching for the truth.

The Software

The program performs parametric diagnostics for gas turbine units. It takes about 20 input parameters from sensors - pressures, temperatures, flow rates. In about two seconds, it calculates over 130 derived parameters, generates three diagnostic charts, and outputs a conclusion: the equipment is safe, requires maintenance, or is critical.

Before this, engineers did these calculations manually in Excel. It took hours. And mistakes were common.

The software runs on Windows, Arch Linux, and Alt Linux. I developed it on Arch and packaged it with PyInstaller for each platform.

Tech stack: Python (3.13.5), customtkinter for the interface, matplotlib for charts, pandas and openpyxl for Excel export, fpdf for PDF reports. The core calculation engine is pure Python - for now.

What it produces:

Full diagnostic report (Excel)
Technical passport (PDF)
Three diagnostic charts (PNG)
Equipment health classification (KTS - technical condition coefficient)

The program doesn't just calculate. It validates every input. It catches unit mismatches. It flags physical impossibilities. I built 111 unit tests to verify every formula - because when you're diagnosing industrial equipment, a wrong number is not an option.

The Plan

I started with a 15-day plan:

Days 1–5: Core math engine, validators, unit tests.
Days 6–10: User interface (customtkinter), input forms, result display.
Days 11–15: Reports (Excel, PDF), charts, packaging for three platforms.

The plan helped me stay focused. When the manual started revealing errors, the plan kept me grounded. I knew what was done and what remained.

It took 40 days instead of 15 - but the structure held.

The Hunt for Errors

When the first calculation result didn't match the manual's reference values, I assumed I had a mistake. That's the normal reaction. I checked my code. I checked the formulas. I checked the constants.

Everything was correct.

So I started checking the manual itself.

Error Type 1: Chemistry That Doesn't Exist

In Appendix D, there is a table with chemical formulas for gas components. For normal butane, the formula was written as C₄H₁₂.

That compound doesn't exist.

Carbon has a valence of 4. Hydrogen has a valence of 1. Butane is C₄H₁₀ - four carbon atoms, ten hydrogen atoms. The authors confused it with pentane, which is C₅H₁₂ and appears one line below.

This is high school chemistry. If they get this wrong, what else did they get wrong?

Error Type 2: Physics That Defies Logic

One of the charts in the manual describes the behaviour of a turbine with 30 blades. The polynomial formula for this case had a plus sign before the first term.

When I plotted it, the curve showed that a turbine with 30 blades produced more power than a turbine with 36 blades.

That is physically impossible.

Fewer blades means less gas impact on the rotor, less torque, less power. I consulted thermodynamics textbooks. I checked the physical model. I concluded that the plus sign was a mistake - it should have been a minus.

I changed it. The chart now matches physics. Because I trust physics more than I trust a manual.

Error Type 3: A 70% Discrepancy

One formula calculates a constant component for gas flow. The manual provides a reference value: 0.00331.

When I calculated it using the manual's own input data and the manual's own formula, I got 0.000991.

That's a 70% discrepancy.

I rechecked every input. I rechecked every unit conversion. The result was consistent. The manual's reference value is simply wrong.

As it turned out, this parameter wasn't just calculated incorrectly - it wasn't being used in the current calculations at all. It had been overlooked.

I was subsequently asked to remove this parameter entirely.

Error Type 4: Violating Their Own Rules

The manual clearly states: "For gas with methane content between 95-100%, use coefficients from "Standard"."

The gas contains ~98% methane. So the Standard coefficients must be used.

But in the control example, the authors used coefficients for "Gas No. 1" - a different set, intended for a different methane range.

This affects 47 parameters. Including the surge margin. Surge is a dangerous mode where gas flows backward through the turbine, causing vibrations and potential destruction. A 4% error in surge margin is like navigating a ship through a reef with a map that's 4% inaccurate. You might survive. Or might not.

I added a choice to the software: "Automatic" - follows the manual's own rules, or "Manual" - matches the control example. Because I can't rewrite physics. I can only show the truth.

Tests, Method, and the Search for Truth

111 Unit Tests

Every formula in the core calculation engine is covered by a unit test.

Not because I wanted to be thorough. Because I needed to know the code was correct. When the manual gives you a 70% discrepancy, you can't trust anything. Every formula becomes suspect. Every constant becomes a potential source of error.

I wrote 111 tests. Each one takes a known input, runs the calculation, and compares the result to an independent reference. If the test passes, the formula is verified. If it fails, I investigate.

The test suite runs every time I change the code. It catches regressions. It catches mistakes. It catches the errors I didn't know I was making.

The Verification Protocol

The project also includes a formal verification document. It lists every calculated parameter, the reference value from the manual, and the program's result. For each parameter, it shows the absolute and relative error.

This document proves that the software is correct - or, more precisely, that it is correct relative to the manual.

But as I found, the manual itself was wrong. So the verification document serves another purpose: it identifies exactly where the manual deviates from physical reality.

The Method: Descartes Without the Philosophy

Rene Descartes wrote: "For the search of truth, method is necessary".

He also wrote: "I think, therefore I am". But the more practical translation for engineering is: "I doubt, therefore I investigate".

I doubted the manual. I doubted the reference values. I doubted my own code. Every time I doubted something, I documented it. Every hypothesis was tested. Every conclusion was verified.

When you're working with industrial equipment, you don't have the luxury of assumptions. You need proof.

What I Learned

Trust the physics, not the paper. Test everything. Document your reasoning.

When you're working alone, your only asset is your method. Without a plan, you drift. Without tests, you guess. Without documentation, you forget.

I built 111 tests - because I wanted to sleep soundly at night.

I also learned that a contract matters - not because of the money, but because of the clarity it provides.

About Me

I'm an engineer in the field of steam and gas turbine units. That's my background. That's how I know what a surge margin is, why fewer blades mean less power, and why a chemical formula like C₄H₁₂ is impossible.

I've been programming in Python for about a year. This project was my first commercial product.

During the development, I also learned C and C++. Not because the project required it, but because I wanted to understand how languages work beneath the surface. And because I knew that if the project ever needed more speed, I could rewrite the core in C++.

I learned both during my university exam session. I passed all exams with top marks.

I am still learning C and C++. Because I want to understand how programming languages work at a deep level.

What I'm looking for

I want to work on challenging projects. I want to create - not just follow instructions. I'm open to contracts, team work, or freelance work.

I value freedom and responsibility equally.

If you need someone who can handle both the physics and the code - who can find the errors in the manual and fix them in the software - let's talk.

Open for contracts, freelance, or full-time opportunities.

You can reach me at:

yan.reysak@gmail.com

DEV Community: Yan Reysak