2. Design & Architecture

This document tracks the technical philosophy and internal structure of the PyEQSP library.

2.1. Module Breakdown

The library is organized to separate performance-critical mathematics logic from user-facing utilities.

2.1.1. Public API (eqsp.*)

  • partitions.py: The core of the EQ algorithm. Contains eq_regions and eq_point_set.

  • point_set_props.py: Modules for measuring distance, energy, and density.

  • visualizations.py: High-level wrappers for Matplotlib and PyVista.

  • utilities.py: Coordinate system transformations.

        graph TD
    subgraph PublicAPI ["Public API (eqsp.*)"]
        A[partitions.py] --> C[point_set_props.py]
        A --> V[visualizations.py]
        A --> UTILS[utilities.py]
    end

    subgraph Private ["Internal (_private.*)"]
        A -.-> P_PART[_partitions.py]
        C -.-> P_RPROP[_region_props.py]
    end

    style PublicAPI fill:#f9f,stroke:#333,stroke-width:2px
    style Private fill:#eee,stroke:#999,stroke-dasharray: 5 5

2.1.2. Internal Logic (eqsp._private)

Modules prefixed with an underscore are intended for internal use and may change without notice. These include:

  • Helper functions for recursive collar calculations.

  • Optimization constants.

2.2. The Composite Strategy

PyEQSP uses a “composite” visualization strategy:

  1. Matplotlib is used for 2D projections and publishing-quality PDF/EPS output.

  2. PyVista is used for real-time 3D interaction and off-screen rendering. The visualizations module acts as a bridge, choosing the best backend for the requested manifold (\(S^2\) vs \(S^3\)).

        graph LR
    User([User Call]) --> V[visualizations.py]

    V -->|Manifold = S^2, 2D| MAT[Matplotlib]
    V -->|Manifold = S^2, 3D| PV[PyVista]
    V -->|Manifold = S^3| PV

    subgraph Backends ["Plotting Engines"]
        MAT
        PV
    end

    style User fill:#d4edda,stroke:#28a745
    style Backends fill:#fff3cd,stroke:#ffc107

2.2.1. Decoupling and Testing Strategy

The composite strategy deliberately decouples the core numerical partitioning logic from heavy optional visualization stacks:

  • Zero Heavy Runtime Coupling: Core algorithms and mathematical properties have no dependency on PyVista or VTK.

  • CI Test Isolation: Continuous integration runners exercise the visualization layer through mock-based testing (tests/src/*_mock.py), validating API contracts, parameter routing, and call configurations without requiring graphics drivers or heavy display stacks.

  • Maintainer Verification: Runtime rendering fidelity is verified locally using interactive inspection utilities (tests/src/inspect_visualizations.py) and PhD thesis reproduction scripts (examples/phd-thesis/).

2.3. Extensibility

2.3.1. Adding New Manifolds

The library is designed for extension. To add support for a new manifold:

  1. Define the measure (area) calculation.

  2. Define the recursive partitioning logic in partitions.py.

  3. Update the visualization suite to handle the new projection requirements.

2.3.2. Property Metrics

New statistical properties can be added by implementing vectorized functions in point_set_props.py.

2.4. Numerical Stability

Precision is maintained by:

  • Using numpy.longdouble where recursion depth might lead to floating-point drift.

  • Implementing robust root-finding for cap radius calculations.