blue-pebble 0.1.0__tar.gz

blue_pebble-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,45 @@
+{
+    "name": "Blue Pebble Development",
+    "build": {
+        "dockerfile": "../Dockerfile",
+        "context": "..",
+        "args": {
+            "RTRS_URL": "${localEnv:RTRS_URL}"
+        }
+    },
+
+    "features": {
+        "ghcr.io/devcontainers/features/github-cli:1": {}
+    },
+
+    // Mount the entire project folder into the container
+    "workspaceMount": "source=${localWorkspaceFolder},target=/workspaces/${localWorkspaceFolderBasename},type=bind",
+    "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
+
+    // Forward the Jupyter port
+    "forwardPorts": [8888],
+
+    // Run commands after the container is created
+    "postCreateCommand": "pip install --no-cache-dir -e '.[dev,docs,examples]'",
+
+    // Start a Jupyter server automatically
+    "postStartCommand": "jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root --NotebookApp.token='' --NotebookApp.password='' --NotebookApp.disable_check_xsrf=True",
+
+    // Configure VS Code settings and extensions for the container
+    "customizations": {
+        "vscode": {
+            "settings": {
+                "python.defaultInterpreterPath": "/usr/local/bin/python"
+            },
+            "extensions": [
+                "ms-python.python",
+                "ms-toolsai.jupyter",
+                "charliermarsh.ruff",
+                "ritwickdey.live"
+            ]
+        }
+    },
+
+    // Keep the container running even when the VS Code window is closed
+    "shutdownAction": "none"
+}

blue_pebble-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

blue_pebble-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+# Pull Request
+
+PR title format: `type(scope): summary`
+
+Examples:
+- `ci: add pytest step to workflow`
+- `fix(plotter): handle empty detections`
+- `docs(api): clarify rtrs installation`
+
+Scope is encouraged but not required.
+
+## Summary
+
+- What changed?
+- Why did it change?
+
+## Validation
+
+- `ruff check .`
+- `pytest`
+- `make -C docs html`
+
+## Compatibility
+
+- Any public API, behavioural, or documentation impact?

blue_pebble-0.1.0/.github/release.yml

@@ -0,0 +1,17 @@
+changelog:
+  categories:
+    - title: Breaking changes
+      labels:
+        - breaking
+    - title: Implemented enhancements
+      labels:
+        - enhancement
+    - title: Fixed bugs
+      labels:
+        - bug
+    - title: Documentation updates
+      labels:
+        - documentation
+    - title: Other changes
+      labels:
+        - "*"

blue_pebble-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  pr-title:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate PR title
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          printf 'PR_TITLE=<%s>\n' "$PR_TITLE"
+          pattern='^(feat|fix|docs|style|refactor|perf|test|build|ci|chore)(\([^)]+\))?(!)?: .+$'
+          if printf '%s' "$PR_TITLE" | grep -Eq "$pattern"; then
+            echo "PR title is a valid Conventional Commit: $PR_TITLE"
+          else
+            echo "PR title must follow Conventional Commits."
+            echo "Use: type(scope): summary"
+            echo "Scope is encouraged but not required."
+            echo "Examples:"
+            echo "  ci: add pytest step to workflow"
+            echo "  fix(plotter): handle empty detections"
+            exit 0
+          fi
+
+  core:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install (core)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint (Ruff)
+        run: |
+          ruff check .
+
+      - name: Tests (Pytest)
+        run: |
+          if [[ "${{ matrix.python-version }}" == "3.12" ]]; then
+            pytest --cov=bluepebble --cov-report=term-missing --cov-report=xml --cov-fail-under=55
+          else
+            pytest
+          fi
+
+      - name: Smoke import
+        run: |
+          python -c "import bluepebble; print(getattr(bluepebble, '__version__', 'no __version__'))"
+
+      - name: Build (sdist/wheel)
+        run: |
+          python -m build --sdist --wheel
+

blue_pebble-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # required for setuptools_scm to resolve version from git tags
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/blue-pebble
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

blue_pebble-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# General Python
+build/
+dist/
+*.egg-info
+__pycache__/
+
+# Virtual environment
+.venv/
+
+# Sphinx documentation
+/docs/build/
+/docs/_build/
+/docs/source/auto*
+/docs/source/sg_execution_times.rst
+/docs/sg_execution_times.rst
+
+# coverage
+.coverage
+coverage.xml
+htmlcov/
+
+# pytest
+.pytest_cache/
+
+# Ruff
+.ruff_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Operating system / editor
+.DS_Store
+.vscode/
+
+# Claude Code — local only
+CLAUDE.md
+.claude/
+
+# Measured data
+docs/examples/measured_data
+
+# Generated PDF figures
+*.pdf
+
+# Generated Sphinx-Gallery figures (large, rebuilt during docs build)
+docs/source/_static/acoustic_source_figs/
+docs/source/_static/measured_data_figs/

blue_pebble-0.1.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-lts-latest
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

blue_pebble-0.1.0/CITATION.cff

@@ -0,0 +1,53 @@
+cff-version: 1.2.0
+message: >
+  If you use this software, please cite both the article and the software itself.
+title: "Blue Pebble: A Passive Sonar Simulation Framework for Tracking Research"
+type: software
+authors:
+  - family-names: Wakefield
+    given-names: Joshua J.
+    orcid: "https://orcid.org/0009-0008-7574-5484"
+  - family-names: Boulton
+    given-names: Finley
+  - family-names: Colquitt
+    given-names: Daniel J.
+  - family-names: Ralph
+    given-names: Jason F.
+  - family-names: Williams
+    given-names: Duncan P.
+
+repository-code: "https://github.com/UoL-SignalProcessingGroup/blue-pebble"
+url: "https://github.com/UoL-SignalProcessingGroup/blue-pebble"
+
+license: "MIT"
+
+keywords:
+  - passive sonar
+  - underwater acoustics
+  - beamforming
+  - acoustic propagation
+  - ray tracing
+  - towed arrays
+  - multi-target tracking
+  - detection theory
+  - simulation framework
+
+preferred-citation:
+  type: paper-conference
+  title: "A Sonar Signal Processing Plugin for Stone Soup"
+  authors:
+    - family-names: Wakefield
+      given-names: Joshua J.
+    - family-names: Boulton
+      given-names: Finley
+    - family-names: Colquitt
+      given-names: Daniel J.
+    - family-names: Ralph
+      given-names: Jason F.
+    - family-names: Williams
+      given-names: Duncan P.
+  year: 2026
+  conference:
+    name: "29th International Conference on Information Fusion (FUSION)"
+  publisher: IEEE
+  status: forthcoming

blue_pebble-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to Blue Pebble
+
+Blue Pebble follows Stone Soup-style contribution practices, adapted for this plugin and toolchain.
+
+## Development Setup
+
+1. Clone the repository and enter it.
+2. Create and activate a Python 3.11+ virtual environment.
+3. Install development dependencies:
+
+```bash
+python3 -m pip install -U pip
+python3 -m pip install -e ".[dev]"
+```
+
+4. If working on docs/examples, also install:
+
+```bash
+python3 -m pip install -e ".[docs,examples]"
+```
+
+## Code Style
+
+- Use clear, descriptive names (prefer domain clarity over shorthand).
+- Use standard Python exceptions/warnings and validate inputs explicitly.
+- Prefer a deprecation period of at least one release cycle before removing/changing public interfaces.
+- Keep components modular with one primary responsibility each.
+- Follow PEP 8 and project linting rules.
+- Lint with `ruff` (this project uses `ruff`, not `flake8`):
+
+```bash
+ruff check .
+```
+
+## Documentation
+
+- Use NumPy-style docstrings for public APIs.
+- Add or update docs for behavior/API changes.
+- For significant new capability, include a minimal reproducible example in `docs/examples/` or `docs/tutorials/`.
+- Where relevant, include references to equations, assumptions, or papers.
+- `.ipynb` files under `docs/tutorials/` and `docs/examples/` are the canonical published sources for notebook-based documentation.
+- Published notebooks are rendered from the committed outputs; the docs build does not execute notebooks.
+- When notebook content changes, refresh the outputs locally before committing so the hosted documentation remains coherent.
+
+Build the docs locally with:
+
+```bash
+make -C docs html
+```
+
+## Tests
+
+- Use `pytest`.
+- Add tests for new behavior and regressions.
+- Add tests for expected failures/exceptions where relevant.
+- For numerical methods, use deterministic checks and appropriate tolerances (`rtol`, `atol`).
+
+Run local checks before opening a PR:
+
+```bash
+ruff check .
+pytest
+make -C docs html
+```
+
+## License
+
+By contributing, you agree your contribution is under the repository license (MIT), unless explicitly stated otherwise in the pull request.
+
+## External Dependencies
+
+- Prefer Python standard library or existing well-maintained libraries.
+- New dependencies should have permissive or weak-copyleft licensing and a clear maintenance story.
+- Add dependencies to `pyproject.toml` with appropriate version constraints.
+
+## Pull Requests
+
+- Use feature branches (for example `feat/<topic>` or `fix/<topic>`).
+- Keep PRs focused and reviewable.
+- Use a Conventional Commit-formatted PR title, for example `ci: add pytest step to workflow`.
+- Prefer the form `type(scope): summary`; scope is encouraged when it adds clarity, but it is not required.
+- Prefer squash merging so the PR title becomes the commit message on `main`.
+- In the PR description, include:
+  - what changed
+  - why it changed
+  - how you validated it (tests, docs build, example output)
+  - any compatibility impact
+
+## Versioning and Releases
+
+This project uses dynamic versioning via `setuptools_scm`.
+
+- Do not manually set `project.version` in `pyproject.toml`.
+- Versions are resolved from Git tags.
+- Use semantic tags for releases, for example `v3.0.0`, `v3.1.0`, `v3.1.1`, or pre-release tags such as `v3.0.0rc1`.

blue_pebble-0.1.0/Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.12-slim
+
+# Install runtime tools required for devcontainer workflows
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    make \
+    build-essential \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set the working directory
+WORKDIR /app
+
+# Optional: install rtrs ray-tracing backend.
+# Pass a pip-installable URL at build time, e.g.:
+#   docker build --build-arg RTRS_URL=https://<token>@github.com/fincb/rtrs.git .
+# Once rtrs is public this can be replaced with a plain pip install.
+ARG RTRS_URL=""
+RUN if [ -n "$RTRS_URL" ]; then \
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal \
+    && export PATH="/root/.cargo/bin:$PATH" \
+    && pip install --no-cache-dir git+"$RTRS_URL"; \
+fi
+
+# The devcontainer will mount the source code and install dependencies.
+# The CMD is also handled by the devcontainer configuration.
+# For a production build, re-enable the COPY and RUN pip install lines.

blue_pebble-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Joshua Wakefield
+Copyright (c) 2026 Finley Boulton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

blue_pebble-0.1.0/NOTICE.md

@@ -0,0 +1,40 @@
+# Attribution and Project Origin
+
+This project is a plugin for the open-source framework [Stone Soup](https://stonesoup.rtfd.io/).
+
+The architecture and class structure in this repository inherit from Stone Soup's existing implementations.
+
+## Original License and Copyright
+
+As an extension to the original work, this project is bound by the terms of the original MIT License under which Stone Soup is distributed. The full, original copyright notice and the license text are included below.
+
+---
+
+**The MIT License (MIT)**
+
+**© Crown Copyright 2017-2025 Defence Science and Technology Laboratory UK**
+**© Crown Copyright 2018-2025 Defence Research and Development Canada / Recherche et développement pour la défense Canada**
+**© Copyright 2018-2025 University of Liverpool UK**
+**© Copyright 2020-2025 Fraunhofer FKIE**
+**© Copyright 2020-2025 John Hiles**
+**© Copyright 2020-2025 Riskaware Ltd**
+**© Copyright 2021-2025 Roke Manor Research Ltd UK**
+**© Copyright 2023-2025 Loughborough University UK**
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.