Ascent: On-the-fly 2D/3D rendering

CMakeLists.txt

@@ -50,6 +50,9 @@ set(pgen
 set(output
     ${default_output}
     CACHE BOOL "Enable output")
+set(ascent
+    ${default_ascent}
+    CACHE BOOL "Enable Ascent in situ visualization")
 set(mpi
     ${default_mpi}
     CACHE BOOL "Use MPI")
@@ -319,6 +322,22 @@ if(${output})
   endif()
 endif()
 
+# Ascent (in situ visualization)
+if(${ascent})
+  if(NOT ${output})
+    message(
+      FATAL_ERROR
+      "${Red}Ascent requires `output=ON` to be enabled.${ColorReset}")
+  endif()
+  find_package(Ascent REQUIRED)
+  add_compile_options("-D ASCENT_ENABLED")
+  if(${mpi})
+    set(DEPENDENCIES ${DEPENDENCIES} ascent::ascent_mpi)
+  else()
+    set(DEPENDENCIES ${DEPENDENCIES} ascent::ascent)
+  endif()
+endif()
+
 link_libraries(${DEPENDENCIES})
 
 set(SRC_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src/)

ascent/field_lines/README.md

@@ -0,0 +1,66 @@
+# `turbulence_lines`
+
+Driven 3D turbulence (re-using the standard
+[`turbulence`](../../turbulence) pgen) with in-situ rendering of magnetic
+**field lines** via [Ascent](https://ascent.readthedocs.io/).
+
+The same setup as
+[`turbulence_ascent`](../turbulence_ascent), but instead of volume-rendering
+`|B|`, this example traces the magnetic field with Ascent's `streamline`
+filter from a uniform grid of seed points inside the box and rasterizes
+the resulting polylines as 3D tubes. One PNG is produced per render
+cycle:
+
+```
+turbulence_lines_0000.png
+turbulence_lines_0001.png
+...
+```
+
+## Files
+
+- `turbulence_lines.toml` — input file (3D, periodic, driven antenna).
+- `ascent_actions.yaml`   — Ascent pipeline (composite_vector → streamline)
+                            + ray-traced pseudocolor scene.
+- `README.md`             — this file.
+
+The C++ problem generator is reused from `pgens/turbulence/pgen.hpp`.
+
+## Build
+
+```sh
+cmake -S . -B build \
+      -D pgen=turbulence \
+      -D output=ON \
+      -D ascent=ON \
+      -D Ascent_DIR=/path/to/ascent/install/lib/cmake/ascent
+cmake --build build -j
+```
+
+## Run
+
+```sh
+./build/src/entity.xc -input pgens/examples/turbulence_lines/turbulence_lines.toml
+```
+
+Ascent writes PNGs into the `turbulence_lines/` simulation directory.
+
+## Tweaking the field-line render
+
+The interesting knobs all live in `ascent_actions.yaml`:
+
+- `num_steps` × `step_size` controls how far each field line is integrated
+  in code units. The default `200 × 0.5 = 100` covers ~1.5× the box width.
+- `rendering/tube_size` sets the rendered tube radius. Reduce it
+  (e.g. `0.2`) for a finer-looking line, or increase it for a thicker,
+  easier-to-see line.
+- `seeds.num_seeds_x` / `num_seeds_y` / `num_seeds_z` set how many seeds
+  are placed along each axis of the seeding box (for `sampling_type:
+  "uniform"`). The example uses a 4×4×4 grid (64 seeds total). Switch to
+  `sampling_type: "random"` to draw `num_seeds` random points instead.
+- `seeds.extents_x` / `extents_y` / `extents_z` define the seeding box.
+- Other supported `seeds.type` values are `point`, `point_list`, `line`
+  — see the Ascent `streamline` filter docs.
+- To color the tubes by some derived scalar, add another filter to the
+  pipeline (e.g. `vector_magnitude` on `B`) before the streamline filter
+  and reference the scalar in the plot's `field` key.

ascent/field_lines/ascent_actions.yaml

@@ -0,0 +1,73 @@
+# Ascent actions for the turbulence_lines example.
+#
+# Pipeline:
+#   streamline: integrate field lines through the published vector field
+#   `B` starting from a uniform grid of seeds across the interior of the
+#   box. Output is rendered as 3D tubes (`enable_tubes = "true"`) so they
+#   can be raytraced.
+# Scene:
+#   pseudocolor plot of the streamline output, ray-traced to PNG.
+#
+# Entity publishes B1/B2/B3 both as scalar fields AND as the (u,v,w)
+# components of a Conduit-Blueprint MCArray vector named `B`, so the
+# streamline filter can read it directly without an extra
+# `composite_vector` step (that step produces a vector layout VTK-h's
+# streamline backend in Ascent v0.9.x can't unpack as Vec<float,3>).
+#
+# This file is loaded automatically by Ascent when the option
+#   output.ascent.actions_file = "ascent_actions.yaml"
+# is set in the toml input file.
+
+-
+  action: "add_pipelines"
+  pipelines:
+    pl_lines:
+      f1:
+        type: "streamline"
+        params:
+          field: "B"
+          # Each line is integrated for num_steps * step_size code-units.
+          num_steps: 200
+          step_size: 0.5
+          seeds:
+            type: "box"
+            sampling_type: "uniform"
+            sampling_space: "interior"
+            # The Ascent vtkh_streamline filter expects `extents_<axis>`
+            # (not `<axis>_extents`) and per-axis seed counts.
+            extents_x: [-28.0, 28.0]
+            extents_y: [-28.0, 28.0]
+            extents_z: [-28.0, 28.0]
+            num_seeds_x: 4
+            num_seeds_y: 4
+            num_seeds_z: 4
+          rendering:
+            # Tube-rasterization options live under `rendering/` in this
+            # version of Ascent. `enable_tubes` is a string ("true"/"false").
+            enable_tubes: "true"
+            tube_size: 0.4
+            tube_sides: 6
+            output_field: "B_lines"
+
+-
+  action: "add_scenes"
+  scenes:
+    s_lines:
+      plots:
+        p1:
+          type: "pseudocolor"
+          pipeline: "pl_lines"
+          field: "B_lines"
+      renders:
+        r1:
+          type: "raytracer"
+          image_width: 1024
+          image_height: 1024
+          image_prefix: "turbulence_lines_%08d"
+          bg_color: [0.0, 0.0, 0.0]
+          fg_color: [1.0, 1.0, 1.0]
+          camera:
+            position: [80.0, 80.0, 80.0]
+            look_at: [0.0, 0.0, 0.0]
+            up: [0.0, 0.0, 1.0]
+            fov: 35.0

ascent/field_lines/turbulence_lines.toml

@@ -0,0 +1,74 @@
+[simulation]
+  name    = "turbulence_lines"
+  engine  = "srpic"
+  runtime = 200.0
+
+[grid]
+  resolution = [64, 64, 64]
+  extent     = [[-32.0, 32.0], [-32.0, 32.0], [-32.0, 32.0]]
+
+  [grid.metric]
+    metric = "minkowski"
+
+  [grid.boundaries]
+    fields    = [["PERIODIC"], ["PERIODIC"], ["PERIODIC"]]
+    particles = [["PERIODIC"], ["PERIODIC"], ["PERIODIC"]]
+
+[scales]
+  larmor0    = 1.0
+  skindepth0 = 1.0
+
+[algorithms]
+  current_filters = 4
+
+  [algorithms.timestep]
+    CFL = 0.5
+
+[particles]
+  ppc0 = 4.0
+
+  [[particles.species]]
+    label    = "e-_p"
+    mass     = 1.0
+    charge   = -1.0
+    maxnpart = 2e6
+
+  [[particles.species]]
+    label    = "e+_p"
+    mass     = 1.0
+    charge   = 1.0
+    maxnpart = 2e6
+
+[setup]
+  temperature = 1e0
+  dB          = 1.0
+  omega_0     = 0.0156
+  gamma_0     = 0.0078
+
+[output]
+  format        = "BPFile"
+  interval_time = 20.0
+
+  [output.fields]
+    quantities = ["B"]
+
+  [output.particles]
+    enable = false
+
+  [output.spectra]
+    enable = false
+
+  [output.stats]
+    enable = false
+
+  # Field-line rendering of the magnetic field via Ascent. We publish the
+  # three component scalars and let the actions file (a) composite them
+  # into a vector, (b) trace streamlines, (c) render as 3D tubes.
+  [output.ascent]
+    enable        = true
+    actions_file  = "ascent_actions.yaml"
+    fields        = ["B1", "B2", "B3"]
+    interval_time = 4.0
+
+[diagnostics]
+  colored_stdout = true

ascent/simple_cube/README.md

@@ -0,0 +1,71 @@
+# `ascent_cube`
+
+Minimal demonstration of the in-situ visualization interface to
+[Ascent](https://ascent.readthedocs.io/) shipped with Entity.
+
+The setup is a 3D periodic cube on a Cartesian Minkowski metric. The
+problem generator initializes the magnetic field with a non-trivial third
+component:
+
+```
+B1 = 0
+B2 = 0
+B3 = B0 * sin(2 pi x / Lx) * sin(2 pi y / Ly)
+```
+
+While the simulation runs, Entity publishes the rectilinear mesh and the
+selected field components to Ascent every `output.fields.interval_time`.
+Ascent reads `ascent_actions.yaml` and renders one PNG per cycle:
+
+```
+ascent_cube_B3_0000.png
+ascent_cube_B3_0001.png
+...
+```
+
+## Build
+
+Configure Entity with Ascent enabled. Make sure `Ascent_DIR` points at
+your Ascent install (which provides `AscentConfig.cmake`):
+
+```sh
+cmake -S . -B build \
+      -D pgen=examples/ascent_cube \
+      -D output=ON \
+      -D ascent=ON \
+      -D Ascent_DIR=/path/to/ascent/install/lib/cmake/ascent
+cmake --build build -j
+```
+
+## Run
+
+```sh
+./build/src/entity.xc -input pgens/examples/ascent_cube/ascent_cube.toml
+```
+
+The PNGs are written next to the `ascent_cube/` simulation output
+directory (controlled by `default_dir` in the writer).
+
+## Toml options
+
+In addition to the usual `[output]` keys, this example uses:
+
+```toml
+[output.ascent]
+  enable        = true
+  actions_file  = "ascent_actions.yaml"
+  fields        = ["B3"]
+  interval_time = 0.02   # Render cadence (independent of [output.fields])
+```
+
+`fields` lists the variable names that Entity should publish to Ascent.
+Vector field components are postfixed with the index, so `B1`, `B2`,
+`B3` give the three components of the magnetic field; `E1`/`E2`/`E3`
+the electric field; `J1`/`J2`/`J3` the current. The names appear
+verbatim as Conduit field names, so the actions file should reference
+them under `field: "B3"`.
+
+The `interval` / `interval_time` keys control how often Ascent renders;
+they are completely independent of the ADIOS field-write cadence in
+`[output.fields]`. If both keys are omitted, the global `[output]`
+cadence is used.

ascent/simple_cube/ascent_actions.yaml

@@ -0,0 +1,27 @@
+# Ascent actions for the ascent_cube example.
+#
+# This file is loaded automatically by Ascent when the option
+#   output.ascent.actions_file = "ascent_actions.yaml"
+# is set in the toml input file.
+#
+# Each cycle Entity publishes a 3D rectilinear mesh containing the field
+# components requested in `output.ascent.fields`. The pseudocolor plot below
+# renders the third component of the magnetic field on a 3D cube.
+-
+  action: "add_scenes"
+  scenes:
+    s_b3:
+      plots:
+        p1:
+          type: "pseudocolor"
+          field: "B3"
+      renders:
+        r1:
+          image_width: 800
+          image_height: 800
+          image_prefix: "cube_B3_%08d"
+          camera:
+            position: [3.0, 3.0, 3.0]
+            look_at: [0.0, 0.0, 0.0]
+            up: [0.0, 0.0, 1.0]
+            fov: 35.0