pyampp 1.0.0__py3-none-any.whl

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/changelog.rst

@@ -0,0 +1,4 @@
+Changelog
+=========
+
+.. include:: ../CHANGELOG.rst

docs/conf.py

@@ -0,0 +1,118 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+
+# -- Project information -----------------------------------------------------
+
+# The full version, including alpha/beta/rc tags
+release = "0.2.0"
+
+project = "pyAMPP"
+copyright = "2022, suncast-org"
+author = "suncast-org"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',  # Automatically document your code
+    'sphinx.ext.napoleon',  # Support for Google-style docstrings
+    'sphinx.ext.viewcode',  # Add links to source code from documentation
+    'sphinx.ext.mathjax',  # Render math via JavaScript
+    'sphinx.ext.autosummary',  # Automatically generates summary tables from the docstrings.
+    'sphinx.ext.githubpages',
+    'sphinx.ext.graphviz',
+    'sphinx.ext.imgmath',
+    # 'sphinx_gallery.gen_gallery',
+    # 'sphinx_gallery',
+    'autoapi.extension'
+    # Add any other Sphinx extensions here.
+]
+
+# Add any paths that contain templates here, relative to this directory.
+# templates_path = ["_templates"]  # NOQA: ERA001
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+html_theme = 'sphinx_rtd_theme'
+
+html_static_path = ['_static']
+
+# The suffix(es) of source filenames.
+# # You can specify multiple suffix as a list of string:
+# source_suffix = ".rst"
+#
+# # The master toctree document.
+# master_doc = "index"
+
+# -- Options for intersphinx extension ---------------------------------------
+
+# Example configuration for intersphinx: refer to the Python standard library.
+# intersphinx_mapping = {"python": ("https://docs.python.org/", None)}
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+# html_theme = "alabaster"
+
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using a default sidebar with
+# the links to the documentation's roots, contents & search, plus a link to
+# the Python.org website.
+html_sidebars = {
+    '**': [
+        'about.html',
+        'navigation.html',
+        'relations.html',  # needs 'show_related': True theme option to display
+        'searchbox.html',
+        'donate.html',
+    ]
+}
+
+# -- Options for sphinx.ext.autodoc -------------------------------------------
+autoapi_type = 'python'
+autoapi_dirs = ['../pyampp']
+autoapi_python_use_implicit_namespaces = True
+autoapi_options = [
+    'members',
+    'undoc-members',
+    'show-inheritance',
+    'show-module-summary',
+]
+autoapi_ignore = [
+    # Ignore test and internal helper trees.
+    'tests/*',
+    '*/tests/*',
+    '_dev/*',
+    '*/_dev/*',
+    'lib/*',
+    '*/lib/*',
+    # Some modules with heavy relative-import assumptions can fail under
+    # AutoAPI static analysis; exclude from API doc generation.
+    'gx_chromo/combo_model.py',
+    '*/gx_chromo/combo_model.py',
+    # Avoid duplicate object descriptions with pyampp.gxbox package exports.
+    'gxbox/gx_box2id.py',
+    '*/gxbox/gx_box2id.py',
+    'gxbox/gx_voxelid.py',
+    '*/gxbox/gx_voxelid.py',
+]
+
+# Keep the docs build signal-to-noise focused on actionable errors.
+suppress_warnings = [
+    'autoapi.python_import_resolution',
+]

docs/conf.py.rej

@@ -0,0 +1,25 @@
+diff a/docs/conf.py b/docs/conf.py	(rejected hunks)
+@@ -76,10 +76,22 @@ intersphinx_mapping = {"python": ("https://docs.python.org/", None)}
+ # a list of builtin themes.
+ html_theme = "alabaster"
+ 
++# Render inheritance diagrams in SVG
++graphviz_output_format = "svg"
++
++graphviz_dot_args = [
++    "-Nfontsize=10",
++    "-Nfontname=Helvetica Neue, Helvetica, Arial, sans-serif",
++    "-Efontsize=10",
++    "-Efontname=Helvetica Neue, Helvetica, Arial, sans-serif",
++    "-Gfontsize=10",
++    "-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif",
++]
++
+ # Add any paths that contain custom static files (such as style sheets) here,
+ # relative to this directory. They are copied after the builtin static files,
+ # so a file named "default.css" will overwrite the builtin "default.css".
+-# html_static_path = ["_static"]
++# html_static_path = ["_static"]  # NOQA: ERA001
+ 
+ # By default, when rendering docstrings for classes, sphinx.ext.autodoc will
+ # make docs with the class-level docstring and the class-method docstrings,

docs/gui_workflow.rst

@@ -0,0 +1,108 @@
+pyAMPP GUI Workflow
+===================
+
+This page documents the current ``pyampp`` command-builder GUI behavior and how it maps to ``gx-fov2box``.
+
+Purpose
+-------
+
+The GUI is a thin command constructor for reproducible CLI runs. It:
+
+- captures model parameters,
+- resolves entry-box resume/rebuild behavior,
+- displays the exact command before execution,
+- streams command output in the status panel.
+
+Data Repositories
+-----------------
+
+The GUI has three path fields:
+
+- ``SDO Data Dir`` (mapped to ``--data-dir``)
+- ``GX Models Dir`` (mapped to ``--gxmodel-dir``)
+- ``Entry Box`` (mapped to ``--entry-box`` when set)
+
+Current behavior:
+
+- ``data-dir`` and ``gxmodel-dir`` persist across sessions via ``QSettings``.
+- If an entry box contains a valid ``metadata/execute`` path and that path exists on the current machine, the GUI pre-fills the corresponding directory field.
+- If execute paths are invalid on this machine, the GUI falls back to default local directories and warns the user.
+
+Model Configuration
+-------------------
+
+Core inputs:
+
+- observation time (UTC)
+- center coordinates with one selected frame:
+  - ``--hpc`` (helioprojective)
+  - ``--hgc`` (Carrington)
+  - ``--hgs`` (Stonyhurst)
+- projection:
+  - ``--cea`` (default)
+  - ``--top``
+- box dimensions:
+  - ``--box-dims NX NY NZ``
+- spatial scale:
+  - ``--dx-km``
+- padding:
+  - ``--pad-frac`` (GUI percent value is converted to fraction)
+- disambiguation:
+  - ``HMI`` (default, no extra flag)
+  - ``SFQ`` (adds ``--sfq`` when applicable)
+
+Entry-Box Modes
+---------------
+
+When ``Entry Box`` is provided, the GUI detects the stage/type and offers three execution modes:
+
+- ``Continue``:
+  - continue from detected entry stage,
+  - command is kept minimal (entry + paths + workflow flags).
+- ``Rebuild from NONE``:
+  - keep entry as source metadata/context but restart stage computation from NONE (``--rebuild-from-none``).
+- ``Rebuild from OBS``:
+  - recompute from observed maps and current GUI model parameters (``--rebuild``).
+
+Pipeline Options and Stage Stops
+--------------------------------
+
+Save toggles:
+
+- ``--save-empty-box``
+- ``--save-potential``
+- ``--save-bounds``
+- ``--save-nas``
+- ``--save-gen``
+
+Stop rules:
+
+- ``Stop after download`` -> ``--stop-after dl``
+- ``NONE only`` -> ``--stop-after none``
+- ``POT only`` -> ``--stop-after pot``
+- ``NAS only`` -> ``--stop-after nas``
+- ``GEN only`` (or CHR disabled) -> ``--stop-after gen``
+
+Other stage controls:
+
+- ``Skip NLFFF`` -> ``--use-potential``
+- ``Skip line computation`` -> ``--skip-lines``
+
+Context-map toggles:
+
+- EUV checkbox -> ``--euv``
+- UV checkbox -> ``--uv``
+
+Command Display and Execution
+-----------------------------
+
+- The command preview updates live as inputs change.
+- ``Run`` launches ``gx-fov2box`` as a subprocess.
+- stdout/stderr are streamed into the status pane.
+- A successful run reports generated model paths and stage timings in the log.
+
+Operational Notes
+-----------------
+
+- If you modify package code, reinstall with ``pip install -e .`` before re-launching the GUI.
+- Cached file reuse depends on ``--data-dir`` and timestamp/series compatibility with downloader filename matching.

docs/index.rst

@@ -0,0 +1,20 @@
+pyAMPP Documentation
+--------------------
+
+This is the documentation for pyAMPP.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   model_hdf5_format
+   gui_workflow
+   viewers
+   changelog
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/model_hdf5_format.rst

@@ -0,0 +1,139 @@
+pyAMPP HDF5 Model Format
+========================
+
+This page documents the current stage-file contract written by ``gx-fov2box`` and consumed by:
+
+- ``gxbox-view`` (3D viewer),
+- ``gxrefmap-view`` (base/refmap browser),
+- resume/rebuild workflows via ``--entry-box``.
+
+File Naming
+-----------
+
+Typical output naming pattern:
+
+- ``hmi.M_720s.YYYYMMDD_HHMMSS.<region>.CEA.NONE.h5``
+- same stem with stage suffixes ``POT``, ``BND``, ``NAS``, ``NAS.GEN``, ``NAS.CHR``
+
+Common Groups (All Stages)
+--------------------------
+
+``base``
+~~~~~~~~
+
+2D boundary maps:
+
+- ``base/bx``, ``base/by``, ``base/bz``
+- ``base/ic``
+- ``base/chromo_mask``
+- ``base/index`` (IDL-compatible serialized header payload)
+
+``metadata``
+~~~~~~~~~~~~
+
+Core provenance:
+
+- ``metadata/id``: model identifier
+- ``metadata/execute``: full command string used to create the model
+- ``metadata/projection``: ``CEA`` or ``TOP``
+- ``metadata/disambiguation``: e.g. ``HMI`` or ``SFQ``
+- ``metadata/axis_order_2d`` and ``metadata/axis_order_3d`` when present
+- ``metadata/vector_layout`` when present
+
+``refmaps``
+~~~~~~~~~~~
+
+Optional context maps, each in its own subgroup:
+
+- ``refmaps/<map_id>/data``
+- ``refmaps/<map_id>/wcs_header``
+
+``grid``
+~~~~~~~~
+
+Grid geometry and identity:
+
+- ``grid/dx``, ``grid/dy``, ``grid/dz``
+- ``grid/voxel_id`` (uint32)
+
+Stage-Specific Groups
+---------------------
+
+NONE
+~~~~
+
+- Minimal model shell for downstream continuation.
+- No solved extrapolation required.
+- ``corona`` may exist as placeholder fields with ``attrs/model_type = "none"``.
+
+POT
+~~~
+
+Potential-field stage in ``corona``:
+
+- ``corona/bx``, ``corona/by``, ``corona/bz``
+- ``corona/dr``
+- ``corona/attrs/model_type = "pot"``
+- ``corona/corona_base`` when available
+
+BND
+~~~
+
+Boundary-conditioned stage in ``corona``:
+
+- ``corona/bx``, ``corona/by``, ``corona/bz``
+- ``corona/dr``
+- ``corona/corona_base`` when available
+
+NAS
+~~~
+
+NLFFF stage in ``corona``:
+
+- ``corona/bx``, ``corona/by``, ``corona/bz``
+- ``corona/dr``
+- ``corona/attrs/model_type = "nlfff"`` (or equivalent)
+
+NAS.GEN
+~~~~~~~
+
+Adds line-tracing products (stored in ``lines`` and/or stage-compatible chromo metadata):
+
+- line indexing arrays (start/end/apex/seed)
+- status/code arrays
+- aggregate line properties (average field, physical length)
+
+NAS.CHR
+~~~~~~~
+
+Adds chromospheric payload in ``chromo`` and finalized grid metadata:
+
+- chromospheric thermodynamic variables (where generated)
+- chromosphere-resolved field cubes (when present)
+- final ``grid/voxel_id`` and geometry values used by viewers/renderers
+
+Reference-map IDs
+-----------------
+
+Typical AIA-derived IDs used by viewers:
+
+- ``AIA_94``, ``AIA_131``, ``AIA_171``, ``AIA_193``, ``AIA_211``, ``AIA_304``, ``AIA_335``
+- ``AIA_1600``, ``AIA_1700`` (if UV requested)
+
+Axis and Layout Notes
+---------------------
+
+- 2D base/refmap arrays are map-shaped with explicit WCS headers retained.
+- 3D field arrays are stored in the package-native HDF5 convention used by current writers/readers.
+- Viewers and adapters handle any required transpose/reindex for rendering and legacy compatibility.
+
+Resume/Entry Compatibility
+--------------------------
+
+For robust resume behavior, entry files should include:
+
+- ``metadata/execute`` (for reproducible command provenance and path recovery),
+- valid ``metadata/id`` stage naming,
+- required stage groups for the selected jump/rebuild mode.
+
+When ``--entry-box`` is supplied, ``gx-fov2box`` detects stage availability and enforces required groups for continuation/rebuild paths.

docs/requirements.txt

@@ -0,0 +1,4 @@
+Sphinx
+sphinx-rtd-theme
+sphinx-gallery
+sphinx-autoapi

docs/viewers.rst

@@ -0,0 +1,58 @@
+Model Viewers
+=============
+
+gxbox-view
+----------
+
+``gxbox-view`` opens an existing model HDF5 file in the 3D viewer without recomputing.
+
+Expected inputs:
+
+- A model file containing at least one of:
+  - ``corona`` (preferred),
+  - ``nlfff`` / ``pot`` (accepted and normalized), or
+  - ``chromo`` with sufficient magnetic cube fields.
+
+Usage:
+
+.. code-block:: bash
+
+   gxbox-view /path/to/model.h5
+
+Optional file picker mode:
+
+.. code-block:: bash
+
+   gxbox-view --pick
+
+gxrefmap-view
+-------------
+
+``gxrefmap-view`` is a 2D map browser for base maps and refmaps stored in model HDF5 files.
+
+Expected layout:
+
+- Base maps:
+  - ``base/bx``, ``base/by``, ``base/bz``, ``base/ic``, ``base/chromo_mask``
+  - base header in ``base/index`` (fallbacks: ``base/index_header``, ``base/wcs_header``)
+- Refmaps:
+  - ``refmaps/<map_id>/data``
+  - ``refmaps/<map_id>/wcs_header``
+
+Usage:
+
+.. code-block:: bash
+
+   gxrefmap-view /path/to/model.h5
+
+List available maps only:
+
+.. code-block:: bash
+
+   gxrefmap-view /path/to/model.h5 --list
+
+Start from a specific map:
+
+.. code-block:: bash
+
+   gxrefmap-view /path/to/model.h5 --start AIA_94

examples/create_box.py

@@ -0,0 +1,20 @@
+import astropy.time
+import sunpy.sun.constants
+from astropy.coordinates import SkyCoord
+from sunpy.coordinates import Heliocentric, Helioprojective,get_earth
+import astropy.units as u
+
+from PyQt5.QtWidgets import QApplication
+app = QApplication([])
+from pyampp.gxbox.gxbox_factory import GxBox
+
+time = astropy.time.Time('2020-12-01T20:00:00')
+observer = get_earth(time)
+box_origin = SkyCoord(450 * u.arcsec, -320 * u.arcsec, obstime=time, observer=observer, rsun=696 * u.Mm, frame='helioprojective')
+box_dimensions = u.Quantity([400, 300, 300]) * u.pix
+box_res = 1.4 * u.Mm
+
+
+gxbox = GxBox(time, observer, box_origin, box_dimensions)
+gxbox.show()
+app.exec_()

licenses/LICENSE.rst

@@ -0,0 +1,25 @@
+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.

licenses/README.rst

@@ -0,0 +1,9 @@
+Licenses
+========
+
+This directory holds license and credit information for the package,
+works the package is derived from, and/or datasets.
+
+Ensure that you pick a package licence which is in this folder and it matches
+the one mentioned in the top level README.rst file. If you are using the
+pre-rendered version of this template check for the word 'Other' in the README.

licenses/TEMPLATE_LICENSE.rst

@@ -0,0 +1,31 @@
+This project is based upon the OpenAstronomy package template
+(https://github.com/OpenAstronomy/package-template/) which is licensed under the terms
+of the following licence.
+
+---
+
+Copyright (c) 2018, OpenAstronomy Developers
+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.

pyampp/__init__.py

@@ -0,0 +1,3 @@
+from . import sfq
+
+__all__ = ["sfq"]

pyampp/_dev/__init__.py

@@ -0,0 +1,6 @@
+"""
+This package contains utilities that are only used when developing in a
+copy of the source repository.
+These files are not installed, and should not be assumed to exist at
+runtime.
+"""

pyampp/_dev/scm_version.py

@@ -0,0 +1,12 @@
+# Try to use setuptools_scm to get the current version; this is only used
+# in development installations from the git repository.
+import os.path
+
+try:
+    from setuptools_scm import get_version
+
+    version = get_version(root=os.path.join('..', '..'), relative_to=__file__)
+except ImportError:
+    raise
+except Exception as e:
+    raise ValueError('setuptools_scm can not determine version.') from e

pyampp/_version.py

@@ -0,0 +1,3 @@
+"""Canonical package version."""
+
+version = "0.2.0"

pyampp/data/README.rst

@@ -0,0 +1,6 @@
+Data directory
+==============
+
+This directory contains data files included with the package source
+code distribution. Note that this is intended only for relatively small files
+- large files should be externally hosted and downloaded as needed.

pyampp/data/__init__.py

@@ -0,0 +1 @@
+__all__=["downloader"]