你已经派生过 gprMax
镜像自地址
https://gitee.com/sunhf/gprMax.git
已同步 2025-08-04 11:36:52 +08:00
Add documentation about the reframe test suite
这个提交包含在：
Nathan Mannall
1
docs/.gitignore
vendored
1
docs/.gitignore
vendored
@@ -1,4 +1,3 @@
|
||||
_*/
|
||||
doctrees/
|
||||
dirhtml/
|
||||
|
||||
|
||||
31
docs/source/_templates/class.rst
普通文件
31
docs/source/_templates/class.rst
普通文件
@@ -0,0 +1,31 @@
|
||||
.. _{{ name }}:
|
||||
|
||||
{{ name | escape | underline}}
|
||||
|
||||
.. currentmodule:: {{ module }}
|
||||
|
||||
.. autoclass:: {{ objname }}
|
||||
|
||||
{% block methods %}
|
||||
.. automethod:: __init__
|
||||
|
||||
{% if methods %}
|
||||
.. rubric:: {{ _('Methods') }}
|
||||
|
||||
.. autosummary::
|
||||
{% for item in methods %}
|
||||
~{{ name }}.{{ item }}
|
||||
{%- endfor %}
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
|
||||
{% block attributes %}
|
||||
{% if attributes %}
|
||||
.. rubric:: {{ _('Attributes') }}
|
||||
|
||||
.. autosummary::
|
||||
{% for item in attributes %}
|
||||
~{{ name }}.{{ item }}
|
||||
{%- endfor %}
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
@@ -0,0 +1,7 @@
|
||||
.. _{{ name }}:
|
||||
|
||||
{{ name | escape | underline}}
|
||||
|
||||
.. currentmodule:: {{ module }}
|
||||
|
||||
.. autoclass:: {{ objname }}
|
||||
@@ -22,7 +22,12 @@ with open("../../gprMax/_version.py", "r") as fd:
|
||||
# -- General configuration ---------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
||||
|
||||
extensions = ["sphinx.ext.mathjax", "sphinx.ext.autodoc", "sphinx.ext.napoleon"]
|
||||
extensions = [
|
||||
"sphinx.ext.mathjax",
|
||||
"sphinx.ext.autodoc",
|
||||
"sphinx.ext.napoleon",
|
||||
"sphinx.ext.autosummary",
|
||||
]
|
||||
|
||||
# Figure numbering
|
||||
numfig = True
|
||||
|
||||
@@ -0,0 +1,119 @@
|
||||
.. _CreatePyenvTest:
|
||||
|
||||
CreatePyenvTest
|
||||
===============
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.base_tests
|
||||
|
||||
.. autoclass:: CreatePyenvTest
|
||||
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
|
||||
.. rubric:: Methods
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~CreatePyenvTest.__init__
|
||||
~CreatePyenvTest.check_performance
|
||||
~CreatePyenvTest.check_requirements_installed
|
||||
~CreatePyenvTest.check_sanity
|
||||
~CreatePyenvTest.cleanup
|
||||
~CreatePyenvTest.compile
|
||||
~CreatePyenvTest.compile_complete
|
||||
~CreatePyenvTest.compile_wait
|
||||
~CreatePyenvTest.depends_on
|
||||
~CreatePyenvTest.disable_hook
|
||||
~CreatePyenvTest.getdep
|
||||
~CreatePyenvTest.info
|
||||
~CreatePyenvTest.install_system_specific_dependencies
|
||||
~CreatePyenvTest.is_dry_run
|
||||
~CreatePyenvTest.is_fixture
|
||||
~CreatePyenvTest.is_local
|
||||
~CreatePyenvTest.is_performance_check
|
||||
~CreatePyenvTest.performance
|
||||
~CreatePyenvTest.pipeline_hooks
|
||||
~CreatePyenvTest.run
|
||||
~CreatePyenvTest.run_complete
|
||||
~CreatePyenvTest.run_wait
|
||||
~CreatePyenvTest.sanity
|
||||
~CreatePyenvTest.set_var_default
|
||||
~CreatePyenvTest.setup
|
||||
~CreatePyenvTest.skip
|
||||
~CreatePyenvTest.skip_if
|
||||
~CreatePyenvTest.skip_if_no_procinfo
|
||||
~CreatePyenvTest.user_deps
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. rubric:: Attributes
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~CreatePyenvTest.build_job
|
||||
~CreatePyenvTest.build_stderr
|
||||
~CreatePyenvTest.build_stdout
|
||||
~CreatePyenvTest.current_environ
|
||||
~CreatePyenvTest.current_partition
|
||||
~CreatePyenvTest.current_system
|
||||
~CreatePyenvTest.disabled_hooks
|
||||
~CreatePyenvTest.display_name
|
||||
~CreatePyenvTest.fixture_variant
|
||||
~CreatePyenvTest.hashcode
|
||||
~CreatePyenvTest.job
|
||||
~CreatePyenvTest.logger
|
||||
~CreatePyenvTest.name
|
||||
~CreatePyenvTest.outputdir
|
||||
~CreatePyenvTest.param_variant
|
||||
~CreatePyenvTest.perfvalues
|
||||
~CreatePyenvTest.prefix
|
||||
~CreatePyenvTest.short_name
|
||||
~CreatePyenvTest.stagedir
|
||||
~CreatePyenvTest.stderr
|
||||
~CreatePyenvTest.stdout
|
||||
~CreatePyenvTest.unique_name
|
||||
~CreatePyenvTest.variant_num
|
||||
~CreatePyenvTest.valid_prog_environs
|
||||
~CreatePyenvTest.valid_systems
|
||||
~CreatePyenvTest.descr
|
||||
~CreatePyenvTest.sourcepath
|
||||
~CreatePyenvTest.sourcesdir
|
||||
~CreatePyenvTest.build_system
|
||||
~CreatePyenvTest.prebuild_cmds
|
||||
~CreatePyenvTest.postbuild_cmds
|
||||
~CreatePyenvTest.executable
|
||||
~CreatePyenvTest.executable_opts
|
||||
~CreatePyenvTest.container_platform
|
||||
~CreatePyenvTest.prerun_cmds
|
||||
~CreatePyenvTest.postrun_cmds
|
||||
~CreatePyenvTest.keep_files
|
||||
~CreatePyenvTest.readonly_files
|
||||
~CreatePyenvTest.tags
|
||||
~CreatePyenvTest.maintainers
|
||||
~CreatePyenvTest.strict_check
|
||||
~CreatePyenvTest.num_tasks
|
||||
~CreatePyenvTest.num_tasks_per_node
|
||||
~CreatePyenvTest.num_gpus_per_node
|
||||
~CreatePyenvTest.num_cpus_per_task
|
||||
~CreatePyenvTest.num_tasks_per_core
|
||||
~CreatePyenvTest.num_tasks_per_socket
|
||||
~CreatePyenvTest.use_multithreading
|
||||
~CreatePyenvTest.max_pending_time
|
||||
~CreatePyenvTest.exclusive_access
|
||||
~CreatePyenvTest.local
|
||||
~CreatePyenvTest.reference
|
||||
~CreatePyenvTest.require_reference
|
||||
~CreatePyenvTest.sanity_patterns
|
||||
~CreatePyenvTest.perf_patterns
|
||||
~CreatePyenvTest.perf_variables
|
||||
~CreatePyenvTest.modules
|
||||
~CreatePyenvTest.env_vars
|
||||
~CreatePyenvTest.variables
|
||||
~CreatePyenvTest.time_limit
|
||||
~CreatePyenvTest.build_time_limit
|
||||
~CreatePyenvTest.extra_resources
|
||||
~CreatePyenvTest.build_locally
|
||||
~CreatePyenvTest.ci_extras
|
||||
@@ -0,0 +1,137 @@
|
||||
.. _GprMaxBaseTest:
|
||||
|
||||
GprMaxBaseTest
|
||||
==============
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.base_tests
|
||||
|
||||
.. autoclass:: GprMaxBaseTest
|
||||
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
|
||||
.. rubric:: Methods
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~GprMaxBaseTest.__init__
|
||||
~GprMaxBaseTest.build_output_file_path
|
||||
~GprMaxBaseTest.build_reference_filepath
|
||||
~GprMaxBaseTest.check_performance
|
||||
~GprMaxBaseTest.check_sanity
|
||||
~GprMaxBaseTest.cleanup
|
||||
~GprMaxBaseTest.combine_task_outputs
|
||||
~GprMaxBaseTest.compile
|
||||
~GprMaxBaseTest.compile_complete
|
||||
~GprMaxBaseTest.compile_wait
|
||||
~GprMaxBaseTest.configure_test_run
|
||||
~GprMaxBaseTest.depends_on
|
||||
~GprMaxBaseTest.disable_hook
|
||||
~GprMaxBaseTest.extract_average_memory_use
|
||||
~GprMaxBaseTest.extract_memory_use_per_rank
|
||||
~GprMaxBaseTest.extract_run_time
|
||||
~GprMaxBaseTest.extract_simulation_time
|
||||
~GprMaxBaseTest.extract_simulation_time_per_rank
|
||||
~GprMaxBaseTest.extract_total_memory_use
|
||||
~GprMaxBaseTest.get_pyenv_path
|
||||
~GprMaxBaseTest.get_test_dependency
|
||||
~GprMaxBaseTest.get_test_dependency_variant_name
|
||||
~GprMaxBaseTest.getdep
|
||||
~GprMaxBaseTest.info
|
||||
~GprMaxBaseTest.inject_dependencies
|
||||
~GprMaxBaseTest.is_dry_run
|
||||
~GprMaxBaseTest.is_fixture
|
||||
~GprMaxBaseTest.is_local
|
||||
~GprMaxBaseTest.is_performance_check
|
||||
~GprMaxBaseTest.performance
|
||||
~GprMaxBaseTest.pipeline_hooks
|
||||
~GprMaxBaseTest.regression_check
|
||||
~GprMaxBaseTest.run
|
||||
~GprMaxBaseTest.run_complete
|
||||
~GprMaxBaseTest.run_wait
|
||||
~GprMaxBaseTest.sanity
|
||||
~GprMaxBaseTest.set_file_paths
|
||||
~GprMaxBaseTest.set_var_default
|
||||
~GprMaxBaseTest.setup
|
||||
~GprMaxBaseTest.setup_env_vars
|
||||
~GprMaxBaseTest.skip
|
||||
~GprMaxBaseTest.skip_if
|
||||
~GprMaxBaseTest.skip_if_no_procinfo
|
||||
~GprMaxBaseTest.test_reference_files_exist
|
||||
~GprMaxBaseTest.test_simulation_complete
|
||||
~GprMaxBaseTest.user_deps
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. rubric:: Attributes
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~GprMaxBaseTest.build_job
|
||||
~GprMaxBaseTest.build_stderr
|
||||
~GprMaxBaseTest.build_stdout
|
||||
~GprMaxBaseTest.current_environ
|
||||
~GprMaxBaseTest.current_partition
|
||||
~GprMaxBaseTest.current_system
|
||||
~GprMaxBaseTest.disabled_hooks
|
||||
~GprMaxBaseTest.display_name
|
||||
~GprMaxBaseTest.fixture_variant
|
||||
~GprMaxBaseTest.hashcode
|
||||
~GprMaxBaseTest.job
|
||||
~GprMaxBaseTest.logger
|
||||
~GprMaxBaseTest.name
|
||||
~GprMaxBaseTest.outputdir
|
||||
~GprMaxBaseTest.param_variant
|
||||
~GprMaxBaseTest.perfvalues
|
||||
~GprMaxBaseTest.prefix
|
||||
~GprMaxBaseTest.short_name
|
||||
~GprMaxBaseTest.stagedir
|
||||
~GprMaxBaseTest.stderr
|
||||
~GprMaxBaseTest.stdout
|
||||
~GprMaxBaseTest.test_dependency
|
||||
~GprMaxBaseTest.unique_name
|
||||
~GprMaxBaseTest.variant_num
|
||||
~GprMaxBaseTest.valid_prog_environs
|
||||
~GprMaxBaseTest.valid_systems
|
||||
~GprMaxBaseTest.descr
|
||||
~GprMaxBaseTest.sourcepath
|
||||
~GprMaxBaseTest.sourcesdir
|
||||
~GprMaxBaseTest.build_system
|
||||
~GprMaxBaseTest.prebuild_cmds
|
||||
~GprMaxBaseTest.postbuild_cmds
|
||||
~GprMaxBaseTest.executable
|
||||
~GprMaxBaseTest.executable_opts
|
||||
~GprMaxBaseTest.container_platform
|
||||
~GprMaxBaseTest.prerun_cmds
|
||||
~GprMaxBaseTest.postrun_cmds
|
||||
~GprMaxBaseTest.keep_files
|
||||
~GprMaxBaseTest.readonly_files
|
||||
~GprMaxBaseTest.tags
|
||||
~GprMaxBaseTest.maintainers
|
||||
~GprMaxBaseTest.strict_check
|
||||
~GprMaxBaseTest.num_tasks
|
||||
~GprMaxBaseTest.num_tasks_per_node
|
||||
~GprMaxBaseTest.num_gpus_per_node
|
||||
~GprMaxBaseTest.num_cpus_per_task
|
||||
~GprMaxBaseTest.num_tasks_per_core
|
||||
~GprMaxBaseTest.num_tasks_per_socket
|
||||
~GprMaxBaseTest.use_multithreading
|
||||
~GprMaxBaseTest.max_pending_time
|
||||
~GprMaxBaseTest.exclusive_access
|
||||
~GprMaxBaseTest.local
|
||||
~GprMaxBaseTest.reference
|
||||
~GprMaxBaseTest.require_reference
|
||||
~GprMaxBaseTest.sanity_patterns
|
||||
~GprMaxBaseTest.perf_patterns
|
||||
~GprMaxBaseTest.perf_variables
|
||||
~GprMaxBaseTest.modules
|
||||
~GprMaxBaseTest.env_vars
|
||||
~GprMaxBaseTest.variables
|
||||
~GprMaxBaseTest.time_limit
|
||||
~GprMaxBaseTest.build_time_limit
|
||||
~GprMaxBaseTest.extra_resources
|
||||
~GprMaxBaseTest.build_locally
|
||||
~GprMaxBaseTest.ci_extras
|
||||
@@ -0,0 +1,8 @@
|
||||
.. _BScanMixin:
|
||||
|
||||
BScanMixin
|
||||
==========
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.mixins
|
||||
|
||||
.. autoclass:: BScanMixin
|
||||
@@ -0,0 +1,8 @@
|
||||
.. _GeometryObjectsReadMixin:
|
||||
|
||||
GeometryObjectsReadMixin
|
||||
========================
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.mixins
|
||||
|
||||
.. autoclass:: GeometryObjectsReadMixin
|
||||
@@ -0,0 +1,8 @@
|
||||
.. _GeometryObjectsWriteMixin:
|
||||
|
||||
GeometryObjectsWriteMixin
|
||||
=========================
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.mixins
|
||||
|
||||
.. autoclass:: GeometryObjectsWriteMixin
|
||||
@@ -0,0 +1,8 @@
|
||||
.. _GeometryOnlyMixin:
|
||||
|
||||
GeometryOnlyMixin
|
||||
=================
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.mixins
|
||||
|
||||
.. autoclass:: GeometryOnlyMixin
|
||||
@@ -0,0 +1,8 @@
|
||||
.. _GeometryViewMixin:
|
||||
|
||||
GeometryViewMixin
|
||||
=================
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.mixins
|
||||
|
||||
.. autoclass:: GeometryViewMixin
|
||||
@@ -0,0 +1,8 @@
|
||||
.. _MpiMixin:
|
||||
|
||||
MpiMixin
|
||||
========
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.mixins
|
||||
|
||||
.. autoclass:: MpiMixin
|
||||
@@ -0,0 +1,8 @@
|
||||
.. _PythonApiMixin:
|
||||
|
||||
PythonApiMixin
|
||||
==============
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.mixins
|
||||
|
||||
.. autoclass:: PythonApiMixin
|
||||
@@ -0,0 +1,8 @@
|
||||
.. _ReceiverMixin:
|
||||
|
||||
ReceiverMixin
|
||||
=============
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.mixins
|
||||
|
||||
.. autoclass:: ReceiverMixin
|
||||
@@ -0,0 +1,8 @@
|
||||
.. _SnapshotMixin:
|
||||
|
||||
SnapshotMixin
|
||||
=============
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.mixins
|
||||
|
||||
.. autoclass:: SnapshotMixin
|
||||
@@ -0,0 +1,8 @@
|
||||
.. _TaskfarmMixin:
|
||||
|
||||
TaskfarmMixin
|
||||
=============
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.mixins
|
||||
|
||||
.. autoclass:: TaskfarmMixin
|
||||
@@ -0,0 +1,31 @@
|
||||
.. _GeometryObjectMaterialsRegressionCheck:
|
||||
|
||||
GeometryObjectMaterialsRegressionCheck
|
||||
======================================
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.regression_checks
|
||||
|
||||
.. autoclass:: GeometryObjectMaterialsRegressionCheck
|
||||
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
|
||||
.. rubric:: Methods
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~GeometryObjectMaterialsRegressionCheck.__init__
|
||||
~GeometryObjectMaterialsRegressionCheck.create_reference_file
|
||||
~GeometryObjectMaterialsRegressionCheck.reference_file_exists
|
||||
~GeometryObjectMaterialsRegressionCheck.run
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. rubric:: Attributes
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~GeometryObjectMaterialsRegressionCheck.error_msg
|
||||
@@ -0,0 +1,31 @@
|
||||
.. _GeometryObjectRegressionCheck:
|
||||
|
||||
GeometryObjectRegressionCheck
|
||||
=============================
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.regression_checks
|
||||
|
||||
.. autoclass:: GeometryObjectRegressionCheck
|
||||
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
|
||||
.. rubric:: Methods
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~GeometryObjectRegressionCheck.__init__
|
||||
~GeometryObjectRegressionCheck.create_reference_file
|
||||
~GeometryObjectRegressionCheck.reference_file_exists
|
||||
~GeometryObjectRegressionCheck.run
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. rubric:: Attributes
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~GeometryObjectRegressionCheck.error_msg
|
||||
@@ -0,0 +1,31 @@
|
||||
.. _GeometryViewRegressionCheck:
|
||||
|
||||
GeometryViewRegressionCheck
|
||||
===========================
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.regression_checks
|
||||
|
||||
.. autoclass:: GeometryViewRegressionCheck
|
||||
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
|
||||
.. rubric:: Methods
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~GeometryViewRegressionCheck.__init__
|
||||
~GeometryViewRegressionCheck.create_reference_file
|
||||
~GeometryViewRegressionCheck.reference_file_exists
|
||||
~GeometryViewRegressionCheck.run
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. rubric:: Attributes
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~GeometryViewRegressionCheck.error_msg
|
||||
@@ -0,0 +1,31 @@
|
||||
.. _H5RegressionCheck:
|
||||
|
||||
H5RegressionCheck
|
||||
=================
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.regression_checks
|
||||
|
||||
.. autoclass:: H5RegressionCheck
|
||||
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
|
||||
.. rubric:: Methods
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~H5RegressionCheck.__init__
|
||||
~H5RegressionCheck.create_reference_file
|
||||
~H5RegressionCheck.reference_file_exists
|
||||
~H5RegressionCheck.run
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. rubric:: Attributes
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~H5RegressionCheck.error_msg
|
||||
@@ -0,0 +1,31 @@
|
||||
.. _ReceiverRegressionCheck:
|
||||
|
||||
ReceiverRegressionCheck
|
||||
=======================
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.regression_checks
|
||||
|
||||
.. autoclass:: ReceiverRegressionCheck
|
||||
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
|
||||
.. rubric:: Methods
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~ReceiverRegressionCheck.__init__
|
||||
~ReceiverRegressionCheck.create_reference_file
|
||||
~ReceiverRegressionCheck.reference_file_exists
|
||||
~ReceiverRegressionCheck.run
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. rubric:: Attributes
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~ReceiverRegressionCheck.error_msg
|
||||
@@ -0,0 +1,31 @@
|
||||
.. _RegressionCheck:
|
||||
|
||||
RegressionCheck
|
||||
===============
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.regression_checks
|
||||
|
||||
.. autoclass:: RegressionCheck
|
||||
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
|
||||
.. rubric:: Methods
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~RegressionCheck.__init__
|
||||
~RegressionCheck.create_reference_file
|
||||
~RegressionCheck.reference_file_exists
|
||||
~RegressionCheck.run
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. rubric:: Attributes
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~RegressionCheck.error_msg
|
||||
@@ -0,0 +1,31 @@
|
||||
.. _SnapshotRegressionCheck:
|
||||
|
||||
SnapshotRegressionCheck
|
||||
=======================
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.regression_checks
|
||||
|
||||
.. autoclass:: SnapshotRegressionCheck
|
||||
|
||||
|
||||
.. automethod:: __init__
|
||||
|
||||
|
||||
.. rubric:: Methods
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~SnapshotRegressionCheck.__init__
|
||||
~SnapshotRegressionCheck.create_reference_file
|
||||
~SnapshotRegressionCheck.reference_file_exists
|
||||
~SnapshotRegressionCheck.run
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
.. rubric:: Attributes
|
||||
|
||||
.. autosummary::
|
||||
|
||||
~SnapshotRegressionCheck.error_msg
|
||||
@@ -62,6 +62,7 @@ gprMax User Guide
|
||||
:caption: Developers
|
||||
|
||||
contributing
|
||||
reframe_test_suite
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
180
docs/source/reframe_test_suite.rst
普通文件
180
docs/source/reframe_test_suite.rst
普通文件
@@ -0,0 +1,180 @@
|
||||
******************
|
||||
ReFrame Test Suite
|
||||
******************
|
||||
|
||||
gprMax includes a test suite built using `ReFrame <https://reframe-hpc.readthedocs.io>`_.
|
||||
|
||||
This is not a unit testing framework, instead it provides a mechanism to perform regression checks on whole model runs. Reference files for regression checks are automatically generated and stored in ``reframe_tests/regression_checks``.
|
||||
|
||||
.. attention::
|
||||
|
||||
The regression checks are sensitive to floating point precision errors so are currently specific to the `ARCHER2 <https://www.archer2.ac.uk/>`_ system. Additional work is required to make them portable between systems.
|
||||
|
||||
Run the test suite
|
||||
==================
|
||||
|
||||
Running the test suite requires ReFrame to be installed:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install reframe-hpc
|
||||
|
||||
The full test suite can be run with:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd reframe_tests
|
||||
$ reframe -c tests/ -r
|
||||
|
||||
If you are running on a HPC system, you will need to be provide a configuration file:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ reframe -C configuration/archer2_settings.py -c tests/ -r
|
||||
|
||||
A ReFrame configuration script for `ARCHER2 <https://www.archer2.ac.uk/>`_ is provided in the ``reframe_tests/configuration`` folder. Configurations for additional machines can be added here.
|
||||
|
||||
.. tip::
|
||||
|
||||
The full test suite is quite large. ReFrame provides a number of ways to filter the tests you want to run such as ``-n`` and ``-t`` (by name and tag respectively). There is much more information in the `ReFrame documentation <https://reframe-hpc.readthedocs.io/en/stable/manpage.html#test-filtering>`_.
|
||||
|
||||
There is also an example job submission script for running the suite as a long running job on ARCHER2. Any additional arguments are passed forwarded to ReFrame. E.g.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sbatch job_scripts/archer2_tests.slurm -n Snapshot
|
||||
|
||||
would run all tests with "Snapshot" in the test name.
|
||||
|
||||
Developer guide
|
||||
===============
|
||||
|
||||
Tests are defined in the ``reframe_tests/tests`` folder with gprMax input files stored in ``reframe_tests/tests/src``.
|
||||
|
||||
Base test classes
|
||||
-----------------
|
||||
|
||||
Every regression test inherits from the :ref:`GprMaxBaseTest` class. This class contains all the logic for launching a gprMax job, checking the simulation completed, and running any regression checks.
|
||||
|
||||
Additionally, every test depends on the :ref:`CreatePyenvTest` class. It creates a new Python environment that all other tests will use.
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.base_tests
|
||||
|
||||
.. autosummary::
|
||||
:template: class.rst
|
||||
:toctree: developer_reference
|
||||
:nosignatures:
|
||||
|
||||
CreatePyenvTest
|
||||
GprMaxBaseTest
|
||||
|
||||
.. tip::
|
||||
|
||||
Avoid rebuilding the Python environment every time you run the test suite by running ReFrame with the ``--restore-session`` flag.
|
||||
|
||||
Adding a new test
|
||||
-----------------
|
||||
|
||||
The easiest way to learn how to write a new test is by looking at the existing tests. The test below runs the B-scan model provided with gprMax:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import reframe as rfm
|
||||
from reframe.core.builtins import parameter
|
||||
|
||||
from reframe_tests.tests.mixins import BScanMixin, ReceiverMixin
|
||||
|
||||
@rfm.simple_test
|
||||
class TestBscan(BScanMixin, ReceiverMixin, GprMaxBaseTest):
|
||||
tags = {"test", "serial", "bscan"}
|
||||
sourcesdir = "src/bscan_tests"
|
||||
model = parameter(["cylinder_Bscan_2D"])
|
||||
num_models = parameter([64])
|
||||
|
||||
- ``@rfm.simple_test`` - marks the class as a ReFrame test.
|
||||
- :ref:`BScanMixin` and :ref:`ReceiverMixin` - mixin classes alter the behaviour to test specific gprMax functionality.
|
||||
- ``tags`` - set tags that can be used to filter tests.
|
||||
- ``sourcesdir`` - path to test source directory.
|
||||
- ``model`` - gprMax input filename (without file extension). This is a ReFrame parameter so it can take multiple values to run the same test with multiple input files.
|
||||
- ``num_models`` - parameter specific to the :ref:`BScanMixin`.
|
||||
|
||||
Test dependencies
|
||||
-----------------
|
||||
|
||||
Tests can also define a test dependency. This uses the ReFrame test dependency mechanism to link tests. The dependent test can access the resources and outputs of the test it depends on. This means we can create a test that should produce an identical result to another test, but is configured differently. For example, to test the MPI domain decomposition functionality using the previous B-scan model, we can add:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from reframe_tests.tests.mixins import MpiMixin
|
||||
|
||||
@rfm.simple_test
|
||||
class TestBscanMPI(MpiMixin, TestBscan):
|
||||
tags = {"test", "mpi", "bscan"}
|
||||
mpi_layout = parameter([[2, 2, 1]])
|
||||
test_dependency = TestBscan
|
||||
|
||||
- Our new class inherits from the above ``TestBscan`` class.
|
||||
- Use the :ref:`MpiMixin` to run with the gprMax domain decomposition functionality.
|
||||
- Override ``tags``.
|
||||
- ``mpi_layout`` - parameter specific to the :ref:`MpiMixin`.
|
||||
- ``test_dependency`` - Depend on the ``TestBscan`` class. It is not sufficient to just inherit from the class. The output from this test will compared with the output from the ``TestBscan`` test.
|
||||
|
||||
.. note::
|
||||
|
||||
Some parameters, such as ``model`` are unified between test dependencies. I.e. the dependent test and test dependency will have the same value for the parameter.
|
||||
|
||||
If a mixin class adds a new parameter, this may need to be unified as well. For an example of how to do this, see the :ref:`BscanMixin` class and the ``num_models`` parameter.
|
||||
|
||||
Mixin classes
|
||||
-------------
|
||||
|
||||
The different mixin classes are used to alter the behaviour of a given test to support testing gprMax functionality - snapshots, geometry objects, geometry views - and different runtime configurations such as task farms, MPI, and the Python API.
|
||||
|
||||
.. important::
|
||||
|
||||
When creating a new test, the mixin class must be specified earlier in the inheritance list than the base ReFrame test class::
|
||||
|
||||
class TestAscan(ReceiverMixin, GprMaxBaseTest):
|
||||
pass
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.mixins
|
||||
|
||||
.. autosummary::
|
||||
:template: class_stub.rst
|
||||
:toctree: developer_reference
|
||||
:nosignatures:
|
||||
|
||||
BScanMixin
|
||||
GeometryObjectsReadMixin
|
||||
GeometryObjectsWriteMixin
|
||||
GeometryOnlyMixin
|
||||
GeometryViewMixin
|
||||
MpiMixin
|
||||
PythonApiMixin
|
||||
ReceiverMixin
|
||||
SnapshotMixin
|
||||
TaskfarmMixin
|
||||
|
||||
Regression checks
|
||||
-----------------
|
||||
|
||||
.. note::
|
||||
|
||||
To make the test suite portable between systems, the main changes would be to these regression check classes. Specifically the way hdf5 files are compared.
|
||||
|
||||
There are a number of classes that perform regression checks.
|
||||
|
||||
.. currentmodule:: reframe_tests.tests.regression_checks
|
||||
|
||||
.. autosummary::
|
||||
:template: class.rst
|
||||
:toctree: developer_reference
|
||||
:nosignatures:
|
||||
|
||||
RegressionCheck
|
||||
H5RegressionCheck
|
||||
ReceiverRegressionCheck
|
||||
GeometryObjectRegressionCheck
|
||||
GeometryObjectMaterialsRegressionCheck
|
||||
GeometryViewRegressionCheck
|
||||
SnapshotRegressionCheck
|
||||
@@ -29,16 +29,25 @@ else:
|
||||
|
||||
|
||||
class ReceiverMixin(GprMaxMixin):
|
||||
"""Add regression tests for receivers.
|
||||
|
||||
Attributes:
|
||||
number_of_receivers (int): Number of receivers to run regression
|
||||
checks on. For values of 0 or less, the whole output file
|
||||
will be checked. Default -1.
|
||||
"""
|
||||
|
||||
number_of_receivers = variable(int, value=-1)
|
||||
|
||||
@run_after("setup", always_last=True)
|
||||
def add_receiver_regression_checks(self):
|
||||
"""Add a regression check for each receiver."""
|
||||
test_dependency = self.get_test_dependency()
|
||||
if test_dependency is not None:
|
||||
if test_dependency is None:
|
||||
reference_file = self.build_reference_filepath(self.output_file)
|
||||
else:
|
||||
output_file = self.build_output_file_path(test_dependency.model)
|
||||
reference_file = self.build_reference_filepath(output_file)
|
||||
else:
|
||||
reference_file = self.build_reference_filepath(self.output_file)
|
||||
|
||||
if self.number_of_receivers > 0:
|
||||
for i in range(self.number_of_receivers):
|
||||
@@ -54,6 +63,8 @@ class ReceiverMixin(GprMaxMixin):
|
||||
class SnapshotMixin(GprMaxMixin):
|
||||
"""Add regression tests for snapshots.
|
||||
|
||||
The test will be skipped if no snapshots are specified.
|
||||
|
||||
Attributes:
|
||||
snapshots (list[str]): List of snapshots to run regression
|
||||
checks on.
|
||||
@@ -114,10 +125,32 @@ class GeometryObjectMixinBase(GprMaxMixin):
|
||||
|
||||
|
||||
class GeometryObjectsReadMixin(GeometryObjectMixinBase):
|
||||
"""Read geometry object(s) created by a test dependency.
|
||||
|
||||
This mixin must be used with a test dependency.
|
||||
|
||||
The test will also be skipped if no geometry objects have been
|
||||
specified, or if the test dependency did not create a specified
|
||||
geometry object.
|
||||
|
||||
Attributes:
|
||||
geometry_objects_read (dict[str, str]): Mapping of geometry
|
||||
objects. The keys are the name of the geometry object(s)
|
||||
created by the test dependency. The values are the name
|
||||
expected by the current test.
|
||||
|
||||
"""
|
||||
|
||||
geometry_objects_read = variable(typ.Dict[str, str], value={})
|
||||
|
||||
@run_after("setup")
|
||||
def copy_geometry_objects_from_test_dependency(self):
|
||||
"""Copy geometry objects to be read to the stage directory.
|
||||
|
||||
The test will be skipped if no test dependency if provided, no
|
||||
geometry objects have been specified, or if the test dependency
|
||||
did not create a specified geometry object.
|
||||
"""
|
||||
self.skip_if(
|
||||
len(self.geometry_objects_read) < 0,
|
||||
f"Must provide a list of geometry objects being read by the test.",
|
||||
@@ -162,6 +195,8 @@ class GeometryObjectsReadMixin(GeometryObjectMixinBase):
|
||||
class GeometryObjectsWriteMixin(GeometryObjectMixinBase):
|
||||
"""Add regression tests for geometry objects.
|
||||
|
||||
The test will be skipped if no geometry objects have been specified.
|
||||
|
||||
Attributes:
|
||||
geometry_objects_write (list[str]): List of geometry objects to
|
||||
run regression checks on.
|
||||
@@ -173,7 +208,8 @@ class GeometryObjectsWriteMixin(GeometryObjectMixinBase):
|
||||
def add_geometry_object_regression_checks(self):
|
||||
"""Add a regression check for each geometry object.
|
||||
|
||||
The test will be skipped if no geometry objects have been specified.
|
||||
The test will be skipped if no geometry objects have been
|
||||
specified.
|
||||
"""
|
||||
self.skip_if(
|
||||
len(self.geometry_objects_write) < 0,
|
||||
@@ -203,6 +239,8 @@ class GeometryObjectsWriteMixin(GeometryObjectMixinBase):
|
||||
class GeometryViewMixin(GprMaxMixin):
|
||||
"""Add regression tests for geometry views.
|
||||
|
||||
The test will be skipped if no geometry views have been specified.
|
||||
|
||||
Attributes:
|
||||
geometry_views (list[str]): List of geometry views to run
|
||||
regression checks on.
|
||||
@@ -222,7 +260,8 @@ class GeometryViewMixin(GprMaxMixin):
|
||||
def add_geometry_view_regression_checks(self):
|
||||
"""Add a regression check for each geometry view.
|
||||
|
||||
The test will be skipped if no geometry views have been specified.
|
||||
The test will be skipped if no geometry views have been
|
||||
specified.
|
||||
"""
|
||||
self.skip_if(
|
||||
len(self.geometry_views) < 0,
|
||||
@@ -251,7 +290,17 @@ class MpiMixin(GprMaxMixin):
|
||||
|
||||
Attributes:
|
||||
mpi_layout (parameter[list[int]]): ReFrame parameter to specify
|
||||
how MPI tasks should be arranged.
|
||||
how MPI tasks should be arranged. This allows the same test
|
||||
to be run in multiple MPI configurations. E.g::
|
||||
|
||||
mpi_layout = parameter([
|
||||
[2, 2, 2],
|
||||
[3, 3, 3],
|
||||
[4, 4, 4],
|
||||
])
|
||||
|
||||
will generate three tests with 8, 27, and 64 MPI tasks
|
||||
respectively.
|
||||
"""
|
||||
|
||||
mpi_layout = parameter()
|
||||
@@ -267,7 +316,14 @@ class BScanMixin(GprMaxMixin):
|
||||
"""Test a B-scan model - a model with a moving source and receiver.
|
||||
|
||||
Attributes:
|
||||
num_models (parameter[int]): Number of models to run.
|
||||
num_models (parameter[int]): ReFrame parameter to specify the
|
||||
number of models to run. This allows the same test
|
||||
to be run in multiple configurations. E.g::
|
||||
|
||||
mpi_layout = parameter([10, 60])
|
||||
|
||||
will generate two tests that run 10 and 60 models
|
||||
respectively.
|
||||
"""
|
||||
|
||||
num_models = parameter()
|
||||
@@ -307,7 +363,11 @@ class BScanMixin(GprMaxMixin):
|
||||
|
||||
|
||||
class TaskfarmMixin(GprMaxMixin):
|
||||
"""Run test using GprMax taskfarm functionality."""
|
||||
"""Run test using GprMax taskfarm functionality.
|
||||
|
||||
Attributes:
|
||||
num_tasks (int): Number of tasks required by this test.
|
||||
"""
|
||||
|
||||
# TODO: Make this a required variabe, or create a new variable to
|
||||
# proxy it.
|
||||
|
||||
在新工单中引用
屏蔽一个用户