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:
! CALL sim_data%print_detailed()
WRITE(chunk_name, '(i6)') parallel%task+100001
chunk_name(1:1) = "."
WRITE(step_name, '(i6)') step+100000
step_name(1:1) = "."
savename = trim(trim(name) //trim(chunk_name)//trim(step_name))
CALL ascent_timer_stop(C_CHAR_"COPY_DATA"//C_NULL_CHAR)
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")
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:
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/tutorial/cloverleaf_demos/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/libs/ascent/python/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/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/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.