CloverLeaf3D Ascent Demos

Here we use Ascent’s example Cloverleaf3D integration to demonstrate basic Ascent usage.

Cloverleaf3D is written in Fortran and depends on MPI, Ascent installs with Fortran and MPI enabled include Cloverleaf3D.

Rendering and transforming data using Ascent’s Pipelines and Scenes

Use Ascent’s pipelines in Cloverleaf3D to transform data and render in situ

For this demo, we will use Ascent to process data from Cloverleaf3D in situ.

To begin, make sure you are in the examples/ascent/proxies/cloverleaf3d directory of your Ascent install.

The default integration example for Cloverleaf3D sets up Ascent to volume render the energy field. Here is a snippet of the related Fortran code that specifies the default actions:

      sim_actions = conduit_node_create()
      add_scene_act = conduit_node_append(sim_actions)
      CALL conduit_node_set_path_char8_str(add_scene_act,"action", "add_scenes")

      scenes = conduit_node_fetch(add_scene_act,"scenes")
      CALL conduit_node_set_path_char8_str(scenes,"s1/plots/p1/type", "volume")
      CALL conduit_node_set_path_char8_str(scenes,"s1/plots/p1/field", "energy")

      CALL ascent_publish(my_ascent, sim_data)
      CALL ascent_execute(my_ascent, sim_actions)

      CALL conduit_node_destroy(sim_actions)
      CALL conduit_node_destroy(sim_data)

Ascent also allows you to override compiled in actions with a ascent_actions.yaml file. In this case, the file we provide with Cloverleaf3D mirrors the compiled in actions:

Cloverleaf3D default ascent_actions.yaml file (examples/ascent/proxies/cloverleaf3d-ref/ascent_actions.yaml):

-
  action: "add_scenes"
  scenes:
    s1:
      plots:
        p1:
          type: "volume"
          field: "energy"

We will override the default actions to compute contours of the input data and render the result. To do this we use a pipeline. Ascent’s pipelines allow you add transforms that modify the mesh data published to Ascent. Pipeline results can be rendered in a scene or used as input to extracts.

Edit the ascent_actions.yaml to create a pipeline that computes contours and renders them using a pseudocolor plot:

-
  action: "add_pipelines"
  pipelines:
    pl1:
      f1:
        type: "contour"
        params:
          field: "velocity_x"
          iso_values: 1.0
-
  action: "add_scenes"
  scenes:
    scene1:
      plots:
        plt1:
          type: "pseudocolor"
          pipeline: "pl1"
          field: "pressure"

(Also available in install directory: examples/ascent/cloverleaf_demos/pipelines_and_scenes/contour.yaml)

You can also compose more complex scenes that render both pipeline results and the published data. To demonstrate this, we combine the pseudocolor rendering of the contour results with a volume rendering of the entire mesh:

-
  action: "add_pipelines"
  pipelines:
    pl1:
      f1:
        type: "contour"
        params:
          field: "velocity_x"
          iso_values: 1.0
-
  action: "add_scenes"
  scenes:
    scene1:
      plots:
        plt1:
          type: "pseudocolor"
          pipeline: "pl1"
          field: "pressure"
        plt2:
          type: "volume"
          field: "energy"

(Also available in install directory: examples/ascent/cloverleaf_demos/pipelines_and_scenes/volume_contour.yaml)

Creating a Cinema image database for post-hoc exploration

Use Ascent to create a Cinema database from Cloverleaf3D that can be explored after the simulation finishes

In this demo, we use Ascent to render out a Cinema database of a plot in Cloverleaf3D.

Make sure you are in examples/ascent/proxies/cloverleaf3d directory of your Ascent install. Edit the Cloverleaf3D ascent_actions.yaml file to direct Ascent to render out a scene using the Cinema Astaire specification (Spec-A):

-
  action: "add_scenes"
  scenes:
    s1:
      plots:
        p1:
          type: "volume"
          field: "energy"
          min_value: 1
          max_value: 3
      renders:
        r1:
          type: "cinema"
          phi: 4
          theta: 4
          db_name: "clover_db"

(Also available in install directory: examples/ascent/tutorial/cloverleaf_demos/cinema/ascent_actions.yaml)

Run Cloverleaf3D with this setup and it will render several viewpoints and construct Cinema database in the current directory. You can then open this database with a Cinema viewer and interactively explore views of data set after the simulation finishes.

Using a Python Extract to execute custom Python analysis

Use Ascent to run a Python script which computes a histogram of Cloverleaf3D’s energy field in situ

Ascent’s Python extract provides a simple path to run Python scripts for custom analysis. Ascent provides the Python environment, so Python extracts can for any host code (even those without a Python interface). Ascent’s Python environment supports distributed-memory executing with a Python interpreter per MPI task.

For this demo we use numpy and mpi4py to compute a histogram of Cloverleaf3D’s energy field.

Again, since we will use the Cloverleaf3D Ascent integration, make sure you are in the examples/ascent/proxies/cloverleaf3d directory of your Ascent install. Then edit the ascent_actions.yaml file to define a single python extract that runs a script file:

-
  action: "add_extracts"
  extracts:
    e1:
      type: "python"
      params:
        file: "ascent_python_extract_histogram_demo.py"

(Also available in install directory: examples/ascent/tutorial/python_extract/ascent_actions.yaml)

This requests a python extract that will use an embedded python interpreter to execute ascent_tutorial_python_extract_histogram.py, which is specified using the file parameter. The python extract also supports a source parameter that allows you to pass a python script as a string.

Next, create our analysis script ascent_tutorial_python_extract_histogram..py:

###############################################################################
#
# file: ascent_tutorial_python_extract_histogram.py
#
###############################################################################

import numpy as np
from mpi4py import MPI

# obtain a mpi4py mpi comm object
comm = MPI.Comm.f2py(ascent_mpi_comm_id())

# get this MPI task's published blueprint data
mesh_data = ascent_data().child(0)

# fetch the numpy array for the energy field values
e_vals = mesh_data["fields/energy/values"]

# find the data extents of the energy field using mpi

# first get local extents
e_min, e_max = e_vals.min(), e_vals.max()

# declare vars for reduce results
e_min_all = np.zeros(1)
e_max_all = np.zeros(1)

# reduce to get global extents
comm.Allreduce(e_min, e_min_all, op=MPI.MIN)
comm.Allreduce(e_max, e_max_all, op=MPI.MAX)

# compute bins on global extents
bins = np.linspace(e_min_all, e_max_all)

# get histogram counts for local data
hist, bin_edges = np.histogram(e_vals[0], bins = bins[0])

# declare var for reduce results
hist_all = np.zeros_like(hist)

# sum histogram counts with MPI to get final histogram
comm.Allreduce(hist, hist_all, op=MPI.SUM)

# print result on mpi task 0
if comm.Get_rank() == 0:
    print("\nEnergy extents: {} {}\n".format(e_min_all[0], e_max_all[0]))
    print("Histogram of Energy:\n")
    print("Counts:")
    print(hist_all)
    print("\nBin Edges:")
    print(bin_edges)
    print("")

(Also available in install directory: examples/ascent/tutorial/cloverleaf_demos/python_extract/ascent_python_extract_histogram_demo.py)

This script computes a basic histogram counting the number of energy field elements that fall into a set of uniform bins. It uses numpy’s histogram function and mpi4py to handle distributed-memory coordination.

Note, there are only two functions provided by ascent:

  • ascent_data()

    Returns a Conduit tree with the data published to this MPI Task.

    Conduit’s Python API mirrors its C++ API, but with leaves returned as numpy.ndarrays. For examples of how to use Conduit’s Python API, see the Conduit Python Tutorial. In this script, we simply fetch a ndarray that points to the values of a known field, energy.

  • ascent_mpi_comm_id()

    Returns the Fortran style MPI handle (an integer) of the MPI Communicator Ascent is using.

    In this script, we use this handle and mpi4py.MPI.Comm.f2py() to obtain a mpi4py Communicator.

Finally, run Cloverleaf3D:

mpiexec -n 2 ./cloverleaf3d_par

With the default clover.in settings, Ascent execute the python script every 10th cycle. The script computes the histogram of the energy field and prints a summary like the following:

Energy extents: 1.0 2.93874088025

Histogram of Energy:

Counts:
[159308   4041   1763   2441   2044   1516   1780   1712   1804   1299
   1366   1959   1668   2176   1287   1066    962   2218   1282   1006
   1606   2236   1115   1420   1185   1293   2495   1255   1191   1062
   1435   1329   2371   1619   1067   2513   3066   2124   2755   3779
   3955   4933   2666   3279   3318   3854   3123   4798   2604]

Bin Edges:
[ 1.          1.03956614  1.07913228  1.11869842  1.15826456  1.1978307
  1.23739684  1.27696298  1.31652912  1.35609526  1.3956614   1.43522754
  1.47479368  1.51435983  1.55392597  1.59349211  1.63305825  1.67262439
  1.71219053  1.75175667  1.79132281  1.83088895  1.87045509  1.91002123
  1.94958737  1.98915351  2.02871965  2.06828579  2.10785193  2.14741807
  2.18698421  2.22655035  2.26611649  2.30568263  2.34524877  2.38481491
  2.42438105  2.4639472   2.50351334  2.54307948  2.58264562  2.62221176
  2.6617779   2.70134404  2.74091018  2.78047632  2.82004246  2.8596086
  2.89917474  2.93874088]

Using the Jupyter Extract for interactive Python analysis

Use Jupyter Notebook with Ascent to interactively analyze and visualize your data in situ

Ascent’s Jupyter extract provides a path for interactive analysis and visualization in Jupyter Notebook. The Jupyter extract is an extension of the Python extract that allows tweaking of analysis methods as the simulation runs.

In this demo we provide two example Jupyter Notebooks with code and instructions under examples/ascent/tutorial/jupyter_extract/notebooks and demonstrate how to connect them with Ascent.

First you will need to install the ascent_jupyter_bridge python module located in your source directory under src/ascent/ascent_jupyter_bridge. Navigate to that directory and make sure you have pip installed then run the following commands:

pip install -r requirements.txt
pip install .

If you are at a site that does SSL interception and can not configure your SSL certificates to avoid pip SSL errors, you can use the following:

pip install  --trusted-host pypi.org --trusted-host files.pythonhosted.org -r requirements.txt
pip install  --trusted-host pypi.org --trusted-host files.pythonhosted.org .

We will once again use the Cloverleaf3D Ascent integration, so make sure you are in the examples/ascent/proxies/cloverleaf3d directory of your Ascent install. Then edit the ascent_actions.yaml file to request that Ascent run the Jupyter extract:

-
  action: "add_extracts"
  extracts:
    e1:
      type: "jupyter"

(Also available in install directory: examples/ascent/tutorial/cloverleaf_demos/jupyter_extract/ascent_actions.yaml)

Finally, run Cloverleaf3D:

mpiexec -n 2 ./cloverleaf3d_par

After the simulation has progressed a number of timesteps it will wait for a connection from Jupyter Notebook. To connect to a demo notebook make sure you are in examples/ascent/tutorial/jupyter_extract/notebooks and run:

jupyter notebook

This will start Jupyter Notebook in your browser where you will see our demo notebooks. Click on a notebook and make sure you see “Ascent Bridge” in the top right corner of the notebook, if you don’t then try selecting it from the “Kernel” menu. Follow the instructions inside the notebook to connect and learn more about how to use the notebook.