Error codes — OGR Slip2D documentation

When OGR Slip2D cannot give a factor of safety, it says why, in a form a program can read as well as a person. A rejected surface carries one of four negative codes in place of its factor of safety, with a failure reason behind it. The admissibility checks, the errors of the operations layer and the MCP server, and the exit codes of the command-line programs follow.

5.5.1Surface error codes#

A surface that has no admissible factor of safety keeps its place among the results, and a negative code is written where its factor would be. How the checks behind −120 and −112 work is explained in Section 3.3.

Table 5.5.1 Codes written in place of the factor of safety of a rejected surface.

Code	Meaning	When
−120	Tensile stress at a slice base	The Tensile Stress Check is on and rejected the surface.
−112	m-alpha below its limit	The m-alpha check rejected the surface: $m_\alpha < 0.2$ on a slice of a method it applies to.
−111	No converged factor of safety	The calculation ended without a converged factor, whatever the reason: the iteration limit, a λ that could not be bracketed or closed, a collapsed $m_\alpha$ or $n_\alpha$ , a mass that does not slide, a surface to which rapid drawdown does not apply… The reason is recorded separately (Section 5.5.2).
−101	Any other rejection	A converged factor rejected by another criterion, such as a Spencer or GLE answer whose interslice thrust is inadmissible, or a surface the checks could not evaluate.

One function gives the code of every rejected evaluation, in this order:

a valid surface that passed the checks has no code;
rejected by the Tensile Stress Check: −120 (tension is tested first, so a surface failing both checks is a tensile rejection);
the checks themselves could not be evaluated: −101;
rejected by the m-alpha check: −112;
no converged factor: −111;
anything else: −101.

Because −111 covers every calculation that produced no converged factor, it is not only a convergence problem: circles whose mass does not slide (zero_driving) and, in a rapid-drawdown analysis, candidates to which the procedure does not apply (drawdown_not_applicable) are −111 too, and the reason tells them apart. A surface rejected before it could be sliced has no result, no code and no row; the census counts it as not sliced.

The codes appear in the Interpret window (Data → Export Raw Data…, whose last column holds the factor of safety or the code; Data → Summary of Invalid Surfaces…; Query → Query Invalid Surfaces, which shows the code of grid centres with no valid surface; and the Surfaces with error code option of the surface filter), and in the MCP tool results_query (views error_codes, invalid_summary, raw_data and filter). The HDF5 results file stores no code: a surface without a factor has no fos attribute and carries its reason (Section 5.4.5).

In OGR Slip2D

The four codes are the constants ERROR_TENSILE, ERROR_M_ALPHA, ERROR_NOT_CONVERGED and ERROR_OTHER, and error_code() is the single mapping used by the raw-data export, the census of the Interpret window and the MCP server.

Source: ogr_slip2d/interpretation.py

5.5.2Failure reasons#

An evaluation that produced no factor of safety has fos = None (never NaN), an error_message written for a person and a reason written for a program: one of the strings below, so that a run can be summarised as "this reason, so many surfaces" without parsing prose. The reason is the reason attribute of a surface in the HDF5 results file and the reason key of a surface in the answers of the operations layer and the MCP server.

Table 5.5.2 Machine-readable reasons why a calculation has no factor of safety.

Reason	Meaning
`no_slices`	The surface produced no slices at all.
`no_shear_strength`	No slice base offers any shear resistance.
`zero_driving`	The total driving moment (or force) vanishes: the mass does not slide, so there is no factor of safety to report. It keeps extremely high factors from being computed when the driving force is very small.
`active_support_exceeds_driving`	Active support alone exceeds the driving moment.
`m_alpha_collapsed`	$m_\alpha$ collapsed towards zero on a slice base.
`n_alpha_collapsed`	$n_\alpha$ collapsed towards zero on a slice base (the analogue in Janbu's methods).
`non_physical_fos`	The arithmetic produced a factor that is not a physical one: zero or negative, or not a finite number.
`not_converged`	The iteration ran out of passes before the factor settled. There is a number, the last iterate, but it is not a converged value; the iteration limit is the setting to look at.
`all_lambda_diverged`	Every sampled interslice ratio λ diverged, leaving no branch to solve on (Spencer, GLE).
`no_lambda_bracket`	The sampled range of λ never changed sign, so the root is not bracketed.
`divergent_at_lambda`	The solution diverged at the λ finally chosen.
`lambda_not_closed`	The bracket on λ was found and refined, but $\|F_f - F_m\|$ is still above the tolerance at the λ returned.
`no_force_bracket`	The force balance of the prescribed-inclination methods (Lowe–Karafiath, Corps of Engineers #1 and #2) found no bracket; what it has is the sampled factor of smallest residual, a fallback, not a solution.
`force_balance_diverged`	That force balance produced no usable factor.
`drawdown_not_applicable`	The rapid-drawdown procedure does not apply to this surface. Not an engine failure: in a search most candidates are like this.
`unsliceable_at_drawdown`	The surface could not be sliced at the drawn-down level.
`envelope_not_converged`	The strength envelope depends on the normal stress, and the stress it was read at never settled on the stress the method resolved, so the factor is not that of the envelope (since v0.1.213).

In OGR Slip2D

The reasons are the REASON_* constants, and ALL_REASONS is the set every method's reason must belong to, so that a new reason cannot be introduced as a loose string. They are deliberately not translated: the interface translates the message where it shows it.

Source: ogr_slip2d/methods/base.py

5.5.3Admissibility checks#

A surface that fails an admissibility check has not failed to compute: its factor converged and is kept, because the searches that steer by the factor of safety need it. The surface is judged inadmissible afterwards and is not reported as the critical one, unless every valid surface is inadmissible; in that case the checks are ignored and the result says so. The verdict is recorded in admissible, admissibility_note and admissibility_reason, with these values:

Table 5.5.3 Admissibility checks, their code and their default.

Reason	Code	Check	Default
`tensile_stress`	−120	Tensile Stress Check: the effective normal stress of the method's own solution on a tested slice base is a tension larger than the material's tensile strength, which is zero except for the two Hoek–Brown models ( $s\,\sigma_{ci}/m_b$ ). Only a percentage of the slices, counted from the toe, is tested (95 % by default), because the slices at the crest are legitimately in tension.	off
`m_alpha`	−112	m-alpha check: $m_\alpha < 0.2$ on any slice at the final iteration (Whitman & Bailey, 1967), with Bishop's denominator, for Bishop simplified, Janbu simplified and corrected, Spencer and GLE. A value below the limit does not by itself mean the factor is wrong; it screens out surfaces whose arithmetic has become untrustworthy.	on
`screen_error`	−101	The checks themselves raised an error, so the surface could not be judged; it is rejected rather than let through (since v0.1.211).	—

Both checks are set in Analysis → Project Settings → Advanced (Tensile stress check with its Percentage of slices, and Check m-alpha < 0.2).

5.5.4Errors of the operations layer and the MCP server#

An operation of ogr_api that fails on purpose raises an OgrApiError with a stable code, a message, a hint where there is one and, sometimes, details. An MCP client receives it as [E_CODE] message Hint: hint; a Python script catches it and reads code, message, hint and details. The codes are stable; the wording of the messages is not. An unknown name always comes with the closest known names (Did you mean …?).

Table 5.5.4 Error codes of the operations layer, the MCP server and the agent bridge.

Code	Raised when
`E_NOT_FOUND`	A handle, id or name that does not exist: a `project_id`, `result_id` or `job_id`, an operation, a file to open; also no model open at all.
`E_INVALID_ARGUMENT`	A value of the wrong type, out of range or not one of the choices, a setting that does not exist; also a relative path when no working folder was given, or several models open and no `project_id`.
`E_CONFLICT`	A valid request that the current model does not allow (a second water table, a factor on a design standard that is not `custom`…); an existing file without `overwrite=true`; unsaved changes, for `project_close` and, in the window, for `project_new` and `project_open`; a window that closed while answering a call.
`E_NOT_CONFIGURED`	The model cannot be analysed as configured; `details["problems"]` lists every reason. Also every call of a server started with `--attach` while no window is open.
`E_BUSY`	Another operation holds the model (after waiting 30 s for it), the window is computing, or the maximum number of jobs is already running.
`E_JOB_FAILED`	A background job failed or crashed; the message carries its error.
`E_INTERNAL`	Default code of the base class; also what the bridge to the window reports for an unexpected exception, with its type and message.
`E_UNAUTHORIZED`	The bridge to the window refused a connection with the wrong protocol or token.

An exception that is not an OgrApiError reaches an MCP client as its type and message, without a code. Over HTTP, the server itself answers 401 to a missing or wrong bearer token, 421 to a Host that is not its own and 403 to a foreign Origin (Section 5.1.11).

In OGR Slip2D

The reader of these messages is very often a language model, and what lets it recover is being told what was wrong and what to do instead; hence the hint, and the suggestions for every unknown name.

Source: ogr_api/errors.py · ogr_api/workspace.py · ogr_gui/agent_bridge.py

5.5.5Exit codes#

Table 5.5.5 Exit codes of the command-line programs.

Program	Code	Meaning
`ogr-slip2d-cli`	0	Success, also when a method found no valid surface.
	1	Project file not found.
	2	Unknown method name, or a usage error.
	3	The project cannot be analysed as configured.
	4	No result for any method.
`ogr-slip2d-mcp`	0	Normal end.
	2	A configuration the server refuses to run with.
	3	The MCP SDK is not installed.

The cases behind each code are listed in Section 5.2 and Section 5.1.3.

5.5.6References#

Whitman, R.V. & Bailey, W.A. (1967). Use of computers for slope stability analysis. Journal of the Soil Mechanics and Foundations Division, ASCE, 93(SM4), 475–498.