k-Wave-python 0.3.2__tar.gz → 0.3.4__tar.gz

k_wave_python-0.3.4/.gitignore

@@ -0,0 +1,46 @@
+# IDE specific files
+.idea/
+.vscode/
+
+# Virtual environments
+.venv/
+
+# Compiled files
+*.pyc
+examples/__pycache__/
+
+# System files
+.DS_Store
+
+# Python egg files
+/k_Wave_python.egg-info/
+
+# Build directories
+build/
+src/
+transfer_temp/
+docs/_build/
+kwave/bin/
+
+# Package manager files
+Pipfile.lock
+
+# Coverage reports
+/.coverage
+
+# Test and temporary files
+difference.py
+test_local.sh
+tests/reference_outputs
+
+# Data and output files
+*.mat
+*.mp4
+*.h5
+*.png
+*.tar.gz
+*.whl
+*.asv
+kspaceFirstOrder-*_metadata.json
+
+

{k_wave_python-0.3.2 → k_wave_python-0.3.4}/.pre-commit-config.yaml

@@ -8,6 +8,15 @@ repos:
     language: python
     types_or: [jupyter]
     minimum_pre_commit_version: 2.9.2
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.2.2
+  hooks:
+    # Run the linter.
+    - id: ruff
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format
 # - repo: https://github.com/pre-commit/pre-commit-hooks
 #   rev: v4.5.0  # Use the ref you want to point at
 #   hooks:

{k_wave_python-0.3.2 → k_wave_python-0.3.4}/CITATION.cff

@@ -1,8 +1,5 @@
 cff-version: 1.2.0
-title: k-Wave-Python
-message: >-
-  If you use this software, please cite it using the
-  metadata from this file.
+title: k-Wave-python
 type: software
 authors:
   - given-names: Farid
@@ -10,12 +7,16 @@ authors:
     email: farid.yagubbayli@tum.de
   - given-names: David
     family-names: Sinden
-    affiliation: Fraunhofer Institute for Digital Medicine
+    affiliation: Fraunhofer Institute for Digital Medicine MEVIS
     orcid: 'https://orcid.org/0000-0002-8514-8279'
   - family-names: Simson
     given-names: Walter
     email: wsimson@stanford.edu
     affiliation: Stanford University
     orcid: 'https://orcid.org/0000-0002-2801-8646'
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.10719460
+    description: Zenodo DOI
 repository-code: 'https://github.com/waltsims/k-wave-python'
 license: GPL-3.0

{k_wave_python-0.3.2 → k_wave_python-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: k-Wave-python
-Version: 0.3.2
+Version: 0.3.4
 Summary: Acoustics toolbox for time domain acoustic and ultrasound simulations in complex and tissue-realistic media.
 Project-URL: Homepage, http://www.k-wave.org/
 Project-URL: Documentation, https://waltersimson.com/k-wave-python/
@@ -687,32 +687,34 @@ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.9
-Requires-Dist: beartype==0.16.4
-Requires-Dist: deepdiff==6.7.1
-Requires-Dist: h5py==3.10.0
-Requires-Dist: matplotlib==3.8.3
-Requires-Dist: nptyping==2.5.0
+Requires-Dist: beartype==0.18.5
+Requires-Dist: deepdiff==7.0.1
+Requires-Dist: h5py==3.11.0
+Requires-Dist: jaxtyping==0.2.31
+Requires-Dist: matplotlib==3.9.0
 Requires-Dist: numpy<1.27.0,>=1.22.2
-Requires-Dist: opencv-python==4.9.0.80
-Requires-Dist: scipy==1.12.0
+Requires-Dist: opencv-python==4.10.0.84
+Requires-Dist: scipy==1.13.1
 Provides-Extra: dev
-Requires-Dist: pre-commit==3.6.2; extra == 'dev'
+Requires-Dist: pre-commit==3.7.1; extra == 'dev'
 Provides-Extra: docs
-Requires-Dist: furo==2024.1.29; extra == 'docs'
-Requires-Dist: m2r2==0.3.2; extra == 'docs'
+Requires-Dist: furo==2024.5.6; extra == 'docs'
 Requires-Dist: sphinx-copybutton==0.5.2; extra == 'docs'
-Requires-Dist: sphinx-tabs==3.4.4; extra == 'docs'
-Requires-Dist: sphinx-toolbox==3.5.0; extra == 'docs'
+Requires-Dist: sphinx-mdinclude==0.6.1; extra == 'docs'
+Requires-Dist: sphinx-tabs==3.4.5; extra == 'docs'
+Requires-Dist: sphinx-toolbox==3.6.0; extra == 'docs'
 Provides-Extra: example
-Requires-Dist: gdown==4.6.0; extra == 'example'
+Requires-Dist: gdown==5.2.0; extra == 'example'
 Provides-Extra: test
-Requires-Dist: coverage==7.4.3; extra == 'test'
+Requires-Dist: coverage==7.5.4; extra == 'test'
 Requires-Dist: phantominator; extra == 'test'
 Requires-Dist: pytest; extra == 'test'
-Requires-Dist: requests==2.31.0; extra == 'test'
+Requires-Dist: requests==2.32.3; extra == 'test'
 Description-Content-Type: text/markdown
 
 # k-Wave-python
+
+[![Support](https://dcbadge.vercel.app/api/server/Yq5Qj6D9vN?style=flat)](https://discord.gg/Yq5Qj6D9vN)
 [![Documentation Status](https://readthedocs.org/projects/k-wave-python/badge/?version=latest)](https://k-wave-python.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/waltsims/k-wave-python/graph/badge.svg?token=6ofwtPiDNG)](https://codecov.io/gh/waltsims/k-wave-python)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/waltsims/k-wave-python/master)
@@ -727,30 +729,11 @@ for medical imaging, algorithmic prototyping, and testing. Many tools and method
 be found here, but this project has and will continue to diverge from the original [k-Wave](http://www.k-wave.org/) APIs
 to leverage pythonic practices.
 
-## Installation
-
-To install the most recent build of k-Wave-python from PyPI, run:
-
-```bash
-pip install k-wave-python
-```
-
-After installing the Python package, the required binaries will be downloaded and installed the first time you run a
-simulation.
-
 ## Getting started
 
 ![](_static/example_bmode.png)
 
-After installation, run the B-mode reconstruction example in the `examples` directory of the repository:
-
-```bash
-git clone https://github.com/waltsims/k-wave-python
-cd k-wave-python
-git checkout v0.3.2
-pip install '.[example]' 
-python3 examples/us_bmode_linear_transducer/us_bmode_linear_transducer.py
-```
+A large [collection of examples](../examples/) exists to get started with k-wave-python. All examples can be run in Google Colab notebooks with a few clicks. One can begin with e.g. the [B-mode reconstruction example notebook](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/us_bmode_linear_transducer/us_bmode_linear_transducer.ipynb).
 
 This example file steps through the process of:
  1. Generating a simulation medium
@@ -758,12 +741,16 @@ This example file steps through the process of:
  3. Running the simulation
  4. Reconstructing the simulation
 
-### Requirements
-This example expects an NVIDIA GPU by default to simulate with k-Wave.
+## Installation
+
+To install the most recent build of k-Wave-python from PyPI, run:
+
+```bash
+pip install k-wave-python
+```
 
-To test the reconstruction on a machine with a GPU,
-set `RUN_SIMULATION` [on line 29 of `us_bmode_linear_transducer.py`](https://github.com/waltsims/k-wave-python/blob/6d2ee982bece84fc6980da99b23600f5675d2fc5/examples/us_bmode_linear_transducer/us_bmode_linear_transducer.py#L29)
-to `True`, and the example will run without the pre-computed data.
+After installing the Python package, the required binaries will be downloaded and installed the first time you run a
+simulation.
 
 ## Development
 

{k_wave_python-0.3.2 → k_wave_python-0.3.4}/docs/README.md

@@ -1,4 +1,6 @@
 # k-Wave-python
+
+[![Support](https://dcbadge.vercel.app/api/server/Yq5Qj6D9vN?style=flat)](https://discord.gg/Yq5Qj6D9vN)
 [![Documentation Status](https://readthedocs.org/projects/k-wave-python/badge/?version=latest)](https://k-wave-python.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/waltsims/k-wave-python/graph/badge.svg?token=6ofwtPiDNG)](https://codecov.io/gh/waltsims/k-wave-python)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/waltsims/k-wave-python/master)
@@ -13,30 +15,11 @@ for medical imaging, algorithmic prototyping, and testing. Many tools and method
 be found here, but this project has and will continue to diverge from the original [k-Wave](http://www.k-wave.org/) APIs
 to leverage pythonic practices.
 
-## Installation
-
-To install the most recent build of k-Wave-python from PyPI, run:
-
-```bash
-pip install k-wave-python
-```
-
-After installing the Python package, the required binaries will be downloaded and installed the first time you run a
-simulation.
-
 ## Getting started
 
 ![](_static/example_bmode.png)
 
-After installation, run the B-mode reconstruction example in the `examples` directory of the repository:
-
-```bash
-git clone https://github.com/waltsims/k-wave-python
-cd k-wave-python
-git checkout v0.3.2
-pip install '.[example]' 
-python3 examples/us_bmode_linear_transducer/us_bmode_linear_transducer.py
-```
+A large [collection of examples](../examples/) exists to get started with k-wave-python. All examples can be run in Google Colab notebooks with a few clicks. One can begin with e.g. the [B-mode reconstruction example notebook](https://colab.research.google.com/github/waltsims/k-wave-python/blob/master/examples/us_bmode_linear_transducer/us_bmode_linear_transducer.ipynb).
 
 This example file steps through the process of:
  1. Generating a simulation medium
@@ -44,12 +27,16 @@ This example file steps through the process of:
  3. Running the simulation
  4. Reconstructing the simulation
 
-### Requirements
-This example expects an NVIDIA GPU by default to simulate with k-Wave.
+## Installation
+
+To install the most recent build of k-Wave-python from PyPI, run:
+
+```bash
+pip install k-wave-python
+```
 
-To test the reconstruction on a machine with a GPU,
-set `RUN_SIMULATION` [on line 29 of `us_bmode_linear_transducer.py`](https://github.com/waltsims/k-wave-python/blob/6d2ee982bece84fc6980da99b23600f5675d2fc5/examples/us_bmode_linear_transducer/us_bmode_linear_transducer.py#L29)
-to `True`, and the example will run without the pre-computed data.
+After installing the Python package, the required binaries will be downloaded and installed the first time you run a
+simulation.
 
 ## Development
 

k_wave_python-0.3.4/kwave/__init__.py

@@ -0,0 +1,203 @@
+import logging
+import os
+import platform
+from urllib.request import urlretrieve
+from pathlib import Path
+from typing import List
+import hashlib
+import json
+
+# Test installation with:
+# python3 -m pip install -i https://test.pypi.org/simple/ --extra-index-url=https://pypi.org/simple/ k-Wave-python==0.3.0
+VERSION = "0.3.4"
+
+# Constants and Configurations
+URL_BASE = "https://github.com/waltsims/"
+BINARY_VERSION = "v1.3.0"
+PREFIX = f"{URL_BASE}kspaceFirstOrder-{{}}-{{}}/releases/download/{BINARY_VERSION}/"
+PLATFORM = platform.system().lower()
+
+if PLATFORM not in ["linux", "windows", "darwin"]:
+    raise NotImplementedError(f"k-wave-python is currently unsupported on this operating system: {PLATFORM}.")
+
+# TODO: install directly in to /bin/ directory system directory is no longer needed
+BINARY_PATH = Path(__file__).parent / "bin" / PLATFORM
+
+
+WINDOWS_DLLS = [
+    "cufft64_10.dll",
+    "hdf5.dll",
+    "hdf5_hl.dll",
+    "libiomp5md.dll",
+    "libmmd.dll",
+    "msvcp140.dll",
+    "svml_dispmd.dll",
+    "szip.dll",
+    "vcruntime140.dll",
+    "zlib.dll",
+]
+
+EXECUTABLE_PREFIX = "kspaceFirstOrder-"
+ARCHITECTURES = ["omp", "cuda"]
+
+
+def get_windows_release_urls(architecture: str) -> list:
+    specific_filenames = [EXECUTABLE_PREFIX + architecture + ".exe"]
+    if architecture == "omp":
+        specific_filenames += WINDOWS_DLLS
+    release_urls = [PREFIX.format(architecture.upper(), PLATFORM.lower()) + filename for filename in specific_filenames]
+    return release_urls
+
+
+URL_DICT = {
+    "linux": {
+        "cuda": [URL_BASE + f"kspaceFirstOrder-CUDA-{PLATFORM}/releases/download/v1.3.1/{EXECUTABLE_PREFIX}CUDA"],
+        "omp": [URL_BASE + f"kspaceFirstOrder-OMP-{PLATFORM}/releases/download/{BINARY_VERSION}/{EXECUTABLE_PREFIX}OMP"],
+    },
+    "darwin": {
+        "cuda": [],
+        "omp": [URL_BASE + f"k-wave-omp-{PLATFORM}/releases/download/v0.3.0rc2/{EXECUTABLE_PREFIX}OMP"],
+    },
+    "windows": {architecture: get_windows_release_urls(architecture) for architecture in ARCHITECTURES},
+}
+
+
+def _hash_file(filepath: str) -> str:
+    buf_size = 65536  # 64kb chunks
+    md5 = hashlib.md5()
+
+    with open(filepath, "rb") as f:
+        while True:
+            data = f.read(buf_size)
+            if not data:
+                break
+            md5.update(data)
+    return md5.hexdigest()
+
+
+def _is_binary_present(binary_name: str, binary_type: str) -> bool:
+    binary_filepath = BINARY_PATH / binary_name
+    binary_file_exists = os.path.exists(binary_filepath)
+    if not binary_file_exists:
+        return False
+
+    if binary_type is None:
+        # this is non-kwave windows binary
+        # it already exists according to the check above
+        return True
+    existing_metadata_path = BINARY_PATH / f"{binary_name}_metadata.json"
+
+    if not os.path.exists(existing_metadata_path):
+        # metadata does not exist => binaries may or may not exist
+        # Let's play safe and claim they don't exist
+        # This will trigger binary download and generation of binary metadata
+        return False
+    existing_metadata = json.loads(Path(existing_metadata_path).read_text())
+
+    # If metadata was somehow corrupted
+    file_hash = _hash_file(binary_filepath)
+    if existing_metadata["file_hash"] != file_hash:
+        return False
+
+    # If there is a new binary
+    latest_urls = URL_DICT[PLATFORM][binary_type]
+    if existing_metadata["url"] not in latest_urls:
+        return False
+
+    # No need to check `version` field for now
+    # because we version is already present in the URL
+    return True
+
+
+def binaries_present() -> bool:
+    """
+    Check if binaries are present
+    Returns:
+        bool, True if binaries are present, False otherwise
+
+    """
+    binary_list = []
+    for binary_type in ARCHITECTURES:
+        for binary_name in URL_DICT[PLATFORM][binary_type]:
+            binary_list.append((binary_name.split("/")[-1], binary_type))
+
+    missing_binaries: List[str] = []
+
+    for binary_name, binary_type in binary_list:
+        if not _is_binary_present(binary_name, binary_type):
+            missing_binaries.append(binary_name)
+
+    if len(missing_binaries) > 0:
+        missing_binaries_str = ", ".join(missing_binaries)
+        logging.log(
+            logging.INFO,
+            f"Following binaries were not found: {missing_binaries_str}"
+            "If this is first time you're running k-wave-python, "
+            "binaries will be downloaded automatically.",
+        )
+
+    return len(missing_binaries) == 0
+
+
+def _record_binary_metadata(binary_version: str, binary_filepath: str, binary_url: str, filename: str) -> None:
+    # note: version is not immediately useful at the moment
+    # because it is already present in the url and we use url to understand if versions match
+    # However, let's record it anyway. Maybe it will be useful in the future.
+    metadata = {"url": binary_url, "version": binary_version, "file_hash": _hash_file(binary_filepath)}
+    metadata_filename = f"{filename}_metadata.json"
+    metadata_filepath = BINARY_PATH / metadata_filename
+    with open(metadata_filepath, "w") as outfile:
+        json.dump(metadata, outfile, indent=4)
+
+
+def download_binaries(system_os: str, bin_type: str):
+    """
+    Download binary from release url
+    Args:
+        system_os: string, current system type
+        bin_type: string of "OMP" or "CUDA"
+
+    Returns:
+        None
+
+    """
+    for url in URL_DICT[system_os][bin_type]:
+        # Extract the file name from the GitHub release URL
+        binary_version, filename = url.split("/")[-2:]
+
+        logging.log(logging.INFO, f"Downloading {filename} to {BINARY_PATH}...")
+
+        # Create the directory if it does not yet exist
+        os.makedirs(BINARY_PATH, exist_ok=True)
+
+        # Download the binary file
+        try:
+            binary_filepath = os.path.join(BINARY_PATH, filename)
+            urlretrieve(url, binary_filepath)
+            _record_binary_metadata(binary_version=binary_version, binary_filepath=binary_filepath, binary_url=url, filename=filename)
+
+        except TimeoutError:
+            logging.log(
+                logging.WARN,
+                f"Download of {filename} timed out. "
+                "This can be due to slow internet connection. "
+                "Partially downloaded files will be removed.",
+            )
+            try:
+                os.remove(BINARY_PATH)
+            except Exception:
+                folder_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "bin")
+                logging.warning(
+                    "Error occurred while removing partially downloaded binary. "
+                    f"Please manually delete the `{folder_path}` folder which "
+                    "can be found in your virtual environment."
+                )
+
+
+def install_binaries():
+    for binary_type in ARCHITECTURES:
+        download_binaries(PLATFORM, binary_type)
+
+
+if not binaries_present():
+    install_binaries()

{k_wave_python-0.3.2 → k_wave_python-0.3.4}/kwave/data.py

@@ -60,6 +60,7 @@ class FlexibleVector(object):
 
     WARNING: The class will be deprecated once we refactor the kWaveGrid class to use the Vector class instead!
     """
+
     data: list
 
     def __post_init__(self):

{k_wave_python-0.3.2 → k_wave_python-0.3.4}/kwave/executor.py

@@ -1,32 +1,39 @@
-import logging
 import stat
 import subprocess
-import unittest.mock
+import sys
 
 import h5py
 
+import kwave
 from kwave.utils.dotdictionary import dotdict
 
 
 class Executor:
-
     def __init__(self, execution_options, simulation_options):
-
         self.execution_options = execution_options
         self.simulation_options = simulation_options
 
         self._make_binary_executable()
 
     def _make_binary_executable(self):
-        self.execution_options.binary_path.chmod(self.execution_options.binary_path.stat().st_mode | stat.S_IEXEC)
+        try:
+            self.execution_options.binary_path.chmod(self.execution_options.binary_path.stat().st_mode | stat.S_IEXEC)
+        except FileNotFoundError as e:
+            if kwave.PLATFORM == "darwin" and self.execution_options.is_gpu_simulation:
+                raise ValueError(
+                    "GPU simulations are currently not supported on MacOS. Try running the simulation on CPU by setting is_gpu_simulation=False."
+                ) from e
+            else:
+                raise e
 
     def run_simulation(self, input_filename: str, output_filename: str, options: str):
-
-        command = f'{self.execution_options.system_string} ' \
-                  f'{self.execution_options.binary_path} ' \
-                  f'-i {input_filename} ' \
-                  f'-o {output_filename} ' \
-                  f'{options}'
+        command = (
+            f"{self.execution_options.system_string} "
+            f"{self.execution_options.binary_path} "
+            f"-i {input_filename} "
+            f"-o {output_filename} "
+            f"{options}"
+        )
 
         try:
             with subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE, shell=True, text=True) as proc:
@@ -34,22 +41,19 @@ class Executor:
                 if self.execution_options.show_sim_log:
                     # Stream stdout in real-time
                     for line in proc.stdout:
-                        print(line, end='')
-                else:
-                    stdout, stderr = proc.communicate()  
+                        print(line, end="")
+
+                stdout, stderr = proc.communicate()
 
-                proc.wait() # wait for process to finish before checking return code
+                proc.wait()  # wait for process to finish before checking return code
                 if proc.returncode != 0:
                     raise subprocess.CalledProcessError(proc.returncode, command, stdout, stderr)
 
         except subprocess.CalledProcessError as e:
-            # Special handling for MagicMock during testing
-            if isinstance(e.returncode, unittest.mock.MagicMock):
-                logging.info('Skipping AssertionError in testing.')
-            else:
-                # This ensures stdout is printed regardless of show_sim_logs value if an error occurs
-                print(e.stdout)
-                raise
+            # This ensures stdout is printed regardless of show_sim_logs value if an error occurs
+            print(e.stdout)
+            print(e.stderr, file=sys.stderr)
+            raise
 
         sensor_data = self.parse_executable_output(output_filename)
 
@@ -57,7 +61,6 @@ class Executor:
 
     @staticmethod
     def parse_executable_output(output_filename: str) -> dotdict:
-
         # Load the simulation and pml sizes from the output file
         # with h5py.File(output_filename, 'r') as output_file:
         #     Nx, Ny, Nz = output_file['/Nx'][0].item(), output_file['/Ny'][0].item(), output_file['/Nz'][0].item()
@@ -79,10 +82,10 @@ class Executor:
         #     z1, z2 = 1 + pml_z_size, Nz - pml_z_size if Nz > 1 else (1, Nz)
 
         # Load the C++ data back from disk using h5py
-        with h5py.File(output_filename, 'r') as output_file:
+        with h5py.File(output_filename, "r") as output_file:
             sensor_data = {}
             for key in output_file.keys():
-                sensor_data[key] = output_file[f'/{key}'][0].squeeze()
+                sensor_data[key] = output_file[f"/{key}"][0].squeeze()
         #     if self.simulation_options.cuboid_corners:
         #         sensor_data = [output_file[f'/p/{index}'][()] for index in range(1, len(key['mask']) + 1)]
         #