.. _release_v3_2_0:

-------------
Version 3.2.0
-------------
*(Current documented package release)*

GeoPrior-v3 3.2.0 |New|
~~~~~~~~~~~~~~~~~~~~~~~

This release marks the first documented release-note entry in
the current **GeoPrior-v3** line and reflects the package
state aligned with the present repository structure,
workflow-oriented CLI, subsidence-forecasting model family,
and dedicated GeoPrior-v3 documentation site.

The most important theme of this release is **consolidation**:

- GeoPrior-v3 is documented as its own project,
- the staged workflow is exposed cleanly through the CLI,
- the flagship subsidence model family is surfaced clearly,
- and the documentation is reorganized around users,
  scientific foundations, applications, APIs, and developer
  guidance.

Highlights
~~~~~~~~~~

* |Docs| **Dedicated GeoPrior-v3 documentation structure**

  The documentation is now organized around the GeoPrior-v3
  project itself rather than an inherited broader package
  context. The documentation tree now clearly separates:

  - Getting Started
  - User Guide
  - Scientific Foundations
  - Applications
  - API Reference
  - Developer Notes
  - Release Notes

  This improves project identity, internal linking, and long-
  term maintainability.

* |Build| **Top-level release-notes layout**

  Release notes are now treated as a top-level documentation
  section rather than being nested under developer-only
  material. This makes version history easier to discover for:

  - users,
  - contributors,
  - and workflow maintainers.

* |Feature| **Structured staged workflow documentation**

  The documentation now covers the full staged GeoPrior
  workflow:

  - Stage-1 preprocessing
  - Stage-2 training
  - Stage-3 tuning
  - Stage-4 inference and export
  - Stage-5 transfer benchmarking

  with dedicated user-guide pages for each stage.

* |Feature| **Expanded scientific documentation**

  A full scientific foundations section is now documented for
  the flagship subsidence model family, including pages for:

  - model overview,
  - GeoPriorSubsNet,
  - physics formulation,
  - poroelastic background,
  - residual assembly,
  - losses and training,
  - data and units,
  - scaling,
  - maths,
  - identifiability,
  - stability and constraints.

* |Feature| **Expanded applications documentation**

  The applications layer now documents GeoPrior-v3 as an
  end-to-end subsidence-forecasting framework, including:

  - subsidence forecasting workflow,
  - tuner workflow,
  - calibration and uncertainty,
  - reproducibility scripts,
  - figure generation.

Added
~~~~~

* |Docs| **New top-level documentation architecture**

  Added a clearer documentation hierarchy with dedicated
  sections for user workflows, scientific model reasoning,
  applications, APIs, and developer guidance.

* |Docs| **New API reference pages**

  Added dedicated API pages for:

  - CLI
  - subsidence
  - tuner
  - utils
  - resources

  These pages are designed to expose both:

  - public import surfaces,
  - and implementation-facing structure where useful.

* |Docs| **Source-visible API pages**

  Several API pages now include ``literalinclude`` source
  listings so inline implementation comments remain visible in
  the built docs, especially for:

  - CLI dispatcher modules,
  - model and tuner modules,
  - resource templates,
  - utility entry surfaces.

* |Feature| **Dedicated release-note section**

  Added a release-note index page plus versioned release-note
  pages under:

  .. code-block:: text

     docs/source/release_notes/

  to make version history scalable and explicit.

* |Docs| **Developer architecture guidance**

  Added developer-facing documentation for:

  - package structure,
  - migration from the older FusionLab-hosted docs context,
  - contribution guidelines.

Changed
~~~~~~~

* |Docs| **Migration away from FusionLab-hosted doc context**

  The documentation now consistently presents GeoPrior-v3 as
  its own project and package namespace. Older FusionLab-style
  context is now treated as historical background rather than
  the active documentation identity.

* |Docs| **Updated import guidance**

  Documentation examples now prefer the current public import
  surfaces such as:

  .. code-block:: python

     from geoprior.models import GeoPriorSubsNet
     from geoprior.models import PoroElasticSubsNet
     from geoprior.models.forecast_tuner import SubsNetTuner
     from geoprior.utils import load_nat_config

  rather than legacy or indirect paths.

* |Build| **Release notes moved out of the developer-only
  section**

  Release notes are now documented at the same top level as
  other major doc sections, which better reflects their role
  as project-wide upgrade and behavior notes rather than only
  contributor notes.

* |Docs| **Stronger workflow-oriented navigation**

  The docs now emphasize the actual user path through the
  package:

  - initialize configuration,
  - preprocess,
  - train,
  - tune,
  - infer,
  - transfer,
  - build artifacts,
  - generate figures.

Fixed
~~~~~

* |Docs| **Corrected project-boundary wording**

  Fixed pages that still implied an older parent-package
  context rather than the current GeoPrior-v3 package
  identity.

* |Docs| **Corrected and modernized internal references**

  Updated stale or misleading cross-references so that pages
  now point to the current GeoPrior-v3 doc structure and API
  targets.

* |Docs| **Improved alignment between user guide and API
  reference**

  The documentation now more clearly separates:

  - workflow meaning,
  - scientific interpretation,
  - API entry points,
  - and developer structure.

Scientific and workflow emphasis
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This release is especially important because GeoPrior-v3 is
not documented merely as a collection of scripts. It is now
presented coherently as:

- a physics-guided forecasting framework,
- a staged workflow system,
- a transfer- and uncertainty-aware application stack,
- and a reproducible scientific software project.

That framing better matches the actual project architecture
and public package surface.

Documentation-visible model scope
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This release documents the current flagship scientific scope
around the subsidence model family, especially:

- :class:`~geoprior.models.GeoPriorSubsNet`
- :class:`~geoprior.models.PoroElasticSubsNet`

along with the supporting tuner, scaling, identifiability,
payload, and diagnostics layers.

Documentation-visible workflow scope
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This release also documents the current workflow surface
around:

- configuration bootstrap,
- staged preprocessing and training,
- tuned-model selection,
- reusable inference,
- cross-city transfer evaluation,
- reproducibility scripts,
- figure-generation commands.

Upgrade notes
~~~~~~~~~~~~~

If you were working from older draft material or from the
previous FusionLab-hosted documentation context, the main
recommended update is:

- use the current ``geoprior`` namespace in examples;
- follow the new dedicated GeoPrior-v3 docs structure;
- prefer the documented public import surfaces and CLI
  families;
- treat release notes as a top-level documentation section.

Compatibility notes
~~~~~~~~~~~~~~~~~~~

This release note page is primarily documentation-facing and
structural.

It does **not** declare a scientific redefinition of the
GeoPrior subsidence model family by itself. Instead, it
records the fact that the package and docs are now presented
through a cleaner and more explicit GeoPrior-v3 project
boundary.

A compact release map
~~~~~~~~~~~~~~~~~~~~~

This release can be summarized as:

.. code-block:: text

   GeoPrior-v3 documented as its own project
        ↓
   staged workflow pages clarified
        ↓
   scientific model family documented in depth
        ↓
   applications layer documented explicitly
        ↓
   API pages expanded
        ↓
   developer guidance added
        ↓
   release notes promoted to top-level docs section

See also
~~~~~~~~

.. seealso::

   - :doc:`../index`
   - :doc:`../user_guide/workflow_overview`
   - :doc:`../scientific_foundations/models_overview`
   - :doc:`../applications/subsidence_forecasting`
   - :doc:`../api/cli`
   - :doc:`../developer/package_structure`
   - :doc:`../developer/migration_from_fusionlab`