Module 5 · Lesson 5.3
Versions, naming and the handover note
The unglamorous half of the subject, and the half that actually fails.
Why this matters
Everything in this module so far has been about information that moves. This lesson is about information about the information: which version, produced when, by whom, containing what, checked how.
It is the least interesting part of computational engineering and it is where a large share of real problems come from. A model that is right but unidentifiable is not usable, because nobody can establish what it describes.
By the end of this lesson you should be able to
- Say why 'the current model' is not a version
- Write a handover note that lists what was NOT sent
- Design a naming convention that survives being used by other people
- Explain what makes a model reproducible a year later
'The current model' is not a version
On a shared environment the model changes continuously and without announcement. An analysis recorded as having been run against 'the current model on 14 March' cannot be reproduced, because there is no way to establish which state that was.
What makes a model identifiable is an immutable reference: a version number the environment issues, or — if it does not — an exported copy taken at the moment of analysis and kept with the results. The copy is not elegant. It works.
The handover note
A handover note is usually written as a description of what is being sent. It is more useful written as a description of what is not.
A note that says 'attached is the analysis model' tells the recipient nothing they could not see. A note that says the following is doing real work:
- Supports are not carried by this route. The model was analysed with a pin at gridline 1 and a roller at gridline 5.
- Releases are not carried. All beam-to-column connections were modelled as rigid.
- Loads are not carried. The model was analysed under the combinations in calculation sheet 4.
- Results are deliberately not included. Re-run them.
- The model is version 7, exported 14 March, from the analysis in calculation sheet 4.
That note takes five minutes and converts an invented model into a checkable one.
Naming
A naming convention has one job: to let somebody who was not there find the right thing. Three properties matter, and they are all unglamorous.
It sorts correctly. Dates as YYYY-MM-DD; numbers zero-padded. Rev2 sorting before Rev10 has cost more time than it should have.
It carries the discriminating fact. Whatever varies between the files is what the name must contain. If four files differ by load case, the load case belongs in the name, not in a folder somebody will flatten.
It survives other people. A convention only you understand is not a convention. The test is whether somebody who has never seen it can pick the right file on their first attempt.
Reproducibility
A model is reproducible if somebody else can obtain the same numbers from it a year later. That needs five things recorded, and they are the same five whatever the software:
- 1.The model, at an identified version
- 2.The software, at an identified version
- 3.The inputs — loads, combinations, material properties — and where each came from
- 4.The assumptions, particularly the ones that were choices rather than data
- 5.The checks that were run, and what they gave
Module 13 turns this into a model record and a review process. It is worth noticing how much of it is already necessary just to make a handover work.
Worked example
Reconstructing an analysis eighteen months later
Given
- A query arrives about a beam on a completed project
- The model file is found, and it opens
- There is no model record, and three model files exist with similar names
Find
What can and cannot be established
Practice
A handover note lists the five attributes that survive no exchange. If a receiving engineer must otherwise invent each of them, and each invented attribute has a 30 % chance of differing from the sender's intent, what is the probability that all five are guessed correctly?
Practice
Files are named Rev1, Rev2, ... Rev12. How many of the twelve sort into the wrong position under a plain alphabetical sort?
Check yourself
What makes a handover note useful, rather than a formality?
Practice
Files are named Rev01 to Rev12 with zero padding. How many sort into the wrong position alphabetically?
Check yourself
What makes a model reproducible a year later?
Check yourself
A shared model environment issues no version numbers. What is the workable answer?
Check yourself
What is the strongest test of a naming convention?
Summary
- 'The current model' is not a version — an immutable reference is
- A handover note earns its place by listing what was NOT sent
- A naming convention must sort correctly, carry the discriminating fact, and survive other people
- Reproducibility needs the model, the software, the inputs, the assumptions and the checks
- A model that is right but unidentifiable is not usable
This is educational material. It uses simplified examples to teach principles, and must not be relied on for real design or safety-critical decisions. Module overview and checkpoint