Development documentation · 0.2.3 30c2f8ba · Intro examples tested with 0.2.3 · Version details · Known limitations

GWpy Behavioral Compatibility Policy#

GWexpy extends GWpy without silently changing the default scientific result of an existing GWpy API.

For APIs corresponding to existing GWpy APIs, when GWpy returns normally with finite numerical results, replacing the corresponding GWpy import with GWexpy under default options must preserve numerical values, shape and selected samples, axis information, and successful completion. Any intentional divergence from these guarantees requires an explicit user opt-in through a GWexpy-specific API or option, unless it is a named, human-approved safety exception that meets every gate below. Internal implementations may differ only when scientific behavior is preserved and no material performance or resource regression is introduced.

What must match#

Apply this policy when all of the following are true:

  1. The operation corresponds to an existing public GWpy API.

  2. The call uses default behavior rather than a GWexpy-specific opt-in.

  3. GWpy accepts the input and returns normally with finite numerical results.

Compare the observable result, not the implementation:

Area

Required comparison

Numerical result

values and units exposed by the corresponding API

Selection

shape, selected samples, and boundary behavior

Axes

t0, dt, times, span, and equivalent axis information

Completion

successful completion in GWpy must not become a GWexpy-only exception

A difference in any required comparison is a release blocker unless the user selected an explicit GWexpy-only API or option or the difference is a named, human-approved safety exception satisfying every requirement below.

Named safety exceptions#

A safety exception is not a general license to improve, reinterpret, or replace GWpy behavior. It is allowed only for a narrowly identified subcase where the normal GWpy result is demonstrably unsafe or outside the requested sample-selection domain. Every safety exception must have all of the following:

  1. A stable name recorded as an inventory marker on only the affected cases.

  2. Direct dual-oracle evidence against every supported GWpy oracle.

  3. Human scientific/data-model approval of the deliberate divergence.

  4. Release-note disclosure that identifies the before/after behavior.

  5. Scope narrower than the whole public API, with parent errors and all other results preserved.

The only approved exception is non_intersecting_window_safety. It applies after a successful parent HDF5 TimeSeriesDict.read() call when an explicit read window is mathematically completely disjoint from a returned series and GWpy selected only samples outside the requested sample-selection domain. GWexpy returns a zero-length entry for that disjoint key. It does not reinterpret parent errors, modify a partial overlap, override pad=, remove collection keys, or change any other result.

An unexplained divergence, an unmarked divergence, or a proposed extension of this exception beyond that subcase remains a release blocker.

Where extension is allowed#

GWexpy may add containers, metadata, precision-preserving state, I/O formats, and analysis methods that GWpy does not provide. Those additions must remain separate from the default behavior of corresponding GWpy APIs. Merely importing GWexpy is not an opt-in to different numerical semantics.

Invalid or contradictory GWexpy-specific metadata may continue to fail closed. Such malformed extension metadata is outside the normal finite-result case, and must have explicit validation tests.

Internal changes and resource use#

Internal structure may change when the public scientific behavior remains the same. Changes to performance-sensitive bootstrap, dispatch, I/O, or numerical kernel paths require performance/resource non-regression evidence proportionate to their risk. A material regression blocks the change unless maintainers explicitly accept and document the trade-off.

Documentation-only changes may record resource evidence as not applicable.

Review checklist#

  1. Is this an existing GWpy API?

  2. Does GWpy return a normal finite result for the case under review?

  3. Do GWpy and GWexpy defaults match in values, shape and selected samples, axes, and completion behavior?

  4. If they differ, is the difference behind an explicit GWexpy-only opt-in or a named, human-approved safety exception satisfying every gate above?

  5. If the change is internal, is proportionate performance and resource evidence attached?

If step 3 fails without satisfying step 4, the review verdict is BLOCK.