The .ogr file format

An OGR Slip2D project is one plain JSON file with the extension .ogr: the geometry, the materials, the loads, the supports, every setting and, once computed, the finite-element groundwater field. It can be read, compared and kept under version control like any text file. The results of a search, which can run to thousands of surfaces with their slices, go to a separate HDF5 file. The keys of the first are listed below, followed by the layout of the second.

5.4.1A plain JSON document#

• Encoding. UTF-8, indented with two spaces; non-ASCII characters are written as they are, not escaped.
• Units. Values are stored in SI (m, kN per metre of slope, kPa, kN/m³, degrees), whatever unit system the window displays: units are converted only where the interface shows or reads them.
• Identifiers. Objects carry UUID strings, and references between them use those ids: a material points at its water surface with water_surface_id, a region assignment at its material with material_id.
• Regions are not stored as such. The regions are computed from the external and material boundaries; what the file keeps is each assignment as a point inside a region (region_assignments), which is re-located in the recomputed regions after every geometry change.
• Shared by all components. The window, ogr-slip2d-cli, the operations layer and the MCP server read and write the same file; project_get returns one section of it to an agent (Section 5.1).

Saving writes the whole document, so a file saved by the current version carries every key below; a calculation does not modify the file.

An excerpt#

The beginning of a two-layer slope with a water table, as saved by v0.1.235; … marks lines left out.

{
  "format_version": "0.1",
  "id": "ed1d8a87-0f66-45c7-9027-1d689a44c66f",
  "name": "Two-layer slope with water table",
  "settings": {
    "units": {
      "system": "metric",
      "time": "d",
      "permeability": "m/s",
      "failure_direction": "L2R",
      "system_id": "metric_kpa"
    },
    "methods": {
      "enabled_methods": [
        "bishop_simplified",
        "spencer",
        "gle_morgenstern_price"
      ],
      "num_slices": 30,
      "tolerance": 0.005,
      "max_iterations": 50,
      "interslice_function": "half_sine",
      "interslice_forces": "total"
    },
    …
  },
  "boundaries": [
    {
      "id": "ea9a0c7f-a789-4ec7-84e8-1f58c319e9c3",
      "name": "External Boundary",
      "type": "EXTERNAL",
      …
      "polyline": {
        "id": "d8620e5a-bf0d-45ad-90e8-7cc9a4062aa1",
        "closed": true,
        "vertices": [
          [
            0.0,
            0.0
          ],
          …
  "materials": [
    {
      "id": "9c481951-90f0-4962-93f7-98cb59eae48d",
      "name": "Silty sand",
      "strength": {
        "model_id": "mohr_coulomb",
        "params": {
          "cohesion": 5.0,
          "friction_angle": 32.0
        }
      },
      "unit_weight": 19.0,
      "sat_unit_weight": 21.0,
      "use_sat_unit_weight": false,
      "pore_pressure": "water_table",
      …
  "user_surfaces": []
}

5.4.2Top-level keys#

5.4.3Settings keys#

The meaning of each setting is given where it is set: Section 2.1 for the window, and catalog("settings") or settings_get for the operations layer, which list every setting with its type and options.

5.4.4Versions and compatibility#

Every file carries "format_version": "0.1", the value of FILE_FORMAT_VERSION in the program. The reader does not consult it: an older file is recognised by the keys it carries, a key that is missing takes its default, and a few conventions that changed are converted when the file is read. Those conversions are documented in the code, for example:

• a closed boundary that repeats its first vertex at the end, as every DXF import wrote before v0.1.197, is read without the repeated vertex (the same polygon);
• a rapid-drawdown project saved before the B̄ fields existed (v0.1.62) gets back the behaviour it was computed with;
• a B̄ rapid-drawdown project drawn with the drawdown convention used before v0.1.69 has its water table and drawdown line exchanged, so that the model means what it meant;
• a water pressure grid that also declares its own value type sets the groundwater method accordingly (v0.1.202).

The conversion of v0.1.69 changes, on purpose, the factor of safety of the files it applies to, and the changelog of that version says so. An older version of the program is not guaranteed to open a file written by a newer one.

5.4.5Results in HDF5#

The results of a search are written to an HDF5 file, normally beside the project with the same name and the extension .h5. The window writes the result of the first method after each Compute once the project has a file; ogr-slip2d-cli compute writes one file per method (Section 5.2); a script uses save_results (Section 5.3). Each file holds one search; an existing file is replaced.

Surfaces rejected before they could be sliced are counted in n_valid + n_invalid and n_attempts but have no group, so n_surfaces can be smaller than the number attempted. The file stores one search, not the model: it is read together with the .ogr it came from.