Metadata-Version: 2.1
Name: pyampp
Version: 0.1.3
Summary: Automatic Model Suff
Home-page: https://github.com/suncast-org/pyAMPP
Author: The SUNCAST team
Author-email: 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.
        
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: dev
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/

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

Install the latest version from PyPI:

.. code-block:: bash

    pip install -U pyampp

Main Interfaces
---------------

pyAMPP installs two GUI applications:

1. **gxampp** – Launches a GUI to select observation time and coordinates. It then invokes `gxbox` to build the 3D model.
2. **gxbox** – Launches a GUI that builds and displays the 3D magnetic field and plasma model. Can be run independently if coordinates are known.

Usage Examples
--------------

**1. Launch the time/coord selector (gxampp)**

.. code-block:: bash

    gxampp

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

**2. 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.

Entrypoints
-----------

After installation, the following commands become available:

- ``gxampp``: Launch the time and location GUI.
- ``gxbox``: Launch the modeling GUI directly with CLI options.

License
-------

Copyright (c) 2024, `SUNCAST <https://github.com/suncast-org/>`_ team. Released under the 3-clause BSD license.
