Merge pull request #82 from SENSEI-insitu/curation-vignettes

Vignettes collected by the team

.github/workflows/base-library.yml

@@ -19,7 +19,7 @@ jobs:
           export DEBIAN_FRONTEND="noninteractive"
           export TZ="America/Los_Angeles"
           sudo apt-get update -qq
-          sudo apt-get install -qq -y git-core gcc g++ gfortran cmake ninja-build subversion automake m4 wget swig python3-dev mpich python3-numpy python3-mpi4py
+          sudo apt-get install -qq -y git-core gcc g++ gfortran cmake ninja-build subversion automake m4 wget swig python3-dev openmpi-bin libopenmpi-dev python3-numpy python3-mpi4py
       - name: Setup CCache
         uses: hendrikmuhs/ccache-action@v1.2
         with:

rtd-docs/conf.py

@@ -66,6 +66,7 @@
 # source_suffix = ['.rst', '.md']
 source_suffix = '.rst'
 
+
 # The master toctree document.
 master_doc = 'index'
 
@@ -82,8 +83,9 @@
 # add any included files to this list to silence warnings about 
 # duplicate references
 exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store', \
-     'reaction_rate_demo', 'adaptor_apisi.rst', 'data_addaptor_apis.rst', \
-     'analysis_adaptor_apis.rst']
+    'data_adaptor_api.rst', 'analysis_adaptor_api.rst', 'ascent_back_end.rst', \
+    'catalyst_back_end.rst', 'histogram_back_end.rst', 'autocorrelation_back_end.rst', \
+    'reaction_rate_demo.rst', 'pipeline_demo.rst']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'friendly'
@@ -107,6 +109,12 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = [
+    'theme_overrides.css',
+]
+
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.
 #

rtd-docs/data_adaptor_api.rst

@@ -15,8 +15,8 @@ Finally the data adaptor is a key piece of SENSEI's in transit system. The
 analysis back end can be run in a different parallel job and be given an in
 transit data adaptor in place of the simulation's data adaptor. In this scenario
 the in transit data adaptor helps move data needed by the analysis back end.
-The data adaptor API enables this scenario to apear the same to the simulation
-and the analysis back end. Neither simulaiton nor analysis need be modified for
+The data adaptor API enables this scenario to appear the same to the simulation
+and the analysis back end. Neither simulation nor analysis need be modified for
 in transit processing.
 
 

rtd-docs/data_model.rst

@@ -1,4 +1,5 @@
 .. _data_model:
+
 Data model
 ==========
 The data model is a key piece of the system. It allows data to be packaged and

rtd-docs/examples.rst

@@ -1,9 +1,8 @@
 .. _examples:
+
 *********
 Examples
 *********
 
 .. include:: reaction_rate_demo.rst
 .. include:: pipeline_demo.rst
-
-

rtd-docs/examples_amrex_tutorials.rst

@@ -0,0 +1,129 @@
+.. _amrextutorials:
+
+***********************************************
+SENSEI + AMReX
+***********************************************
+
+========
+Synopsis
+========
+
+AMReX is a freely available simulation software framework designed to enable massively parallel block-structured adaptive mesh refinement (AMR) applications.
+
+The `AMReX Tutorials repository <https://github.com/AMReX-Codes/amrex-tutorials>`_ houses several tutorial examples demonstrating the use of SENSEI in AMReX based simulation codes. The full list of tutorials are documented `here <https://amrex-codes.github.io/amrex/tutorials_html/>`_.
+
+--------
+Overview
+--------
+
+Two distinct tutorial examples are available with multiple configurations:
+
++--------------------+---------------------------------------------------------------------------+
+| Name               | Description                                                               |
++====================+===========================================================================+
+| Advection_AmrCore  | This tutorial illustrates an explicit SENSEI instrumentation of a code    |
+|                    | that makes use of `amrex::AmrMesh`.                                       |
++--------------------+---------------------------------------------------------------------------+
+| Advection_AmrLevel | This tutorial illustrates 3 scenarios with a code that makes use of       |
+|                    | `amrex::Amr`. The first, `ImplcitAmr`, illustrates using SENSEI with the  |
+|                    | built-in instrumentation in `amrex::Amr`. The second, `ExplcitAmr`,       |
+|                    | illustrates using SENSEI with an explicit instrumentation. The third,     |
+|                    | `ExplicitParticlesAndAmr`, illustrates using SENSEI from a simulation     |
+|                    | that generates both particle and meshed based data.                       |
++--------------------+---------------------------------------------------------------------------+
+
+Note that the `Advection_AmrLevel` contains code for 3 different scenarios.
+Which of these is active/available depends on how AMReX is compiled. See below
+for the details on configuring the build.
+
+
+==========
+Setting Up
+==========
+
+Compiling the AMReX SENSEI tutorials requires that SENSEI is previously
+installed. The options that SENSEI was built with determine the specific in
+situ capabilities available. Additional CMake options must also be passed
+when compiling AMReX to activate the SENSEI bridge and adaptors bundled
+with AMReX. The AMReX library is available on `GitHub <https://github.com/AMReX-Codes/amrex>`_.
+
+-------------
+Build options
+-------------
+
+The options that AMReX is compiled with determine which SENSEI tutorials are
+available. The following table summarizes the various combinations and results.
+
++---------------------------------+--------------------------------------------------------------+
+| CMake Options                   | What gets built                                              |
++=================================+==============================================================+
+| -DAMReX_SENSEI=ON               | Enables SENSEI features in AMReX. Required to compile SENSEI |
+| -DAMReX_FORTRAN=ON              | tutorials. Enables the AmrCore tutorial and AmrLevel         |
+| -DSENSEI_DIR=<path to install>  | implicit tutorial.                                           |
++---------------------------------+--------------------------------------------------------------+
+| -DAMReX_SENSEI=ON               | Enables the AmrCore tutorial, AmrLevel explicit tutorial,    |
+| -DAMReX_PARTICLES=ON            | and particle based tutorials to be compiled.                 |
+| -DAMReX_NO_SENSEI_AMR_INST=TRUE |                                                              |
+| -DAMReX_FORTRAN=ON              |                                                              |
+| -DSENSEI_DIR=<path to install>  |                                                              |
++---------------------------------+--------------------------------------------------------------+
+| -DAMReX_SENSEI=ON               | Enables the AmrCore tutorial, AmrLevel explicit tutorial.    |
+| -DAMReX_NO_SENSEI_AMR_INST=TRUE |                                                              |
+| -DAMReX_FORTRAN=ON              |                                                              |
+| -DSENSEI_DIR=<path to install>  |                                                              |
++---------------------------------+--------------------------------------------------------------+
+
+===================
+Running the Example
+===================
+
+Once the tutorials are compiled they can be run from their corresponding
+directory.  The executable is passed an AMReX parm-parse `inputs` file
+configuring the run. Options inside the `inputs` file configure the SENSEI
+instrumentation inside AMReX. Additionally SENSEI needs to configure the
+back-end that will process the data generated. This is done with a SENSEI XML
+file. Within each tutorial the `sensei` directory contains a number of SENSEI
+XML configuration files. The `inputs` file must be modified to point to one of
+these. Which one depends on how SENSEI was compiled. For instance the following
+snippet from an `inputs` file would configure SENSEI to send data to ParaView
+Catalyst,
+
+.. highlight:: shell
+
+::
+
+   sensei.enabled = 1                                 # turn SENSEI in situ on/off
+   sensei.config = sensei/render_iso_catalyst_3d.xml  # render simulation data with ParaView Catalyst
+   sensei.frequency = 1                               # number of level 0 steps between in situ processing
+
+while the following snippet would configure SENSEI to send data to VisIt Libsim,
+
+.. highlight:: shell
+
+::
+
+   sensei.enabled = 1                                 # turn SENSEI in situ on/off
+   sensei.config = sensei/render_iso_libsim_3d.xml    # render simulation data with ParaView Catalyst
+   sensei.frequency = 1                               # number of level 0 steps between in situ processing
+
+There are a number of XML files providing the configuration for a number of the
+available back-ends. A given SENSEI XML configuration is only valid when the
+SENSEI install has been compiled with the requisite back-end enabled.
+
+Note that the `Advection_AmrLevel_ExplicitParticlesAndAmr` uses the file
+`inputs.tracers` while the others use the file `inputs`.
+
+The tutorials are run by switching into the tutorial's build directory and
+issuing the launching command. For instance the
+`Advection_AmrLevel_ImplicitAmr` tutorial is launched by a command similar to:
+
+.. highlight:: shell
+
+::
+
+   mpiexec -np 4 ./Advection_AmrLevel_ImplicitAmr inputs
+
+=======
+Results
+=======
+

rtd-docs/examples_catalyst_bidirectional.rst

@@ -0,0 +1,83 @@
+.. _catalystbidirectional:
+
+***********************************************
+Computational Steering with Catalyst and SENSEI
+***********************************************
+
+========
+Synopsis
+========
+
+In this example, we demonstrate using SENSEI with a bidirectional Catalyst 1.0
+Analysis Adaptor to perform computational steering. Here, we employ the
+oscillator miniapp. The list of oscillator objects are exposed to Catalyst
+where each oscillator can be manipulated. Position of oscillators as well as
+oscillator properties can be modified on the fly, changing the behavior of the
+simulated domain.
+
+==========
+Setting Up
+==========
+
+You will need ParaView 5.10 installed, and SENSEI compiled with the options
+`ENABLE_CATALYST` and `ENABLE_CATALYST_PYTHON` turned on.
+
+Note, only Catalyst 1.0 scripts are compatible with computational steering in
+SENSEI. Unfortunately, those scripts cannot be generated automatically in the
+most recent editions of ParaView. The provided example script can be modified
+manually for your own purposes.
+
+===================
+Running the Example
+===================
+
+Open the ParaView application and navigate to `Tools`->`Manage Plugins`. Press
+the `Load New...` button, and navigate the file browser to the location of the
+`oscillator_catalyst_steering_proxies.xml` file, and select that file.
+
+Next, navigate to `Catalyst`->`Connect` and accept incoming connections on port
+22222. This will tell ParaView to begin listening for Catalyst connections on
+that port. If a different port number is desired, you will need to edit the
+port number in the Catalyst python script `oscillator_catalyst_steering.py` to
+the desired port, and then start Catalyst in ParaView with the same desired
+port number.
+
+In a terminal, navigate to your desired run directory (this testing directory
+is fine to run from), and start the oscillator miniapp with the SENSEI config
+xml `oscillator_catalyst_steering.xml`. Oscillator miniapp options can be set
+as desired, but a good starting point is:
+
+.. code-block:: bash
+
+    $ mpirun -np 1 /path/to/oscillator -g 1 -t 0.01 -f oscillator_catalyst_steering.xml simple.osc
+
+With the Oscillator miniapp running, ParaView should automatically detect a new Catalyst connection and add several items to the catalsyt server list in the `Pipeline Browser`. Clicking the icon next to `mesh` and `oscillator` will display the data to the 3D viewport, updating as the miniapp progresses.
+
+Click on the `Steering Parameters` item in the `Pipeline Browser`. The `Properties` panel will display several controls over each oscillator which can be modified, manipulating the oscillator parameters as the miniapp executes.
+
+.. figure:: images/pv_catalyst_steering_gui.png
+   :width: 30 %
+   :align: center
+
+   The Properties panel provides parameters to add or delete oscillators in the domain, and change the parameters of the oscillators independently.
+
+
+.. figure:: images/pv_catalyst_steering_window.png
+   :width: 80 %
+   :align: center
+
+   ParaView's GUI contains the Properties panel, where oscillator parameters can be edited, a center 3D Viewport where the oscillators are rendered using ray-traced volume rendering, and a second 3D Viewport where the 5 existing oscillators' locations are visualized with respect to one another.
+
+
+=======
+Results
+=======
+
+The key takeaway from this example is that Catalyst and SENSEI can be used to
+perform computational steering tasks with in situ visualization. The
+oscillators, whose properties and locations can be modified in situ, respond to
+the user's modifications. Setting up such a computational steering workflow in
+your own simulation code requires exposing desired parameters to SENSEI, and
+writing XML instructions for ParaView to generate the GUI for modifying the
+parameters.
+

rtd-docs/examples_example_rst.rst

@@ -0,0 +1,55 @@
+.. _example_example:
+
+Example Template
+==========================
+
+Come up with a decent title and underline it with your favorite non-alphanumeric character (# is a good choice).
+
+Synopsis
+########
+
+Write a quick synopsis of your example. Detail briefly how it uses SENSEI and what code you are connecting to. `Hyperlinks <https://xkcd.com/2632/>`_ to the science code/repository are appropriated here.
+
+Setting Up
+##########
+
+Here, we provide instructions on how to setup the build environment. Briefly describe which options you want for this example in SENSEI, but don't worry about going into detail about building dependencies that SENSEI needs as that is documented elsewhere (I hope...). Detail whatever unique build options and weird steps are required to build the science code with SENSEI enabled, but do not go into depth on how to build that science code in general, simply link to their build instructions (which are hopefully well documented).
+
+If there are multiple ways of setting up the science code, or there are multiple ways to build SENSEI which provide different functionality, detail those variations here as well.
+
+Running the Example
+###################
+
+Next, we detail the procedures to run the example. You will want to include your SENSEI config xml(s) here like this:
+
+.. _python_insitu_xml:
+.. code-block:: xml
+
+   <sensei>
+     <analysis type="python" script_file="configs/volume_above_sm.py" enabled="1">
+       <initialize_source>
+   threshold=1.0
+   mesh='mesh'
+   array='data'
+   cen=1
+   out_file='random_2d_64_python.png'
+        </initialize_source>
+     </analysis>
+   </sensei>
+
+Subsections would be worthwhile if there are multiple ways to run the example.
+
+You can write terminal commands here like this:
+
+.. code-block:: shell
+
+mpirun -np 1 /path/to/oscillator -g 1 -t 0.01 -f oscillator_catalyst_steering.xml simple.osc
+
+If you have simple supplementary scripts (like Catalyst Python scripts, or bash scripts), you may want to write them in here as well, though sometimes these get quite long, and a hyperlink to the source code will suffice.
+
+For interactive examples (i.e. steering), provide instructions for interacting with the example.
+
+Results
+#######
+
+Finally, briefly showcase what successfully running the example will yield. Provide pictures of output, or sample data output etc.

rtd-docs/examples_intransit.rst

@@ -0,0 +1,52 @@
+.. _example_intransit:
+
+In Transit MxN communication with LAMMPS, SENSEI, and Paraview/Catalyst
+=======================================================================
+
+Synopsis
+########
+
+In this example we instrument the molecular dynamics simulation code LAMMPS with SENSEI and demonstrate in transit capabilities. Our example showcases M to N ranks redistribution and the Catalyst analysis adaptor to generate a Cinema database.
+
+Setting Up
+##########
+
+This example uses Docker containers. There are two containers: (1) Producer, which uses the LAMMPS molecular dynamics simulator instrumented with SENSEI; and (2) Consumer, which uses the SENSEI endpoint and the Paraview/Catalyst analysis adaptor. 
+
+A Zenodo artifact is available at https://zenodo.org/record/6336286 , containing Dockerfile recipes to build the Producer and Consumer. Please refer to file "containers.zip"
+
+You should be able to build your own images with the Dockerfiles provided. If you would like to use prebuilt docker containers you can get them from the Docker hub:
+
+.. highlight:: shell
+
+::
+
+   docker pull srizzi/woiv22producer_runtime
+   docker pull srizzi/woiv22consumer_runtime
+
+If your site uses Singularity you can build Singularity images pulling from the Docker hub
+
+Running the Example
+###################
+
+From the same Zenodo artifact, you can download "in_transit_demo_files.zip" , containing SENSEI xml configuration files and scripts to run the demo.
+
+The LAMMPS producer is configured to run a simple simulation configured in file in_lj
+
+With the parameters in in_lj the simulation evolves about 16 million hydrogen atoms. If you would like to change the size of the simulation, edit the multipliers for xx, yy, and zz in file in_lj. The multipliers are 16 in the file provided, which results in 67108864 atoms simulated.
+
+The producer is launched with producer.sh . Notice that settings in this script are specific for ThetaGPU, but you should not find any major difficulties if you wish to adapt it for your system. The script also relies on a local build of mpich.
+
+Notice that SENSEI uses the file adios_write_sst.xml to configure its backend. You will likely need to change the NetworkInterface in this xml file with an appropiate value for your own system.
+
+The consumer side contains SENSEI with ParaView/Catalyst. For simplicity, in this demo we use the PosthocIO backend, which saves the received data in VTK format.
+
+The consumer is launched with script consumer.sh and there are two xml configuration files required for SENSEI. The first defines the network transport and its called adios_transport_sst.xml . Once again, you may need to change the NetworkInterface parameter in this file according to your system.
+The second xml file, vtk_io.xml in this case, activates the PosthocIO analysis adaptor in SENSEI and specifies a directory to save the data.
+
+These are intended to run on different machines and different ranks on producer (M) and consumer (N). The scripts provided will launch 16 MPI ranks on the producer and 4 MPI ranks on the consumer.
+
+Results
+#######
+
+The simulation is configure to run five timesteps. The SENSEI endpoint should receive data for each timestep and save it as VTK files.