Metadata-Version: 2.1
Name: pyampp
Version: 1.0.0
Summary: Python Automatic Model Production Pipeline for solar coronal modeling
Author-email: The SUNCAST team <sijie.yu@njit.edu>
License: Copyright (c) 2024, suncast-org
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without modification,
        are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        * Redistributions in binary form must reproduce the above copyright notice, this
          list of conditions and the following disclaimer in the documentation and/or
          other materials provided with the distribution.
        * Neither the name of the Astropy Team nor the names of its contributors may be
          used to endorse or promote products derived from this software without
          specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
        ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
        (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
        ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
        (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/suncast-org/pyAMPP
Project-URL: Documentation, https://pyampp.readthedocs.io/en/latest/
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
Provides-Extra: tests
Provides-Extra: docs
License-File: LICENSE

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.

1. **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:

   .. code-block:: bash

      conda create -n suncast python=3.10
      conda activate suncast

3. **Upgrade pip and install pyampp**

   .. code-block:: bash

      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):

   .. code-block:: bash

      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)**

.. code-block:: bash

    pyampp

.. image:: docs/images/pyampp_gui.png
    :alt: pyampp GUI screenshot
    :align: center
    :width: 600px

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

.. code-block:: bash

    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)**

.. code-block:: bash

    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

.. image:: docs/images/gxbox_gui.png
    :alt: gxbox GUI screenshot
    :align: center
    :width: 600px

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.

.. image:: docs/images/MagFieldViewer_gui.png
    :alt: MagFieldViewer GUI screenshot
    :align: center
    :width: 600px

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 <https://github.com/suncast-org/>`_ team. Released under the 3-clause BSD license.
