Metodología de verificación

OGR Slip2D se verifica comparando lo que calcula con algo que el programa no ha producido: un factor de seguridad publicado en un artículo, en un estudio comparativo o en un manual de referencia, una solución analítica o una identidad que tiene que cumplirse exactamente. Esta página describe el método. Los casos en sí se exponen en la Sección 4.2 y en la Sección 4.3.

4.1.1El principio: una referencia externa#

La confianza que merece un factor de seguridad depende de las pruebas que respaldan al programa que lo ha calculado. La prueba habitual, que el programa dé hoy el mismo número que ayer, es débil: un test que compara la salida con un registro de la salida anterior del propio programa protege frente al cambio, no frente al error, y si ese registro contiene un error, el test lo da por bueno. Por eso OGR Slip2D se verifica con referencias que no ha producido él mismo, y una comparación con su propia salida no se registra como verificación.

Esta regla es la primera condición que las normas de contribución del proyecto imponen a un método, un motor de cálculo o una fórmula nuevos: deben contar con un valor de referencia (un caso publicado, una solución analítica o una propiedad analítica) y no con una copia de lo que el código imprime en ese momento (CONTRIBUTING.md). La página de Verificación resume el resultado para una primera lectura; este capítulo lo expone caso por caso.

4.1.2Cuatro tipos de referencia#

La Tabla 4.1.1 enumera los tipos de referencia que se admiten, con un ejemplo de cada uno y la sección en que se usa.

4.1.3Comprobar la búsqueda y comprobar el método#

Un factor de seguridad publicado puede responder a dos preguntas distintas, y el caso se construye según la que permita su fuente.

• Un caso de búsqueda. La fuente da el factor de seguridad mínimo de un talud. El caso ejecuta la búsqueda definida en su modelo y compara el factor de seguridad crítico de cada método indicado con el publicado, de modo que la búsqueda y el método se comprueban a la vez: una búsqueda que no encuentra el círculo crítico da un factor de seguridad mayor y el caso falla. Los casos 001 a 006 son de este tipo.
• Un caso de superficie dada. La fuente fija la superficie de rotura y da el factor de seguridad sobre ella. El caso evalúa cada método sobre esa superficie, sin búsqueda, así que la cifra mide solo el método. El caso 007 es de este tipo.

Solo el segundo tipo permite distinguir un método de otro. Sobre un círculo crítico que cada método encuentra por su cuenta, la diferencia entre dos métodos mezcla el efecto del método con el de la búsqueda, y un método que diera la respuesta de otro más sencillo podría pasar inadvertido (Sección 4.1.5).

4.1.4Cómo se elige la tolerancia de un caso#

La tolerancia de un caso es la diferencia relativa que admite entre el factor de seguridad calculado con OGR Slip2D y el valor de referencia:

donde

$F$

factor de seguridad calculado con OGR Slip2D

$F_{\mathrm{ref}}$

valor de referencia del caso (fos en su esperado.json)

$\varepsilon$

tolerancia del caso (tolerancia_relativa), expresada como fracción: 0.02 equivale a un 2 %

La tolerancia se fija en el caso y no en el test, porque depende de la calidad de la fuente: un valor leído en una figura no merece la precisión de uno tabulado. Para elegirla se plantean tres preguntas a la fuente.

1. ¿Cuánto discrepan entre sí las cifras publicadas? Un estudio comparativo publica un valor del árbitro y la media de los programas participantes, y los dos difieren. Una tolerancia más estrecha que esa dispersión haría fallar el caso por la calidad de su referencia.
2. ¿Qué deja sin precisar la fuente? Un parámetro que no da el enunciado hay que deducirlo o suponerlo, y el efecto de esa elección sobre el factor de seguridad forma parte de la tolerancia.
3. ¿Qué valor publicado tiene respaldo estadístico o independiente? Se prefiere la media de muchos programas al resultado de uno solo, para que en ningún caso quede escrita la salida de un programa concreto.

El test de los archivos de los casos da por fallido un caso que no indica tolerancia o que indica una superior al 10 %, porque a partir de ahí una validación deja de discriminar nada. La Tabla 4.1.2 recoge la tolerancia de cada caso con el motivo que consta en su archivo.

Cuando una fuente publica varias cifras, el caso indica cuál utiliza y por qué, y si la fuente no da ningún valor para un método, el caso no declara ninguno. El estudio de ACADS, por ejemplo, da para los problemas 1(a) y 1(c) una media de Bishop y una media de todos los programas juntos, pero ningún valor para cada método riguroso; Spencer y GLE / Morgenstern-Price solo se declaran en el caso 007, donde el enunciado fija el círculo y el estudio da un valor del árbitro. Un test de la batería vigila esta regla en los casos 001 a 004 y exige que al menos un caso distinga un método riguroso del de Bishop frente a una cifra publicada.

4.1.5Cuando un caso falla#

Un caso que falla no se modifica para que pase. Si no se reproduce un valor de referencia, el error está en el código o en el valor esperado, y para distinguirlos sirve un caso de validación. Ni el valor esperado ni la tolerancia se ajustan a la salida: la tolerancia pertenece a la fuente, y el valor esperado es un dato que consta en una publicación.

Un defecto ilustra por qué importa el tipo de caso. Hasta la versión 0.1.106, el método de Spencer (Spencer, 1967) y el método GLE / Morgenstern-Price (Morgenstern y Price, 1965) daban, sobre una superficie circular, el mismo factor de seguridad que el método simplificado de Bishop (Bishop, 1955), con una coincidencia de seis cifras. Ningún caso de la carpeta podía detectarlo: cada uno comparaba el mínimo hallado por una búsqueda con un mínimo publicado, y el valor de Bishop es una respuesta plausible. El defecto, que en realidad eran tres, duró unas ochenta versiones. El caso 007 se escribió para ponerlo de manifiesto. El círculo lo fija el enunciado, y las dos referencias publicadas, una media de Bishop de 2.204 y un valor del árbitro de 2.29, difieren en un 3.9 %, de modo que un método de equilibrio completo que diera la cifra de Bishop no superaría el caso. Con la versión 0.1.105, el método de Spencer daba 2.2088 sobre ese círculo, más de un 3 % por debajo del valor del árbitro y fuera de la tolerancia del 2 % del caso. Las mediciones constan en la auditoría que se conserva en el repositorio.

4.1.6La carpeta de validación#

Los casos están en la carpeta validacion/ del repositorio, con una subcarpeta por caso, numeradas en el orden en que se añadieron:

validacion/
├── README.md
└── casos/
    ├── 000-plantilla/         plantilla; el ejecutor la omite porque no tiene modelo
    ├── 001-acads-1a/
    │   ├── caso.md            qué es el caso y de dónde procede su valor esperado
    │   ├── modelo.ogr         el modelo, listo para abrirlo en el programa
    │   └── esperado.json      valores esperados, tolerancia y cómo ejecutar el caso
    └── ...

El archivo .ogr es el modelo del caso, en JSON de texto plano (Sección 5.4). La Tabla 4.1.3 enumera lo que contiene esperado.json y lo que hace con ello el ejecutor.

El modelo, el valor esperado y su fuente se incluyen en el control de versiones; los archivos de proyecto de otros programas, las capturas de pantalla de otros programas y los informes de terceros, no. La distinción es de derechos de autor: el archivo .ogr es del propio proyecto, y el número esperado es un dato que puede citarse.

4.1.7Ejecución de los casos#

Un único test, tests/test_validation_cases.py, recorre todas las carpetas de casos que tienen un modelo y un esperado.json, así que para añadir un caso no hace falta escribir código. El proyecto usa su propio ejecutor de tests y no necesita pytest; los módulos de test no pueden importarse fuera del ejecutor. Desde un clon del repositorio (Sección 1.1.5):

python tests/_runner.py validation_cases     # los siete casos y las comprobaciones de sus archivos
python tests/_runner.py published_cases      # las comprobaciones que los acompañan

Si se selecciona por nombre de archivo, se imprime una advertencia FILTERED RUN junto a los totales y el resultado no vale como prueba para publicar una versión; la batería completa, que es lo que necesita una versión, se ejecuta sin argumentos. Además de reproducir los valores esperados, el test comprueba que cada carpeta tiene sus tres archivos, que esperado.json es válido, que cada caso cita una fuente y declara una tolerancia razonable, que los identificadores de método y los tipos de búsqueda existen, y que al menos un caso se ejecuta de verdad, de modo que una carpeta vacía no pueda pasar sin avisar.

Para añadir un caso, construye el modelo en el programa y guárdalo como modelo.ogr; escribe caso.md con la geometría, los materiales y, sobre todo, de dónde procede el número esperado, porque sin fuente un valor esperado no es más que una opinión; rellena esperado.json y ejecuta el test. Se agradecen casos nuevos: un talud cuyo factor de seguridad se conozca por una publicación o por un cálculo a mano, con su fuente (abre un caso de validación).

4.1.8Reglas que complementan los casos#

Un valor de referencia no puede detectar todo tipo de errores, y las normas de contribución del proyecto añaden tres hábitos más a los casos.

• Ningún ajuste puede quedar sin efecto. Toda opción nueva se acompaña de un test que comprueba que modifica el resultado, porque un control sin efecto hace creer al usuario que el análisis lo respeta.
• Las anomalías se comunican antes de corregirlas. Un comportamiento que parece erróneo se describe, con las pruebas, antes de cambiar el código.
• Los tests no dejan estado residual. El idioma, las unidades y las cachés se restauran, porque si un test deja estado sin restaurar, otros tests sin relación fallan solo en una ejecución completa.

4.1.9Lo que la verificación no demuestra#

4.1.10Referencias#

• Bishop, A.W. (1955). The use of the slip circle in the stability analysis of slopes. Géotechnique, 5(1), 7–17.
• Morgenstern, N.R. & Price, V.E. (1965). The analysis of the stability of general slip surfaces. Géotechnique, 15(1), 79–93.
• Spencer, E. (1967). A method of analysis of the stability of embankments assuming parallel inter-slice forces. Géotechnique, 17(1), 11–26.