Calculator Validation and Worked Example Library

Calculator Validation andWorked Example Library

Make every calculation traceable to a defined method, a reproducible reference case and a named implementation version.

Website content • Three editable review worksheets • 48 reference cases • Executable reference library

1. Engineering answer: a calculator needs evidence, not just an answer

A calculator validation and worked example library connects a defined engineering question to documented inputs, reproducible expected answers, controlled error behaviour and a specific software version. It allows a user to see why a result is reasonable and allows a developer to demonstrate whether an implementation produces the intended result. A calculator displaying a plausible number is not sufficient evidence that its units, assumptions, boundaries or decisions are correct.

For Reddy Compressors, this library sits between the individual engineering worksheets and their eventual website implementation. It preserves examples that can be repeated after a formula, data importer, interface or export changes. The important record is not simply “tested”; it is which case was run, against which implementation, with which expected result, and what actually happened. This page retains that distinction.

The first issue contains 48 machine-readable reference cases, four detailed worked investigations and a local reference engine. The companion execution report records the outcome of running those cases against that reference engine. It does not certify the live Reddy website, every earlier calculator, a compressor installation or a customer measurement. The value is a usable starting library with visible coverage, rather than an unsupported claim that every function is already validated.

2. The decision owns

Individual tool pages continue to own their engineering purpose and applicability. The fixed map assigns this page the distinct purpose of providing independent reference cases and version history, with a downloadable test-case catalogue.

Use this resource when a calculator is first implemented, when an existing formula changes, when data are imported from another system, when a reported result is disputed, or when a developer hands work to another developer. A successful run should answer a specific question about a defined implementation, not become a reusable general approval badge.

Three activities remain separate. Arithmetic verification checks whether the implemented calculation matches its stated equation and conventions. Engineering validation checks whether that equation and those conventions suit the intended duty. Operational acceptance checks whether the actual installation and evidence satisfy its project requirements. A numerical library supports the first and informs the second; it does not independently perform the third. This distinction prevents a software test from being presented as equipment acceptance or air-quality release.

3. Define the calculation contract before writing a test

Each tool needs a short calculation contract describing what its inputs mean, what quantities it returns, when its equations apply and when it must withhold a result. This contract is not a commercial contract. It is the technical definition against which a software implementation can be assessed. A case without that definition may compare identical numbers that represent different physical quantities.

For a specific-power calculation, for example, define the electrical boundary, airflow basis, pressure and averaging period. For a thermal calculation, identify the liquid, property assumptions and temperature points. For a sample concentration, identify the accepted sample volume and particle band.

The contract should also distinguish a usable zero from an undefined result. Zero temperature difference is meaningful; a zero denominator in a concentration calculation is not. A missing uncertainty value is not an agreed uncertainty of zero. Record the expected response for each condition so that error handling is reviewed as part of the engineering behaviour, not added later as a cosmetic message.

4. Reuse the existing examples without rewriting their history

Their source case numbers remain attached to the new library records.

A source example is not automatically an independent test oracle. When the same person or system creates both the equation and the expected answer, a shared mistake can survive. The practical response is to retain a visible hand calculation, use an alternative arithmetic route where possible, freeze the expected value separately from the implementation, and reserve independent engineering review as a distinct status. This issue uses separately encoded expected outputs; it does not claim independent professional certification.

Do not silently change a historical answer to make a new implementation pass. If an error is found, preserve the earlier case, record the reason for correction and issue a new case revision. Identify calculations or reports affected by the change. Conversely, a difference in displayed decimals alone should not trigger a rewrite when the underlying result is consistent with the stated numerical tolerance and original rounding.

5. Give every case a durable identity and source trail

A case identifier must survive sorting, export, copying and a change of filename. This issue uses A01–A12 for capacity and power arithmetic, B01–B12 for decisions and uncertainty, C01–C12 for thermal calculations, and D01–D12 for sampling, time and comparison rules. Each case has its own revision, input object, expected output, source description, derivation and execution target.

Keep case identity separate from tool identity. One thermal time-weighting example may test a shared calculation component used by several tools, but it does not prove that every consuming tool calls that component correctly. Record the tool relationship and the actual target tested. A passed reference function and an untested website integration must remain visible as different records.

The source trail should identify the relevant document section or method rather than merely a supplier homepage. The supplied benchmark collections are useful reference locators, but their inclusion of manufacturers or technical libraries is not proof of the equations or results in this catalogue. Repeated copies of the same reference index are not independent corroboration. Original source files remain unmodified.

6. Build a small but purposeful range of tests

A useful suite contains more than ordinary positive examples. It challenges the cases most likely to produce a convincing but wrong engineering answer: missing inputs, an inappropriate unit basis, a value exactly at a limit, unequal durations, overlapping events and a result qualified by a less-than sign. These are not decorative edge cases. They are common ways that a calculator can mislead its user even when its main equation is simple.

Select tests by failure consequence and by the distinct branches in the calculation. A water-volume tool needs meaningful period and rollover checks. A pressure tool needs compatible references and timing. A quality tool needs retained qualifiers and evidence states. Do not generate hundreds of nearly identical examples while leaving one important decision branch untested.

A test suite is also not a list of situations in which the software should say no. Include legitimate zeros, equality boundaries and unusual but valid observations. Over-restrictive validation can erase useful evidence. The desired behaviour is to accept inputs that belong to the stated domain and reject or qualify those that do not, with reasons the user can act on.

7. Establish expected answers independently of the implementation

Expected answers should exist before the tested implementation is used to produce its report. For simple cases, retain the arithmetic in the catalogue. For more involved cases, use a separate reviewed reference method and record its assumptions. Do not generate every expected answer by calling the same function being tested and then store the resulting number as proof that the function works.

Alternative routes are especially useful. The unequal-duration specific-power case can be checked using time-weighted mean power divided by time-weighted mean flow, and separately using total electrical energy divided by delivered volume. These routes should reconcile after the necessary factor of sixty is applied. The worked case below shows both paths.

Keep three kinds of evidence distinct: a published rounded example, an independently recalculated reference number, and an actual output from a named software build. Each can be useful, but none should impersonate another. Where the original case gives nine decimal places, a binary floating-point result need not reproduce the exact text string if it falls inside an appropriately documented numerical tolerance. Status labels, units, qualifiers and error codes, however, are not approximate numerical quantities.

8. Test units, reference conditions and measurement boundaries

Units belong to the calculation contract, not only to the screen label. Testing a flow conversion requires the original unit and whether the volume represents actual, reference or another defined condition. Testing pressure requires a declared gauge or absolute basis. A numeric conversion cannot supply an absent atmospheric-pressure measurement or predict a compressor's output at another discharge pressure.

Its equation rescales a stated gas quantity between reference conditions. It does not manufacture an OEM performance correction or prove the compressor meets a different duty. A companion negative case deliberately supplies a gauge basis and must return a controlled hold/error rather than silently treating it as absolute.

Temperature tests make a different distinction. An absolute Fahrenheit reading needs the offset conversion, whereas a Fahrenheit temperature difference uses only the scale factor. The two tests are deliberately adjacent so an implementation cannot apply the same formula indiscriminately. The future units dictionary should supply the shared definitions; this library records whether a particular implementation preserves them.

9. Treat missing, invalid and unusual inputs differently

A missing operand should produce a missing-input response. A negative volume where the selected mode requires a positive accepted volume should produce a domain response. A Boolean value supplied where a measured number is required should produce a type response. An unexpected software exception should fail the test; it should not be relabeled as a successful rejection of invalid data.

Keep the original input available in the execution record. A visible field error does not justify deleting the source row, converting an empty value to zero or overwriting a qualified result. In a production implementation, unaffected valid outputs may remain available while the dependent output is held. The reference engine uses controlled errors to keep this seed implementation small and explicit.

Do not assume that a broad plausibility limit is an equipment limit. A test that rejects zero kelvin checks an equation's mathematical domain. It does not establish a permitted compressor temperature. An input may also be mathematically acceptable but outside a supplier curve's supported range. That second question requires its own applicability check and cannot be closed by the numerical domain test alone.

10. Set numerical tolerances without moving engineering limits

For numerical reference comparisons, this issue uses the explicit rule: absolute(actual − expected) ≤ max(absolute tolerance, relative tolerance × absolute(expected)). The relative term is anchored to the expected reference. Each case stores both tolerances; the seed cases generally use 10⁻⁸ for each. These are software comparison allowances, not claims about instrument accuracy or a supplier's permissible performance deviation.

An absolute tolerance matters near zero. A relative-only comparison against zero has no useful nonzero allowance. For larger quantities, the relative term avoids requiring the same absolute precision across very different magnitudes. Neither setting should be widened simply because a test fails; first determine whether the difference comes from rounding, arithmetic, a changed convention or an actual defect.

The Python documentation describes a related symmetric comparison using the larger magnitude of actual and expected. Compare booleans, strings, nulls, list lengths, field names and decision states exactly. A tiny numerical error and a missing warning are different failures.

11. Keep measurement uncertainty separate from software error

Measurement uncertainty describes limitations in the evidence used to estimate a quantity. Numerical tolerance describes how closely two computations must agree. An instrument uncertainty must not be used as permission for a coding error, and a very small computational difference must not be interpreted as proof that the underlying measurement is precise.

For independent standard uncertainty contributions to a sum or difference, the seed cases use the square root of the sum of squared contributions, followed by the explicit multiplier k. The broader propagation method includes sensitivity coefficients and covariance where relevant. Independence is therefore an assumption of these particular cases, not a default fact for all instruments. [R1; S2, S3]

The library should test correlated models separately before advertising correlated-uncertainty support. This seed engine does not implement a general covariance matrix or statistical confidence calculation. Its independent-sum operation is named accordingly. The supplied case with four standard uncertainties of 0.4 K gives a combined value of 0.8 K and an expanded value of 1.6 K for k = 2. Passing that case proves this calculation branch only; it does not validate a complete uncertainty assessment.

12. Preserve time meaning before integrating or averaging

A time series may contain instantaneous readings, interval means, interval totals or state records. These meanings are not interchangeable. The seed weighted cases start with explicitly supplied interval means and their supported durations. They do not infer a continuous signal between arbitrary samples or extend one reading across an instrumentation outage.

Validate timestamps, timezone, interval ordering and duplicate policy in the eventual importer before passing values to these kernels. A ten-minute observation and a one-minute observation must not receive equal weight merely because each occupies one row. Equally, an unresolved five-minute gap must not be counted as five minutes of zero temperature, zero demand or normal quality.

Coverage belongs with the result. Report the scheduled period, valid observed duration, any explicitly estimated duration and unresolved missing duration. A high valid-data percentage can still miss the one transient that matters. The numerical coverage figure therefore supports review; it does not establish representative sampling or an acceptable process state. Preserve the sequence of events even when a separate view sorts observations for a duration curve or statistical summary.

13. Test the actual decision rule, including equality

A calculator may correctly calculate a value and still apply the wrong acceptance rule. Minimum limits reverse the direction. These are declared worksheet conventions, not universal laboratory or contractual rules.

Include cases exactly at the boundary and immediately on either side. Do not round a value into compliance. Do not apply a numerical test tolerance to the engineering limit. The reference engine uses decimal-input arithmetic for the interval endpoints, preserving the stated inclusive-equality convention for decimal inputs. Its numerical output comparison remains a separate step.

A decision also depends on evidence completeness. A conforming moisture result cannot close a missing oil requirement; a passed performance item cannot erase a failed mandatory item. The seed overall-state case preserves one failure and one hold instead of returning a green overall result. In the eventual application, these statuses should remain visible in the screen, export and issued snapshot.

14. Add property checks and deliberately wrong results

A property check tests a relationship rather than just one answer. For a valid weighted mean, splitting an interval into two equal-valued intervals should not change the result. Reordering non-overlapping event records before sorting should not change their union duration. Increasing a positive numerator while keeping a positive denominator fixed should increase the ratio. Such checks are useful complements to fixed examples, provided the assumptions are stated.

Properties are not universally true without boundaries. Doubling a plant flow does not necessarily double compressor electrical input. A unit round trip does not prove that the original reference conditions were correct. Keep simple mathematical properties separate from physical performance predictions and avoid testing a convenient relationship that the engineering model does not support.

The companion runner includes six deliberately incorrect output challenges. They check that the comparator rejects an unweighted ratio, a wrong temperature-difference conversion, a row-count thermal mean, a hidden overall pass, an incorrect equality verdict and double-counted overlap duration. These are targeted comparator challenges, not exhaustive mutation testing of all software branches. Their actual outcomes are reported separately from the 48 reference cases.

15. Verify import, calculation and export as separate stages

A correct calculation kernel can be connected to an incorrect interface. The screen may send litres per second while the function expects cubic metres per minute. A spreadsheet import may remove leading zeros from an asset ID. An export may drop a less-than sign, the missing-data warning or the revision that makes a result reproducible. These defects require integration cases beyond the local arithmetic suite.

Prepare representative round-trip records containing an ordinary value, a valid zero, a missing value, a qualifier, a time near midnight and a long identifier. Import, calculate, export and re-import the record, then compare meaning as well as digits. Do not regard successful file opening as proof that the evidence survived the transfer.

The supplied JSON catalogue avoids executable formulas and does not evaluate arbitrary expressions. A later CSV or spreadsheet export needs its own handling for text that spreadsheet software could interpret as a formula. Production import limits, access permissions, file-type handling and confidential-data retention require separate implementation tests. They are identified here as obligations, not presented as completed by the reference runner.

16. Version the equation, case, implementation and result separately

One version field cannot describe everything that can change. The engineering method can change while the user interface remains the same. A typo in a case explanation can be corrected without changing its expected answer. A calculation implementation can change while the method and test inputs stay fixed. An execution report must therefore identify the particular combination used.

This issue uses library version 1.0.0 and case revision 1. The execution report records the reference-engine version, execution time, Python environment and SHA-256 hashes of the catalogue and two executable files. A hash identifies a specific file state; it does not establish engineering correctness, professional approval or source authenticity.

Keep earlier issued reports. When a meaningful change occurs, describe whether it changes results, interpretation, eligibility, warning behaviour or presentation. Identify dependent tools and the tests selected for rerun. Do not claim that every historical output must change, but do not assume that a small code edit is harmless. A one-character inequality change can alter an acceptance decision without visibly changing the displayed measurement.

17. Report coverage by behaviour, not by an impressive total

The 48-case count is the size of this seed reference suite. It is not a count of completed website tools. Many other engineering tools require additional cases, supplier data, model assumptions or interfaces that are not represented here.

This issue does not declare all 45 implementations recovered, executed or approved. Maintain a separate tool-coverage register showing which requirements have reference cases, which have actual implementation results and which remain untested. A case may cover more than one shared function, but sharing a function does not prove every user interface is connected correctly.

Show unresolved coverage honestly. A reference result can be ready while browser tests remain pending. A browser interaction can pass while the engineering method is awaiting review. A revised component can pass its local tests while affected downstream exports remain untested. The register should make these differences easy to see without converting every unknown into either failure or success.

18. Diagnose a failed test before changing the answer

A failed numerical comparison is a prompt to investigate, not evidence that the expected result must be wrong. First verify the case identity, revision, units and selected operation. Then reproduce the simplest arithmetic independently. Review rounding, time weighting, state selection and reference conversion. Finally, inspect implementation details or a possible error in the source expectation.

Classify the failure so the right person can act. A field-mapping defect belongs to integration work; an unclear flow basis belongs to the engineering requirement; a stale expected answer belongs to the case register; an unexpected exception belongs to software robustness. Record what failed and what was changed. Avoid a vague “fixed” note that cannot explain why the result is now different.

Retain the failing output before repair. Rerun the affected case and the relevant shared-function cases after the correction. There is no need to reopen every unrelated bookmark or reformat the entire document when one arithmetic branch changes. A focused rerun can be efficient and defensible when the dependency record explains its scope. Unrelated requirements must not be marked revalidated merely because they were present in the same folder.

19. Worked example A: one duty record, two independent arithmetic routes

The first operating interval lasts ten minutes with package input 120 kW and compatible delivered flow 20 m³/min. The second lasts twenty minutes with input 112 kW and flow 18 m³/min. Both describe the same boundary and agreed pressure basis; those assumptions are essential to combining them.

The duration-weighted mean power is (120 × 10 + 112 × 20) / 30 = 114.666666667 kW. Mean flow is (20 × 10 + 18 × 20) / 30 = 18.666666667 m³/min. Dividing the two gives 6.142857143 kW per m³/min. Dividing by sixty gives 0.102380952 kWh/m³.

A second route checks the same result. Electrical energy is 120 × 10/60 + 112 × 20/60 = 57.333333333 kWh. Delivered reference volume is 20 × 10 + 18 × 20 = 560 m³. Energy divided by volume is again 0.102380952 kWh/m³. Multiplying by sixty returns the specific-power value above.

The unweighted arithmetic mean of the two interval ratios, (120/20 + 112/18)/2, is 6.111111111. It is not the aggregate result for the stated duty. Even a duration-weighted mean of those ratios is generally different from the ratio of aggregate energy to volume. The test should therefore compare the intended aggregate quantity, not a superficially similar statistic.

The catalogue also tests Q = 0 separately. A zero-flow observation can be legitimate operating evidence, but P/Q is undefined. The correct software response is to retain the observation and block that ratio, not replace the denominator with a small positive number. Neither successful arithmetic route proves annual efficiency, a guaranteed duty point or customer savings.

20. Worked example B: warmer water does not prove more heat removal

Assume cooling-water flow of 6 m³/h, density 1,000 kg/m³, specific heat 4.18 kJ/(kg·K) and a measured temperature rise of 6 K. These are declared example properties, not a universal fluid specification.

Mass flow is 6 × 1,000 / 3,600 = 1.666666667 kg/s. Heat transferred to that water is 1.666666667 × 4.18 × 6 = 41.80 kW. With the same stated properties, a second case has 3 m³/h and a rise of 9 K. Its heat estimate is 3 × 1,000 / 3,600 × 4.18 × 9 = 31.35 kW. The water becomes warmer across the second case, yet the estimated heat removal is 25% lower.

A software defect that compares only temperature rise could label the second case as improved heat removal. The reference suite instead calculates the actual flow-and-temperature expression. A separate case checks 41.80 kW for two hours: 83.60 kWh thermal. The output name deliberately preserves “thermal”; it must not become electrical savings in the interface.

A companion unit pair checks 104°F = 40°C and a temperature difference of 18°F = 10 K. Applying the absolute-temperature offset to the difference would produce −7.777777778 instead of 10. The deliberate-wrong-output challenge confirms that this error is rejected.

The engineering interpretation remains limited. These calculations do not establish why cooling-water flow fell, whether the exchanger is fouled, whether the thermal duty was steady or whether the liquid remained single-phase. The workbook tests the arithmetic and identifies the evidence needed for a separate diagnosis. A clean numerical result cannot fill missing flow or fluid-property evidence.

21. Worked example C: accepted sample volume and overlapping exposure

A sampling instrument draws 2 L/min during a 25-minute elapsed observation that includes a documented five-minute pause. Accepted active time is twenty minutes, and accepted sample volume is 2 × 20 / 1,000 = 0.040 m³ on the stated basis. Twelve accepted counts therefore correspond to 300 particles/m³ for the specified particle band.

Using all twenty-five minutes would give 0.050 m³ and an apparently lower concentration of 240 particles/m³. The difference comes from an invalid denominator, not a cleaner air system. If a verified sample totaliser already excluded the pause, subtracting it again would be another error. The seed function is explicitly a rate-times-active-time calculation, not a totaliser correction function.

Now consider investigation windows 08:10–08:50 and 08:30–09:00 on the same process path. Their individual lengths are forty and thirty minutes, but their union is only fifty minutes. The overlap must not be counted twice. The catalogue preserves the source windows and the merged 08:10–09:00 interval.

For a screening estimate only, suppose production was 600 units from 08:00–08:30 and 900 units from 08:30–09:00, with uniform production within each interval explicitly assumed. The union overlaps twenty minutes of the first block and all thirty minutes of the second. Potentially associated production is 600/30 × 20 + 900/30 × 30 = 1,300 units.

That calculation is not a finding that 1,300 units are contaminated, rejected or released. It is a traceable screening count under a stated timing model. Product disposition and the investigation's technical conclusion remain separate. The actual application must also prevent overlapping production records from creating a second form of double counting.

22. Worked example D: exact decisions and approximate arithmetic are different

The interval is 124–126. Under the declared optional rule, its upper endpoint equals the permitted maximum, so the comparison is conforming. A program using a strict less-than test would return the wrong decision. This decision string must match exactly.

Now compare two purely numerical computations. Expected output is 100; actual output is 100.00000005; absolute tolerance is 0.000001 and relative tolerance is 0.00000001. The allowed error is max(0.000001, 0.00000001 × 100) = 0.000001. The difference is approximately 0.00000005, so the numerical comparison passes. This says nothing about a physical acceptance limit.

Near zero, expected output is 0 and actual output is 0.0002 with absolute tolerance 0.0001 and the same relative tolerance. The permitted error is 0.0001, and the case fails. Increasing the tolerance solely to hide the mismatch would make the reference test less useful.

Finally, a fictional overall assessment contains one conforming item, one nonconforming mandatory item and one mandatory hold. The correct aggregate status is not fully accepted, with the failure and hold counts visible. A numeric test can pass while this aggregation fails; they are different behaviours requiring different checks.

The companion runner executes these distinctions. Its separate incorrect-output challenges deliberately alter an equality verdict and an overall status to verify that exact-state comparison catches them. They do not demonstrate that a production application has already implemented the same rules or that a professional acceptance decision has been issued.

23. Editable worksheet A: reference-case definition

Use this worksheet before adding a case to the controlled catalogue. Enter one clear engineering purpose and enough information to reproduce the expected result without access to an undocumented working spreadsheet. Where the reference comes from an existing RC page, retain its original case number and section alongside the new library ID.

The expected response may be a number, a structured set of outputs, a qualifier, a decision state or a controlled error. State which is intended. Do not force an invalid-domain case to contain a numerical answer merely to make every row look alike. Include the observation that would distinguish a valid result from an attractive but wrong one.

The entry remains draft until its expected answer and applicability have been reviewed under the project's chosen process. “Draft” is not the same as unusable: it means the user can see what has been prepared and what remains to be checked. The seed catalogue's provenance field identifies new explanatory cases without suggesting that they were recovered from actual plant measurements.

24. Editable worksheet B: execution and defect record

An execution record links a fixed case revision to a fixed implementation. Record the exact build or code identity and retain the actual output. A screenshot can help document presentation, but structured values and error states are needed to reproduce the comparison. Separate a reference-engine run from a browser, spreadsheet or service integration run.

When a test fails, describe the mismatch and the requirement it affects. Record the corrective change and the subsequent rerun. Do not overwrite the failing observation with the successful one. The history explains whether an earlier release contained an error and which outputs may need review.

The companion report automates part of this worksheet for the local reference engine: case ID, actual output, controlled error, unexpected exception and pass/fail outcome. It also records code and catalogue hashes. Approval, domain review and downstream impact remain human-controlled fields; they are not automatically completed because a script ran without failure.

25. Editable worksheet C: release, revision and coverage

Use a release record to state exactly what is being made available. A reference catalogue can be released for developer use before a public calculator is ready, provided that the difference is explicit. The release must identify its files, versions, tested target, known limitations, unresolved obligations and next owner.

For a later production release, add evidence from the actual implementation: supported browsers or interfaces, imports, exports, error messages, accessibility and the engineering scenarios required for that tool. Retain the reference execution separately so its scope remains clear. A changed public page must not inherit a previous pass merely because its page ID is unchanged.

A release decision should be understandable without reading every test line. It should state what passed, what was not run, what failed and what was accepted only with conditions. Any exception needs an accountable rationale. The worksheet does not authorise publication, equipment operation, supplier messages or customer-data sharing.

26. Practical questions about calculator evidence

Does a worked example prove the whole calculator is correct?

No. It demonstrates a particular input-and-rule combination. A calculator also needs tests for units, invalid inputs, boundary decisions, data import, output presentation and changes in operating assumptions. The case record should explain the behaviour covered rather than turn one successful number into a general guarantee.