diff --git a/.github/actions/sample-project-setup/action.yml b/.github/actions/sample-project-setup/action.yml index 552ca96c..b7e32770 100644 --- a/.github/actions/sample-project-setup/action.yml +++ b/.github/actions/sample-project-setup/action.yml @@ -130,7 +130,7 @@ runs: # 2023/1/18: You still need install these even after installing stuff # with apt AND if the sysem python matches your current python. I don't # know why. - pip3 install empy \ + python3 -m pip install empy \ rospkg \ wheel \ pyparsing \ diff --git a/.github/actions/sierra-setup/action.yml b/.github/actions/sierra-setup/action.yml index 102eeeb0..0936c4bf 100644 --- a/.github/actions/sierra-setup/action.yml +++ b/.github/actions/sierra-setup/action.yml @@ -68,8 +68,14 @@ runs: run: | cd docs && make man && cd .. - python3 -m pip install . - python3 -m pip install .[devel] + # 2024-11-13 [JRH]: This works around an issue with msgpec failing to + # compile from source on OSX because of recent default compiler changes + # on OSX 13. Once a new release of mspspec is released with the fix, + # this should go away. + # python3 -m pip install git+https://github.com/jcrist/msgspec.git@main + python3 -m pip install nox coverage + # python3 -m pip install . + # python3 -m pip install .[devel] - which sierra-cli - sierra-cli --version + # which sierra-cli + # sierra-cli --version diff --git a/.github/workflows/core.yml b/.github/workflows/core.yml index a41326dc..891bba18 100644 --- a/.github/workflows/core.yml +++ b/.github/workflows/core.yml @@ -44,7 +44,7 @@ jobs: timeout_minutes: 3600 max_attempts: 3 shell: bash - command: ./scripts/core-integration-tests.sh -f ${{ matrix.function }} + command: nox -s core_integration -p ${{ matrix.python-version }} -- -f ${{ matrix.function }} - uses: actions/upload-artifact@v3 with: @@ -94,7 +94,7 @@ jobs: timeout_minutes: 3600 max_attempts: 3 shell: bash - command: ./scripts/${{ matrix.platform }}-integration-tests.sh -f bc_bivar_sanity_test + command: nox -s plugin_${{ matrix.platform }}_integration -p ${{ matrix.python-version }} -- -f bc_bivar_sanity_test - uses: actions/upload-artifact@v3 @@ -151,7 +151,7 @@ jobs: timeout_minutes: 3600 max_attempts: 3 shell: bash - command: ./scripts/${{ matrix.platform }}-integration-tests.sh -f stage1_bivar_test + command: nox -s plugin_${{ matrix.platform }}_integration -p ${{ matrix.python-version }} -- -f stage1_bivar_test - uses: actions/upload-artifact@v3 with: @@ -193,7 +193,7 @@ jobs: timeout_minutes: 3600 max_attempts: 3 shell: bash - command: ./scripts/argos-integration-tests.sh -f stage3_univar_test + command: nox -s plugin_argos_integration -p ${{ matrix.python-version }} -- -f stage3_univar_test - uses: actions/upload-artifact@v3 with: @@ -235,7 +235,7 @@ jobs: timeout_minutes: 3600 max_attempts: 3 shell: bash - command: ./scripts/argos-integration-tests.sh -f stage3_bivar_test + command: nox -s plugin_argos_integration -p ${{ matrix.python-version }} -- -f stage3_bivar_test - uses: actions/upload-artifact@v3 with: @@ -277,7 +277,7 @@ jobs: timeout_minutes: 3600 max_attempts: 3 shell: bash - command: ./scripts/argos-integration-tests.sh -f stage4_univar_test + command: nox -s plugin_argos_integration -p ${{ matrix.python-version }} -- -f stage4_univar_test - uses: actions/upload-artifact@v3 with: @@ -318,7 +318,7 @@ jobs: timeout_minutes: 3600 max_attempts: 3 shell: bash - command: ./scripts/argos-integration-tests.sh -f stage5_univar_test + command: nox -s plugin_argos_integration -p ${{ matrix.python-version }} -- -f stage5_univar_test - uses: actions/upload-artifact@v3 with: @@ -361,7 +361,7 @@ jobs: timeout_minutes: 3600 max_attempts: 3 shell: bash - command: ./scripts/argos-integration-tests.sh -f stage5_bivar_test + command: nox -s plugin_argos_integration -p ${{ matrix.python-version }} -- -f stage5_bivar_test - uses: actions/upload-artifact@v3 with: diff --git a/.github/workflows/coverage-top.yml b/.github/workflows/coverage-top.yml index de1755c1..2a2cbc6f 100644 --- a/.github/workflows/coverage-top.yml +++ b/.github/workflows/coverage-top.yml @@ -87,9 +87,6 @@ jobs: # ls -al ci-*-Linux-${{ matrix.python-version }}-coverage/.* || true # ls -al ci-*-Linux-${{ matrix.python-version }}-coverage/* || true - echo HERE1 - find . -name "ci-*-Linux-${{ matrix.python-version }}-coverage*" - echo HERE2 coverage \ combine \ $(find . -name "ci-*-Linux-${{ matrix.python-version }}-coverage*") diff --git a/.github/workflows/plugin.yml b/.github/workflows/plugin.yml index 3a21f312..14daa97c 100644 --- a/.github/workflows/plugin.yml +++ b/.github/workflows/plugin.yml @@ -79,7 +79,7 @@ jobs: with: timeout_minutes: 3600 max_attempts: 3 - command: ./scripts/argos-integration-tests.sh -f ${{ matrix.function }} -e hpc.local + command: nox -s plugin_argos_integration -p ${{ matrix.python-version }} -- -f ${{ matrix.function }} -e hpc.local - uses: actions/upload-artifact@v4 with: @@ -117,7 +117,10 @@ jobs: - name: Integration tests run: | - ./scripts/ros1robot-integration-tests.sh -f ${{ matrix.function }} -e hpc.local + nox \ + -s plugin_ros1robot_integration \ + -p ${{ matrix.python-version }} \ + -- -f ${{ matrix.function }} -e hpc.local - uses: actions/upload-artifact@v4 with: @@ -157,7 +160,10 @@ jobs: - name: Integration tests run: | - ./scripts/ros1gazebo-integration-tests.sh -f ${{ matrix.function }} -e hpc.local + nox \ + -s plugin_ros1gazebo_integration \ + -p ${{ matrix.python-version }} \ + -- -f ${{ matrix.function }} -e hpc.local - uses: actions/upload-artifact@v4 with: @@ -211,7 +217,10 @@ jobs: - name: Integration Tests if: matrix.platform != '' run: | - ./scripts/${{ matrix.platform }}-integration-tests.sh -f stage2_univar_test -e ${{ matrix.exec-env }} + nox \ + -s plugin_${{ matrix.platform }}_integration \ + -p ${{ matrix.python-version }} \ + -- -f stage2_univar_test -e ${{ matrix.exec-env }} - uses: actions/upload-artifact@v4 with: diff --git a/docs/index.rst b/docs/index.rst index 4ce5a2b3..3633cb53 100755 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,6 +3,8 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +.. _main: + =========================================================================== SIERRA (reSearch pIpEline for Reproducibility, Reusability, and Automation) =========================================================================== diff --git a/docs/man/sierra-cli.rst b/docs/man/sierra-cli.rst index 3ab77ba5..6b8b63f9 100755 --- a/docs/man/sierra-cli.rst +++ b/docs/man/sierra-cli.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-usage-cli: +.. _usage/cli: ###################### Command Line Interface @@ -12,7 +12,7 @@ If an option is given more than once, the last such occurrence is used. See also :manpage:`sierra-examples`. -:seealso:`ln-sierra-examples` +:seealso:`sierra-examples` =========== diff --git a/docs/src/api.rst b/docs/src/api.rst index a99caad8..6a7dc47a 100755 --- a/docs/src/api.rst +++ b/docs/src/api.rst @@ -1,3 +1,5 @@ +.. _api: + ============= API Reference ============= diff --git a/docs/src/contributing.rst b/docs/src/contributing.rst index 0a826518..181ab0a7 100755 --- a/docs/src/contributing.rst +++ b/docs/src/contributing.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-contributing: +.. _contributing: ============ Contributing @@ -11,8 +11,8 @@ All types of contributions are welcome: bugfixes, adding unit/integration tests, etc. If you're only have a little bit of time and/or are new to SIERRA, looking at the issues is a good place to look for places to contribute. If you have more time and/or want to give back to the community in a bigger way, see -:ref:`ln-sierra-roadmap` for some big picture ideas about where things might be -going, and help shape the future! +:ref:`roadmap` for some big picture ideas about where things might be going, and +help shape the future! Mechanics ========= @@ -70,7 +70,7 @@ repository. - ``models/`` - Model interfaces. - ``pipeline/`` - Core pipline code in 5 stages (see - :ref:`ln-sierra-usage-pipeline`). + :ref:`usage/pipeline`). - ``ros1/`` - Common :term:`ROS1` bindings. diff --git a/docs/src/description.rst b/docs/src/description.rst index 4229da10..879987e4 100755 --- a/docs/src/description.rst +++ b/docs/src/description.rst @@ -9,7 +9,6 @@ SIERRA is a command line tool and plugin framework for: - Improving the reproducibility of scientific research, particular in AI. It supports a wide range of platforms, execution environments, and experiment -input/output formats--see :ref:`ln-sierra-support-matrix` for details. A short -overview of the research automation SIERRA provides is here: -:ref:`ln-sierra-usage-pipeline`. To get started, see -:ref:`ln-sierra-getting-started`. +input/output formats--see :ref:`support-matrix` for details. A short overview +of the research automation SIERRA provides is here: :ref:`usage/pipeline`. To +get started, see :ref:`getting-started`. diff --git a/docs/src/faq.rst b/docs/src/faq.rst index a2b1f930..cadf0adf 100755 --- a/docs/src/faq.rst +++ b/docs/src/faq.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-faq: +.. _faq: === FAQ @@ -16,14 +16,14 @@ FAQ A: No! Experiment execution happens in stage 2, and graph generation happens in stage4. If you just want to add/remove lines from a graph, change the title, formatting, etc., you can just tell SIERRA to re-run stage 4 via - ``--pipeline 4``. See :ref:`ln-sierra-usage-pipeline` for more details about + ``--pipeline 4``. See :ref:`usage/pipeline` for more details about pipeline stages. #. Q: How to I resume an experiment which got killed part of the way through by an HPC scheduler for exceeding its job time limit ? A: Run SIERRA just as you did before, but add ``--exec-resume``, which will - tell SIERRA to pick up where it left off. See :ref:`ln-sierra-usage-cli` for + tell SIERRA to pick up where it left off. See :ref:`usage/cli` for the full cmdline reference. #. Q: How do I run a non-default set of pipeline stages, such as {3,4}? @@ -63,7 +63,7 @@ FAQ #. Q: SIERRA fails to run on my HPC environment? A: The most likely reason is that you don't have the necessary environment - variables set up--see :ref:`ln-sierra-exec-env-hpc` for details on what is + variables set up--see :ref:`plugins/exec-env/hpc` for details on what is required. #. Q: SIERRA doesn't generate any graphs during stage4/the graph I'm interested @@ -95,7 +95,7 @@ FAQ stages. The files generated in stages {3,4,5} are generated `from` the earlier results, so it is OK to overwrite those. However, if you are sure you want to overwrite stuff, you can pass ``--exp-overwrite`` to disable this - behavior during stages {1,2}. See also :ref:`ln-sierra-philosophy`. + behavior during stages {1,2}. See also :ref:`philosophy`. #. Q: I need to apply very precise/nuanced configuration to experiments that is too specific to be easily captured in a :term:`Batch Criteria` or other @@ -107,7 +107,7 @@ FAQ tags, modifying attributes. This is a good way to apply tricky configuration which doesn't really fit anywhere else, or to try out some "quick and dirty" changes to see if they do what you want before codifying them with a python - class (see :ref:`ln-sierra-tutorials-project-main-config` for details on how + class (see :ref:`tutorials/project/main-config` for details on how to do that). #. Q: SIERRA can't find a module it should be able to find via diff --git a/docs/src/getting_started.rst b/docs/src/getting_started.rst index 25d5361c..6d42537c 100755 --- a/docs/src/getting_started.rst +++ b/docs/src/getting_started.rst @@ -1,11 +1,11 @@ -.. _ln-sierra-getting-started: +.. _getting-started: =========================== Getting Started With SIERRA =========================== If you're looking for the "I just want to try out SIERRA without doing any work" -quickstart, see :ref:`ln-sierra-trial`. Otherwise, the steps to start using +quickstart, see :ref:`trial`. Otherwise, the steps to start using SIERRA are below. Basic Setup @@ -18,14 +18,14 @@ Basic Setup Seriously--it will make the later steps make more sense. -#. Check requirements at :ref:`ln-sierra-req` to how to organize your +#. Check requirements at :ref:`req` to how to organize your experimental inputs/template input files so they can be used with SIERRA, and if you need to modify the way your code outputs data so that SIERRA can process it. #. Install SIERRA - - Install SIERRA packages by following :ref:`ln-sierra-packages`. + - Install SIERRA packages by following :ref:`packages`. - Install OS packages (if you don't see your OS below you will have to find and install the equivalent packages). @@ -84,18 +84,23 @@ do so are: #. Select which :term:`Platform` SIERRA should target (what platform it targets will partially define how you create your project plugin). See - :ref:`ln-sierra-platform-plugins` for supported platforms. If your desired + :ref:`plugins/platform` for supported platforms. If your desired platform is not in the list, never fear! It's easy to create a new platform - plugin, see :ref:`ln-sierra-tutorials-plugin-platform`. + plugin, see :ref:`tutorials/plugin/platform`. -#. Setup the interface between your code and SIERRA by defining a SIERRA by - following :ref:`ln-sierra-tutorials-project-project`. +#. Setup the interface between your code and SIERRA by following + :ref:`tutorials/project/project`. #. Select an execution environment for SIERRA that matches your available - computational resources: :ref:`ln-sierra-exec-env-hpc` or - :ref:`ln-sierra-exec-env-robot`, following the appropriate setup guide. If + computational resources: + + - :ref:`plugins/exec-env/hpc` + + - :ref:`plugins/exec-env/realrobot` + + and following the appropriate setup guide. If there is nothing suitable, never fear! It's easy to create a new execution - environment plugin, see :ref:`ln-sierra-tutorials-plugin-exec-env`. + environment plugin, see :ref:`tutorials/plugin/exec-env`. Usage Setup =========== @@ -108,20 +113,20 @@ SIERRA! The steps to do so are: want to change across some range and see how system behavior changes, or doesn't change). Which criteria are available to use depends on your :term:`Platform`; if you don't see something suitable, you can - :ref:`Define A New Batch Criteria `. + :ref:`Define A New Batch Criteria `. -#. Look at the :ref:`ln-sierra-usage-cli` to understand how to invoke SIERRA in +#. Look at the :ref:`usage/cli` to understand how to invoke SIERRA in general. -#. Look at the :ref:`ln-sierra-usage-examples` to get ideas on how to craft your - own SIERRA invocation. If you get stuck, look at :ref:`ln-sierra-faq` for +#. Look at the :ref:`usage/examples` to get ideas on how to craft your + own SIERRA invocation. If you get stuck, look at :ref:`faq` for answers to common questions. #. Determine how to invoke SIERRA. At a minimum you need to tell it the following: - What platform you are targeting/want to run on: ``--platform``. See - :ref:`ln-sierra-platform-plugins` for details. + :ref:`plugins/platform` for details. - What project to load: ``--project``. This is used to: @@ -132,16 +137,16 @@ SIERRA! The steps to do so are: processing configuration from. - What template input file to use: ``--template-input-file``. See - :ref:`ln-sierra-tutorials-project-template-input-file` for requirements. + :ref:`tutorials/project/template-input-file` for requirements. - How many variations of the main settings for each experiment to run: ``--n-runs``. - Where it is running/how to run experiments: ``--exec-env``. See - :ref:`ln-sierra-exec-env-hpc` for available plugins. + :ref:`plugins/exec-env/hpc` for available plugins. - What controller to run: ``--controller``. See - :ref:`ln-sierra-tutorials-project-main-config` for details on how valid + :ref:`tutorials/project/main-config` for details on how valid controllers are defined for a :term:`Project`. Project dependent. - How large the arena should be, what block distribution type to use (for @@ -156,7 +161,7 @@ SIERRA! The steps to do so are: doing anything substantial. Full documentation of all command line options it accepts is in - :ref:`ln-sierra-usage-cli`, and there are many useful options that SIERRA + :ref:`usage/cli`, and there are many useful options that SIERRA accepts, so skimming the CLI docs is **very** worthwhile. .. IMPORTANT:: Generally speaking, do not try to run SIERRA on HPC @@ -172,11 +177,11 @@ SIERRA! The steps to do so are: Different platforms may require additional environments to be set. -#. Learn SIERRA's runtime :ref:`ln-sierra-usage-runtime-exp-tree`. When running, +#. Learn SIERRA's runtime :ref:`usage/runtime-exp-tree`. When running, SIERRA will create a (rather) large directory structure for you, so reading the docs is worthwhile to understand what the structure means, and to gain intuition into where to look for the inputs/outputs of different stages, etc., without having to search exhaustively through the filesystem. -#. Invoke SIERRA! Again, look at the :ref:`ln-sierra-usage-examples` for some +#. Invoke SIERRA! Again, look at the :ref:`usage/examples` for some ideas. diff --git a/docs/src/glossary.rst b/docs/src/glossary.rst index 3e66c787..e5ebbe27 100755 --- a/docs/src/glossary.rst +++ b/docs/src/glossary.rst @@ -1,3 +1,5 @@ +.. _glossary: + ======== Glossary ======== @@ -56,7 +58,7 @@ works/is designed the way it is, and to help you find your way around. separate projects with shared python code imported into each as needed. - Specified via ``--project`` on the cmdline. See :ref:`ln-sierra-usage-cli` for + Specified via ``--project`` on the cmdline. See :ref:`usage/cli` for documentation. Tick @@ -69,9 +71,9 @@ works/is designed the way it is, and to help you find your way around. A `variable` you wish to use with SIERRA to measure its effect on system behavior. A batch criteria can has a single axis (such as - :ref:`ln-sierra-platform-argos-bc-population-size`), in which case it is + :ref:`plugins/platform/argos/bc/population-size`), in which case it is called `univariate`, or have two axes (such as - :ref:`ln-sierra-platform-argos-bc-population-size` and another batch + :ref:`plugins/platform/argos/bc/population-size` and another batch criteria such as one defining sensor and actuator noise to apply to the robots), in which case it is called `bivariate`. @@ -100,7 +102,7 @@ works/is designed the way it is, and to help you find your way around. The batch criteria you can use depends on: - The :term:`Project` you have loaded, as each project can define their - own batch criteria (see :ref:`ln-sierra-tutorials-project-new-bc`). + own batch criteria (see :ref:`tutorials/project/new-bc`). - The :term:`Platform` you have selected, as each platform defines some basic batch criteria that any project/experiment can use. @@ -114,7 +116,7 @@ works/is designed the way it is, and to help you find your way around. generated by the selected :term:`Batch Criteria` to a template ``.argos`` file passed to SIERRA during stage 1 via ``--template-input-file``. - For example, for the :ref:`ln-sierra-platform-argos-bc-population-size` + For example, for the :ref:`plugins/platform/argos/bc/population-size` batch criteria, each experiment is defined by a single XML change to the provided ``.argos`` file: the number of robots in the swarm. Depending on the specifics you set for the `range` of sizes you are interested in, @@ -224,7 +226,7 @@ works/is designed the way it is, and to help you find your way around. ringbuffer of remembered objects and a decaying ringbuffer of remembered objects (i.e., an object is forgotten after some period of time even if it is not forced out of the ringbuffer by seeing a new object). See - :ref:`configuring ` your project. + :ref:`configuring ` your project. Model diff --git a/docs/src/matrix.rst b/docs/src/matrix.rst index e03957fd..3644c33d 100644 --- a/docs/src/matrix.rst +++ b/docs/src/matrix.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-support-matrix: +.. _support-matrix: ===================== SIERRA Support Matrix @@ -6,7 +6,7 @@ SIERRA Support Matrix SIERRA supports multiple :term:`Platforms ` which researchers can write code to target, as shown below. If your desired platform is not listed, -see the :ref:`ln-sierra-tutorials` for how to add it via a plugin. +see the :ref:`tutorials` for how to add it via a plugin. .. IMPORTANT:: In SIERRA terminology, platform != OS. If a SIERRA platform runs on a given OS, then SIERRA supports doing so; if it does not, @@ -40,7 +40,7 @@ see the :ref:`ln-sierra-tutorials` for how to add it via a plugin. SIERRA supports multiple HPC environments for execution of experiments in on HPC hardware (see :doc:`/src/exec_env/hpc`) and on real robots (see :doc:`/src/exec_env/robot`). If your desired execution environment is not -listed, see the :ref:`ln-sierra-tutorials` for how to add it via a plugin. +listed, see the :ref:`tutorials` for how to add it via a plugin. .. list-table:: :header-rows: 1 @@ -95,9 +95,9 @@ listed, see the :ref:`ln-sierra-tutorials` for how to add it via a plugin. later is required. SIERRA also supports multiple output formats for experimental outputs. If the -format for your experimental outputs is not listed, see the -:ref:`ln-sierra-tutorials` for how to add it via a plugin. SIERRA currently only -supports XML experimental inputs. +format for your experimental outputs is not listed, see the :ref:`tutorials` for +how to add it via a plugin. SIERRA currently only supports XML experimental +inputs. .. list-table:: :header-rows: 1 diff --git a/docs/src/packages.rst b/docs/src/packages.rst index e5843214..ed87dbff 100644 --- a/docs/src/packages.rst +++ b/docs/src/packages.rst @@ -1,10 +1,10 @@ -.. _ln-sierra-packages: +.. _packages: ============================= SIERRA Installation Reference ============================= -.. _ln-sierra-packages-pypi: +.. _packages/pypi: SIERRA PyPi Package =================== @@ -44,7 +44,7 @@ Installing SIERRA pip3 install sierra-research -.. _ln-sierra-packages-rosbridge: +.. _packages/rosbridge: SIERRA ROSBridge ================ diff --git a/docs/src/philosophy.rst b/docs/src/philosophy.rst index 2d8acc93..8796e9df 100644 --- a/docs/src/philosophy.rst +++ b/docs/src/philosophy.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-philosophy: +.. _philosophy: ======================== SIERRA Design Philosophy @@ -52,7 +52,7 @@ applications. When in doubt, SIERRA exposes relevant settings as configuration Swiss Army Pipeline =================== -SIERRAS 5-stage :ref:`Pipeline` is meant to be like a Swiss +SIERRAS 5-stage :ref:`Pipeline` is meant to be like a Swiss army knife, in that you can run (mostly) arbitrary subsets of the 5 stages and have everything work as you would expect it to, to help with tweaking experimental design, generated graphs, etc., with minimal headaches of "Grrr I diff --git a/docs/src/exec_env/hpc.rst b/docs/src/plugins/exec_env/hpc.rst similarity index 96% rename from docs/src/exec_env/hpc.rst rename to docs/src/plugins/exec_env/hpc.rst index 24b5d203..e2fec521 100755 --- a/docs/src/exec_env/hpc.rst +++ b/docs/src/plugins/exec_env/hpc.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-exec-env-hpc: +.. _plugins/exec-env/hpc: ================================= HPC Execution Environment Plugins @@ -12,9 +12,9 @@ environments that come with SIERRA are listed on this page. These plugins tested with the following platforms (they may work on other platforms out of the box too): -- :ref:`ln-sierra-platform-plugins-argos` +- :ref:`plugins/platform/argos` -- :ref:`ln-sierra-platform-plugins-ros1gazebo` +- :ref:`plugins/platform/ros1gazebo` SIERRA makes the following assumptions about the HPC environments corresponding to the plugins listed on this page: @@ -44,7 +44,7 @@ to the plugins listed on this page: if everything ran on a common filesystem prior to running any later stages. -.. _ln-sierra-hpc-plugins-local: +.. _plugins/exec-env/hpc/local: Local HPC Plugin ================ @@ -70,7 +70,7 @@ The # threads per :term:`experimental run ` is defined with ``--physics-n-engines``, and that option is required for this HPC environment during stage 1. -.. _ln-sierra-hpc-plugins-pbs: +.. _plugins/exec-env/hpc/pbs: PBS HPC Plugin ============== @@ -133,7 +133,7 @@ The following environmental variables are used in the PBS HPC environment: variables automatically, and because GNU parallel starts another level of child shells. -.. _ln-sierra-hpc-plugins-slurm: +.. _plugins/exec-env/hpc/slurm: SLURM HPC Plugin ================ @@ -208,7 +208,7 @@ The following environmental variables are used in the SLURM HPC environment: automatically, because GNU parallel starts another level of child shells. -.. _ln-sierra-hpc-plugins-adhoc: +.. _plugins/exec-env/hpc/adhoc: Adhoc HPC Plugin ================ diff --git a/docs/src/exec_env/index.rst b/docs/src/plugins/exec_env/index.rst similarity index 84% rename from docs/src/exec_env/index.rst rename to docs/src/plugins/exec_env/index.rst index 3c8d1db4..9cc1a584 100644 --- a/docs/src/exec_env/index.rst +++ b/docs/src/plugins/exec_env/index.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-exec-env-plugins: +.. _plugins/exec-env: ============================= Execution Environment Plugins diff --git a/docs/src/exec_env/robot.rst b/docs/src/plugins/exec_env/robot.rst similarity index 90% rename from docs/src/exec_env/robot.rst rename to docs/src/plugins/exec_env/robot.rst index 816aa8f5..4aaea671 100755 --- a/docs/src/exec_env/robot.rst +++ b/docs/src/plugins/exec_env/robot.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-exec-env-robot: +.. _plugins/exec-env/realrobot: ======================================== Real Robot Execution Environment Plugins @@ -11,9 +11,9 @@ this page. These plugins are tested with the following platforms (they may work with other platforms out of the box too): -- :ref:`ln-sierra-platform-plugins-ros1robot` +- :ref:`plugins/platform/ros1robot` -.. _ln-sierra-exec-env-robot-plugins-turtlebot3: +.. _plugins/exec-env/real-robot/turtlebot3: Turtlebot3 ========== diff --git a/docs/src/plugins/index.rst b/docs/src/plugins/index.rst index 9d2d355d..b7d0a695 100644 --- a/docs/src/plugins/index.rst +++ b/docs/src/plugins/index.rst @@ -1,3 +1,5 @@ +.. _plugins: + ============== SIERRA Plugins ============== @@ -6,6 +8,6 @@ SIERRA Plugins :maxdepth: 1 :caption: Contents: - ../platform/index.rst - ../exec_env/index.rst - ../storage/index.rst + platform/index.rst + exec_env/index.rst + storage/index.rst diff --git a/docs/src/platform/argos/batch_criteria.rst b/docs/src/plugins/platform/argos/batch_criteria.rst similarity index 79% rename from docs/src/platform/argos/batch_criteria.rst rename to docs/src/plugins/platform/argos/batch_criteria.rst index 87a9a223..6c077fe3 100755 --- a/docs/src/platform/argos/batch_criteria.rst +++ b/docs/src/plugins/platform/argos/batch_criteria.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-platform-argos-bc: +.. _plugins/platform/argos/bc: ============== Batch Criteria @@ -9,24 +9,24 @@ short version is that they are the core of SIERRA--how to get it to DO stuff for you. The following batch criteria are defined which can be used with any :term:`Project`. -- :ref:`ln-sierra-platform-argos-bc-population-size` -- :ref:`ln-sierra-platform-argos-bc-population-constant-density` -- :ref:`ln-sierra-platform-argos-bc-population-variable-density` +- :ref:`plugins/platform/argos/bc/population-size` +- :ref:`plugins/platform/argos/bc/population-constant-density` +- :ref:`plugins/platform/argos/bc/population-variable-density` -.. _ln-sierra-platform-argos-bc-population-size: +.. _plugins/platform/argos/bc/population-size: Population Size =============== Changing the population size to investigate behavior across scales within a static arena size (i.e., variable density). This criteria is functionally -identical to :ref:`ln-sierra-platform-argos-bc-population-variable-density` in +identical to :ref:`plugins/platform/argos/bc/population-variable-density` in terms of changes to the template XML file, but has a different semantic meaning which can make generated deliverables more immediately understandable, depending on the context of what is being investigated (e.g., population size vs. population density on the X axis). -.. _ln-sierra-platform-argos-bc-population-size-cmdline: +.. _plugins/platform/argos/bc/population-size-cmdline: Cmdline Syntax -------------- @@ -56,7 +56,7 @@ Examples - ``population_size.Linear10.C2``: Static population sizes 5...10 (2) -.. _ln-sierra-platform-argos-bc-population-constant-density: +.. _plugins/platform/argos/bc/population-constant-density: Constant Population Density =========================== @@ -66,11 +66,11 @@ size/arena size ratio to investigate behavior across scales. .. NOTE:: This criteria is for `constant` density of robots as population sizes increase. For `variable` robot density, use - :ref:`ln-sierra-platform-argos-bc-population-size` or - :ref:`ln-sierra-platform-argos-bc-population-variable-density`. + :ref:`plugins/platform/argos/bc/population-size` or + :ref:`plugins/platform/argos/bc/population-variable-density`. -.. _ln-sierra-platform-argos-bc-population-constant-density-cmdline: +.. _plugins/platform/argos/bc/population-constant-density-cmdline: Cmdline Syntax -------------- @@ -92,15 +92,14 @@ Examples dimensions will increase by 16 in both X and Y for each experiment in the batch (4 total). -.. _ln-sierra-platform-argos-bc-population-variable-density: - +.. _plugins/platform/argos/bc/population-variable-density: Variable Population Density =========================== Changing the population size to investigate behavior across scales within a static arena size. This criteria is functionally identical to -:ref:`ln-sierra-platform-argos-bc-population-size` in terms of changes to the +:ref:`plugins/platform/argos/bc/population-size` in terms of changes to the template XML file, but has a different semantic meaning which can make generated deliverables more immediately understandable, depending on the context of what is being investigated (e.g., population density vs. population size on the X @@ -108,9 +107,9 @@ axis). .. NOTE:: This criteria is for `variable` density of robots as population sizes increase. For `constant` robot density, use - :ref:`ln-sierra-platform-argos-bc-population-constant-density`. + :ref:`plugins/platform/argos/bc/population-constant-density`. -.. _ln-sierra-platform-argos-bc-population-variable-density-cmdline: +.. _platform/argos/bc/population-variable-density-cmdline: Cmdline Syntax -------------- diff --git a/docs/src/platform/argos/index.rst b/docs/src/plugins/platform/argos/index.rst similarity index 81% rename from docs/src/platform/argos/index.rst rename to docs/src/plugins/platform/argos/index.rst index 7fbd3fc2..97bdb588 100644 --- a/docs/src/platform/argos/index.rst +++ b/docs/src/plugins/platform/argos/index.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-platform-plugins-argos: +.. _plugins/platform/argos: ============== ARGoS Platform @@ -26,5 +26,5 @@ uses to seed each experiment. :term:`Project` code should use this mechanism or a similar random seed generator manager seeded by the same value so that experiments can be reproduced exactly. By default SIERRA does not overwrite its generated random seeds for each experiment once generated; you can override with -``--no-preserve-seeds``. See :ref:`ln-sierra-tutorials-project-template-input-file` and -:ref:`ln-sierra-req-exp` for details on the format of the provided seed. +``--no-preserve-seeds``. See :ref:`tutorials/project/template-input-file` and +:ref:`req/exp` for details on the format of the provided seed. diff --git a/docs/src/platform/index.rst b/docs/src/plugins/platform/index.rst similarity index 92% rename from docs/src/platform/index.rst rename to docs/src/plugins/platform/index.rst index c40f775e..64586ef7 100644 --- a/docs/src/platform/index.rst +++ b/docs/src/plugins/platform/index.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-platform-plugins: +.. _plugins/platform: ================ Platform Plugins diff --git a/docs/src/platform/ros1gazebo/batch_criteria.rst b/docs/src/plugins/platform/ros1gazebo/batch_criteria.rst similarity index 86% rename from docs/src/platform/ros1gazebo/batch_criteria.rst rename to docs/src/plugins/platform/ros1gazebo/batch_criteria.rst index 8a02c470..4843b3b7 100644 --- a/docs/src/platform/ros1gazebo/batch_criteria.rst +++ b/docs/src/plugins/platform/ros1gazebo/batch_criteria.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-platform-ros1gazebo-bc: +.. _plugins/platforms/ros1gazebo/bc: ============== Batch Criteria @@ -9,9 +9,9 @@ short version is that they are the core of SIERRA--how to get it to DO stuff for you. The following batch criteria are defined which can be used with any :term:`Project`. -- :ref:`ln-sierra-platform-ros1gazebo-bc-population-size` +- :ref:`plugins/platform/ros1gazebo/bc/population-size` -.. _ln-sierra-platform-ros1gazebo-bc-population-size: +.. _plugins/platform/ros1gazebo/bc/population-size: System Population Size ====================== @@ -19,7 +19,7 @@ System Population Size Changing the system size to investigate behavior across scales within a static arena size (i.e., variable density). Systems are homogeneous. -.. _ln-sierra-platform-ros1gazebo-bc-population-size-cmdline: +.. _plugins/platform/ros1gazebo/bc/population-size-cmdline: Cmdline Syntax -------------- diff --git a/docs/src/platform/ros1gazebo/index.rst b/docs/src/plugins/platform/ros1gazebo/index.rst similarity index 80% rename from docs/src/platform/ros1gazebo/index.rst rename to docs/src/plugins/platform/ros1gazebo/index.rst index e486d7a7..ee96684d 100644 --- a/docs/src/platform/ros1gazebo/index.rst +++ b/docs/src/plugins/platform/ros1gazebo/index.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-platform-plugins-ros1gazebo: +.. _plugins/platform/ros1gazebo: ==================== ROS1+Gazebo Platform @@ -9,7 +9,7 @@ This platform can be selected via ``--platform=platform.ros1gazebo``. This is the platform on which SIERRA will run experiments using the :term:`Gazebo` simulator and :term:`ROS1`. It cannot be used to run experiments on real robots. To use this platform, you must setup the -:ref:`SIERRA ROSBridge `. +:ref:`SIERRA ROSBridge `. Worlds within ROS1+Gazebo are infinite from the perspective of physics engines, even though a finite area shows up in rendering. So, to place robots randomly in @@ -36,7 +36,7 @@ Random Seeding For Reproducibility ROS1+Gazebo do not provide a random number generator manager, but SIERRA provides random seeds to each :term:`Experimental Run` which :term:`Project` code should use to manage random number generation, if needed, to maximize -reproducability. See :ref:`ln-sierra-tutorials-project-template-input-file` and -:ref:`ln-sierra-req-exp` for details on the format of the provided seed. By default -SIERRA does not overwrite its generated random seeds for each experiment once +reproducability. See :ref:`tutorials/project/template-input-file` and +:ref:`req/exp` for details on the format of the provided seed. By default SIERRA +does not overwrite its generated random seeds for each experiment once generated; you can override with ``--no-preserve-seeds``. diff --git a/docs/src/platform/ros1robot/batch_criteria.rst b/docs/src/plugins/platform/ros1robot/batch_criteria.rst similarity index 86% rename from docs/src/platform/ros1robot/batch_criteria.rst rename to docs/src/plugins/platform/ros1robot/batch_criteria.rst index e5751f5d..424027b9 100644 --- a/docs/src/platform/ros1robot/batch_criteria.rst +++ b/docs/src/plugins/platform/ros1robot/batch_criteria.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-platform-ros1robot-bc: +.. _plugins/platform/ros1robot/bc: ============== Batch Criteria @@ -9,9 +9,9 @@ short version is that they are the core of SIERRA--how to get it to DO stuff for you. The following batch criteria are defined which can be used with any :term:`Project`. -- :ref:`ln-sierra-platform-ros1robot-bc-population-size` +- :ref:`plugins/platform/ros1robot/bc/population-size` -.. _ln-sierra-platform-ros1robot-bc-population-size: +.. _plugins/platform/ros1robot/bc/population-size: System Population Size ====================== @@ -19,7 +19,7 @@ System Population Size Changing the system size to investigate behavior across scales within a static arena size (i.e., variable density). Systems are homogeneous. -.. _ln-sierra-platform-ros1robot-bc-population-size-cmdline: +.. _plugins/platform/ros1robot/bc/population-size/cmdline: ``population_size.{model}{N}[.C{cardinality}]`` diff --git a/docs/src/platform/ros1robot/index.rst b/docs/src/plugins/platform/ros1robot/index.rst similarity index 79% rename from docs/src/platform/ros1robot/index.rst rename to docs/src/plugins/platform/ros1robot/index.rst index 336d027d..399f4bca 100644 --- a/docs/src/platform/ros1robot/index.rst +++ b/docs/src/plugins/platform/ros1robot/index.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-platform-plugins-ros1robot: +.. _plugins/platform/ros1robot: =================== ROS1+Robot Platform @@ -9,11 +9,11 @@ This platform can be selected via ``--platform=platform.ros1robot``. This is the platform on which SIERRA will run experiments using :term:`ROS1` on a real robot of your choice. To use this platform, you must setup the -:ref:`SIERRA ROSBridge `. This is a generic +:ref:`SIERRA ROSBridge `. This is a generic platform meant to work with most real robots which :term:`ROS1` supports, and as a starting point to derive more specific platform configuration for a given robot (if needed). For all execution environments using this platform (see -:ref:`ln-sierra-exec-env-robot` for examples), SIERRA will run experiments +:ref:`plugins/exec-env/robot` for examples), SIERRA will run experiments spread across multiple robots using GNU parallel. SIERRA designates the host machine as the ROS master, and allows you to @@ -37,10 +37,10 @@ Random Seeding For Reproducibility ROS do not provide a random number generator manager, but SIERRA provides random seeds to each :term:`Experimental Run` which :term:`Project` code should use to manage random number generation, if needed, to maximize reproducability. See -:ref:`ln-sierra-tutorials-project-template-input-file` and -:ref:`ln-sierra-req-exp` for details on the format of the provided seed. By -default SIERRA does not overwrite its generated random seeds for each experiment -once generated; you can override with ``--no-preserve-seeds``. +:ref:`tutorials/project/template-input-file` and :ref:`req/exp` for details on +the format of the provided seed. By default SIERRA does not overwrite its +generated random seeds for each experiment once generated; you can override with +``--no-preserve-seeds``. Real Robot Considerations ========================= @@ -56,17 +56,17 @@ invocation: - The robots have static IP addresses, or are always allocated an IP from a known set so you can pass the set of IPs to SIERRA to use. This set of IP address/hostnames can be explicitly passed to SIERRA via cmdline (see - :ref:`ln-sierra-usage-cli`) or implicitly passed via + :ref:`usage/cli`) or implicitly passed via :envvar:`SIERRA_NODEFILE`. - The ROS environment is setup either in the .bashrc for the robot login user, or the necessary bits are in a script which SIERRA sources on login to each robot (this is a configuration parameter--see - :ref:`ln-sierra-tutorials-project-main-config`). + :ref:`tutorials/project/main-config`). - ROS does not provide a way to say "Run this experiment for X seconds", so SIERRA inserts its own timekeeper node into each robot which will exit after X seconds and take the roslaunch process with it on each robot and/or the master node. -See also :ref:`ln-sierra-req-code-ros1robot`. +See also :ref:`req/code/ros1robot`. diff --git a/docs/src/storage/index.rst b/docs/src/plugins/storage/index.rst similarity index 84% rename from docs/src/storage/index.rst rename to docs/src/plugins/storage/index.rst index 389b91d4..99493514 100644 --- a/docs/src/storage/index.rst +++ b/docs/src/plugins/storage/index.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-storage-plugins: +.. _plugins/storage: =============== Storage Plugins @@ -7,9 +7,9 @@ Storage Plugins SIERRA is capable of reading :term:`Experimental Run` output data in a number of formats. Supported formats that come with SIERRA are: -- :ref:`ln-sierra-storage-plugins-csv` +- :ref:`plugins/storage/csv` -.. _ln-sierra-storage-plugins-csv: +.. _plugins/storage/csv: CSV === diff --git a/docs/src/requirements.rst b/docs/src/requirements.rst index 5fdb1cba..87f3a187 100644 --- a/docs/src/requirements.rst +++ b/docs/src/requirements.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-req: +.. _req: ========================== Requirements To Use SIERRA @@ -9,7 +9,7 @@ in a more or less out-of-the-box fashion. Because SIERRA is highly modular, use cases which don't meet one or more of the parameters described below can likely still be accommodated with an appropriate plugin. -.. _ln-sierra-req-OS: +.. _req/os: OS Requirements =============== @@ -37,7 +37,7 @@ Python Requirements Python 3.8+. Tested with 3.8-3.10. It may work for newer versions, probably won't for older. -.. _ln-sierra-req-exp: +.. _req/exp: Experimental Definition Requirements ==================================== @@ -68,7 +68,7 @@ SIERRA restricts the content of this file in a few modest ways. relatively straightforward for projects to read experimental definitions from XML. -#. No reserved XML tokens are present. See :ref:`ln-sierra-req-xml` for details. +#. No reserved XML tokens are present. See :ref:`req/xml` for details. #. All experiments from which you want to generate statistics/graphs are: @@ -107,7 +107,7 @@ SIERRA restricts the content of this file in a few modest ways. :term:`Platforms ` may have additional experiment requirements, as shown below. -.. _ln-sierra-req-exp-argos: +.. _req/exp/argos: :term:`ARGoS` Platform ---------------------- @@ -149,7 +149,7 @@ shown below. ... - See also :ref:`ln-sierra-tutorials-project-main-config`. + See also :ref:`tutorials/project/main-config`. :term:`ROS1`-based Platforms ---------------------------- @@ -166,7 +166,7 @@ These requirements apply to any :term:`Platform` which uses :term:`ROS1` (e.g., parameters you want to be able to modify with SIERRA must be present in a single ``.launch`` file. Other parameters you don't want to modify with SIERRA can be present in other ``.launch`` or ``.world`` files, and using the - usual ```` mechanism. See also :ref:`ln-sierra-philosophy`. + usual ```` mechanism. See also :ref:`philosophy`. #. Within the template ``.launch`` file (``--template-input-file``), the root XML tag must be ```` . The @@ -175,13 +175,13 @@ These requirements apply to any :term:`Platform` which uses :term:`ROS1` (e.g., standard, which states that there can be only a single root element (i.e., you can't have a ```` element and a ```` element both at the root level--see options below). See - :ref:`ln-sierra-tutorials-project-template-input-file` for details of required + :ref:`tutorials/project/template-input-file` for details of required structure of passed ``--template-input-file``, and what changes are applied to them by SIERRA to use with ROS. :term:`Projects ` can choose either of the following options for specifying controller parameters. See - :ref:`ln-sierra-tutorials-project-template-input-file` for further details of + :ref:`tutorials/project/template-input-file` for further details of required structure of passed ``--template-input-file``, and what changes are applied to them by SIERRA to use with ROS, depending on the option chosen. @@ -208,7 +208,7 @@ These requirements apply to any :term:`Platform` which uses :term:`ROS1` (e.g., ``.launch`` file. All SIERRA configuration exposed via XML parameters uses the ROS - parameter server. See :ref:`ln-sierra-tutorials-project-template-input-file` + parameter server. See :ref:`tutorials/project/template-input-file` for specifics. #. ROS does not currently provide a way to shut down after a given # of @@ -242,7 +242,7 @@ Additional Platform Requirements via (a) a start barrier triggered from the master node, or else timestamp the data from robots and marshal it on the master node in some fashion. The :ref:`SIERRA ROSBridge - ` provides some support for (a). + ` provides some support for (a). - Mount a shared directory on each robot where it can write its data, and then after execution finishes but before your code exits you process the @@ -256,7 +256,7 @@ Additional Platform Requirements - Record some/all messages sent and received via one or more ROSbag files, and use these files directly as a "database" to query during stage 3. This would require writing a SIERRA storage plugin (see - :ref:`ln-sierra-tutorials-plugin-storage`). + :ref:`tutorials/plugin/storage`). .. IMPORTANT:: This method requires that whatever is recorded into the ROSbag file is per-run, not per-robot; that is, if a given @@ -265,7 +265,7 @@ Additional Platform Requirements then sent to a dedicated topic to be recorded. -.. _ln-sierra-req-code: +.. _req/code: Requirements For Project Code ============================= @@ -280,7 +280,7 @@ your code does not meet these assumptions, then you will need to make some #. Project code uses a configurable random seed. While this is not technically `required` for use with SIERRA, all research code should do this for - reproducibility. See :ref:`ln-sierra-platform-plugins` for platform-specific + reproducibility. See :ref:`plugins/platform` for platform-specific details about random seeding and usage with SIERRA. #. :term:`Experimental Runs` can be launched from `any` @@ -293,25 +293,25 @@ your code does not meet these assumptions, then you will need to make some outputs need to appear in a directory such as ``$HOME/exp/research/simulations/sim1/outputs``. The directory within the experimental run root which SIERRA looks for simulation outputs is configured - via YAML; see :ref:`ln-sierra-tutorials-project-main-config` for details. + via YAML; see :ref:`tutorials/project/main-config` for details. - For HPC execution environments (see :ref:`ln-sierra-exec-env-hpc`), this requirement + For HPC execution environments (see :ref:`plugins/exec-env/hpc`), this requirement is easy to meet. For real robot execution environments - (see :ref:`ln-sierra-exec-env-robot`), this can be more difficult to meet. + (see :ref:`plugins/exec-env/realrobot`), this can be more difficult to meet. #. All experimental run outputs are in a format that SIERRA understands within - the output directory for the run. See :ref:`ln-sierra-storage-plugins` for which + the output directory for the run. See :ref:`plugins/storage` for which output formats are currently understood by SIERRA. If your output format is not in the list, never fear! It's easy to create a new storage plugin, see - :ref:`ln-sierra-tutorials-plugin-storage`. + :ref:`tutorials/plugin/storage`. ARGoS Platform -------------- #. ``--project`` matches the name of the C++ library for the project (i.e. ``--project.so``), unless ``library_name`` is present in - ``sierra.main.run`` YAML config. See :ref:`ln-sierra-tutorials-project-main-config` - for details. For example if you pass ``--project=project-awesome``, then + ``sierra.main.run`` YAML config. See :ref:`tutorials/project/main-config` + for details. For example if you pass ``--project=project/awesome``, then SIERRA will tell ARGoS to search in ``proj-awesome.so`` for both loop function and controller definitions via XML changes, unless you specify otherwise in project configuration. You *cannot* put the @@ -324,7 +324,7 @@ ROS1+Gazebo Project Platform #. :envvar:`ROS_PACKAGE_PATH` is set up properly prior to invoking SIERRA. -.. _ln-sierra-req-code-ros1robot: +.. _req/code/ros1robot: ROS1+Robot Platform ------------------- @@ -338,20 +338,20 @@ ROS1+Robot Platform verify this by trying to launch a ROS master on each robot: if it launches without errors, then these values are setup properly. -.. _ln-sierra-req-models: +.. _req/models: ============================ Model Framework Requirements ============================ When running models during stage 4 (see -:ref:`ln-sierra-tutorials-project-models`) SIERRA requires that: +:ref:`tutorials/project/models`) SIERRA requires that: - All models return :class:`pandas.DataFrame` (if they don't do this natively, then their python bindings will have to do it). This is enforced by the interfaces models must implement. -.. _ln-sierra-req-xml: +.. _req/xml: XML Content Requirements ======================== @@ -364,16 +364,16 @@ that including these tokens would cause problems, because SIERRA looks for them in `specific` places in the ``--template-input-file``, they should be avoided. - ``__CONTROLLER__`` - Tag used when as a placeholder for selecting which - controller present in an input file (if there are multiple) a user wants - to use for a specific :term:`Experiment`. Can appear in XML attributes. This + controller present in an input file (if there are multiple) a user wants to + use for a specific :term:`Experiment`. Can appear in XML attributes. This makes auto-population of the controller name based on the ``--controller`` argument and the contents of ``controllers.yaml`` (see - :ref:`ln-sierra-tutorials-project-main-config` for details) in template input files - possible. + :ref:`tutorials/project/main-config` for details) in template input + files possible. - ``__UUID__`` - XPath substitution optionally used when a :term:`ROS1` platform is selected in ``controllers.yaml`` (see - :ref:`ln-sierra-tutorials-project-main-config`) when adding XML tags to force + :ref:`tutorials/project/main-config`) when adding XML tags to force addition of the tag once for every robot in the experiment, with ``__UUID__`` replaced with the configured robot prefix concatenated with its numeric ID (0-based). Can appear in XML attributes. diff --git a/docs/src/roadmap.rst b/docs/src/roadmap.rst index 3c052b25..2ad48480 100644 --- a/docs/src/roadmap.rst +++ b/docs/src/roadmap.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-roadmap: +.. _roadmap: =================== Development Roadmap diff --git a/docs/src/trial.rst b/docs/src/trial.rst index 356a43a9..824898de 100755 --- a/docs/src/trial.rst +++ b/docs/src/trial.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-trial: +.. _trial: ================= Trying Out SIERRA @@ -177,7 +177,7 @@ you clone things somewhere else. . /path/to/setup.bash -#. Run SIERRA (invocation inspired by :ref:`ln-sierra-usage-examples`). +#. Run SIERRA (invocation inspired by :ref:`usage/examples`). .. tabs:: @@ -207,7 +207,7 @@ you clone things somewhere else. so to run. After it finishes, you can go to ``$HOME/research/exp`` and find all the simulation outputs, including camera ready graphs! For an explanation of SIERRA's runtime directory tree, see - :ref:`ln-sierra-usage-runtime-exp-tree`. You can also run the same experiment + :ref:`usage/runtime-exp-tree`. You can also run the same experiment again, and it will overwrite the previous one because you passed ``--exp-overwrite``. diff --git a/docs/src/tutorials/hpc/cluster_setup.rst b/docs/src/tutorials/hpc/cluster_setup.rst index a97f10d0..31b5e86e 100755 --- a/docs/src/tutorials/hpc/cluster_setup.rst +++ b/docs/src/tutorials/hpc/cluster_setup.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials-hpc-cluster-setup: +.. _tutorials/hpc/cluster-setup: ================= HPC Cluster Setup @@ -9,8 +9,8 @@ your local machine. If you haven't done that yet--shoo! This setup applies to the following SIERRA HPC cluster environments: -- :ref:`ln-sierra-hpc-plugins-pbs` -- :ref:`ln-sierra-hpc-plugins-slurm` +- :ref:`tutorials/hpc/plugins/pbs` +- :ref:`tutorial/hpc/plugins/slurm` ARGoS Setup on HPC Clusters =========================== @@ -35,7 +35,7 @@ The steps to properly configure the C++ libraries for :term:`ARGoS` and your Once ARGoS/your C++ code has been built, you can setup SIERRA: -#. Install SIERRA package by following the instructions in :ref:`ln-sierra-packages`. +#. Install SIERRA package by following the instructions in :ref:`packages`. #. Verify GNU :program:`parallel` is installed; if it is not installed, ask your cluster admin to install it for you. @@ -46,7 +46,7 @@ Once ARGoS/your C++ code has been built, you can setup SIERRA: directory with the EXACT name you want it to be callable with on the cmdline via ``--project``. -#. Read the documentation for :ref:`ln-sierra-exec-env-hpc`, and select and +#. Read the documentation for :ref:`plugins/exec-env/hpc`, and select and appropriate plugin to use. Be sure to define all necessary environment variables!! diff --git a/docs/src/tutorials/hpc/local_setup.rst b/docs/src/tutorials/hpc/local_setup.rst index a0d4f538..e7055264 100644 --- a/docs/src/tutorials/hpc/local_setup.rst +++ b/docs/src/tutorials/hpc/local_setup.rst @@ -1,8 +1,8 @@ -.. _ln-sierra-tutorials-hpc-local-setup: +.. _tutorials/hpc/local-setup: =============== HPC Local Setup =============== To set up SIERRA for HPC on your local machine, follow -:ref:`ln-sierra-getting-started`. +:ref:`getting-started`. diff --git a/docs/src/tutorials/index.rst b/docs/src/tutorials/index.rst index c2380d7d..39075124 100755 --- a/docs/src/tutorials/index.rst +++ b/docs/src/tutorials/index.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials: +.. _tutorials: ===================================== Configuration and Extension Tutorials @@ -7,7 +7,7 @@ Configuration and Extension Tutorials This page contains tutorials to setup and/or extend SIERRA according to your needs. -.. _ln-sierra-tutorials-project: +.. _tutorials/project: .. toctree:: :maxdepth: 1 @@ -24,7 +24,7 @@ needs. project/hooks.rst project/models.rst -.. _ln-sierra-tutorials-hpc: +.. _tutorials/hpc: .. toctree:: :maxdepth: 1 @@ -33,7 +33,7 @@ needs. hpc/cluster_setup.rst hpc/local_setup.rst -.. _ln-sierra-tutorials-extension: +.. _tutorials/extension: .. toctree:: :maxdepth: 1 diff --git a/docs/src/tutorials/plugin/exec_env/index.rst b/docs/src/tutorials/plugin/exec_env/index.rst index 751ebe99..8b7aa9e6 100755 --- a/docs/src/tutorials/plugin/exec_env/index.rst +++ b/docs/src/tutorials/plugin/exec_env/index.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials-plugin-exec-env: +.. _tutorials/plugin/exec-env: =========================================== Creating a New Execution Environment Plugin @@ -11,7 +11,7 @@ For the purposes of this tutorial, I will assume you are creating a new HPC If you are creating a new HPC plugin for an existing platform that comes with SIERRA (e.g., :term:`ARGoS`) you have two options: -#. Following :ref:`ln-sierra-tutorials-plugin-platform` to create a new platform +#. Following :ref:`tutorials/plugin/platform` to create a new platform to add support for your execution environment within the existing platform. #. Open a pull request for SIERRA with your created HPC plugin to get it into diff --git a/docs/src/tutorials/plugin/platform/index.rst b/docs/src/tutorials/plugin/platform/index.rst index 2a3828a0..07a3d53a 100644 --- a/docs/src/tutorials/plugin/platform/index.rst +++ b/docs/src/tutorials/plugin/platform/index.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials-plugin-platform: +.. _tutorials/plugin/platform: ============================== Creating a New Platform Plugin diff --git a/docs/src/tutorials/plugin/storage/index.rst b/docs/src/tutorials/plugin/storage/index.rst index fb615ef2..7336a108 100755 --- a/docs/src/tutorials/plugin/storage/index.rst +++ b/docs/src/tutorials/plugin/storage/index.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials-plugin-storage: +.. _tutorials/plugin/storage: ============================= Creating a New Storage Plugin diff --git a/docs/src/tutorials/project/cmdline.rst b/docs/src/tutorials/project/cmdline.rst index d089c4ec..97bc63e5 100644 --- a/docs/src/tutorials/project/cmdline.rst +++ b/docs/src/tutorials/project/cmdline.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials-project-cmdline: +.. _tutorials/project/cmdline: ============================ Extending the SIERRA Cmdline diff --git a/docs/src/tutorials/project/generators.rst b/docs/src/tutorials/project/generators.rst index 854cca43..73cd04b0 100755 --- a/docs/src/tutorials/project/generators.rst +++ b/docs/src/tutorials/project/generators.rst @@ -1,10 +1,10 @@ -.. _ln-sierra-tutorials-project-generators: +.. _tutorials/project/generators: ======================= Generator Configuration ======================= -.. _ln-sierra-tutorials-project-generators-scenario-config: +.. _tutorials/project/generators/scenario-config: Per-Scenario Configuration ========================== @@ -71,7 +71,7 @@ you specify, you need to: ... -.. _ln-sierra-tutorials-project-generators-sim-config: +.. _tutorials/project/generators/sim-config: Per-Experimental Run Configuration ================================== diff --git a/docs/src/tutorials/project/graphs_config.rst b/docs/src/tutorials/project/graphs_config.rst index c6581c7f..bb047066 100755 --- a/docs/src/tutorials/project/graphs_config.rst +++ b/docs/src/tutorials/project/graphs_config.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials-project-graphs-config: +.. _tutorials/project/graphs-config: =================== Graph Configuration @@ -32,7 +32,7 @@ Add a root level dictionary to one of the following YAML configuration files: data across all runs within a single experiment (1 graph per experiment), *OR* created from each experimental run (multiple graphs per experiment). The former is generally used to generate graph deliverables, and the latter used - as part of imagizing/generating videos; see :ref:`ln-sierra-usage-rendering` + as part of imagizing/generating videos; see :ref:`usage/rendering` for more details. - ``/config/inter-graphs-line.yaml`` for inter-experiment line @@ -222,4 +222,4 @@ If you added a new :term:`Graph Category`, it will not automatically be used to generate graphs for existing or new controllers. You will need to modify the ``/config/controllers.yaml`` file to specify which controllers your new category of graphs should be generated for. See -:ref:`ln-sierra-tutorials-project-main-config` for details. +:ref:`tutorials/project/main-config` for details. diff --git a/docs/src/tutorials/project/hooks.rst b/docs/src/tutorials/project/hooks.rst index b875f83c..159ef717 100644 --- a/docs/src/tutorials/project/hooks.rst +++ b/docs/src/tutorials/project/hooks.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials-project-hooks: +.. _tutorials/project/hooks: ============ SIERRA Hooks diff --git a/docs/src/tutorials/project/main_config/index.rst b/docs/src/tutorials/project/main_config/index.rst index 189139b1..6b52e24e 100755 --- a/docs/src/tutorials/project/main_config/index.rst +++ b/docs/src/tutorials/project/main_config/index.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials-project-main-config: +.. _tutorials/project/main-config: ================== Main Configuration diff --git a/docs/src/tutorials/project/models.rst b/docs/src/tutorials/project/models.rst index 87a15ae4..c59f6c82 100755 --- a/docs/src/tutorials/project/models.rst +++ b/docs/src/tutorials/project/models.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials-project-models: +.. _tutorials/project/models: ==================================== Adding Models to your SIERRA Project @@ -31,7 +31,7 @@ Create A New Intra-Experiment Model Configuration`_ below for details. #. Run your model during stage 4. You also need to pass ``--models-enable`` - (models are not enabled by default); see :ref:`ln-sierra-usage-cli` for more + (models are not enabled by default); see :ref:`usage/cli` for more details. Model File Requirements diff --git a/docs/src/tutorials/project/new_bc.rst b/docs/src/tutorials/project/new_bc.rst index ce1826aa..0b9dd5a1 100755 --- a/docs/src/tutorials/project/new_bc.rst +++ b/docs/src/tutorials/project/new_bc.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials-project-new-bc: +.. _tutorials/project/new-bc: =========================== Create A New Batch Criteria diff --git a/docs/src/tutorials/project/project.rst b/docs/src/tutorials/project/project.rst index 1cd33f37..f934523c 100755 --- a/docs/src/tutorials/project/project.rst +++ b/docs/src/tutorials/project/project.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials-project-project: +.. _tutorials/project/project: ============================= Creating a New SIERRA Project @@ -29,12 +29,12 @@ Creating a New SIERRA Project all files are required when running a stage that utilizes them): - ``main.yaml`` - Main SIERRA configuration file. This file is required for - all pipeline stages. See :ref:`ln-sierra-tutorials-project-main-config` + all pipeline stages. See :ref:`tutorials/project/main-config` for documentation. - ``controllers.yaml`` - Configuration for controllers (input file/graph generation). This file is required for all pipeline stages. See - :ref:`ln-sierra-tutorials-project-main-config` for documentation. + :ref:`tutorials/project/main-config` for documentation. - ``intra-graphs-line.yaml`` - Configuration for intra-experiment linegraphs. This file is optional. If it is present, graphs defined in it @@ -70,18 +70,18 @@ Creating a New SIERRA Project - ``scenario_generator_parser.py`` - Contains the parser for parsing the contents of ``--scenario`` into a dictionary which can be used to configure experiments. This file is required. See - :ref:`ln-sierra-tutorials-project-generators-scenario-config` for + :ref:`tutorials/project/generators-scenario-config` for documentation. - ``scenario_generators.py`` - Specifies classes and functions to enable SIERRA to generate XML file modifications to the ``--template-input-file`` based on what is passed as ``--scenario`` on the cmdline. This file is required. See - :ref:`ln-sierra-tutorials-project-generators-scenario-config` for documentation. + :ref:`tutorials/project/generators/scenario-config` for documentation. - ``exp_generators.py`` - Contains extensions to the per-:term:`Experiment` and per-:term:`Experimental Run` configuration that SIERRA performs. See - :ref:`ln-sierra-tutorials-project-generators-sim-config` for documentation. This + :ref:`tutorials/project/generators/sim-config` for documentation. This file is optional. - ``variables/`` - Additional variables (including batch criteria) defined by @@ -98,8 +98,8 @@ Creating a New SIERRA Project documentation. #. Configure your project so SIERRA understands how to generate -:term:`Experimental Run` inputs and process outputs correctly by following -:ref:`ln-sierra-tutorials-project-main-config`. + :term:`Experimental Run` inputs and process outputs correctly by following + :ref:`tutorials/project/main-config`. #. Define graphs to be generated from :term:`Experiment` outputs by following :doc:`graphs_config`. Strictly speaking this is optional, but automated graph @@ -113,7 +113,7 @@ Optional Steps ============== #. Define additional batch criteria to investigate variables of interest - specific to your project by following :ref:`ln-sierra-tutorials-project-new-bc`. + specific to your project by following :ref:`tutorials/project/new-bc`. #. Define one or more :term:`Models ` to run to compare with empirical data. diff --git a/docs/src/tutorials/project/stage5_config.rst b/docs/src/tutorials/project/stage5_config.rst index 004c2b9a..04d2015d 100644 --- a/docs/src/tutorials/project/stage5_config.rst +++ b/docs/src/tutorials/project/stage5_config.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials-project-stage5-config: +.. _tutorials/project/stage5-config: ===================== Stage 5 Configuration @@ -15,7 +15,7 @@ This page has the following sections: All configuration for stage 5 is in ``/config/stage5.yaml`` file. This file is mandatory for running stage 5, and optional otherwise. -.. _ln-sierra-tutorials-project-stage5-config-intra: +.. _tutorials/project/stage5-config/intra: Intra-Scenario Comparison ========================= @@ -103,7 +103,7 @@ Unless stated otherwise, all keys are required. -.. _ln-sierra-tutorials-project-stage5-config-inter: +.. _tutorials/project/stage5-config/inter: Inter-Scenario Comparison ========================= diff --git a/docs/src/tutorials/project/template_input_file.rst b/docs/src/tutorials/project/template_input_file.rst index 8ba8801d..b1b8240b 100644 --- a/docs/src/tutorials/project/template_input_file.rst +++ b/docs/src/tutorials/project/template_input_file.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-tutorials-project-template-input-file: +.. _tutorials/project/template-input-file: ==================== Template Input Files @@ -34,7 +34,7 @@ Examples of the structure/required content of the XML file passed to SIERRA via ... - See :ref:`ln-sierra-req-xml` for usage/description of the ``__CONTROLLER__`` tag. + See :ref:`req/xml` for usage/description of the ``__CONTROLLER__`` tag. .. group-tab:: ROS1 (Using parameter server) diff --git a/docs/src/usage/cli.rst b/docs/src/usage/cli.rst index 02243cc4..09b9fb22 100755 --- a/docs/src/usage/cli.rst +++ b/docs/src/usage/cli.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-usage-cli: +.. _usage/cli: ====================== Command Line Interface @@ -10,6 +10,7 @@ apply to a subset of the available :term:`Batch Criteria`. If an option is given more than once, the last such occurrence is used. + SIERRA Core =========== diff --git a/docs/src/usage/environment.rst b/docs/src/usage/environment.rst index e68028c4..22d5ff41 100755 --- a/docs/src/usage/environment.rst +++ b/docs/src/usage/environment.rst @@ -1,4 +1,4 @@ -.. _ln-usage-env-vars: +.. _usage/env-vars: Environment Variables ===================== diff --git a/docs/src/usage/examples.rst b/docs/src/usage/examples.rst index 7bacd976..7dc74893 100644 --- a/docs/src/usage/examples.rst +++ b/docs/src/usage/examples.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-usage-examples: +.. _usage/examples: *********************** SIERRA Usage By Example @@ -7,7 +7,7 @@ SIERRA Usage By Example This page contains reference examples of SIERRA usage to help you craft your own SIERRA invocation. These examples use the SIERRA project plugins from the SIERRA sample project repo: :xref:`SIERRA_SAMPLE_PROJECT`. See -:ref:`ln-sierra-trial` or :ref:`ln-sierra-getting-started` for setting up the +:ref:`trial` or :ref:`getting-started` for setting up the sample project repository. In all examples: @@ -67,7 +67,7 @@ Within each experiment, 3 copies of each simulation will be run (each with different random seeds), for a total of 21 ARGoS simulations. On a reasonable machine it should take about 10 minutes or so to run. After it finishes, you can go to ``$HOME/exp`` and find all the simulation outputs. For an explanation of -SIERRA's runtime directory tree, see :ref:`ln-sierra-usage-runtime-exp-tree`. +SIERRA's runtime directory tree, see :ref:`usage/runtime-exp-tree`. HPC Example =========== @@ -154,7 +154,7 @@ videos of simulations. The runs 3 simulations in parallel with 1 physics engine each, and runs ARGoS under :program:`Xvfb` to get it to render headless images. During stage 4, these images are stitched together using :program:`ffmpeg` to create videos (see -:ref:`ln-sierra-usage-runtime-exp-tree` for where the videos will appear). No +:ref:`usage/runtime-exp-tree` for where the videos will appear). No graphs are generated during stage 4 in this example. You may also be interested in the ``--camera-config`` option, which allows you @@ -298,7 +298,7 @@ different random seeds), for a total of 16 Gazebo simulations. Each experimental run will be will be 10 seconds of simulated time. On a reasonable machine it should take about 10 minutes or so to run. After it finishes, you can go to ``$HOME/exp`` and find all the simulation outputs. For an explanation of -SIERRA's runtime directory tree, see :ref:`ln-sierra-usage-runtime-exp-tree`. +SIERRA's runtime directory tree, see :ref:`usage/runtime-exp-tree`. HPC Example =========== @@ -414,4 +414,4 @@ could also omit ``--nodefile`` and set :envvar:`SIERRA_NODEFILE` instead. For these experiments, no master node is needed, so it is disabled. After all runs have completed and SIERRA finishes stages 3 and 4, you can go to ``$HOME/exp`` and find all the simulation outputs. For an explanation of -SIERRA's runtime directory tree, see :ref:`ln-sierra-usage-runtime-exp-tree`. +SIERRA's runtime directory tree, see :ref:`usage/runtime-exp-tree`. diff --git a/docs/src/usage/index.rst b/docs/src/usage/index.rst index b54807d6..05876d80 100755 --- a/docs/src/usage/index.rst +++ b/docs/src/usage/index.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-usage: +.. _usage: ==================================== SIERRA Overview: A Practical Summary @@ -6,9 +6,9 @@ SIERRA Overview: A Practical Summary This page contains more in-depth documentation on how SIERRA works beyond the minimum needed to get started, and assumes that you have either gotten SIERRA -working via :ref:`ln-sierra-trial` or :ref:`ln-sierra-getting-started`. Once -you've done that, the docs on this page provide a good way to understand how to -get the most out of SIERRA. +working via :ref:`trial` or :ref:`getting-started`. Once you've done that, the +docs on this page provide a good way to understand how to get the most out of +SIERRA. .. toctree:: :maxdepth: 1 diff --git a/docs/src/usage/pipeline.rst b/docs/src/usage/pipeline.rst index 94f55087..69f53792 100755 --- a/docs/src/usage/pipeline.rst +++ b/docs/src/usage/pipeline.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-usage-pipeline: +.. _usage/pipeline: SIERRA Pipeline =============== @@ -22,9 +22,9 @@ experimental inputs allowing you to focus on their *content*, rather than the mechanics of how to turn the content into something that can be executed. See also: -- :ref:`ln-sierra-support-matrix` +- :ref:`support-matrix` -- :ref:`ln-sierra-usage-cli` +- :ref:`usage/cli` Part of default pipeline. @@ -46,11 +46,11 @@ multiple experimental runs from each experiment in parallel if possible. Similar to stage 1, switching between execution environments is as easy as changing a single command line argument. See also: -- :ref:`ln-sierra-exec-env-plugins` +- :ref:`plugins/exec-env` -- :ref:`ln-sierra-platform-plugins` +- :ref:`plugins/platform` -- :ref:`ln-sierra-support-matrix` +- :ref:`support-matrix` Part of default pipeline. @@ -64,11 +64,11 @@ running the batch experiment; some parts of this can be done in parallel. This includes one or more of: - Computing statistics over/about experimental data for stage 4 for use in graph - generation in stage 4. See :ref:`ln-sierra-usage-cli` documentation for + generation in stage 4. See :ref:`usage/cli` documentation for ``--dist-stats`` for details. - Creating images from project CSV files for rendering in stage 4. See - :ref:`ln-sierra-usage-rendering-project` for details. + :ref:`usage/rendering/project` for details. Part of default pipeline. @@ -89,10 +89,10 @@ simplifying reproduction of previous results if you need to tweak a given graph SIERRA also has a rich model framework allowing you to run arbitrary models, generate data, and plot it on the same figure as empirical results, -automatically. See :ref:`ln-sierra-tutorials-project-models` for details. +automatically. See :ref:`tutorials/project/models` for details. For some examples, see the "Generating Deliverables" section of -:xref:`2022-aamas-demo`. See :ref:`ln-sierra-usage-rendering` for details about +:xref:`2022-aamas-demo`. See :ref:`usage/rendering` for details about rendering capabilities. Part of default pipeline. @@ -106,9 +106,9 @@ which can be dropped immediately into academic papers without modification. This can be used to compare: - Different agent control algorithms which have all been run in the same - ``--scenario``. See :ref:`ln-sierra-usage-stage5-intra-scenario` for details. + ``--scenario``. See :ref:`usage/stage5/intra-scenario` for details. - A single ``--controller`` across multiple scenarios. See - :ref:`ln-sierra-usage-stage5-inter-scenario` for details. + :ref:`usage/stage5/inter-scenario` for details. Not part of default pipeline. diff --git a/docs/src/usage/rendering.rst b/docs/src/usage/rendering.rst index c13d9d99..3758e1fc 100755 --- a/docs/src/usage/rendering.rst +++ b/docs/src/usage/rendering.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-usage-rendering: +.. _usage/rendering: ========= Rendering @@ -8,14 +8,14 @@ SIERRA's capabilities for rendering video outputs are detailed in this section. SIERRA can render frames (images) into videos from 3 sources: - Those captured using ``--platform-vc``, details :ref:`here - `. + `. - Those imagized from project CSV output files via ``--project-imagizing`` using ``--project-rendering`` details :ref:`here - `. + `. - Inter-experiment heatmaps from bivariate batch criteria ``--bc-rendering``, - details :ref:`here `. + details :ref:`here `. .. NOTE:: Using BOTH the platform and project rendering capabilities @@ -23,7 +23,7 @@ section. SIERRA can render frames (images) into videos from 3 sources: ``--project-rendering`` during stage 3), but discouraged unless you have multiple terrabytes of disk space available. ``--exp-range`` is your friend. -.. _ln-sierra-usage-rendering-platform: +.. _usage/rendering/platform: Platform Visual Capture ======================= @@ -44,7 +44,7 @@ This is applicable to the following platforms: computing power available. -.. _ln-sierra-usage-rendering-platform-argos: +.. _usage/rendering/platform/argos: ARGos Visual Capture -------------------- @@ -63,18 +63,18 @@ that: we can output to a file. During stage 2, ARGoS outputs captured frames to ``frames/`` in each output -directory (see :ref:`config.kRendering`). During stage 4, ``--platform-vc`` -causes frames captured during stage 2 to be stitched together into a unique -video file using :program:`ffmpeg` (precise command configurable via -``--render-cmd-opts``), and output to ``/videos/``. +directory. During stage 4, ``--platform-vc`` causes frames captured during +stage 2 to be stitched together into a unique video file using :program:`ffmpeg` +(precise command configurable via ``--render-cmd-opts``), and output to +``/videos/``. -.. _ln-sierra-usage-rendering-project: +.. _usage/rendering/project: Project Rendering ================= Projects can generate CSV files residing in subdirectories within the -``main.run_metrics_leaf`` (see :ref:`ln-sierra-tutorials-project-main-config`) +``main.run_metrics_leaf`` (see :ref:`tutorials/project/main-config`) directory (directory path set on a per ``--project`` basis) for each experimental run, in addition to generating CSV files residing directly in the ``main.run_metrics_leaf.`` directory. SIERRA can then render these CSV @@ -84,7 +84,7 @@ images together to make videos. .. IMPORTANT:: Imagized/rendered images/videos are generated per :term:`Experiment` rather - than per :term:`Experiment Run`, and thus the raw inputs *ARE* averaged + than per :term:`Experimental Run`, and thus the raw inputs *ARE* averaged before imagizing and subsequent rendering. To use, do the following: @@ -96,7 +96,7 @@ To use, do the following: suitable for video rendering in stage 4. Not all subdirectories under ``main.run_metrics_leaf`` *have* to contain stuff for imagizing; what is selected for imagizing is controlled by ``intra-graphs-hm.yaml``--see - :ref:`ln-sierra-tutorials-project-graphs-config` for details. + :ref:`tutorials/project/graphs-config` for details. The following restrictions apply: @@ -140,7 +140,7 @@ To use, do the following: getting paid by the hour). -.. _ln-sierra-usage-rendering-bc: +.. _usage/rendering/bc: Batch Criteria Rendering ======================== diff --git a/docs/src/usage/run_time_tree.rst b/docs/src/usage/run_time_tree.rst index 71501cc2..3b0326df 100755 --- a/docs/src/usage/run_time_tree.rst +++ b/docs/src/usage/run_time_tree.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-usage-runtime-exp-tree: +.. _usage/runtime-exp-tree: SIERRA Runtime Directory Tree ============================= @@ -34,7 +34,7 @@ Basic Structure configuration/inputs from where you tell it to, but all outputs generated during at any pipeline stage will appear under here. - - `--sierra-root`. See :ref:`ln-sierra-usage-cli` for more details. + - `--sierra-root`. See :ref:`usage/cli` for more details. * - Batch root @@ -86,7 +86,7 @@ Basic Structure will get their own subdirectory in this root for their model outputs to accrue into. - - No/named ``/models``. + - No/named ``/models``. * - Batch statistics root @@ -250,13 +250,13 @@ it runs: together in stage 4 to generated videos. Each experiment will get its own directory under here, with unique sub-directories for each different type of :term:`Experimental Run` data captured for - imagizing. See :ref:`ln-sierra-usage-rendering-project` for more + imagizing. See :ref:`usage/rendering/project` for more details. - ``videos`` - Root directory for holding rendered videos generated during stage 4 from either captured simulator frames for imagized project files. Each experiment will get its own directory under here, - with See :ref:`ln-sierra-usage-rendering` for more details. + with See :ref:`usage/rendering` for more details. - ``models`` - During stage4, the dataframes generated by all executed models are stored under this directory. Each experiment in the batch @@ -307,7 +307,7 @@ it runs: (scenario names are arbitrary for the purposes of stage 5 and entirely depend on the project). Inside this directory will be all graphs generated according to the configuration specified in - :ref:`ln-sierra-tutorials-project-stage5-config`. + :ref:`tutorials/project/stage5-config`. Second, the experiment tree for `controller comparison` :: @@ -330,4 +330,4 @@ it runs: examining the directory tree for stages 1-4). Controller names are arbitrary for the purposes of stage 5 and entirely depend on the project). Inside this directory will be all graphs generated according to the configuration - specified in :ref:`ln-sierra-tutorials-project-stage5-config`. + specified in :ref:`tutorials/project/stage5-config`. diff --git a/docs/src/usage/stage5.rst b/docs/src/usage/stage5.rst index e1cf419e..350bf17e 100644 --- a/docs/src/usage/stage5.rst +++ b/docs/src/usage/stage5.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-usage-stage5: +.. _usage/stage5: ================ Pipeline Stage 5 @@ -27,17 +27,17 @@ SIERRA invocation), because the options are quite different, but you don't linegraphs containing 3,6,9,..., lines with duplicated data. In general, you want to delete the directories generated by stage 5 between successive runs. See - :ref:`ln-sierra-usage-runtime-exp-tree` for details on what + :ref:`usage/runtime-exp-tree` for details on what directories are generated. -.. _ln-sierra-usage-stage5-intra-scenario: +.. _usage/stage5/intra-scenario: Intra-Scenario Comparison ========================= Intra-scenario comparison compares the of experiments using one or more controllers on the same ``--scenario``. To use it, you need to pass the -following options to SIERRA (see :ref:`ln-sierra-usage-cli` for documentation): +following options to SIERRA (see :ref:`usage/cli` for documentation): - ``--scenario-comparison`` @@ -50,16 +50,16 @@ Other ``--plot-*`` options providing for fine-grained control of the generated graphs may also be of interest. For YAML configuration, see -:ref:`ln-sierra-tutorials-project-stage5-config-intra`. +:ref:`tutorials/project/stage5-config/intra`. -.. _ln-sierra-usage-stage5-inter-scenario: +.. _usage/stage5/inter-scenario: Inter-Scenario Comparison ========================= Inter-scenario comparison compares the same ``--controller`` across multiple ``--scenarios``. To use it, you need to pass the following options to SIERRA -when running stage 5 (see :ref:`ln-sierra-usage-cli` for documentation): +when running stage 5 (see :ref:`usage/cli` for documentation): - ``--controller-comparison`` @@ -72,4 +72,4 @@ Other ``--plot-*`` options providing for fine-grained control of the generated graphs may also be of interest. For YAML configuration, see -:ref:`ln-sierra-tutorials-project-stage5-config-inter`. +:ref:`tutorials/project/stage5-config/inter`. diff --git a/docs/src/usage/subprograms.rst b/docs/src/usage/subprograms.rst index ffdedb87..fc573fdb 100755 --- a/docs/src/usage/subprograms.rst +++ b/docs/src/usage/subprograms.rst @@ -9,11 +9,11 @@ depending on what you are doing. experiments (:term:`ARGoS`, :term:`ROS1+Gazebo`, :term:`ROS1+Robot` platforms). - :program:`ffmpeg` - Used during stage 3 if imagizing is run. See - :ref:`ln-sierra-usage-rendering-platform`. + :ref:`usage/rendering/platform`. - :program:`Xvfb` - Used during stage 1 when generating simulation inputs, and during stage 2 when running experiments for the :term:`ARGoS` - :term:`Platform`. See also :ref:`ln-sierra-usage-rendering-platform`. + :term:`Platform`. See also :ref:`usage/rendering/platform`. - :program:`parallel-ssh` - Used during stage 1 when generating experiments experiments (:term:`ROS1+Robot` platform). diff --git a/docs/src/usage/variables.rst b/docs/src/usage/variables.rst index 780f9be1..7d8ac605 100755 --- a/docs/src/usage/variables.rst +++ b/docs/src/usage/variables.rst @@ -1,4 +1,4 @@ -.. _ln-sierra-usage-vars: +.. _usage/vars: ============================= Configurable SIERRA Variables @@ -8,9 +8,9 @@ Non-:term:`Batch Criteria` variables which you can use to configure simulations. All batch criteria are variables, but not all variables are batch criteria. -- :ref:`Experiment Setup ` +- :ref:`Experiment Setup ` -.. _ln-sierra-vars-expsetup: +.. _usage/vars/expsetup: Experiment Setup ================ @@ -19,7 +19,7 @@ Configure :term:`Experiment` time: length, controller cadence (:term:`Tick` duration/timestep), and how many datapoints to capture per :term:`Experimental Run`. -.. _ln-sierra-vars-expsetup-cmdline: +.. _usage/vars/expsetup/cmdline: Cmdline Syntax -------------- diff --git a/noxfile.py b/noxfile.py index 3d687a28..c79f48e5 100644 --- a/noxfile.py +++ b/noxfile.py @@ -166,3 +166,36 @@ def unit_tests(session): session.run('pytest', '--cov') + +# 2024-11-19 [JRH]: This currently is just a paper-thin wrapper around the shell +# scripts, which were implemented a long time ago. And it works. Some/all of the +# stuff in these scripts should be migrated into python, where doing things like +# loops is way easier. + + +@nox.session(python=versions) +def core_integration(session): + session.install('.') # same as 'pip3 install .' + + session.run('./scripts/core-integration-tests.sh', *session.posargs) + + +@nox.session(python=versions) +def plugin_argos_integration(session): + session.install('.') # same as 'pip3 install .' + + session.run('./scripts/argos-integration-tests.sh', *session.posargs) + + +@nox.session(python=versions) +def plugin_ros1gazebo_integration(session): + session.install('.') # same as 'pip3 install .' + + session.run('./scripts/ros1gazebo-integration-tests.sh', *session.posargs) + + +@nox.session(python=versions) +def plugin_ros1robot_integration(session): + session.install('.') # same as 'pip3 install .' + + session.run('./scripts/ros1robot-integration-tests.sh', *session.posargs) diff --git a/scripts/argos-integration-tests.sh b/scripts/argos-integration-tests.sh index 5d5fa8eb..99db522b 100755 --- a/scripts/argos-integration-tests.sh +++ b/scripts/argos-integration-tests.sh @@ -50,12 +50,12 @@ setup_env() { --sierra-root=$SIERRA_ROOT \ --platform=platform.argos \ --project=argos_project \ - --exp-setup=exp_setup.T500.K5 \ + -esetup=exp_setup.T500.K5 \ --n-runs=4 \ - --exec-strict \ + -xstrict \ --template-input-file=$SAMPLE_ROOT/exp/argos/template.argos \ --scenario=LowBlockCount.10x10x2 \ - --exec-no-devnull \ + -xno-devnull \ --with-robot-leds \ --with-robot-rab \ --log-level=TRACE" @@ -694,8 +694,9 @@ stage5_univar_test() { --pipeline 5 \ --n-runs=4 \ --bc-univar \ - --plot-log-yscale \ - --plot-large-text \ + -plog-yscale \ + -plarge-text \ + -pprimary-axis=1 \ --log-level=TRACE" # Compare the controllers diff --git a/scripts/core-integration-tests.sh b/scripts/core-integration-tests.sh index 874d2400..d7a25b0c 100755 --- a/scripts/core-integration-tests.sh +++ b/scripts/core-integration-tests.sh @@ -58,10 +58,10 @@ setup_env() { --project=argos_project \ --exp-setup=exp_setup.T5000.K5 \ --n-runs=4 \ - --exec-strict \ + -xstrict \ --template-input-file=$SAMPLE_ROOT/exp/argos/template.argos \ --scenario=LowBlockCount.10x10x2 \ - --exec-no-devnull \ + -xno-devnull \ --with-robot-leds \ --with-robot-rab\ --log-level=TRACE" @@ -74,12 +74,12 @@ setup_env() { --project=ros1gazebo_project \ --exp-setup=exp_setup.T10.K5.N50\ --n-runs=4 \ - --exec-strict\ + -xstrict\ --template-input-file=$SAMPLE_ROOT/exp/ros1gazebo/turtlebot3_house.launch \ --scenario=HouseWorld.10x10x2 \ --controller=turtlebot3.wander \ --robot turtlebot3\ - --exec-no-devnull \ + -xno-devnull \ --log-level=TRACE" } @@ -105,7 +105,9 @@ print(path) export SIERRA_ARCH=fizzbuzz which argos3 - ln -s /usr/local/bin/argos3 /usr/local/bin/argos3-fizzbuzz + + ln -sf /usr/local/bin/argos3 /usr/local/bin/argos3-fizzbuzz + SIERRA_CMD="$SIERRA_BASE_CMD_ARGOS \ --physics-n-engines=1 \ --batch-criteria population_size.Linear3.C3 \ diff --git a/scripts/ros1gazebo-integration-tests.sh b/scripts/ros1gazebo-integration-tests.sh index 87a348ce..a73f2228 100755 --- a/scripts/ros1gazebo-integration-tests.sh +++ b/scripts/ros1gazebo-integration-tests.sh @@ -49,12 +49,12 @@ setup_env() { --project=ros1gazebo_project \ --exp-setup=exp_setup.T5.K5\ --n-runs=4 \ - --exec-strict \ + -xstrict \ --template-input-file=$SAMPLE_ROOT/exp/ros1gazebo/turtlebot3_house.launch \ --scenario=HouseWorld.10x10x2 \ --controller=turtlebot3.wander \ --robot turtlebot3 \ - --exec-no-devnull \ + -xno-devnull \ --log-level=TRACE" export PARALLEL="--env LD_LIBRARY_PATH" diff --git a/scripts/ros1robot-integration-tests.sh b/scripts/ros1robot-integration-tests.sh index 2c67c642..48b13f9a 100755 --- a/scripts/ros1robot-integration-tests.sh +++ b/scripts/ros1robot-integration-tests.sh @@ -52,8 +52,8 @@ setup_env() { --scenario=OutdoorWorld.10x10x2 \ --controller=turtlebot3.wander \ --robot turtlebot3 - --skip-online-check\ - --skip-sync\ + -sonline-check\ + -ssync\ --log-level=TRACE" export PARALLEL="--env LD_LIBRARY_PATH" diff --git a/sierra/core/batchroot.py b/sierra/core/batchroot.py index c82c612f..3e4633f3 100644 --- a/sierra/core/batchroot.py +++ b/sierra/core/batchroot.py @@ -5,7 +5,7 @@ # """Functionality for generating root directory paths for a batch experiment. -See :ref:`ln-sierra-usage-runtime-exp-tree` for details about the defined root +See :ref:`usage/runtime-exp-tree` for details about the defined root directories in SIERRA. """ @@ -21,6 +21,9 @@ class ExpRootLeaf(): + """ + Representation of the "name" in pathlib parlance in :python:`ExpRoot`. + """ @staticmethod def from_name(leaf: str) -> 'ExpRootLeaf': template_stem = ''.join(leaf.split('-')[0]) @@ -59,6 +62,10 @@ def to_str(self) -> str: class ExpRoot(): + """ + Representation of the filesystem path containing all per-experiment data. + """ + def __init__(self, sierra_root: str, project: str, @@ -66,21 +73,19 @@ def __init__(self, leaf: ExpRootLeaf) -> None: """Generate the directory path for the rootbatch root directory. - The directory path depends on all of the input arguments to this function, - and if ANY of the arguments change, so will the generated path. - - root is: + The directory path depends on all of the input arguments to this + class, and if ANY of the arguments change, so will the generated + path. Root is: //-++ Arguments: - root: The path to the root directory where SIERRA should store - everything. + root: The path to the root directory where SIERRA should store + everything. - project: The name of the project plugin used. - - controller: The name of the controller used. + project: The name of the project plugin used. + controller: The name of the controller used. """ self.leaf = leaf @@ -100,6 +105,12 @@ def to_str(self) -> str: class PathSet(): + """ + The set of filesystem paths under ``--sierra-root`` that SIERRA uses. + + Collected here in the interest of DRY. + """ + def __init__(self, root: ExpRoot) -> None: self.input_root = root.to_path() / "exp-inputs" self.output_root = root.to_path() / "exp-outputs" @@ -176,3 +187,12 @@ def from_exp(sierra_root: str, batch_leaf) logging.info('Generated batch root %s', root.to_path()) return PathSet(root) + + +__api__ = [ + "from_exp", + "from_cmdline", + "PathSet", + "ExpRoot", + "ExpRootLeaf", +] diff --git a/sierra/core/cmdline.py b/sierra/core/cmdline.py index f638025a..bc0a7dc1 100755 --- a/sierra/core/cmdline.py +++ b/sierra/core/cmdline.py @@ -178,26 +178,26 @@ def __init__(self) -> None: - ``hpc.local`` - This directs SIERRA to run experiments on the local machine. See - :ref:`ln-sierra-hpc-plugins-local` for a detailed + :ref:`plugins/hpc/local` for a detailed description. - ``hpc.pbs`` - The directs SIERRA to run experiments spread across multiple allocated nodes in an HPC computing environment managed - by TORQUE-PBS. See :ref:`ln-sierra-hpc-plugins-pbs` + by TORQUE-PBS. See :ref:`plugins/hpc/pbs` for a detailed description. - ``hpc.slurm`` - The directs SIERRA to run experiments spread across multiple allocated nodes in an HPC computing environment managed by SLURM. See - :ref:`ln-sierra-hpc-plugins-slurm` for a + :ref:`plugins/hpc/slurm` for a detailed description. - ``hpc.adhoc`` - This will direct SIERRA to run experiments on an ad-hoc network of computers. See - :ref:`ln-sierra-hpc-plugins-adhoc` for a + :ref:`hpc/plugins/adhoc` for a detailed description. - ``robot.turtlebot3`` - This will direct SIERRA @@ -220,26 +220,6 @@ def __init__(self, self.scaffold_cli(parents) self.init_cli(stages) - def init_cli(self, stages: tp.List[int]) -> None: - """Define cmdline arguments for stages 1-5.""" - if -1 in stages: - self.init_multistage() - - if 1 in stages: - self.init_stage1() - - if 2 in stages: - self.init_stage2() - - if 3 in stages: - self.init_stage3() - - if 4 in stages: - self.init_stage4() - - if 5 in stages: - self.init_stage5() - def scaffold_cli(self, parents: tp.Optional[tp.List[ArgumentParser]]) -> None: """ @@ -265,6 +245,88 @@ def scaffold_cli(self, 'Stage4: General options for generating graphs') self.stage5 = self.parser.add_argument_group( 'Stage5: General options for controller comparison') + self.shortforms = self.parser.add_argument_group( + title='Shortform aliases', + description=""" + Most cmdline options to SIERRA are longform (i.e., + ``--option``), but some families of options have + shortforms (i.e., ``-o`` for ``--option``) as + well. Shortform arguments behave the same as their + longform counterparts. + """) + + def init_cli(self, stages: tp.List[int]) -> None: + """Define cmdline arguments for stages 1-5.""" + if -1 in stages: + self.init_multistage() + self.init_shortforms() + + if 1 in stages: + self.init_stage1() + + if 2 in stages: + self.init_stage2() + + if 3 in stages: + self.init_stage3() + + if 4 in stages: + self.init_stage4() + + if 5 in stages: + self.init_stage5() + + def init_shortforms(self) -> None: + """ + Define cmdline shortform arguments for all pipeline stages. + """ + self.shortforms.add_argument("-p", action="append", nargs="+", + help=""" + Alias of ``--plot-``; any number of + ``--plot-XX`` option can be passed + with separate ``-p`` arguments . + If the argument to ``-p`` does not map + to a valid ``plot-XX`` option it is + ignored. + + .. versionadded:: 1.3.14 + """) + + self.shortforms.add_argument("-e", action="append", nargs="+", + help=""" + Alias of ``--exp-``; any number of + ``--exp-XX`` option can be passed + with separate ``-e`` arguments . + If the argument to ``-e`` does not map + to a valid ``exp-XX`` option it is + ignored. + + .. versionadded:: 1.3.14 + """) + + self.shortforms.add_argument("-x", action="append", nargs="+", + help=""" + Alias of ``--exec-``; any number of + ``--exec-XX`` option can be passed + with separate ``-x`` arguments . + If the argument to ``-x`` does not map + to a valid ``exec-XX`` option it is + ignored. + + .. versionadded:: 1.3.14 + """) + + self.shortforms.add_argument("-s", action="append", nargs="+", + help=""" + Alias of ``--skip``; any number of + ``--skip-XX`` option can be passed + with separate ``-s`` arguments . + If the argument to ``-s`` does not map + to a valid ``skip-XX`` option it is + ignored. + + .. versionadded:: 1.3.14 + """) def init_multistage(self) -> None: """ @@ -280,7 +342,7 @@ def init_multistage(self) -> None: content of the file can be any valid XML, with the exception of the SIERRA requirements detailed in - :ref:`ln-sierra-tutorials-project-template-input-file`. + :ref:`tutorials/project/template-input-file`. """ + self.stage_usage_doc([1, 2, 3, 4])) @@ -414,7 +476,7 @@ def init_multistage(self) -> None: selected ``--platform`` does not support visual capture, then this option has no effect. See - :ref:`ln-sierra-usage-rendering-platform` + :ref:`usage/rendering/platform` for full details. """ + self.stage_usage_doc([1, 4]), @@ -532,7 +594,7 @@ def init_multistage(self) -> None: For example, in a bivariate batch criteria composed of - - :ref:`ln-sierra-platform-argos-bc-population-size` + - :ref:`plugins/platform/argos/bc/population-size` on the X axis (rows) - Another batch criteria which does not @@ -904,7 +966,7 @@ def init_stage4(self) -> None: Enable generation of image files from CSV files captured during stage 2 and averaged during stage 3 for each experiment. See - :ref:`ln-sierra-usage-rendering-project` for + :ref:`usage/rendering/project` for details and restrictions. """ + self.stage_usage_doc([3, 4]), @@ -916,7 +978,7 @@ def init_stage4(self) -> None: Enable generation of videos from imagized CSV files created as a result of ``--project-imagizing``. See - :ref:`ln-sierra-usage-rendering-project` for + :ref:`usage/rendering/project` for details. """ + self.stage_usage_doc([4]), @@ -929,7 +991,7 @@ def init_stage4(self) -> None: graphs, such as heatmaps. Bivariate batch criteria only. - .. versionadded: 1.2.20 + .. versionadded:: 1.2.20 """ + self.stage_usage_doc([4]), action='store_true') diff --git a/sierra/core/exproot.py b/sierra/core/exproot.py index a04a911c..22b05357 100644 --- a/sierra/core/exproot.py +++ b/sierra/core/exproot.py @@ -14,6 +14,12 @@ class PathSet(): + """ + The set of filesystem paths under the per-experiment root that SIERRA uses. + + Collected here in the interest of DRY. + """ + def __init__(self, batch: batchroot.PathSet, exp_name: str, @@ -23,7 +29,13 @@ def __init__(self, self.graph_root = batch.graph_root / exp_name self.model_root = batch.model_root / exp_name self.stat_root = batch.stat_root / exp_name + self.parent = batch.root if exp0_name: self.exp0_output_root = batch.output_root / exp0_name self.exp0_stat_root = batch.stat_root / exp0_name + + +__api__ = [ + "PathSet" +] diff --git a/sierra/core/pipeline/pipeline.py b/sierra/core/pipeline/pipeline.py index e93c0167..63791d2b 100755 --- a/sierra/core/pipeline/pipeline.py +++ b/sierra/core/pipeline/pipeline.py @@ -3,7 +3,7 @@ # SPDX-License-Identifier: MIT """The 5 pipeline stages implemented by SIERRA. -See :ref:`ln-sierra-usage-pipeline` for high-level documentation. +See :ref:`usage/pipeline` for high-level documentation. """ @@ -34,15 +34,22 @@ def __init__(self, args: argparse.Namespace, controller: tp.Optional[str], pathset: tp.Optional[batchroot.PathSet] = None) -> None: - self.args = args self.logger = logging.getLogger(__name__) self.pathset = pathset - self.logger.trace("%s", self.pathset) + self.logger.trace("Run-time tree:\n%s", self.pathset) assert all(stage in [1, 2, 3, 4, 5] for stage in args.pipeline), \ f"Invalid pipeline stage in {args.pipeline}: Only 1-5 valid" + # After running this, all shortform aliases have been converted to their + # longform counterparts in the argparse.Namespace. The namespace passed + # in contains arguments for the core and all plugins, so its OK to + # handle shortforms which aren't in the SIERRA core at this point. This + # also preserves the "longforms trump shortforms if both are passed" + # policy because their converted shortforms are overwritten below. + self.args = self._handle_shortforms(args) + self.cmdopts = { # multistage 'pipeline': self.args.pipeline, @@ -169,6 +176,55 @@ def run(self) -> None: self.cmdopts, self.pathset).run(self.args) + def _handle_shortforms(self, args: argparse.Namespace) -> argparse.Namespace: + """ + Replace all shortform arguments in with their longform counterparts. + + SIERRA always references arguments internally via longform if needed, so + this is required. + + """ + shortform_map = { + 'p': 'plot', + 'e': 'exp', + 'x': 'exec', + 's': 'skip', + } + + for k in shortform_map: + passed = getattr(args, k, None) + if not passed: + self.logger.trace(("No shortform args for -%s -> --%s " + "passed to SIERRA"), + k, + shortform_map[k]) + continue + + self.logger.trace("Collected shortform args for -%s -> --%s: %s", + k, + shortform_map[k], + passed) + + # There are 3 ways to pass shortform arguments, assuming a shortform + # of 'X: + # + # 1. -Xarg + # 2. -Xarg=foo + # 3. -Xarg foo + for p in passed: + if len(p) == 1 and '=' not in p[0]: # boolean + key = '{0}_{1}'.format(shortform_map[k], p[0].replace('-', '_')) + setattr(args, key, True) + elif len(p) == 1 and '=' in p[0]: + arg, value = p[0].split('=') + key = '{0}_{1}'.format(shortform_map[k], arg.replace('-', '_')) + setattr(args, key, value) + else: + key = '{0}_{1}'.format(shortform_map[k], p[1:].replace('-', '_')) + setattr(args, key, p[1:]) + + return args + def _load_config(self) -> None: self.logger.debug("Loading project config from '%s'", self.cmdopts['project_config_root']) diff --git a/sierra/core/pipeline/stage3/collate.py b/sierra/core/pipeline/stage3/collate.py index fb920fac..ec2e38c4 100755 --- a/sierra/core/pipeline/stage3/collate.py +++ b/sierra/core/pipeline/stage3/collate.py @@ -159,7 +159,7 @@ class ExpRunCSVGatherer: """Gather :term:`Output .csv` files across all runs within an experiment. This class can be extended/overriden using a :term:`Project` hook. See - :ref:`ln-sierra-tutorials-project-hooks` for details. + :ref:`tutorials/project/hooks` for details. Attributes: diff --git a/sierra/core/pipeline/stage3/imagize.py b/sierra/core/pipeline/stage3/imagize.py index 1b687d81..071a5f85 100755 --- a/sierra/core/pipeline/stage3/imagize.py +++ b/sierra/core/pipeline/stage3/imagize.py @@ -4,7 +4,7 @@ """Classes for creating image files from ``.mean`` files for experiments. -See :ref:`ln-sierra-usage-rendering` for usage documentation. +See :ref:`usage/rendering` for usage documentation. """ @@ -106,7 +106,7 @@ def _proc_single_exp(HM_config: types.YAMLDict, """Create images from the averaged ``.mean`` files from a single experiment. If no ``.mean`` files suitable for averaging are found, nothing is done. See - :ref:`ln-sierra-usage-rendering` for per-platform descriptions of what + :ref:`usage/rendering` for per-platform descriptions of what "suitable" means. Arguments: diff --git a/sierra/core/pipeline/stage4/graphs/collate.py b/sierra/core/pipeline/stage4/graphs/collate.py index b1e63cad..28a03eac 100755 --- a/sierra/core/pipeline/stage4/graphs/collate.py +++ b/sierra/core/pipeline/stage4/graphs/collate.py @@ -70,8 +70,8 @@ def __init__(self, def __call__(self, criteria, target: dict) -> None: - self.logger.info("Univariate files from batch in %s for graph '%s'...", - self.pathset.output_root, + self.logger.info("Univariate files from batch in /%s for graph '%s'...", + self.pathset.output_root.relative_to(self.pathset.root), target['src_stem']) self.logger.trace(json.dumps(target, indent=4)) # type: ignore diff --git a/sierra/core/pipeline/stage4/graphs/inter/generate.py b/sierra/core/pipeline/stage4/graphs/inter/generate.py index 12e161a5..86d07adb 100755 --- a/sierra/core/pipeline/stage4/graphs/inter/generate.py +++ b/sierra/core/pipeline/stage4/graphs/inter/generate.py @@ -40,7 +40,7 @@ def generate(main_config: types.YAMLDict, :class:`~sierra.core.pipeline.stage4.pipeline_stage4.PipelineStage4`. This class can be extended/overriden using a: term: `Project` hook. See - :ref: `ln-sierra-tutorials-project-hooks` for details. + :ref:`tutorials/project/hooks` for details. Attributes: diff --git a/sierra/core/pipeline/stage4/graphs/intra/generate.py b/sierra/core/pipeline/stage4/graphs/intra/generate.py index 75e8c816..f3fad0fc 100755 --- a/sierra/core/pipeline/stage4/graphs/intra/generate.py +++ b/sierra/core/pipeline/stage4/graphs/intra/generate.py @@ -85,7 +85,7 @@ class IntraExpGraphGenerator: in :class:`~sierra.core.pipeline.stage4.pipeline_stage4.PipelineStage4`. This class can be extended/overriden using a :term:`Project` hook. See - :ref:`ln-sierra-tutorials-project-hooks` for details. + :ref:`tutorials/project/hooks` for details. Attributes: diff --git a/sierra/core/pipeline/stage4/graphs/intra/heatmap.py b/sierra/core/pipeline/stage4/graphs/intra/heatmap.py index 27cbf347..a32a1b4c 100644 --- a/sierra/core/pipeline/stage4/graphs/intra/heatmap.py +++ b/sierra/core/pipeline/stage4/graphs/intra/heatmap.py @@ -29,7 +29,8 @@ def generate(cmdopts: types.Cmdopts, targets = targets - _logger.info("Heatmaps from %s", pathset.stat_root) + _logger.info("Heatmaps from /%s", + pathset.stat_root.relative_to(pathset.parent)) # For each category of heatmaps we are generating for category in targets: diff --git a/sierra/core/pipeline/stage4/graphs/intra/line.py b/sierra/core/pipeline/stage4/graphs/intra/line.py index 5a0b4f62..bd2e91bd 100644 --- a/sierra/core/pipeline/stage4/graphs/intra/line.py +++ b/sierra/core/pipeline/stage4/graphs/intra/line.py @@ -25,7 +25,8 @@ def generate(cmdopts: types.Cmdopts, Generate linegraphs from: term: `Averaged .csv` files within an experiment. """ - _logger.info("Linegraphs from %s", pathset.stat_root) + _logger.info("Linegraphs from /%s", + pathset.stat_root.relative_to(pathset.parent)) # For each category of linegraphs we are generating for category in targets: diff --git a/sierra/core/pipeline/stage4/graphs/loader.py b/sierra/core/pipeline/stage4/graphs/loader.py index 2bcb351f..29990f38 100755 --- a/sierra/core/pipeline/stage4/graphs/loader.py +++ b/sierra/core/pipeline/stage4/graphs/loader.py @@ -37,7 +37,7 @@ def load_config(cmdopts: types.Cmdopts) -> tp.Dict[str, types.YAMLDict]: inter_LN, intra_HM, inter_HM``. This function can be extended/overriden using a :term:`Project` hook. See - :ref:`ln-sierra-tutorials-project-hooks` for details. + :ref:`tutorials/project/hooks` for details. """ inter_LN_config = {} diff --git a/sierra/core/pipeline/stage4/render.py b/sierra/core/pipeline/stage4/render.py index b39300dd..06089e60 100755 --- a/sierra/core/pipeline/stage4/render.py +++ b/sierra/core/pipeline/stage4/render.py @@ -135,7 +135,7 @@ def from_platform(main_config: types.YAMLDict, /videos/ ```` is controlled via configuration. For more - details, see :ref:`ln-sierra-usage-rendering`. + details, see :ref:`usage/rendering`. .. note:: This currently only works with PNG images. """ @@ -168,7 +168,7 @@ def from_project_imagized(main_config: types.YAMLDict, """Render THINGS previously imagized in a project in stage 3 into videos. Frames (images) in each subdirectory in the imagize root (see - :ref:`ln-sierra-usage-runtime-exp-tree`) are stitched together to make a + :ref:`usage/runtime-exp-tree`) are stitched together to make a video using :program:`ffmpeg`. Output format controlled via configuration. Targets to render are found in:: @@ -179,7 +179,7 @@ def from_project_imagized(main_config: types.YAMLDict, /videos// - For more details, see :ref:`ln-sierra-usage-rendering`. + For more details, see :ref:`usage/rendering`. .. note:: This currently only works with PNG images. """ @@ -225,7 +225,7 @@ def from_bivar_heatmaps(main_config: types.YAMLDict, /videos/ - For more details, see :ref:`ln-sierra-usage-rendering`. + For more details, see :ref:`usage/rendering`. versionadded:: 1.2.20 """ diff --git a/sierra/core/pipeline/stage5/outputroot.py b/sierra/core/pipeline/stage5/outputroot.py index fdbc06b8..e2bf0db3 100644 --- a/sierra/core/pipeline/stage5/outputroot.py +++ b/sierra/core/pipeline/stage5/outputroot.py @@ -15,6 +15,12 @@ class PathSet: + """ + The set of filesystem paths used during stage 5. + + Collected here in the interest of DRY. + """ + def __init__(self, cmdopts: types.Cmdopts, controllers: tp.List[str], @@ -50,3 +56,8 @@ def __init__(self, self.model_root = pathlib.Path(cmdopts['sierra_root'], cmdopts['project'], '+'.join(scenarios) + "-sc-models") + + +__api__ = [ + "PathSet" +] diff --git a/sierra/core/ros1/cmdline.py b/sierra/core/ros1/cmdline.py index bc96dc39..59a7eb96 100644 --- a/sierra/core/ros1/cmdline.py +++ b/sierra/core/ros1/cmdline.py @@ -72,7 +72,7 @@ def init_stage1(self) -> None: Defines experiment run length, ticks per second for the experiment, # of datapoints to capture/capture interval for each - simulation. See :ref:`ln-sierra-vars-expsetup` for + simulation. See :ref:`usage/vars/expsetup` for a full description. """ + self.stage_usage_doc([1]), @@ -87,7 +87,7 @@ def init_stage1(self) -> None: The key name of the robot model, which must be present in the appropriate section of ``{0}`` for the :term:`Project`. See - :ref:`ln-sierra-tutorials-project-main-config` + :ref:`tutorials/project/main-config` for details. """.format(config.kYAML.main) + self.stage_usage_doc([1])) @@ -115,7 +115,7 @@ class ROSCmdlineValidator(): """ def __call__(self, args: argparse.Namespace) -> None: - assert args.robot is not None,\ + assert args.robot is not None, \ "You must specify the --robot to use" diff --git a/sierra/core/ros1/variables/exp_setup.py b/sierra/core/ros1/variables/exp_setup.py index 62c5851b..a57d705b 100644 --- a/sierra/core/ros1/variables/exp_setup.py +++ b/sierra/core/ros1/variables/exp_setup.py @@ -4,7 +4,7 @@ """Classes for the ``--exp-setup`` cmdline option for ROS1 platforms. -See :ref:`ln-sierra-vars-expsetup` for usage documentation. +See :ref:`usage/vars/expsetup` for usage documentation. """ diff --git a/sierra/core/storage.py b/sierra/core/storage.py index 6395ad3c..94606fe6 100755 --- a/sierra/core/storage.py +++ b/sierra/core/storage.py @@ -2,9 +2,9 @@ # # SPDX-License-Identifier: MIT """ -Terminal interfare for the various storage plugins that come with SIERRA. +Terminal interface for the various storage plugins that come with SIERRA. -See :ref:`ln-sierra-tutorials-plugin-storage` for more details. +See :ref:`tutorials/plugin/storage` for more details. """ # Core packages diff --git a/sierra/core/variables/exp_setup.py b/sierra/core/variables/exp_setup.py index bcf5b9c7..457c3941 100644 --- a/sierra/core/variables/exp_setup.py +++ b/sierra/core/variables/exp_setup.py @@ -18,7 +18,7 @@ class Parser(): """Enforces the cmdline definition of ``--exp-setup``. - See :ref:`ln-sierra-vars-expsetup` for documentation. + See :ref:`usage/vars/expsetup` for documentation. """ @@ -32,7 +32,7 @@ def __call__(self, arg: str) -> types.CLIArgSpec: # remove variable name, leaving only the spec sections = sections[1:] - assert len(sections) >= 1 and len(sections) <= 3,\ + assert len(sections) >= 1 and len(sections) <= 3, \ ("Spec must have between 1 and 3 sections separated by '.'; " f"have {len(sections)} from '{arg}'") diff --git a/sierra/plugins/platform/argos/cmdline.py b/sierra/plugins/platform/argos/cmdline.py index 42a663d5..3b9b4ed0 100755 --- a/sierra/plugins/platform/argos/cmdline.py +++ b/sierra/plugins/platform/argos/cmdline.py @@ -61,7 +61,7 @@ def init_stage1(self) -> None: ` per second for the experiment ( tag), # of datapoints to capture/capture interval for each - simulation. See :ref:`ln-sierra-vars-expsetup` for + simulation. See :ref:`vars/expsetup` for a full description. """ + self.stage_usage_doc([1]), diff --git a/sierra/plugins/platform/argos/variables/exp_setup.py b/sierra/plugins/platform/argos/variables/exp_setup.py index 2aff02c7..d1ac6472 100644 --- a/sierra/plugins/platform/argos/variables/exp_setup.py +++ b/sierra/plugins/platform/argos/variables/exp_setup.py @@ -4,7 +4,7 @@ """Classes for the ``--exp-setup`` cmdline option. -See :ref:`ln-sierra-vars-expsetup` for usage documentation. +See :ref:`usage/vars/expsetup` for usage documentation. """ diff --git a/sierra/plugins/platform/argos/variables/population_constant_density.py b/sierra/plugins/platform/argos/variables/population_constant_density.py index 6947c984..4777f6c2 100755 --- a/sierra/plugins/platform/argos/variables/population_constant_density.py +++ b/sierra/plugins/platform/argos/variables/population_constant_density.py @@ -4,7 +4,7 @@ # """Classes for the constant population density batch criteria. -See :ref:`ln-sierra-platform-argos-bc-population-constant-density` for usage +See :ref:`plugins/platform/argos/bc/population-constant-density` for usage documentation. """ diff --git a/sierra/plugins/platform/argos/variables/population_size.py b/sierra/plugins/platform/argos/variables/population_size.py index 8df2feb0..07bf83c6 100755 --- a/sierra/plugins/platform/argos/variables/population_size.py +++ b/sierra/plugins/platform/argos/variables/population_size.py @@ -3,7 +3,7 @@ # SPDX-License-Identifier: MIT """Classes for the population size batch criteria. -See :ref:`ln-sierra-platform-argos-bc-population-size` for usage documentation. +See :ref:`plugins/platform/argos/bc/population-size` for usage documentation. """ diff --git a/sierra/plugins/platform/argos/variables/population_variable_density.py b/sierra/plugins/platform/argos/variables/population_variable_density.py index e30a9862..69968198 100755 --- a/sierra/plugins/platform/argos/variables/population_variable_density.py +++ b/sierra/plugins/platform/argos/variables/population_variable_density.py @@ -4,7 +4,7 @@ # """Classes for the variable population density batch criteria. -See :ref:`ln-sierra-platform-argos-bc-population-variable-density` for usage +See :ref:`plugins/platform/argos/bc/population-variable-density` for usage documentation. """ diff --git a/sierra/plugins/platform/ros1gazebo/variables/population_size.py b/sierra/plugins/platform/ros1gazebo/variables/population_size.py index 80fd0ee3..dc49fc43 100755 --- a/sierra/plugins/platform/ros1gazebo/variables/population_size.py +++ b/sierra/plugins/platform/ros1gazebo/variables/population_size.py @@ -3,7 +3,7 @@ # SPDX-License-Identifier: MIT """Classes for the population size batch criteria. -See :ref:`ln-sierra-platform-ros1gazebo-bc-population-size` for usage +See :ref:`plugins/platform/ros1gazebo/bc/population-size` for usage documentation. """ diff --git a/sierra/plugins/platform/ros1robot/cmdline.py b/sierra/plugins/platform/ros1robot/cmdline.py index 4273e704..c210c1ed 100755 --- a/sierra/plugins/platform/ros1robot/cmdline.py +++ b/sierra/plugins/platform/ros1robot/cmdline.py @@ -137,23 +137,23 @@ def init_stage2(self) -> None: default=False) @staticmethod - def cmdopts_update(cli_args, cmdopts: types.Cmdopts) -> None: + def cmdopts_update(args: argparse.Namespace, cmdopts: types.Cmdopts) -> None: """Update cmdopts with ROS1+robot-specific cmdline options. """ - ros1.cmdline.ROSCmdline.cmdopts_update(cli_args, cmdopts) + ros1.cmdline.ROSCmdline.cmdopts_update(args, cmdopts) updates = { # Multistage 'exec_jobs_per_node': 1, # (1 job/robot) - 'skip_online_check': cli_args.skip_online_check, - 'online_check_method': cli_args.online_check_method, + 'skip_online_check': args.skip_online_check, + 'online_check_method': args.online_check_method, # stage 1 - 'skip_sync': cli_args.skip_sync, + 'skip_sync': args.skip_sync, # stage 2 - 'exec_resume': cli_args.exec_resume, - 'exec_inter_run_pause': cli_args.exec_inter_run_pause + 'exec_resume': args.exec_resume, + 'exec_inter_run_pause': args.exec_inter_run_pause } cmdopts.update(updates) diff --git a/sierra/plugins/platform/ros1robot/variables/population_size.py b/sierra/plugins/platform/ros1robot/variables/population_size.py index 7280438a..525fe68c 100755 --- a/sierra/plugins/platform/ros1robot/variables/population_size.py +++ b/sierra/plugins/platform/ros1robot/variables/population_size.py @@ -3,7 +3,7 @@ # SPDX-License-Identifier: MIT """Classes for the population size batch criteria. -See :ref:`ln-sierra-platform-ros1robot-bc-population-size` for usage +See :ref:`plugins/platform/ros1robot/bc/population-size` for usage documentation. """ diff --git a/todo.org b/todo.org index fc953125..6e90e3f4 100644 --- a/todo.org +++ b/todo.org @@ -1,5 +1,5 @@ * SIERRA :sierra: -** TODO [#B] Add additional integration tests [50%] +** TODO [#B] Add additional integration tests [60%] - [X] Verifying ARGoS stage 1,2,3,4 outputs - [X] Testing ARGoS video generation - [X] Verifying ROS1+Gazebo stage 1 outputs @@ -12,39 +12,21 @@ core not tested by the plugin integration tests. This should get its own workflow file. What shows up as github badges should be a core+plugins yml file with an "Integration tests" label. -- [ ] Testing that the generated experiments match between python versions - (i.e., file contents is the same). - [ ] Simple model for testing in the sample project, associated tests - [ ] Switch from bash to something else (python/noxfile?); my scripts are getting too complicated. +- [X] Imagizing integration tests ** TODO Add additional unit tests [0%] - [ ] Parser unit tests (for CLI variables that can be used as batch criteria) - [ ] Nodefile parsing -** TODO Better tasking framework/organization -- Switch to calling nox instead of calling bash directly from the yml workflow -files. This will allow me to easily parameterize multiple versions of python, -AND reduce the # of jobs I need/total workflow runtime on github by a good bit. - -** TODO Switch from cmdopts dictionary to a data class with fields -I will get WAY better help from the static analyzer - ** TODO Add quick quick start: a linux VM with SIERRA all set up and ready to go ** TODO Added tutorial for creating a new model - And add an example in the sample project ** TODO Add --seed to gazebo commands so experiments are more idempotent -** TODO Change n_robots -> n_agents everywhere - -** TODO Add short options with some category prefixes -- To emulate GCC syntax, which is really nice. Some ideas: --E -> --exec- --e -> --exp- --s -> --skip- --L -> --plot- --c -> --controller- ** TODO [#A] Add plugin interface for experimental inputs - This is needed as part of making SIERRA directly able to support platforms @@ -59,12 +41,14 @@ setup written to the pkl file. Might be helpful to spot trends among different controllers. Would also need to be implemented in stage 5 as another comparison option. -** TODO [#B] Remove **kwargs usage from graphs--explicit arguments leads to way better type checking +** TODO [#B] Remove **kwargs usage from graphs--explicit arguments leads to way +better type checking ** TODO [#B] Rename perf measure config from 'perf' to 'stage1/stage3/stage4/etc'. Much clearer this way. Also fits better with the 'stage5.yaml' config file idea. ** TODO [#C] Check out the fastcore library ** TODO [#C] Try Modin as a parallel pandas wrapper +** TODO [#C] Fix all links in document to not be prefixed with 'ln-sierra' ** TODO [#B] Document why you need 2 GNU parallel processes for rosrobot :sierra: Because you can't have robot controllers running on the master, which could happen if you only had a single GNU parallel process. @@ -167,3 +151,33 @@ Does what I do, but much better ** DONE Add sys.excepthook hook asking the user to file a bug. CLOSED: [2022-10-18 Tue 15:02] + +** DONE Switch from cmdopts dictionary to a data class with fields +CLOSED: [2024-11-12 Tue 12:53] +I will get WAY better help from the static analyzer + +** DONE Add short options with some category prefixes +CLOSED: [2024-11-13 Wed 11:21] +- To emulate GCC syntax, which is really nice. Some ideas: +-E -> --exec- +-e -> --exp- +-s -> --skip- +-L -> --plot- +-c -> --controller- + +After implementing this, I'm not sure at this point that there is that much +value in doing this, because it adds more complexity than it removes for most +users. But its there, and can be removed easily enough... + +** DONE Change n_robots -> n_agents everywhere +CLOSED: [2024-11-13 Wed 11:22] + +** DONE Better tasking framework/organization +CLOSED: [2024-11-13 Wed 11:24] +- Switch to calling nox instead of calling bash directly from the yml workflow +files. This will allow me to easily parameterize multiple versions of python, +AND reduce the # of jobs I need/total workflow runtime on github by a good bit. + +** DONE [#B] Make all fs paths shown be relative to batch root +CLOSED: [2024-11-19 Tue 11:27] +- Screen will be much less cluttered; could make this toggleable if desired.