Códigos de error — documentación de OGR Slip2D

Cuando OGR Slip2D no puede dar un factor de seguridad, explica el motivo de una forma que entiende tanto una persona como un programa. Una superficie rechazada lleva uno de cuatro códigos negativos en lugar de su factor de seguridad, con un motivo de fallo detrás. A continuación figuran las comprobaciones de admisibilidad, los errores de la capa de operaciones y del servidor MCP, y los códigos de salida de los programas de línea de comandos.

5.5.1Códigos de error de las superficies#

Una superficie sin factor de seguridad admisible conserva su lugar entre los resultados, y en el sitio de su factor se escribe un código negativo. El funcionamiento de las comprobaciones que hay detrás de −120 y −112 se explica en la Sección 3.3.

Tabla 5.5.1 Códigos que se escriben en lugar del factor de seguridad de una superficie rechazada.

Código	Significado	Cuándo
−120	Tensión de tracción en la base de una dovela	La comprobación de tracción (Tensile Stress Check) está activada y ha rechazado la superficie.
−112	m-alfa por debajo de su límite	La comprobación de m-alfa ha rechazado la superficie: $m_\alpha < 0.2$ en una dovela de un método al que se aplica.
−111	El factor de seguridad no converge	El cálculo termina sin un factor convergido, sea cual sea el motivo: el límite de iteraciones, un λ que no se puede acotar ni cerrar, un $m_\alpha$ o un $n_\alpha$ que tiende a cero, una masa que no desliza, una superficie a la que no se aplica el desembalse rápido… El motivo se registra aparte (Sección 5.5.2).
−101	Cualquier otro motivo de rechazo	Un factor convergido que se rechaza por otro criterio, como una solución de Spencer o GLE cuyo empuje entre dovelas no es admisible, o una superficie que las comprobaciones no han podido evaluar.

Una sola función asigna el código de cada evaluación rechazada, siguiendo este orden:

una superficie válida que supera las comprobaciones no tiene código;
rechazada por la comprobación de tracción: −120 (la tracción se comprueba primero, de modo que una superficie que falla en ambas comprobaciones se cuenta como rechazo por tracción);
las propias comprobaciones no se pudieron evaluar: −101;
rechazada por la comprobación de m-alfa: −112;
sin factor convergido: −111;
cualquier otro caso: −101.

Como −111 abarca todo cálculo que no ha dado un factor convergido, no indica solo un problema de convergencia: también reciben −111 los círculos cuya masa no desliza (zero_driving) y, en un análisis de desembalse rápido, las superficies candidatas a las que no se aplica el procedimiento (drawdown_not_applicable), y el motivo permite distinguirlos. Una superficie rechazada antes de dividirla en dovelas no tiene resultado, código ni fila; el recuento la cuenta como no dividida en dovelas.

Los códigos aparecen en la ventana Interpret, en Data → Export Raw Data… (cuya última columna contiene el factor de seguridad o el código), en Data → Summary of Invalid Surfaces…, en Query → Query Invalid Surfaces (que muestra el código de los centros de la rejilla sin ninguna superficie válida) y en la opción Surfaces with error code del filtro de superficies. También aparecen en la herramienta MCP results_query (vistas error_codes, invalid_summary, raw_data y filter). El archivo de resultados HDF5 no guarda ningún código: una superficie sin factor no tiene el atributo fos y lleva su reason (Sección 5.4.5).

En OGR Slip2D

Los cuatro códigos son las constantes ERROR_TENSILE, ERROR_M_ALPHA, ERROR_NOT_CONVERGED y ERROR_OTHER, y error_code() es la única función que convierte un rechazo en su código; la usan la exportación de datos brutos, el recuento de la ventana Interpret y el servidor MCP.

Código: ogr_slip2d/interpretation.py

5.5.2Motivos de fallo#

Una evaluación que no ha dado factor de seguridad tiene fos = None (nunca NaN), un error_message redactado para una persona y un reason para un programa: una de las cadenas siguientes. Así se puede resumir un cálculo como «este motivo, tantas superficies» sin tener que interpretar texto libre. El motivo es el atributo reason de una superficie en el archivo de resultados HDF5 y la clave reason de una superficie en las respuestas de la capa de operaciones y del servidor MCP.

Tabla 5.5.2 Motivos legibles por máquina por los que un cálculo no da factor de seguridad.

Motivo	Significado
`no_slices`	La superficie no produce ninguna dovela.
`no_shear_strength`	Ninguna base de dovela ofrece resistencia al corte.
`zero_driving`	El momento desestabilizador total (o la fuerza desestabilizadora) se anula: la masa no desliza y no hay factor de seguridad que dar. Así se evita calcular factores altísimos cuando la fuerza desestabilizadora es muy pequeña.
`active_support_exceeds_driving`	El soporte activo, por sí solo, supera el momento desestabilizador.
`m_alpha_collapsed`	$m_\alpha$ tiende a cero en la base de una dovela.
`n_alpha_collapsed`	$n_\alpha$ tiende a cero en la base de una dovela (su equivalente en los métodos de Janbu).
`non_physical_fos`	El cálculo da un factor sin sentido físico: cero, negativo o que no es un número finito.
`not_converged`	Se agotan las iteraciones permitidas antes de que el factor se estabilice. Hay un valor, el último iterado, pero no es un valor convergido; el ajuste que conviene revisar es el límite de iteraciones.
`all_lambda_diverged`	Divergen todos los valores muestreados de la relación λ de las fuerzas entre dovelas, y no queda ninguna rama en la que resolver (Spencer, GLE).
`no_lambda_bracket`	En el intervalo muestreado de λ no hay ningún cambio de signo, así que la raíz no queda acotada.
`divergent_at_lambda`	La solución diverge para el valor de λ finalmente elegido.
`lambda_not_closed`	Se encuentra y se refina el intervalo que acota λ, pero $\|F_f - F_m\|$ sigue por encima de la tolerancia en el valor de λ devuelto.
`no_force_bracket`	El equilibrio de fuerzas de los métodos de inclinación prescrita (Lowe-Karafiath, Corps of Engineers #1 y #2) no encuentra ningún intervalo que acote la raíz; lo único disponible es el factor muestreado de menor residuo, un valor de reserva y no una solución.
`force_balance_diverged`	Ese equilibrio de fuerzas no da ningún factor utilizable.
`drawdown_not_applicable`	El procedimiento de desembalse rápido no se aplica a esta superficie. No es un fallo del motor: en una búsqueda, la mayoría de las candidatas se encuentran en este caso.
`unsliceable_at_drawdown`	La superficie no se puede dividir en dovelas con el nivel de agua ya descendido.
`envelope_not_converged`	La envolvente de resistencia depende de la tensión normal, y la tensión con la que se leyó nunca llega a coincidir con la que obtiene el método, de modo que el factor no corresponde a la envolvente (desde v0.1.213).

En OGR Slip2D

Los motivos son las constantes REASON_*, y ALL_REASONS es el conjunto al que debe pertenecer el motivo de cada método, de modo que no pueda aparecer un motivo nuevo como una cadena suelta. No se traducen a propósito: la interfaz traduce el mensaje en el lugar donde lo muestra.

Código: ogr_slip2d/methods/base.py

5.5.3Comprobaciones de admisibilidad#

Una superficie que no supera una comprobación de admisibilidad no ha fallado en el cálculo: su factor ha convergido y se conserva, porque lo necesitan las búsquedas que se guían por el factor de seguridad. Después se la considera inadmisible y no se da como crítica, salvo que todas las superficies válidas sean inadmisibles; en ese caso se ignoran las comprobaciones y el resultado lo indica. La decisión se registra en admissible, admissibility_note y admissibility_reason, con estos valores:

Tabla 5.5.3 Comprobaciones de admisibilidad, su código y su valor por defecto.

Motivo	Código	Comprobación	Por defecto
`tensile_stress`	−120	Comprobación de tracción (Tensile Stress Check): la tensión normal efectiva que da la propia solución del método en la base de una dovela comprobada es una tracción mayor que la resistencia a tracción del material, que es nula salvo en los dos modelos de Hoek-Brown ( $s\,\sigma_{ci}/m_b$ ). Solo se comprueba un porcentaje de las dovelas, contado desde el pie (95 % por defecto), porque es normal que las dovelas de la coronación estén en tracción.	desactivada
`m_alpha`	−112	Comprobación de m-alfa: $m_\alpha < 0.2$ en cualquier dovela en la iteración final (Whitman y Bailey, 1967), con el denominador de Bishop, para Bishop simplificado, Janbu simplificado y corregido, Spencer y GLE. Un valor por debajo del límite no implica por sí solo que el factor sea erróneo; sirve para descartar las superficies cuyo cálculo ya no es fiable.	activada
`screen_error`	−101	Las propias comprobaciones dan un error, de modo que no se puede juzgar la superficie; se rechaza en lugar de dejarla pasar (desde v0.1.211).	—

Las dos comprobaciones se configuran en Analysis → Project Settings → Advanced (Tensile stress check, con su Percentage of slices, y Check m-alpha < 0.2).

5.5.4Errores de la capa de operaciones y del servidor MCP#

Cuando una operación de ogr_api falla a propósito, lanza un OgrApiError con un código estable, un mensaje, una sugerencia (si la hay) y, a veces, detalles. Un cliente MCP lo recibe como [E_CODE] message Hint: hint; un script de Python lo captura y lee code, message, hint y details. Los códigos son estables; la redacción de los mensajes, no. Cuando un nombre no existe, el error propone los nombres conocidos más parecidos (Did you mean …?).

Tabla 5.5.4 Códigos de error de la capa de operaciones, del servidor MCP y del puente para agentes.

Código	Cuándo se produce
`E_NOT_FOUND`	Una referencia, un identificador o un nombre que no existe: un `project_id`, `result_id` o `job_id`, una operación o un archivo que se quiere abrir; también cuando no hay ningún modelo abierto.
`E_INVALID_ARGUMENT`	Un valor de tipo incorrecto, fuera de los límites admitidos o que no es una de las opciones posibles, o un ajuste que no existe; también una ruta relativa cuando no se ha indicado carpeta de trabajo, o varios modelos abiertos sin `project_id`.
`E_CONFLICT`	Una petición válida que el modelo actual no admite (un segundo nivel freático, un coeficiente en una norma de diseño que no es `custom`…); un archivo ya existente sin `overwrite=true`; cambios sin guardar, al usar `project_close` y, en la ventana, `project_new` y `project_open`; una ventana que se cierra mientras responde a una llamada.
`E_NOT_CONFIGURED`	El modelo no se puede analizar tal como está configurado; `details["problems"]` enumera todos los motivos. También cualquier llamada a un servidor arrancado con `--attach` cuando no hay ninguna ventana abierta.
`E_BUSY`	Otra operación tiene ocupado el modelo (tras esperar 30 s), la ventana está calculando o ya se está ejecutando el número máximo de tareas.
`E_JOB_FAILED`	Una tarea en segundo plano ha fallado o ha terminado de forma inesperada; el mensaje incluye su error.
`E_INTERNAL`	Código por defecto de la clase base; también el que comunica el puente con la ventana ante una excepción inesperada, junto con su tipo y su mensaje.
`E_UNAUTHORIZED`	El puente con la ventana rechaza una conexión con un protocolo o un token incorrectos.

Una excepción que no es un OgrApiError llega a un cliente MCP con su tipo y su mensaje, sin código. Con HTTP, el propio servidor responde 401 si falta el token de portador o es incorrecto, 421 si el Host no es el suyo y 403 si el Origin es ajeno (Sección 5.1.11).

En OGR Slip2D

Con mucha frecuencia, quien lee estos mensajes es un modelo de lenguaje, y lo que le permite recuperarse es que se le diga qué ha ido mal y qué debe hacer en su lugar; de ahí la sugerencia y las alternativas propuestas para cada nombre desconocido.

Código: ogr_api/errors.py · ogr_api/workspace.py · ogr_gui/agent_bridge.py

5.5.5Códigos de salida#

Tabla 5.5.5 Códigos de salida de los programas de línea de comandos.

Programa	Código	Significado
`ogr-slip2d-cli`	0	Correcto, también cuando un método no encuentra ninguna superficie válida.
	1	No se encuentra el archivo del proyecto.
	2	Nombre de método desconocido o error de uso.
	3	El proyecto no se puede analizar tal como está configurado.
	4	Ningún método da resultado.
`ogr-slip2d-mcp`	0	Fin normal.
	2	Configuración con la que el servidor se niega a arrancar.
	3	El SDK de MCP no está instalado.

Los casos que corresponden a cada código se detallan en la Sección 5.2 y en la Sección 5.1.3.

5.5.6Referencias#

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.