Training toolbox
The TheTechIdea.OilGas.Training package. Settings: toolboxes.training in the environment.
Scenarios: exercises as data files
A scenario is one exercise: a well shown on the existing well views as evidence, questions about it, and the answer key - a single JSON
file written by an instructor, named <anything>.scenario.json. Well files can sit beside it as plain .json. Comments and trailing
commas are allowed.
{
// an instructor writes this; nothing here needs code
"id": "tops-01", // unique across all scenario files
"title": "Pick the top of the Upper Sand",
"course": "Log interpretation", // optional
"level": "basic", // optional, free text
"depthUnit": "m", // the unit the well is drawn in: "m" or "ft" (see below)
"instructions": "Use the logs to pick the top of the Upper Sand formation.",
"well": "well.json", // the well the trainee sees (a well model file, relative to this file)
"solutionWell": "well-solution.json", // optional: the same well with the answer visible, shown after answering
"questions": [
{ "id": "q1", "type": "depth", "prompt": "Depth of the top of the Upper Sand?", "points": 4,
"unit": "m", "correctValue": 2450, "tolerance": 10, "partialTolerance": 30,
"hint": "Look for the gamma ray break.", "hintPenalty": 0.25,
"explanation": "The gamma ray drops at 2450 m." },
{ "id": "q2", "type": "choice", "prompt": "Which curve shows it best?",
"options": [ { "id": "gr", "text": "Gamma ray" }, { "id": "cal", "text": "Caliper" } ], "correctOption": "gr",
"correctFeedback": "Yes - the shale / sand contrast." },
{ "id": "q3", "type": "multi", "prompt": "Which intervals are sands?", "scoring": "partial", "points": 2,
"options": [ { "id": "a", "text": "A" }, { "id": "b", "text": "B" }, { "id": "c", "text": "C" } ], "correctOptions": [ "a", "c" ] },
{ "id": "q4", "type": "number", "prompt": "Net-to-gross?", "unit": "v/v", "correctValue": 0.6, "tolerance": 0.05 }
]
}
The trainee's well must not give the answer away. That is why the well and the solution well are separate files: the trainee's well carries the evidence (strings, logs, pressures), the solution well the same plus the answer (the formation top, the failed barrier element). Validation flags a solution identical to the trainee's well.
Question types and how they score
| Type | The trainee gives | Scores |
|---|---|---|
choice |
one option | all the points for the right one, none otherwise |
multi |
any options | exact (default): all points only for exactly the right set. partial: (right picks - wrong picks) / right options, never below zero |
depth |
a value and a unit | all points within tolerance of correctValue (the answer is converted to the question's unit, so 8 039 ft is 2 450 m). With partialTolerance, points fall linearly to zero at that distance; without it a miss earns nothing |
number |
a value (and unit) | as depth, for any quantity |
Scoring is a pure function of the scenario and the answers - the same answers always give the same score, whatever order they are given in.
Unanswered questions score zero. Each hint a trainee uses costs the question's hintPenalty fraction of its points (default 0: hints are
free), never taking it below zero. An answer for a question the scenario does not have is an error, never ignored. Feedback is the
author's correctFeedback / incorrectFeedback, or a default text (translatable through the environment's labels:
training.correct, training.incorrect, training.partlyCorrect, training.notAnswered); the explanation is shown after answering.
Loading and checking
Scenario.Load(path) reads one file; ScenarioLibrary.Validate(scenario) lists every problem - a missing or unknown correct option,
fewer than two options, a depth question without a unit, a tolerance missing or a partialTolerance that is not larger, an unknown unit,
duplicate question ids, missing well files. ScenarioLibrary.LoadFolder(folder, problems) loads the *.scenario.json files of a folder and
reports - rather than stopping at - a file that cannot be read, a duplicate scenario id, or an unsound scenario.
toolboxes.training.scenarioFolders lists folders (relative to the environment file); ScenarioLibrary.LoadConfigured loads them all.
The depth unit of the picture
Without depthUnit the picture follows the environment's depth unit, so an exercise that asks for a depth in metres would show a trainee feet.
Set "depthUnit": "m" (or "ft") on a scenario to draw it in the unit its questions use. Validation reports any depth question whose unit
differs from the unit the picture will be drawn in. Pictures are fitted on one page (whatever the well's depth), so they suit a screen.
Showing the well
ScenarioRender.Document(scenario, solution), ToSvg and ToPng draw the scenario's well with the same code as every other well view;
solution: true shows the solution well after the trainee has answered (when there is none, the trainee's well again - there is
nothing more to reveal).
A map instead of a well
A scenario shows one exhibit: a well file, or a map written inline (an exercise with both is refused, and so is one with neither). A map exhibit is a surface gridded from picks, a bubble map, or wells and
places marked on a plan; it is drawn by the same views as every other map, and the questions are the same four types - except that a map has no well to read a depth off, so a depth question is refused.
"map": {
"title": "Top Alpha - depth below sea level (m)", "valueUnit": "m",
"points": [ { "label": "W-1", "x": 300, "y": 1000, "value": 2443 }, ... ], // the picks a surface is gridded from: none, or three or more
"method": "inverseDistance", "gridX0": 0, "gridY0": 0, "cellSize": 50, "gridNx": 41, "gridNy": 31,
"contourInterval": 25, "indexEvery": 4, // or "targetContours": 10 for the round interval that gives about that many lines
"showLabels": true, "showValues": false, // what the trainee sees ...
"solution": { "showValues": true, "addMarkers": [ { "label": "A-1 pick", "x": 2000, "y": 1000 } ] } // ... and what is added once they have answered
}
bubbles (a value per well, the area of the bubble proportional to it) and markers (wells or places on the plan) take the same point form. The coordinates are metres, and so is the scale bar, whatever the machine's
depth unit is.
State what shapes an answer. The right answer to "how many contour lines are there?" must not depend on the settings of the machine the trainee uses. So the exhibit declares the grid, the method, the contour interval
(or the number of lines to aim at) and the index frequency itself, and validation refuses a contoured surface that states neither contourInterval nor targetContours. Colours, the theme and the language still follow the
environment: they change how the picture looks, not what it says.
Kriging and uncertainty maps. "method": "kriging" grids the picks by ordinary kriging from every pick, with a variogram stated in the exhibit - variogramModel, variogramNugget, variogramSill, variogramRange (metres) - and validation
refuses a kriging exhibit that does not state its sill and range: the trainee's environment may hold another variogram, and with it every answer would change. "uncertainty": true draws the kriging error's standard deviation instead of the surface.
The solution can show the same picks another way: solution.method regrids them (inverse distance, minimum curvature or kriging), solution.uncertainty switches between the surface and its uncertainty, solution.contourInterval sets the interval of a picture whose values are on another
scale, and solution.title captions it - which validation requires whenever the revealed picture is not the one the question showed, since a picture captioned as another would teach the wrong thing (it did, in a first draft of the gridding exercises).
Put the picks on grid nodes. Inverse-distance gridding returns a pick itself on its node and never leaves the range of the data, so the grid's range is exactly the range of the picks and the contour levels - their count, which are index contours - can be worked out by hand. Minimum curvature gives a smoother picture but overshoots the data between picks, so its range is not the data's: use it for a picture, not for an answer that counts contours. Inverse distance does flatten the surface round an isolated pick, so give a surface enough picks that follow one smooth shape.
The trainee's copy has no data. A trainee's page is told that there is a map and its title; the picks, bubbles and values the picture hides are not in what it receives, and the solution picture (solution) arrives only with the
reply to an attempt. valueUnit must be a unit of the environment for a surface (it takes part in interval conversions); for a bubble map it is only a label. As with the sample courses, check every key against the engine it teaches.
The pass mark
toolboxes.training.passMark (a fraction, e.g. 0.7) sets what passes a scenario. There is no default - a pass mark is the training
department's policy - so without one a result reports its score and fraction only (Passed is empty).
Showing a trainee a scenario
A scenario file contains its answers. A front end must show the trainee scenario.WithoutAnswers() - a copy without the answer keys,
tolerances, feedback, explanations and the solution well - and only after the trainee has answered use the full scenario to score and to
show the feedback, the explanation and the solution well. Never hand out the file itself.
Courses
A course is a data file, <anything>.course.json, that groups scenarios in order:
{ "id": "integrity-basics", "title": "Well integrity basics", "description": "...", "passMark": 0.7,
"scenarios": [ "integrity-corroded-joint", "integrity-annulus", "integrity-categories" ] }
CourseLibrary.Validate reports a missing title, no scenarios, a scenario that does not exist or is listed twice, and a pass mark out
of range; LoadFolder / LoadConfigured load the *.course.json files beside the scenarios and report - rather than stop at - broken,
duplicate or unsound files. A course's own passMark overrides training.passMark for that course.
Results
ResultsLedger records what trainees did. Record(trainee, scenario, answers, courseId) scores the answers and keeps them with the
score, the per-question scores and the time (UTC). Because the answers are kept, ResultsLedger.Rescore(attempt, scenario) can score an
attempt again if an answer key was later found to be wrong - the recorded attempt is left as it was, so the correction is a visible
decision. The trainee is whatever identifier the host supplies (a staff number); nothing else about a person is recorded, and nothing is
stored anywhere unless the host saves the ledger (ToJson / FromJson).
Which attempt counts for a course result is toolboxes.training.attemptPolicy: latest (the default - the plainest reading of what a
trainee scored last), best or first. It is the training department's policy, so it is a setting. Course(trainee, course,
scenarios) gives the result: the points of the counted attempts (a scenario not yet attempted counts zero), whether the course is
complete, and whether it is passed - passed means complete and at or above the pass mark (the course's, else training.passMark);
without a pass mark there is no verdict.
Exports are CSV: AttemptsCsv() (a row per attempt), QuestionsCsv() (a row per question of every attempt) and
ResultsLedger.CourseResultsCsv(...) (a row per trainee and course), numbers in the invariant format. Text that would be read as a
formula when the file is opened in a spreadsheet - a trainee identifier starting with =, +, - or @ - is neutralised with a
leading apostrophe.
Sample courses
wellbore-config training-sample-pack <folder> writes nine sample courses: one per toolbox - Reading the schematic (core), Well integrity basics (corroded casing re-rating, annulus MAWOP, integrity categories),
Drilling basics (a build section, hook load), Production basics (Vogel inflow, exponential decline) and Data management basics (duplicate wells, the confirmation principle) - two for mapping: Reading maps (a structure
map, choosing a contour interval, a bubble map) and Maps from wells (where a pick lies along a deviated hole, thickness between two tops, why a well is missing from a map) - and one for coordinate systems: Coordinate systems (UTM zones, a south-orientated grid and the units of a coordinate, the datum under a position) and one for gridding: Gridding (which method for which job, and reading the uncertainty map of a kriged surface). Twenty-one scenarios in all, as ordinary scenario and course files to read,
change and extend. The numeric answer keys were calculated independently and the test suite checks every one against the engine of the toolbox it teaches.
The trainee web app
wellbore-config training-serve <environment.json> [--port 8765] [--bind 127.0.0.1] [--ledger file] runs a small web server and one page: a trainee
types a name or staff number, picks a course, reads the scenario with the well drawn on the views, answers (with an optional hint), submits and
sees the score, the feedback and explanation for each question, the solution picture and their progress in each course. The scenarios come from
toolboxes.training.scenarioFolders; results are saved to the ledger file (default training-results.json beside the environment file) after every
attempt, and reloaded when the server starts. Scoring is done by the same engine as everywhere else - the page only shows questions and sends answers.
Its words come from the label set (training.app.*, and ui.direction = rtl flips the page for right-to-left languages); the page's language and the format of its numbers come from locale.culture, not from the machine the browser is on. wellbore-config validate checks
that the scenario folders exist and hold sound scenarios and courses.
What it protects. It serves only WithoutAnswers() copies of scenarios; the solution picture is sent only in the reply to a submitted attempt. It
listens on this machine only (127.0.0.1) unless you choose another address, and then it warns you. It refuses requests for another host name (DNS
rebinding) and from another web origin, so a page on the internet cannot post results to it, and accepts only JSON, of limited size. The page builds
everything from text (never markup) under a strict content security policy. The result exports - GET /admin/attempts.csv, questions.csv,
courses.csv - are off unless the environment variable TRAINING_ADMIN_KEY is set, and then need it in an X-Admin-Key header (never in the address).
What it does not do. There is no sign-in: the trainee name is typed, not verified, and hints used are reported by the page. It is a practice tool, not an exam. If it must be reached from other machines, put it behind your organisation's sign-in and TLS - it speaks plain HTTP.
Settings of the web app
toolboxes.training.server holds what the web app does when started: port (8765), bind (127.0.0.1), maxBodyBytes (1 000 000), traineeNameMaxLength (64) and resultsFile
(training-results.json, beside the environment file). wellbore-config training-serve reads them, and its --port, --bind and --ledger options override them for one run.