Skip to content

Commit 48add0d

Browse files
waltsimsclaude
waltsims
and
claude
committed
Simplify developer docs: remove outdated sections, modernize setup
- Overview: no longer says C++ binaries are "required" - Setup: uv sync replaces uv venv + uv pip install - Testing: note that most tests work without MATLAB - Remove: old integration testing / H5 hash sections (C++ pipeline) - Remove: detailed MATLAB reference generation steps (niche workflow) - Remove: hardcoded commit SHA links Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent e5194e4 commit 48add0d

1 file changed

Lines changed: 22 additions & 130 deletions

File tree

‎docs/development/development_environment.rst‎

Lines changed: 22 additions & 130 deletions
Original file line numberDiff line numberDiff line change
@@ -3,172 +3,64 @@ Development Environment
33

44
Overview
55
--------
6-
k-Wave-python is a Python interface to the k-Wave C++ binaries, which are required to run simulations. The binaries are automatically downloaded when the package runs for the first time.
6+
k-Wave-python provides both a pure Python/NumPy solver and an interface to pre-compiled C++ binaries. The Python backend works out of the box — no extra dependencies needed.
77

8-
Environment Setup with uv
9-
-------------------------
8+
Environment Setup
9+
-----------------
10+
11+
1. Install `uv <https://docs.astral.sh/uv/getting-started/installation/>`_
1012

11-
1. Install uv
12-
Uv is "An extremely fast Python package and project manager, written in Rust." We would recommend that you use it. Installation instructions can be found `here <https://docs.astral.sh/uv/getting-started/installation/#installation-methods>`_.
13+
2. Clone and install:
1314

14-
2. Clone the Repository
15-
~~~~~~~~~~~~~~~~~~~~~~~
1615
.. code-block:: bash
1716
1817
git clone https://github.com/waltsims/k-wave-python
1918
cd k-wave-python
20-
21-
3. Create and Activate Virtual Environment
22-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
23-
.. code-block:: bash
24-
25-
uv venv
26-
source .venv/bin/activate # On Windows: .venv\Scripts\activate
27-
28-
4. Install Dependencies
29-
~~~~~~~~~~~~~~~~~~~~~~~
30-
Install development and testing dependencies using uv:
31-
32-
.. code-block:: bash
33-
34-
uv pip install -e '.[dev,test]'
35-
36-
5. Configure Pre-commit Hooks
37-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38-
.. code-block:: bash
39-
40-
pre-commit install
19+
uv sync --extra dev --extra test
20+
uv run pre-commit install
4121
4222
Testing
4323
-------
4424

45-
Prerequisites
46-
~~~~~~~~~~~~~
47-
- MATLAB installed locally (see `Alternative to MATLAB`_ if you don't have MATLAB)
48-
- `k-Wave <https://github.com/ucl-bug/k-wave>`_ installed in a parallel directory to k-wave-python
49-
50-
**Directory structure for parallel installation:**
51-
52-
.. code-block:: text
25+
.. code-block:: bash
5326
54-
<parent_dir>/
55-
├── k-wave/
56-
│ ├── k-Wave/
57-
│ ├── LICENSE.txt
58-
│ └── README.md
59-
└── k-wave-python/
60-
├── kwave/
61-
└── ...
27+
uv run pytest
6228
29+
Most tests run without MATLAB. Tests that need MATLAB reference data will skip gracefully if the references are not available.
6330

64-
Running Tests
65-
~~~~~~~~~~~~~
31+
.. note::
32+
**Without MATLAB:** Download pre-generated references from
33+
`GitHub CI <https://nightly.link/waltsims/k-wave-python/workflows/pytest/master/matlab_reference_test_values.zip>`_
34+
and unpack into ``tests/matlab_test_data_collectors/python_testers/collectedValues/``.
6635

67-
Full Test Suite
68-
^^^^^^^^^^^^^^^
69-
Run the complete Python test suite:
36+
Test coverage:
7037

71-
.. code-block:: bash
72-
73-
uv run pytest
74-
75-
Test Coverage
76-
^^^^^^^^^^^^^
7738
.. code-block:: bash
7839
7940
uv run coverage run
8041
8142
Running Examples
8243
~~~~~~~~~~~~~~~~
8344

84-
Run a single example:
85-
8645
.. code-block:: bash
8746
8847
uv run python examples/ivp_homogeneous_medium.py
8948
90-
Force CPU Execution
91-
^^^^^^^^^^^^^^^^^^
49+
Force CPU (skip GPU even if available):
50+
9251
.. code-block:: bash
9352
9453
KWAVE_FORCE_CPU=1 uv run python examples/ivp_homogeneous_medium.py
9554
96-
Test Architecture
97-
-----------------
98-
99-
The test suite compares Python and MATLAB outputs through two methodologies:
100-
101-
1. Unit Testing
102-
~~~~~~~~~~~~~~~
103-
- Tests k-Wave-python functions against their MATLAB counterparts
104-
- Reference outputs stored in ``.mat`` files
105-
- Generated by MATLAB scripts in ``tests/matlab_test_data_collectors/matlab_collectors/``
106-
- Master script: ``tests/matlab_test_data_collectors/run_all_collectors.m``
107-
- Output location: ``tests/matlab_test_data_collectors/python_testers/collectedValues/``
55+
Publishing
56+
----------
10857

109-
.. _`Alternative to MATLAB`:
58+
`uv <https://docs.astral.sh/uv/>`_ is used to build and publish to `PyPI <https://pypi.org/>`_.
11059

11160
.. note::
112-
**Alternative to MATLAB:** If you don't have a local MATLAB installation, you can download pre-generated reference artifacts from `GitHub CI <https://nightly.link/waltsims/k-wave-python/workflows/pytest/master/matlab_reference_test_values.zip>`_.
113-
114-
115-
.. _`GitHub CI artifacts link`: https://nightly.link/waltsims/k-wave-python/workflows/pytest/master/matlab_reference_test_values.zip
116-
117-
2. Integration Testing
118-
~~~~~~~~~~~~~~~~~~~~~~
119-
- Validates ``.h5`` files produced by k-Wave-python against original k-Wave outputs
120-
- Uses hash values from MATLAB examples stored in JSON files
121-
- Hash files location: ``tests/reference_outputs/``
122-
- These files are committed to the repository and only require updates for new k-Wave releases
123-
124-
Generating MATLAB Reference Files
125-
---------------------------------
126-
127-
Process for Creating Reference Files
128-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
129-
130-
1. Open target MATLAB example (e.g., ``example_pr_2D_TR_directional_sensors.m`` from the `k-Wave repository <https://github.com/ucl-bug/k-wave/blob/main/k-Wave/examples/example_pr_2D_TR_directional_sensors.m>`_)
131-
132-
2. Locate ``kSpaceFirstOrder`` function call:
133-
134-
.. code-block:: matlab
135-
136-
input_args = {'PMLInside', false, 'PMLSize', PML_size, 'PlotPML', false, 'Smooth', false};
137-
sensor_data = kspaceFirstOrder2D(kgrid, medium, source, sensor, input_args{:});
138-
139-
3. Add save options to ``input_args``:
140-
141-
.. code-block:: matlab
142-
143-
input_args = {'PMLInside', false, 'PMLSize', PML_size, 'PlotPML', false, 'Smooth', false, 'SaveToDisk', true, 'SaveToDiskExit', true};
144-
145-
4. Run modified example to generate ``.h5`` files in your ``tmp`` folder:
146-
147-
- Single function call: creates ``example_input.h5``
148-
- Multiple calls: creates ``example_input_1.h5``, ``example_input_2.h5``, etc.
149-
150-
5. Convert ``.h5`` files to JSON hashes using ``H5Summary``:
151-
152-
- Single file: see `lines 92-95 <https://github.com/waltsims/k-wave-python/blob/1f9df5d987d0b3edb1a8a43fad0885d3d6079029/tests/h5_summary.py#L92-L95>`_
153-
- Multiple files: see `lines 97-106 <https://github.com/waltsims/k-wave-python/blob/1f9df5d987d0b3edb1a8a43fad0885d3d6079029/tests/h5_summary.py#L97-L106>`_
154-
155-
Publishing k-wave-python
156-
-----------------
157-
158-
`uv <https://docs.astral.sh/uv/>`_ is used to build and publish k-wave-python to `PyPI <https://pypi.org/>`_.
159-
160-
.. note::
161-
This is only performed by developers with write access to the k-wave-python package on PyPI.
162-
163-
The package can be built using:
61+
Only for maintainers with PyPI write access.
16462

16563
.. code-block:: bash
16664
16765
uv build
168-
169-
And pushed to the production index with:
170-
171-
.. code-block:: bash
172-
17366
uv publish --token $PYPI_TOKEN
174-

0 commit comments

Comments
 (0)