pyAMPP: Python Automatic Model Production Pipeline

pyAMPP is a Python implementation of the Automatic Model Production Pipeline (AMPP) for solar coronal modeling. It streamlines the process of generating realistic 3D solar atmosphere models with minimal user input.

Documentation

Full documentation is available at: https://pyampp.readthedocs.io/en/latest/

Format and viewer references:

• Upgraded HDF5 stage format (NONE/BND/POT/NAS/NAS.GEN/NAS.CHR): docs/model_hdf5_format.rst
• GUI workflow and command mapping: docs/gui_workflow.rst
• Viewer guide (gxbox-view and gxrefmap-view): docs/viewers.rst
• Release notes: CHANGELOG.rst

Overview

AMPP automates the production of 3D solar models by:

• Downloading vector magnetic field data from the Helioseismic and Magnetic Imager (HMI) onboard the Solar Dynamics Observatory (SDO)
• Optionally downloading contextual Atmospheric Imaging Assembly (AIA) data
• Performing magnetic field extrapolations (Potential and/or Nonlinear Force-Free Field)
• Generating synthetic plasma emission models assuming either steady-state or impulsive heating
• Producing non-LTE chromospheric models constrained by photospheric measurements
• Enabling interactive 3D inspection and customization through user-friendly GUIs

Installation

pyAMPP can be installed directly from PyPI.

0. Setting up a Python 3.10 Environment (Recommended)

We strongly recommend running pyAMPP in a dedicated Python 3.10 environment. You may use any of the following tools to install Python and create an isolated environment:

• Miniforge: https://github.com/conda-forge/miniforge
• Miniconda: https://www.anaconda.com/docs/getting-started/miniconda/install
• Anaconda: https://www.anaconda.com/docs/getting-started/anaconda/install
• Conda: https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html
• pyenv: https://github.com/pyenv/pyenv?tab=readme-ov-file#installation

Please refer to the official installation instructions for your chosen tool. Their documentation is comprehensive and up to date, so we will not repeat it here.

You can skip this environment setup section if you already have a suitable Python environment.

The instructions below use Conda as an example:

1. Install Conda If you don’t have Conda yet, follow the instructions for your platform here: https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html

2. Create and activate your environment Open an Anaconda Prompt or Command Prompt and run:

   conda create -n suncast python=3.10
   conda activate suncast

3. Upgrade pip and install pyampp

   pip install -U pip setuptools wheel
   pip install -U pyampp

4. (Optional) Install additional dependencies

   For a full scientific Python stack (e.g., SunPy and related tools):

   pip install -U sunpy[all]

Main Interfaces

pyAMPP provides a GUI for building a reproducible CLI command and separate tools for model generation and visualization:

1. pyampp – Launches a GUI to select observation time, coordinates, and options. It generates a gx-fov2box CLI command (shown above the Run button) and can launch it.
2. gx-fov2box – Pure CLI model generator (IDL gx_fov2box equivalent). It saves the requested stages and records the full command in metadata/execute.
3. gxbox – Launches the map GUI and 3D visualization for browsing existing models.

Usage Examples

1. Launch the time/coord selector (pyampp)

pyampp

2. Generate a model via CLI (gx-fov2box)

gx-fov2box \
  --time "2022-03-30T17:22:37" \
  --coords 34.44988566346035 14.26110705696788 \
  --hgs \
  --box-dims 360 180 200 \
  --dx-km 1400 \
  --pad-frac 0.25 \
  --data-dir /path/to/download_dir \
  --gxmodel-dir /path/to/gx_models_dir \
  --save-potential \
  --save-bounds

3. Launch the modeling GUI directly (Gxbox Map Viewer)

gxbox \
  --time "2022-03-30T17:22:37" \
  --coords 34.44988566346035 14.26110705696788 \
  --hgs \
  --box-dims 360 180 200 \
  --box-res 0.729 \
  --pad-frac 0.25 \
  --data-dir /path/to/download_dir \
  --gxmodel-dir /path/to/gx_models_dir \
  --external-box /path/to/boxfile.gxbox

The Gxbox Map Viewer GUI automatically downloads the required solar data and builds the 3D model based on the user's input. The resulting model can be visualized in a VTK-based viewer (Gxbox 3D Viewer) that supports interactive exploration of the magnetic field structure.

Additionally, users can trace and extract magnetic field lines within the 3D model and send them back to the gxbox GUI, where they can be overlaid on solar images for contextual visualization.

Notes:

• --coords takes two floats, separated by space (no brackets or commas).
• One of --hpc, --hgc, or --hgs must be specified to define the coordinate system.
• Remaining parameters are optional and have default values.
• Set PYAMPP_JSOC_NOTIFY_EMAIL to override the JSOC export notification email (default: suncasa-group@njit.edu).

Entry-Box Resume / Jump Rules

gx-fov2box supports --entry-box with .h5 or .sav input for stage-aware resume/recompute.

• --rebuild: ignore stage payload and recompute from NONE using resolved entry parameters.
• --clone-only: convert/copy an entry box to normalized HDF5 without recomputation (useful as convert-from-sav).
• Without --jump2*, the pipeline starts from the detected entry stage.
• When --entry-box contains metadata/execute, --data-dir and --gxmodel-dir default from that execute string.
• Explicit CLI values for --data-dir / --gxmodel-dir always override execute-derived defaults.
• Jump validation rules are enforced: - backward jumps are allowed, - forward jumps are allowed by one stage, - POT -> NAS is explicitly allowed (implicit POT -> BND -> NAS), - POT -> GEN is explicitly allowed (skip both BND and NAS/NLFFF; keep true POT vectors).
• Save requests for stages before the selected start stage are ignored with a warning.
• In --clone-only mode, only no-jump or jump-to-self is allowed.

Entrypoints

After installation, the following commands become available:

• pyampp: Launch the command-builder GUI.
• gx-fov2box: Run the model-generation pipeline headlessly.
• gxbox: Launch the modeling/visualization GUI.
• gxbox-view: Open an existing HDF5 model in the 3D viewer.
• gxrefmap-view: Open base/refmaps from an HDF5 model in a 2D map browser.
• gx-idl2fov2box: Translate IDL gx_fov2box execute strings (or SAV EXECUTE) into Python gx-fov2box commands.

License

Copyright (c) 2024, SUNCAST team. Released under the 3-clause BSD license.