Tutorial

The tutorial has sixteen examples in four sets, covering PVA (PyVisual Application) from a single sphere to field lines traced across the corona and the heliosphere, picking points and lines in the 3-D view, spacecraft data, null points, plasma flow along field lines, exporting and re-reading a modified field, and animations. Each example is small and introduces a handful of features; the notes inside each session give the procedure, and the README beside it gives terminology and background. Examples are numbered set.example, from 1.1 to 4.4.

Prerequisites

PVA installed and launching.
A network connection the first time the examples of sets 1 and 2 and examples 4.1 to 4.3 are run: the sample data files come from the psi-data-utils package and are downloaded on first use, then cached. Example 4.2 also reads the velocity files of the corona run.
Examples 3.1 to 3.4 also need a network connection on their first run, to fetch spacecraft positions from JPL Horizons (through sunpy) and in situ measurements from CDAWeb (through the hapiclient package). The results are cached, so later runs of the same window work offline.
Example 4.4 reads a folder of MAS files with many time steps, which the public samples do not provide; its README gives the file naming it expects.

Examples 2.3, 2.4 and 4.1 are interactive and involve picking in the 3-D view. Their solved files ship a few pre-made picks, so a headless render shows only those, not live clicks.

Keyboard shortcuts are written Ctrl+…; macOS shows the same keys as ⌘.

Opening an example

File ▸ Open Session… opens a file chooser for a .pyv file. A .pyv file can also be opened by double-clicking it (or Open With ▸ PVA).

Every example folder holds three files:

<name>.pyv is the starter. Everything the example needs is already placed on the canvas, but the part it teaches is left undone. The numbered notes along the top of the canvas describe how to finish it.
<name>-solved.pyv is the finished result. It serves as the reference for comparison.
README.md explains the terms and ideas behind the example.

Starters include the finished, collapsed groups from earlier examples that the example builds on, so earlier work is not rebuilt.

Set 1: Basics

Nodes, slices, scaling and a 2-D map; the vocabulary every later example builds on.

Example	Title	Goal
1.1	Hello World	Build the smallest complete scene (a sphere in a 3-D viewport) and introduce the vocabulary used throughout the tutorial.
1.2	A Radial Slice	Read a real model file, cut one radial layer out of it, plot it, and package the result as a group.
1.3	Scaled Slices	Cut the same file along theta and phi, and apply two kinds of scaling: scaling the data and scaling a scale.
1.4	The Coronal Hole Map	Draw a 2-D map of the Sun's surface by giving it a radius.

Set 2: Field-Line Tracing

Tracing from a lattice, from other launch points, from clicks in the 3-D view and from a picked line.

Example	Title	Goal
2.1	Field-Line Tracing	Trace magnetic field lines through the corona in three ways, and color them by length and by polarity.
2.2	Launch Points	Choose where field lines start by wiring a dataset into the optional `lps` port.
2.3	Click to Trace	Right-click a gray shell around the Sun to place a point there, keep a growing set of those clicks with an Accumulator, and trace a field line from each of them.
2.4	Picking a Line	Pick one field line in the 3-D view, color just that line by the radial field sampled along it, and aim the camera at it.

Set 3: Spacecraft

Ephemeris and in situ data, tracing from spacecraft positions, and a curtain of samples under an orbit.

Example	Title	Goal
3.1	Spacecraft Ephemeris	Fetch a spacecraft's trajectory for a chosen time window and plot it around the Sun.
3.2	In Situ Data Versus the Model	Plot the magnetic field a spacecraft measured along its track, then sample the MAS model at the same points and compare the two in separate viewports.
3.3	Tracing from Spacecraft Positions	Start field lines from points along a spacecraft's track and trace each one through the corona and the heliosphere, using Trace Multi Domain to continue each line from one model domain into the other.
3.4	A Curtain Under the Orbit	Hang a surface from a spacecraft's orbit down toward the Sun and color it with the magnitude of the model's magnetic field, sampled from three scalar files combined into a vector field.

Set 4: Analyses

Null points, travel along field lines, exporting and re-reading a modified field, and animations.

Example	Title	Goal
4.1	Null Points	Find the magnetic null points of the corona model, pick one of them in the 3-D view, and trace field lines from small discs placed around it along its spine and in its fan.
4.2	Flow Along Lines	Resample traced field lines at equal steps of plasma travel time, so that a window of samples advances along each line with the flow, and drive that window with an animation.
4.3	Export, Modify and Retrace	Cut a shell out of the magnetic field, amplify its azimuthal component, write the result to disk as three PSI files, read the files back through a MAS File and trace field lines through the modified field, beside the original lines for comparison.
4.4	Animations	Read a folder of MAS files that holds many time steps as one source, build a scene from it, and render an animation that steps through the time steps.