Version Control, Git & Reproducible Engineering

The Engineering Problem

An engineering computation produces a result. Six months later, another engineer asks which code produced it, which inputs were used and whether the result can be reproduced. Without version control, the answer is often a collection of files with names like final.py, final2.py and final_latest_REAL.py. Version control provides the discipline to answer this question definitively.

Why Engineering Code Needs Configuration Control

Engineering code is engineering work product. When it supports a technical decision, it becomes part of the evidence chain. Like any engineering work product, it needs configuration control — a defined version, a record of changes, an ability to reproduce a specific result and a way to trace the code that produced it.

A computational result should be reproducible from a defined code version and defined input data.

Core Version Control Concepts

Version control systems — Git is the most widely used — provide a structured way to manage code changes over time. The key concepts are straightforward and map directly to engineering configuration control.

The Engineering Reproducibility Chain

A computational result is the product of multiple inputs — the code, the input data, the material data, the solver version and the computational environment. All of these must be controlled to make the result reproducible.

Code Commit A × Inputs Rev 3 × Materials Rev B × Solver Version → Result Set R14

If any link in the chain changes, the result may change. Reproducibility requires controlling all links, not just the code.

What to Put Under Version Control

Version control is not just for code. Engineering reproducibility requires controlling all inputs that affect the result.

• Source code — scripts, functions, modules
• Input data files — loads, material properties, geometry parameters
• Configuration files — solver settings, mesh parameters, analysis options
• Documentation — assumptions, methodology, verification records
• Test cases and benchmark results
• Dependency specifications — package versions, environment definition

What Not to Put Under Version Control

Large binary files, solver output files and derived data generally should not be stored in version control. They should be regenerable from the controlled inputs. If they must be stored, use a system designed for large files (Git LFS or equivalent).

• Large binary files — meshes, result databases, images
• Derived data — anything that can be regenerated from controlled inputs
• Temporary files and intermediate results
• Software dependencies themselves — use a dependency file instead

Commit Messages as Engineering Records

A commit message should explain what changed and why. For engineering code, this means documenting what engineering change was made, what the effect on results is and whether verification was performed. "Updated calculation" is not a useful commit message. "Corrected unit conversion in load input — kN to N — re-verified against benchmark case 3" is.

COMMON MISTAKE: Using vague commit messages like "fixed" or "updated". An engineering commit message should describe what changed, why and whether verification was performed.

Versioning Spreadsheets and Scripts

Version control is most natural for text-based code. Spreadsheets and other binary formats are more challenging but not impossible. Where formal Git is impractical, a disciplined naming convention, a change log and a release register provide a minimum level of configuration control. The key principle is that any engineering result should be traceable to a specific version of the tool that produced it.

• Use a naming convention with version numbers — not "final_v2_REAL"
• Maintain a change log describing what changed between versions
• Record which version produced each engineering result
• Keep previous versions accessible — do not overwrite the verified version

Reproducibility

Reproducibility means that another engineer, given the code version, input data and environment definition, can regenerate the same result. This is the ultimate test of configuration control. If a result cannot be reproduced, the configuration control has failed — some input or dependency was not controlled.

ENGINEERING CHECK: Can another engineer reproduce this result from the controlled code and data? If not, the configuration control is incomplete.

Implementation Considerations

Adopting version control for engineering code requires discipline but pays off in traceability, reproducibility and collaboration. Start simple — a Git repository for each project or tool, regular commits with descriptive messages, tags for verified releases.

• Use a repository per project or engineering tool
• Commit regularly with descriptive messages
• Tag verified releases with a version number
• Keep input data alongside code where practical
• Document the environment — Python version, package versions, solver version

Key Takeaways

• Version control is engineering configuration control for computational work
• A computational result should be reproducible from defined code and data versions
• Control all inputs that affect the result — code, data, configuration, environment
• Commit messages are engineering records — describe what, why and verification status
• Reproducibility is the ultimate test — if a result cannot be reproduced, control has failed