TheTechIdea OilGas - User guide Developer guide →

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.