Release v1

[steven-murray]

Release v1 collection branch.

Summary by Sourcery

Introduce a structured PowerSpectrum result type for get_power and update callers and docs to use it.

New Features:

• Add a PowerSpectrum dataclass to encapsulate power spectrum outputs, including bin metadata and optional diagnostics.

Enhancements:

• Refine get_power to return PowerSpectrum, computing bin edges/centres consistently and handling partial angular averaging with k_unbinned coordinates.
• Suppress invalid-operation warnings during bin averaging and field averaging, and standardize bins_upto_boxlen handling with a future warning.
• Expose PowerSpectrum in the public API and update documentation notebooks to use the new structured result.

Build:

• Adjust dev dependency group in pyproject.toml to use prek instead of pre-commit.

Documentation:

• Revise demo notebooks to consume PowerSpectrum attributes when plotting power spectra and bin coordinates.

Tests:

• Update existing tests to work with PowerSpectrum and add comprehensive tests validating its attributes, variance handling, partial averaging behavior, and validation logic for inconsistent shapes.

Chores:

• Add AGENTS.md with project workflow, tooling, and safety guidelines for contributors.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[sourcery-ai]

Reviewer's Guide

Introduce a structured PowerSpectrum result object for get_power, refactor get_power to return this dataclass with consistent bin metadata, improve numerical robustness of bin averaging, and update tests and docs to use the new API and behavior.

Sequence diagram for get_power constructing PowerSpectrum

sequenceDiagram
    actor User
    participant ToolsModule
    participant AngularAverage
    participant PowerSpectrum

    User->>ToolsModule: get_power(field, boxlength, parameters)
    ToolsModule->>ToolsModule: compute_freq_and_kmag(field, boxlength, dim)
    ToolsModule->>ToolsModule: resolve_bins_upto_boxlen(bins, kmag)
    ToolsModule->>ToolsModule: bin_edges = _getbins(bins, kmag, log_bins, bins_upto_boxlen)
    ToolsModule->>ToolsModule: bin_centres = compute_bin_centres(bin_edges, log_bins)
    ToolsModule->>AngularAverage: angular_average_nd(P, coords, bin_edges, bin_ave=True, get_variance, log_bins, weights, interpolation_method, interp_points_generator, bins_upto_boxlen)
    AngularAverage-->>ToolsModule: power, bin_avg, variance, nsamples
    ToolsModule->>ToolsModule: apply_shotnoise_correction_if_needed(power)
    ToolsModule->>ToolsModule: collapse_partial_average_axes(bin_avg, nsamples, res_ndim, dim)
    ToolsModule->>PowerSpectrum: __init__(power, bin_edges, bin_centres, bin_avg, nsamples, variance, k_unbinned)
    PowerSpectrum->>PowerSpectrum: __post_init__() validate shapes
    PowerSpectrum-->>ToolsModule: validated_instance
    ToolsModule-->>User: PowerSpectrum instance

Loading

Class diagram for PowerSpectrum and get_power result structure

classDiagram
    class PowerSpectrum {
        +np.ndarray power
        +np.ndarray bin_edges
        +np.ndarray bin_centres
        +np.ndarray bin_avg
        +np.ndarray nsamples
        +np.ndarray variance
        +tuple k_unbinned
        +__post_init__()
    }

    class ToolsModule {
        +PowerSpectrum get_power(field, boxlength, N, bins, dim, res_ndim, log_bins, get_variance, remove_shotnoise, bins_upto_boxlen)
        +tuple angular_average_nd(field, coords, bins, bin_ave, get_variance, log_bins, weights, interpolation_method, interp_points_generator, bins_upto_boxlen)
    }

    ToolsModule --> PowerSpectrum : returns
    ToolsModule --> PowerSpectrum : validates via __post_init__

Loading

File-Level Changes

Change	Details	Files
Introduce PowerSpectrum dataclass as the structured return type for get_power and validate internal consistency of power spectrum metadata.	Add PowerSpectrum dataclass encapsulating power, bin_edges, bin_centres, bin_avg, nsamples, variance, and k_unbinned. Implement post_init to coerce arrays and validate length/shape consistency between bins, averages, and variance. Export PowerSpectrum from the public powerbox package API and add tests covering its invariants and error conditions.	src/powerbox/tools.py src/powerbox/__init__.py tests/test_power.py
Refactor get_power to compute explicit bin edges/centres once, improve handling of bins_upto_boxlen and log bins, and return a PowerSpectrum rather than multiple arrays.	Change get_power signature to return PowerSpectrum and remove bin_ave and return_sumweights arguments. Resolve bins_upto_boxlen only once, emit a FutureWarning for the default behavior, and precompute bin_edges via _getbins to avoid duplicate work and warnings. Compute bin_centres as linear or geometric midpoints depending on log_bins, always pass explicit bin_edges and bin_ave=True to angular_average_nd, and handle res_ndim=0 by returning unbinned k_unbinned coordinates. Ensure nsamples and bin_avg are collapsed to 1D when averaging over fewer than all dimensions and propagate shot-noise removal into the new PowerSpectrum structure. Improve numerical robustness of _get_binweights and _field_average by using np.errstate around divisions that can encounter invalid operations.	src/powerbox/tools.py
Update tests to use the new PowerSpectrum API from get_power and add coverage for new behaviors such as variance, partial averaging, and log binning.	Adjust existing tests to access result.power, result.bin_avg, result.bin_edges, etc., instead of unpacking tuples, and ensure behavior of k_weights, ignore_zero_mode, and cross power remains unchanged. Add new tests that assert get_power returns a PowerSpectrum, validate attribute shapes, variance population, monotonic bin_edges, bin_centres placement, partial averaging semantics, and PowerSpectrum validation errors. Update discrete, lognormal, and tools tests to use the PowerSpectrum API and to assert that nsamples/bin_avg shapes are correct for partial averaging scenarios.	tests/test_power.py tests/test_discrete.py tests/test_tools.py tests/test_lognormal.py
Align documentation notebooks and development tooling with the new PowerSpectrum API and project conventions.	Update demo notebooks to store get_power results in PowerSpectrum objects and use bin_avg and power attributes for plotting comparisons against analytic spectra. Adjust development dependencies to replace pre-commit with prek in the dev extra and add AGENTS.md documenting project tooling, testing, and process guidelines. Ensure docs examples call get_power consistently with the new API and bins_upto_boxlen handling.	docs/demos/getting_started.ipynb docs/demos/cosmological_fields.ipynb docs/demos/dft.ipynb pyproject.toml agents.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[steven-murray]

@copilot resolve the merge conflicts in this pull request

[codecov]

Codecov Report

❌ Patch coverage is 96.38728% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 95.02%. Comparing base (1f85d68) to head (a326fee).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/powerbox/jax/tools.py	94.88%	13 Missing ⚠️
src/powerbox/jax/powerbox.py	95.41%	5 Missing ⚠️
src/powerbox/tools.py	93.44%	4 Missing ⚠️
src/powerbox/_hermitianity.py	92.30%	2 Missing ⚠️
src/powerbox/dft_backend.py	96.96%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #127      +/-   ##
==========================================
+ Coverage   94.54%   95.02%   +0.47%     
==========================================
  Files           5       12       +7     
  Lines         605     1206     +601     
==========================================
+ Hits          572     1146     +574     
- Misses         33       60      +27     

Flag	Coverage Δ
unittests	95.02% <96.38%> (+0.47%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sourcery-ai]

Hey - I've left some high level feedback:

• The get_power API has changed quite significantly (removed bin_ave/return_sumweights, changed return type from tuple to PowerSpectrum), which is a breaking change; consider adding a backwards-compatible shim or deprecation period (e.g., optional flag returning the old tuple form) to avoid silently breaking existing users.
• The FutureWarning message in get_power is built from adjacent string literals ("box." "Set bins_upto_boxlen..."), which currently concatenates as "box.Set ..."; add a trailing space to the first literal or a leading space to the second to fix the wording.
• In agents.md, the command hint uv sync" has a stray closing quote; remove the extra " so the instruction renders correctly.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The `get_power` API has changed quite significantly (removed `bin_ave`/`return_sumweights`, changed return type from tuple to `PowerSpectrum`), which is a breaking change; consider adding a backwards-compatible shim or deprecation period (e.g., optional flag returning the old tuple form) to avoid silently breaking existing users.
- The `FutureWarning` message in `get_power` is built from adjacent string literals (`"box." "Set bins_upto_boxlen..."`), which currently concatenates as `"box.Set ..."`; add a trailing space to the first literal or a leading space to the second to fix the wording.
- In `agents.md`, the command hint `uv sync"` has a stray closing quote; remove the extra `"` so the instruction renders correctly.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved in commit 80e8fe4. The merge kept the PowerSpectrum interface from v1 while incorporating changes from main (import additions, type annotations, ruff/complexity fixes). All 84 tests pass and ruff checks are clean.