fullwave25 1.4.3.dev0__tar.gz → 1.5.0.dev0__tar.gz

{fullwave25-1.4.3.dev0 → fullwave25-1.5.0.dev0}/.bumpversion.toml

@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "1.4.3-dev0"
+current_version = "1.5.0-dev0"
 parse = """(?x)
     (?P<major>0|[1-9]\\d*)\\.
     (?P<minor>0|[1-9]\\d*)\\.
@@ -26,7 +26,7 @@ tag_message = "Bump version: {current_version} → {new_version}"
 
 pre_commit_hooks = [
     "uv lock",
-    "git add uv.lock .bumpversion.toml fullwave/__init__.py pyproject.toml",
+    "git add uv.lock .bumpversion.toml fullwave/__init__.py pyproject.toml examples",
 ]
 
 [[tool.bumpversion.files]]
@@ -41,6 +41,19 @@ filename = "fullwave/__init__.py"
 search = '__version__ = "{current_version}"'
 replace = '__version__ = "{new_version}"'
 
+[[tool.bumpversion.files]]
+# Colab install cell of the example notebooks
+glob = "examples/**/*.ipynb"
+search = 'fullwave25=={current_version}'
+replace = 'fullwave25=={new_version}'
+ignore_missing_version = true
+
+[[tool.bumpversion.files]]
+glob = "examples/**/*.ipynb"
+search = 'fullwave25[mach]=={current_version}'
+replace = 'fullwave25[mach]=={new_version}'
+ignore_missing_version = true
+
 [tool.bumpversion.parts.pre_l]
 values = ["dev", "rc", "final"]
 optional_value = "final"

{fullwave25-1.4.3.dev0 → fullwave25-1.5.0.dev0}/.gitignore

@@ -12,3 +12,4 @@ wheels/
 temp/*
 outputs
 .env
+.claude/*

{fullwave25-1.4.3.dev0 → fullwave25-1.5.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fullwave25
-Version: 1.4.3-dev0
+Version: 1.5.0-dev0
 Summary: Fullwave 2.5: Ultrasound wave propagation simulation with heterogeneous power law attenuation modelling capabilities
 Author: Masashi Sode, Gianmarco Pinton
 Maintainer: Masashi Sode
@@ -80,7 +80,7 @@ The solver advances the pressure $p$ and the particle velocity $\mathbf{v}$ with
 
 $$\nabla_1 p + \rho \cfrac{\partial {\bf{v}}}{\partial t} = 0, \qquad \nabla_2 \cdot {\bf{v}} + \kappa \cfrac{\partial p}{\partial t} = 0 .$$
 
-in which the spatial derivatives $\nabla_1$ and $\nabla_2$ carry a set of relaxation mechanisms. fullwave25 looks up the parameters of these mechanisms in a precomputed table for the $\alpha_0$ and $\gamma$ of each cell, so that the simulated attenuation matches the power law and the phase velocity matches its Kramers-Kronig dispersion. The table spans $\alpha_0$ up to 1.0 dB/(MHz^γ cm) and $\gamma$ from 0.4 to 2.0, for frequencies from 0.1 to 20 MHz.
+in which the spatial derivatives $\nabla_1$ and $\nabla_2$ carry a set of relaxation mechanisms. fullwave25 looks up the parameters of these mechanisms in a precomputed table for the $\alpha_0$ and $\gamma$ of each cell, so that the simulated attenuation matches the power law and the phase velocity matches its Kramers-Kronig dispersion. The table spans $\alpha_0$ up to 1.0 dB/(MHz^γ cm) and $\gamma$ from 0.4 to 2.0, for frequencies from 0.1 to 20 MHz. It extends to $\alpha_0$ = 2.0 dB/(MHz^γ cm) for $\gamma$ from 0.4 to 1.6, and to $\alpha_0$ = 10 dB/(MHz^γ cm) for $\gamma$ = 1.0. A specified pair on a cell the table does not fit logs a warning.
 
 The figure compares the target attenuation $\alpha_0 f^\gamma$ (red lines) with the simulated attenuation (black dots) for $\alpha_0 =$ 0.25, 0.5 and 0.75 dB/(MHz^γ cm) and $\gamma =$ 0.4, 0.7, 1.0, 1.3 and 1.6. Each dot is one simulation of a plane wave through a uniform medium, read at two depths.
 
@@ -133,7 +133,7 @@ To start your own simulation, copy [simple_plane_wave.py](examples/simple_plane_
 
 ### Simulation guide
 
-[.claude/skills/fullwave25/SKILL.md](.claude/skills/fullwave25/SKILL.md) is a short guide to setting up a simulation the standard way. It covers:
+[docs/claude_skill/fullwave25/SKILL.md](docs/claude_skill/fullwave25/SKILL.md) is a short guide to setting up a simulation the standard way. It covers:
 
 - the basic flow, the output shapes and the sensor order;
 - scatterers, air and the discretized attenuation values;
@@ -141,7 +141,7 @@ To start your own simulation, copy [simple_plane_wave.py](examples/simple_plane_
 - transducers, presets and beamforming;
 - multi-GPU runs, the container and troubleshooting.
 
-Read it before writing a new simulation. The same file is a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill: Claude Code loads it in a clone of this repository, and you can copy the folder to `~/.claude/skills/fullwave25/` to use it in your own projects.
+Read it before writing a new simulation. The same file is a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill: to use it in Claude Code, copy the folder `docs/claude_skill/fullwave25/` to `~/.claude/skills/fullwave25/`.
 
 ## Transducers and transmits
 

{fullwave25-1.4.3.dev0 → fullwave25-1.5.0.dev0}/README.md

@@ -35,7 +35,7 @@ The solver advances the pressure $p$ and the particle velocity $\mathbf{v}$ with
 
 $$\nabla_1 p + \rho \cfrac{\partial {\bf{v}}}{\partial t} = 0, \qquad \nabla_2 \cdot {\bf{v}} + \kappa \cfrac{\partial p}{\partial t} = 0 .$$
 
-in which the spatial derivatives $\nabla_1$ and $\nabla_2$ carry a set of relaxation mechanisms. fullwave25 looks up the parameters of these mechanisms in a precomputed table for the $\alpha_0$ and $\gamma$ of each cell, so that the simulated attenuation matches the power law and the phase velocity matches its Kramers-Kronig dispersion. The table spans $\alpha_0$ up to 1.0 dB/(MHz^γ cm) and $\gamma$ from 0.4 to 2.0, for frequencies from 0.1 to 20 MHz.
+in which the spatial derivatives $\nabla_1$ and $\nabla_2$ carry a set of relaxation mechanisms. fullwave25 looks up the parameters of these mechanisms in a precomputed table for the $\alpha_0$ and $\gamma$ of each cell, so that the simulated attenuation matches the power law and the phase velocity matches its Kramers-Kronig dispersion. The table spans $\alpha_0$ up to 1.0 dB/(MHz^γ cm) and $\gamma$ from 0.4 to 2.0, for frequencies from 0.1 to 20 MHz. It extends to $\alpha_0$ = 2.0 dB/(MHz^γ cm) for $\gamma$ from 0.4 to 1.6, and to $\alpha_0$ = 10 dB/(MHz^γ cm) for $\gamma$ = 1.0. A specified pair on a cell the table does not fit logs a warning.
 
 The figure compares the target attenuation $\alpha_0 f^\gamma$ (red lines) with the simulated attenuation (black dots) for $\alpha_0 =$ 0.25, 0.5 and 0.75 dB/(MHz^γ cm) and $\gamma =$ 0.4, 0.7, 1.0, 1.3 and 1.6. Each dot is one simulation of a plane wave through a uniform medium, read at two depths.
 
@@ -88,7 +88,7 @@ To start your own simulation, copy [simple_plane_wave.py](examples/simple_plane_
 
 ### Simulation guide
 
-[.claude/skills/fullwave25/SKILL.md](.claude/skills/fullwave25/SKILL.md) is a short guide to setting up a simulation the standard way. It covers:
+[docs/claude_skill/fullwave25/SKILL.md](docs/claude_skill/fullwave25/SKILL.md) is a short guide to setting up a simulation the standard way. It covers:
 
 - the basic flow, the output shapes and the sensor order;
 - scatterers, air and the discretized attenuation values;
@@ -96,7 +96,7 @@ To start your own simulation, copy [simple_plane_wave.py](examples/simple_plane_
 - transducers, presets and beamforming;
 - multi-GPU runs, the container and troubleshooting.
 
-Read it before writing a new simulation. The same file is a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill: Claude Code loads it in a clone of this repository, and you can copy the folder to `~/.claude/skills/fullwave25/` to use it in your own projects.
+Read it before writing a new simulation. The same file is a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill: to use it in Claude Code, copy the folder `docs/claude_skill/fullwave25/` to `~/.claude/skills/fullwave25/`.
 
 ## Transducers and transmits
 

{fullwave25-1.4.3.dev0 → fullwave25-1.5.0.dev0}/fullwave/__init__.py

@@ -66,7 +66,7 @@ try:
     __version__ = version("fullwave")
 except PackageNotFoundError:
     # Update via bump-my-version, not manually
-    __version__ = "1.4.3-dev0"
+    __version__ = "1.5.0-dev0"
 
 VERSION = __version__  # for convenience
 logger.info("Fullwave version: %s", __version__)

{fullwave25-1.4.3.dev0 → fullwave25-1.5.0.dev0}/fullwave/medium.py

@@ -19,6 +19,7 @@ from fullwave.solver.utils import initialize_relaxation_param_dict
 from fullwave.utils import check_functions, plot_utils
 from fullwave.utils.coordinates import coords_to_map, map_to_coords
 from fullwave.utils.relaxation_parameters import (
+    RelaxationParametersGenerator,
     _array_module,
     band_scaled_sound_speed,
     generate_relaxation_params,
@@ -1258,9 +1259,11 @@ class Medium:
             Path to the relaxation parameters database.
         path_invalid_cells : Path, optional
             Path to the JSON record an evaluation wrote, which names every
-            invalid cell of the table and why it is invalid. A request that lands
-            on one is warned about, and the lookup still serves it. Without it
-            nothing is marked and the behaviour is unchanged.
+            invalid cell of the table and why it is invalid. Without it, the
+            record ``<table stem>_invalid_cells.json`` beside the table is read
+            where it exists. A voxel on a ``not_fitted`` cell uses the nearest
+            fitted exponent of the same row, and a voxel on another invalid cell
+            uses that cell and warns.
         n_relaxation_mechanisms : int, optional
             Number of relaxation mechanisms, by default 4
         attenuation_builder : str, optional
@@ -1292,15 +1295,19 @@ class Medium:
             ``MediumRelaxationMaps.sound_speed`` reports the base speed that
             gives it. See ``band_scaled_sound_speed``.
         scale_to_requested_alpha_coeff : bool, optional
-            Give the requested attenuation coefficient rather than the
-            calibrated level the lookup serves. The coefficient axis holds
-            0.0022 and then 0.01 to 1.00 in absolute steps of 0.01, so a request
-            between two levels is served the one above and a request past either
-            end is clipped. Setting this True scales the relaxation departure by
-            the shortfall instead. It matters most under a band transfer, which
-            multiplies the request by a factor and often carries it off the
-            axis. False, the default, reproduces every result produced before
-            this existed.
+            Give the specified attenuation coefficient rather than the
+            coefficient of the cell used. The coefficient axis holds
+            0.0022, then 0.01 to 1.00 in steps of 0.01, then 1.1 to 2.0 in
+            steps of 0.1, then 3 to 10 in steps of 1, so a specified value
+            between two nodes maps to the node above and a value past either
+            end maps to the last node. Above 1.0 the table fits only some
+            exponents, so a cell it does not fit maps to the fitted exponent
+            nearest to it in the same coefficient row. The lookup logs a warning
+            that names each specified value and the cell used. Setting this True
+            scales the relaxation departure by the shortfall instead. It matters
+            most under a band transfer, which multiplies the specified
+            coefficient by a factor and often carries it off the axis. False,
+            the default, reproduces every result produced before this existed.
         n_jobs : int, optional
             Number of parallel jobs for relaxation parameter calculation.
             Default is -1, which uses all available CPUs.
@@ -1612,6 +1619,20 @@ class Medium:
             }
         return relaxation_param_dict
 
+    def _exponent_used(
+        self,
+        alpha_coeff: NDArray[np.float64],
+        alpha_power: NDArray[np.float64],
+    ) -> NDArray[np.float64]:
+        """Return the exponent of the cell each voxel uses, which sets the band anchor."""
+        if self.band_scale == 1.0:
+            return alpha_power
+        return RelaxationParametersGenerator(
+            n_relaxation_mechanisms=self.n_relaxation_mechanisms,
+            path_database=self.path_relaxation_parameters_database,
+            path_invalid_cells=self.path_invalid_cells,
+        )._exponent_used(alpha_coeff, alpha_power, band_scale=self.band_scale)
+
     def relaxation_parameters_at(
         self,
         coords: NDArray[np.int64],
@@ -1636,7 +1657,7 @@ class Medium:
         sound_speed = band_scaled_sound_speed(
             self._to_numpy(self.sound_speed[index]),
             alpha_coeff,
-            alpha_power,
+            self._exponent_used(alpha_coeff, alpha_power),
             self.band_scale,
         )
         parameters = self._relaxation_parameters_of(sound_speed, alpha_coeff, alpha_power)
@@ -1668,7 +1689,7 @@ class Medium:
         sound_speed = band_scaled_sound_speed(
             self.sound_speed,
             self.alpha_coeff,
-            self.alpha_power,
+            self._exponent_used(self.alpha_coeff, self.alpha_power),
             self.band_scale,
         )
         relaxation_param_dict = self._relaxation_parameters_of(