fullwave25 1.4.2.dev3__tar.gz → 1.4.2.dev4__tar.gz

{fullwave25-1.4.2.dev3 → fullwave25-1.4.2.dev4}/.bumpversion.toml

@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "1.4.2-dev3"
+current_version = "1.4.2-dev4"
 parse = """(?x)
     (?P<major>0|[1-9]\\d*)\\.
     (?P<minor>0|[1-9]\\d*)\\.

{fullwave25-1.4.2.dev3 → fullwave25-1.4.2.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fullwave25
-Version: 1.4.2-dev3
+Version: 1.4.2-dev4
 Summary: Fullwave 2.5: Ultrasound wave propagation simulation with heterogeneous power law attenuation modelling capabilities
 Author: Masashi Sode, Gianmarco Pinton
 Maintainer: Masashi Sode
@@ -261,6 +261,8 @@ grid = fullwave.Grid(domain_size=(4.5e-2, 4.5e-2), f0=5.208e6, duration=6.7e-5,
 
 transducer = fullwave.Transducer.l7_4(grid)
 transducer.plane_wave(angle_deg=2.5)
+maps = transducer.fill_probe_above_face(sound_speed=sound_speed_map, density=density_map, alpha_coeff=alpha_coeff_map, alpha_power=alpha_power_map)
+medium = fullwave.Medium(grid, beta=beta_map, **maps)
 
 solver = fullwave.Solver(work_dir="./outputs/my_run", grid=grid, medium=medium, transducer=transducer)
 recorded = solver.run()
@@ -270,9 +272,11 @@ The arrays are `l7_4` (linear, 128 elements, 5.208 MHz), `c5_2v` (curved, 49.57
 
 The transmits are `plane_wave(angle_deg=...)`, `focus(focus_m=...)`, `diverging(virtual_source_m=...)` and `synthetic_aperture(element)`. Each takes `apodization` and `pulse`. Set `transducer.active_source_elements` first to use part of the aperture.
 
-The source type is `"hard_released_after"` by default: the transducer assigns its pressure while the drive signal plays, then the source cells evolve freely. `"hard"` assigns it for the whole run, so the cells stay at zero pressure after the drive ends. `"soft"` adds the signal to the field, and is what the calibrated setups use. Pass `source_type=` to `Transducer.l7_4`, `c5_2v`, `p4_1c` or `fullwave.Solver`.
+The flat arrays (`l7_4`, `p4_1c`, `LinearTransducer`, `make_p4_1c_trasnducer`) share one layout. The source is one wavelength of rows (at least 8) with its first row on grid row 0, the sponge directly behind it. The receiver row is directly in front of the last source row, and the probe face (depth 0) is the row after it, where the medium starts. The array is centered in the grid, so make the grid wider than the array (the calibrated L7-4 uses 45 mm for its 38.09 mm). `transducer.fill_probe_above_face(...)` sets the cells above the face between the first and the last element edge (the source, kerf and receiver cells) to the probe fill (1540 m/s, 1000 kg/m3, attenuation 0.005 dB/MHz/cm, power 1.0), and the columns beside the array on the same rows to water (the same values with power 1.999), with no scatterers; pass its result to `fullwave.Medium`, or register `transducer.probe_fill_domain()` last in a `MediumBuilder`. `transducer.face_row_px` is the face row and `transducer.face_depth_m` its depth: start the tissue there (for an `AbdominalWallDomain`, pass `start_depth=transducer.face_depth_m`) and measure targets and focus depths from it. `Beamformer(..., face_row_px=...)` measures its depths from there. The curved `c5_2v` keeps its own layout, and `transducer.make_surface_reflective_with_air()` returns the air behind it.
 
-`transducer.apply_transducer_stack(...)` paints a probe's backing, matching layer, lens and standoff onto the medium maps before the `Medium` is built. `fullwave.TransducerStack` holds the values.
+The source type is `"hard"` by default for the named arrays: the transducer assigns its pressure for the whole run, so the source cells stay at zero pressure after the drive ends and the face stays reflective. `"hard_released_after"` assigns it while the drive signal plays, then the source cells evolve freely. `"soft"` adds the signal to the field. Pass `source_type=` to `Transducer.l7_4`, `c5_2v`, `p4_1c` or `fullwave.Solver`.
+
+`transducer.apply_transducer_stack(...)` still paints a probe's backing, matching layer, lens and standoff onto the medium maps before the `Medium` is built, for a calibrated stack. `fullwave.TransducerStack` holds the values.
 
 ### Transmit batches
 
@@ -297,6 +301,7 @@ recorded = solver.run_batch(sources)  # [n_transmits, n_sensors, n_t]
 | I want to                          | example                                                                                                     |
 | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | send one plane wave                | [simple_plane_wave.py](examples/simple_plane_wave/simple_plane_wave.py)                                     |
+| do the same with fullwave2-ultra   | [simple_plane_wave_ultra.py](examples/simple_plane_wave/simple_plane_wave_ultra.py)                         |
 | do the same in 3D                  | [simple_plane_wave_3d.py](examples/wave_3d/simple_plane_wave_3d.py)                                         |
 | compound plane waves into a B-mode | [plane_wave_compounding.py](examples/linear_transducer/plane_wave_compounding.py)                           |
 | run a transmit sequence as batches | [transmit_batch_basics.py](examples/transmit_batch/transmit_batch_basics.py)                                |
@@ -395,7 +400,7 @@ Please see the following examples for more advanced usage.
 
 The fullwave2-ultra backend is optimized for speed at ppw = 6 (`Grid.ppw`); a larger ppw runs, but more slowly, and gives a warning.
 
-fullwave25 does not ship the fullwave2-ultra binaries. Get them from <https://github.com/pinton-lab/fullwave2-ultra> or contact the Pinton lab.
+fullwave25 does not ship the fullwave2-ultra binaries. Obtain them from the Pinton lab.
 
 Point the solver to the binary with `path_fullwave_simulation_bin` or with the environment variable `FW2U_BATCH_BIN`. Either can be the binary file or the folder that contains it. The binary name is `bench_2d_batch` for a 2D grid and `bench_3d_opt` for a 3D grid.
 
@@ -407,7 +412,7 @@ import fullwave
 solver = fullwave.Solver(
     work_dir=Path("./outputs/ultra"),
     grid=grid,  # 2D or 3D fullwave.Grid
-    medium=medium,  # fullwave.Medium with alpha_power == 1 everywhere
+    medium=medium,  # fullwave.Medium; alpha_power other than 1 is converted to power 1 at f0
     source=source,
     sensor=sensor,
     path_fullwave_simulation_bin=Path("/path/to/fullwave2-ultra/bin"),
@@ -431,17 +436,40 @@ Supported now:
 - `run_batch` in 3D.
 - Velocity sources, and sources that are not pressure sources.
 - Sparse-grid sensors, `is_static_map`, and `record_whole_domain`.
-- Media other than `fullwave.Medium` (exponential attenuation), and `alpha_power` other than 1.
+- Media other than `fullwave.Medium` (exponential attenuation).
 - `use_pml=False`, `m_spatial_order` other than 8, `use_gpu=False`, and an invalid `source_type`.
 - In 2D, a binary that does not read the files for air cells, for the additive channel, or for releasing the source (with such a binary, pad `p0` to `grid.nt`).
 - In 3D, air cells with a binary that does not read `icczero.dat` and `nzero0.dat`, and additive sources with a binary that does not read `ncoords_add.dat` and `icmat_add.dat`.
 
 This list will grow as the backend does.
 
-The backend runs the exponential attenuation model (frequency-independent: the same attenuation at every frequency). Set the width of its absorbing sponge, in cells, with `ultra_sponge_thickness_px`; the default is 6 wavelengths in 2D and 4 wavelengths in 3D. `exponential_attenuation_pml_thickness_px` no longer sets this width with `use_ultra=True`; a script that relied on it now gets the default width until it passes `ultra_sponge_thickness_px`.
+Unless `ultra_attenuation_parameters` is set (below), the backend runs the exponential attenuation model (frequency-independent: the same attenuation at every frequency); a frequency-dependent attenuation is available only with `ultra_attenuation_parameters` and a compatible binary. Without it, cells with an `alpha_power` other than 1 are converted to power 1 with the same attenuation at `f0` (`alpha_coeff * f0_MHz**(alpha_power - 1)`), with one warning that names the converted range. Set the width of its absorbing sponge, in cells, with `ultra_sponge_thickness_px`; the default is 6 wavelengths in 2D and 4 wavelengths in 3D. `exponential_attenuation_pml_thickness_px` no longer sets this width with `use_ultra=True`; a script that relied on it now gets the default width until it passes `ultra_sponge_thickness_px`.
 
 Options that only tune the native solver are ignored with a warning, once per process: `pml_layer_thickness_px`, `n_transition_layer`, `pml_alpha_entrance`, `exponential_attenuation_pml_thickness_px` (use `ultra_sponge_thickness_px` instead), `use_gpu_pml`, `save_gpu_memory`, `write_maps_the_solver_does_not_read`, `use_isotropic_relaxation=False`, and a `cuda_device_id` that lists more than one device (the run uses the first one listed). `use_exponential_attenuation=False`, the native default, also warns that the backend runs the exponential attenuation model, whose attenuation is frequency-independent, not the relaxation model, whose attenuation is frequency-dependent. Pass `use_exponential_attenuation=True` to silence it.
 
+#### Attenuation modes
+
+A 2D or 3D run has three attenuation modes. Each needs `use_ultra=True`; the last two need the power-law attenuation binaries from the Pinton lab and `use_exponential_attenuation=False`.
+
+```python
+# 1. Default: frequency-independent attenuation (as described above).
+solver = fullwave.Solver(..., use_ultra=True, path_fullwave_simulation_bin=bin_folder)
+
+# 2. Power-law attenuation alpha_coeff * f**alpha_power.
+solver = fullwave.Solver(
+    ...,
+    use_ultra=True,
+    use_exponential_attenuation=False,
+    path_fullwave_simulation_bin=bin_folder,
+    ultra_attenuation_parameters="centered",  # or "author", or the path of a settings file
+)
+
+# 3. The same with any number of materials (more GPU memory).
+solver = fullwave.Solver(..., ultra_attenuation_parameters="centered", ultra_unlimited_materials=True)
+```
+
+`bin_folder` is the folder of the binaries. With `ultra_attenuation_parameters` it gives the power-law build of the grid dimension; without it, `bench_2d_batch` or `bench_3d_opt`. A name looks for `attenuation_parameters_<name>_v1.dat` next to the binary, then in the `params` folder beside `bin_folder`; the error lists the places searched. "centered" is the recommended band. `UltraUnsupportedError` is raised without `use_ultra=True`, with `use_exponential_attenuation=True`, for a missing settings file, for a binary that does not read `alpha_power.dat`, and, with `ultra_unlimited_materials=True`, for a binary that does not support it. The run directory then gets `alpha_coeff.dat`, `alpha_power.dat`, `f0.dat` and a copy of the settings file as `attenuation_parameters.dat`, and `Aexp.dat` holds the sponge only. The environment variable `FW2U_BATCH_BIN` is not used in modes 2 and 3.
+
 ---
 
 ## Attention

{fullwave25-1.4.2.dev3 → fullwave25-1.4.2.dev4}/README.md

@@ -220,6 +220,8 @@ grid = fullwave.Grid(domain_size=(4.5e-2, 4.5e-2), f0=5.208e6, duration=6.7e-5,
 
 transducer = fullwave.Transducer.l7_4(grid)
 transducer.plane_wave(angle_deg=2.5)
+maps = transducer.fill_probe_above_face(sound_speed=sound_speed_map, density=density_map, alpha_coeff=alpha_coeff_map, alpha_power=alpha_power_map)
+medium = fullwave.Medium(grid, beta=beta_map, **maps)
 
 solver = fullwave.Solver(work_dir="./outputs/my_run", grid=grid, medium=medium, transducer=transducer)
 recorded = solver.run()
@@ -229,9 +231,11 @@ The arrays are `l7_4` (linear, 128 elements, 5.208 MHz), `c5_2v` (curved, 49.57
 
 The transmits are `plane_wave(angle_deg=...)`, `focus(focus_m=...)`, `diverging(virtual_source_m=...)` and `synthetic_aperture(element)`. Each takes `apodization` and `pulse`. Set `transducer.active_source_elements` first to use part of the aperture.
 
-The source type is `"hard_released_after"` by default: the transducer assigns its pressure while the drive signal plays, then the source cells evolve freely. `"hard"` assigns it for the whole run, so the cells stay at zero pressure after the drive ends. `"soft"` adds the signal to the field, and is what the calibrated setups use. Pass `source_type=` to `Transducer.l7_4`, `c5_2v`, `p4_1c` or `fullwave.Solver`.
+The flat arrays (`l7_4`, `p4_1c`, `LinearTransducer`, `make_p4_1c_trasnducer`) share one layout. The source is one wavelength of rows (at least 8) with its first row on grid row 0, the sponge directly behind it. The receiver row is directly in front of the last source row, and the probe face (depth 0) is the row after it, where the medium starts. The array is centered in the grid, so make the grid wider than the array (the calibrated L7-4 uses 45 mm for its 38.09 mm). `transducer.fill_probe_above_face(...)` sets the cells above the face between the first and the last element edge (the source, kerf and receiver cells) to the probe fill (1540 m/s, 1000 kg/m3, attenuation 0.005 dB/MHz/cm, power 1.0), and the columns beside the array on the same rows to water (the same values with power 1.999), with no scatterers; pass its result to `fullwave.Medium`, or register `transducer.probe_fill_domain()` last in a `MediumBuilder`. `transducer.face_row_px` is the face row and `transducer.face_depth_m` its depth: start the tissue there (for an `AbdominalWallDomain`, pass `start_depth=transducer.face_depth_m`) and measure targets and focus depths from it. `Beamformer(..., face_row_px=...)` measures its depths from there. The curved `c5_2v` keeps its own layout, and `transducer.make_surface_reflective_with_air()` returns the air behind it.
 
-`transducer.apply_transducer_stack(...)` paints a probe's backing, matching layer, lens and standoff onto the medium maps before the `Medium` is built. `fullwave.TransducerStack` holds the values.
+The source type is `"hard"` by default for the named arrays: the transducer assigns its pressure for the whole run, so the source cells stay at zero pressure after the drive ends and the face stays reflective. `"hard_released_after"` assigns it while the drive signal plays, then the source cells evolve freely. `"soft"` adds the signal to the field. Pass `source_type=` to `Transducer.l7_4`, `c5_2v`, `p4_1c` or `fullwave.Solver`.
+
+`transducer.apply_transducer_stack(...)` still paints a probe's backing, matching layer, lens and standoff onto the medium maps before the `Medium` is built, for a calibrated stack. `fullwave.TransducerStack` holds the values.
 
 ### Transmit batches
 
@@ -256,6 +260,7 @@ recorded = solver.run_batch(sources)  # [n_transmits, n_sensors, n_t]
 | I want to                          | example                                                                                                     |
 | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | send one plane wave                | [simple_plane_wave.py](examples/simple_plane_wave/simple_plane_wave.py)                                     |
+| do the same with fullwave2-ultra   | [simple_plane_wave_ultra.py](examples/simple_plane_wave/simple_plane_wave_ultra.py)                         |
 | do the same in 3D                  | [simple_plane_wave_3d.py](examples/wave_3d/simple_plane_wave_3d.py)                                         |
 | compound plane waves into a B-mode | [plane_wave_compounding.py](examples/linear_transducer/plane_wave_compounding.py)                           |
 | run a transmit sequence as batches | [transmit_batch_basics.py](examples/transmit_batch/transmit_batch_basics.py)                                |
@@ -354,7 +359,7 @@ Please see the following examples for more advanced usage.
 
 The fullwave2-ultra backend is optimized for speed at ppw = 6 (`Grid.ppw`); a larger ppw runs, but more slowly, and gives a warning.
 
-fullwave25 does not ship the fullwave2-ultra binaries. Get them from <https://github.com/pinton-lab/fullwave2-ultra> or contact the Pinton lab.
+fullwave25 does not ship the fullwave2-ultra binaries. Obtain them from the Pinton lab.
 
 Point the solver to the binary with `path_fullwave_simulation_bin` or with the environment variable `FW2U_BATCH_BIN`. Either can be the binary file or the folder that contains it. The binary name is `bench_2d_batch` for a 2D grid and `bench_3d_opt` for a 3D grid.
 
@@ -366,7 +371,7 @@ import fullwave
 solver = fullwave.Solver(
     work_dir=Path("./outputs/ultra"),
     grid=grid,  # 2D or 3D fullwave.Grid
-    medium=medium,  # fullwave.Medium with alpha_power == 1 everywhere
+    medium=medium,  # fullwave.Medium; alpha_power other than 1 is converted to power 1 at f0
     source=source,
     sensor=sensor,
     path_fullwave_simulation_bin=Path("/path/to/fullwave2-ultra/bin"),
@@ -390,17 +395,40 @@ Supported now:
 - `run_batch` in 3D.
 - Velocity sources, and sources that are not pressure sources.
 - Sparse-grid sensors, `is_static_map`, and `record_whole_domain`.
-- Media other than `fullwave.Medium` (exponential attenuation), and `alpha_power` other than 1.
+- Media other than `fullwave.Medium` (exponential attenuation).
 - `use_pml=False`, `m_spatial_order` other than 8, `use_gpu=False`, and an invalid `source_type`.
 - In 2D, a binary that does not read the files for air cells, for the additive channel, or for releasing the source (with such a binary, pad `p0` to `grid.nt`).
 - In 3D, air cells with a binary that does not read `icczero.dat` and `nzero0.dat`, and additive sources with a binary that does not read `ncoords_add.dat` and `icmat_add.dat`.
 
 This list will grow as the backend does.
 
-The backend runs the exponential attenuation model (frequency-independent: the same attenuation at every frequency). Set the width of its absorbing sponge, in cells, with `ultra_sponge_thickness_px`; the default is 6 wavelengths in 2D and 4 wavelengths in 3D. `exponential_attenuation_pml_thickness_px` no longer sets this width with `use_ultra=True`; a script that relied on it now gets the default width until it passes `ultra_sponge_thickness_px`.
+Unless `ultra_attenuation_parameters` is set (below), the backend runs the exponential attenuation model (frequency-independent: the same attenuation at every frequency); a frequency-dependent attenuation is available only with `ultra_attenuation_parameters` and a compatible binary. Without it, cells with an `alpha_power` other than 1 are converted to power 1 with the same attenuation at `f0` (`alpha_coeff * f0_MHz**(alpha_power - 1)`), with one warning that names the converted range. Set the width of its absorbing sponge, in cells, with `ultra_sponge_thickness_px`; the default is 6 wavelengths in 2D and 4 wavelengths in 3D. `exponential_attenuation_pml_thickness_px` no longer sets this width with `use_ultra=True`; a script that relied on it now gets the default width until it passes `ultra_sponge_thickness_px`.
 
 Options that only tune the native solver are ignored with a warning, once per process: `pml_layer_thickness_px`, `n_transition_layer`, `pml_alpha_entrance`, `exponential_attenuation_pml_thickness_px` (use `ultra_sponge_thickness_px` instead), `use_gpu_pml`, `save_gpu_memory`, `write_maps_the_solver_does_not_read`, `use_isotropic_relaxation=False`, and a `cuda_device_id` that lists more than one device (the run uses the first one listed). `use_exponential_attenuation=False`, the native default, also warns that the backend runs the exponential attenuation model, whose attenuation is frequency-independent, not the relaxation model, whose attenuation is frequency-dependent. Pass `use_exponential_attenuation=True` to silence it.
 
+#### Attenuation modes
+
+A 2D or 3D run has three attenuation modes. Each needs `use_ultra=True`; the last two need the power-law attenuation binaries from the Pinton lab and `use_exponential_attenuation=False`.
+
+```python
+# 1. Default: frequency-independent attenuation (as described above).
+solver = fullwave.Solver(..., use_ultra=True, path_fullwave_simulation_bin=bin_folder)
+
+# 2. Power-law attenuation alpha_coeff * f**alpha_power.
+solver = fullwave.Solver(
+    ...,
+    use_ultra=True,
+    use_exponential_attenuation=False,
+    path_fullwave_simulation_bin=bin_folder,
+    ultra_attenuation_parameters="centered",  # or "author", or the path of a settings file
+)
+
+# 3. The same with any number of materials (more GPU memory).
+solver = fullwave.Solver(..., ultra_attenuation_parameters="centered", ultra_unlimited_materials=True)
+```
+
+`bin_folder` is the folder of the binaries. With `ultra_attenuation_parameters` it gives the power-law build of the grid dimension; without it, `bench_2d_batch` or `bench_3d_opt`. A name looks for `attenuation_parameters_<name>_v1.dat` next to the binary, then in the `params` folder beside `bin_folder`; the error lists the places searched. "centered" is the recommended band. `UltraUnsupportedError` is raised without `use_ultra=True`, with `use_exponential_attenuation=True`, for a missing settings file, for a binary that does not read `alpha_power.dat`, and, with `ultra_unlimited_materials=True`, for a binary that does not support it. The run directory then gets `alpha_coeff.dat`, `alpha_power.dat`, `f0.dat` and a copy of the settings file as `attenuation_parameters.dat`, and `Aexp.dat` holds the sponge only. The environment variable `FW2U_BATCH_BIN` is not used in modes 2 and 3.
+
 ---
 
 ## Attention

{fullwave25-1.4.2.dev3 → fullwave25-1.4.2.dev4}/fullwave/__init__.py

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

{fullwave25-1.4.2.dev3 → fullwave25-1.4.2.dev4}/fullwave/beamformer/beamformer.py

@@ -14,12 +14,13 @@ class Beamformer:
     For faster implementations, consider using libraries such as
     mach beamformer: https://github.com/Forest-Neurotech/mach
 
-    Conventions: ``axial_position_m`` is measured from the top of the grid
-    (row 0), not from the array. ``transducer_coordinates`` must be the
-    receiver positions in grid points (for example from
-    ``Transducer.element_id_to_receiver_center``). The time origin is the
-    mean receiver row, so the array depth is subtracted from the two-way
-    travel time.
+    Conventions: ``axial_position_m`` is the depth below the probe face, so
+    depth 0 is the face row ``face_row_px`` (``Transducer.face_row_px``, the
+    first medium row, one row in front of the receiver row).
+    ``transducer_coordinates`` must be the receiver positions in grid points
+    (for example from ``Transducer.element_id_to_receiver_center``). The time
+    origin is the mean receiver row, so the array depth is subtracted from the
+    two-way travel time.
 
     References
     ----------
@@ -38,6 +39,7 @@ class Beamformer:
         axial_position_m: np.ndarray,
         num_elements: int,
         transducer_coordinates: np.ndarray,
+        face_row_px: int,
         f_number: float = 1.0,
     ) -> None:
         """Initialize the beamformer with simulation and transducer parameters.
@@ -53,11 +55,14 @@ class Beamformer:
         lateral_position_m : np.ndarray
             Lateral positions (m) where the beamformed image will be computed.
         axial_position_m : np.ndarray
-            Axial positions (m) from the top of the grid where the image is computed.
+            Depths (m) below the probe face where the image is computed.
         num_elements : int
             Number of transducer elements.
         transducer_coordinates : np.ndarray
             Receiver coordinates [n_elements, 2] in grid points (row, column).
+        face_row_px : int
+            Grid row of the probe face (depth 0), for example
+            ``Transducer.face_row_px``.
         f_number : float, optional
             F-number for aperture calculation, by default 1.0.
 
@@ -69,6 +74,7 @@ class Beamformer:
         self.axial_position_m = axial_position_m
         self.num_elements = num_elements
         self.transducer_coordinates = transducer_coordinates
+        self.face_row_px = face_row_px
         self.f_number = f_number
 
     def run(self, signals: np.ndarray) -> np.ndarray:
@@ -83,7 +89,9 @@ class Beamformer:
         Returns
         -------
         np.ndarray
-            Beamformed image. Shape: [n_axial, n_lateral, n_transmit].
+            Beamformed image. Shape: [n_axial, n_lateral, n_transmit]. Row 0
+            of the first axis is the first depth of ``axial_position_m``, which
+            is measured from the probe face.
 
         """
         # signals: [n_elements, n_time, n_transmit]
@@ -110,12 +118,13 @@ class Beamformer:
                 desc="Lateral positions",
                 total=len(self.lateral_position_m),
             ):
-                for i_axial, axial in tqdm(
+                for i_axial, depth in tqdm(
                     enumerate(self.axial_position_m),
                     desc="Axial positions",
                     total=len(self.axial_position_m),
                     leave=False,
                 ):
+                    axial = self.face_row_px * self.dx + depth
                     fcen = np.array(
                         [
                             int(axial / self.dx),

{fullwave25-1.4.2.dev3 → fullwave25-1.4.2.dev4}/fullwave/solver/input_file_writer.py

@@ -293,6 +293,7 @@ class InputFileWriter:
                     _incoords_vel,
                 )
         self._queue_coords_write(simulation_dir / "icc.dat", self.source.incoords)
+        self._save_drive_params(simulation_dir, members)
         self._copy_simulation_bin_file(simulation_dir)
 
         if not self.use_exponential_attenuation:
@@ -1275,8 +1276,6 @@ class InputFileWriter:
             "ncoords_w",
             "ncoordsout",
             "ncoordszero",
-            "nTic",
-            "hold_source",
             "modT",
             "modX",
             "modY",
@@ -1374,6 +1373,27 @@ class InputFileWriter:
             save_path = simulation_dir / f"{var_name}.dat"
             self._queue_v_abs_write(np.float32, save_path, var)
 
+    def _save_drive_params(
+        self,
+        simulation_dir: Path,
+        members: Sequence[fullwave.Source] | None = None,
+    ) -> None:
+        """Write the drive length and the hold flag of this transmit.
+
+        Every transmit folder gets its own files, never a link to the shared
+        static-map files, and a flag left by an earlier run is removed when the
+        hold is off. The members of a batch share one length, which can exceed the
+        length of the source, so the drive length is the one of the members.
+        """
+        drive_length_file = simulation_dir / "nTic.dat"
+        hold_flag_file = simulation_dir / "hold_source.dat"
+        drive_length_file.unlink(missing_ok=True)
+        hold_flag_file.unlink(missing_ok=True)
+        drive_source = self.source if members is None else members[0]
+        self._queue_v_abs_write(np.int32, drive_length_file, drive_source.icmat.shape[1])
+        if self._holds_the_source:
+            self._queue_v_abs_write(np.int32, hold_flag_file, 1)
+
     def _save_coords_params(self, simulation_dir: Path) -> None:
         var_list = [
             ("nX", self.grid.nx),
@@ -1382,11 +1402,8 @@ class InputFileWriter:
             ("ncoords", self.source.n_sources),
             ("ncoordsout", self.sensor.n_sensors),
             ("ncoordszero", self.medium.n_air),
-            ("nTic", self.source.icmat.shape[1]),
             ("modT", self.sensor.sampling_modulus_time),
         ]
-        if self._holds_the_source:
-            var_list.append(("hold_source", 1))
         n_sources_add = getattr(self.source, "n_sources_add", 0)
         if n_sources_add > 0:
             var_list.append(("ncoords_add", n_sources_add))

{fullwave25-1.4.2.dev3 → fullwave25-1.4.2.dev4}/fullwave/solver/solver.py

@@ -1,6 +1,7 @@
 """solver module."""
 
 import contextlib
+import copy
 import logging
 import os
 import time
@@ -22,6 +23,7 @@ from fullwave.solver.source_type import (
     is_hard_held,
     is_soft,
 )
+from fullwave.ultra import attenuation_parameters as power_law_attenuation
 from fullwave.ultra import backend, binary, factory
 from fullwave.utils import (
     check_functions,
@@ -470,10 +472,12 @@ class Solver:
         verify_gpu: bool = True,
         use_gpu_pml: bool = False,
         pml_alpha_entrance: float | None = None,
-        source_type: str = HARD_RELEASED_AFTER,
+        source_type: str | None = None,
         write_maps_the_solver_does_not_read: bool = False,
         use_ultra: bool = False,
         ultra_sponge_thickness_px: int | None = None,
+        ultra_attenuation_parameters: str | Path | None = None,
+        ultra_unlimited_materials: bool = False,
     ) -> None:
         """Initialize a Solver instance for the fullwave simulation.
 
@@ -599,12 +603,14 @@ class Solver:
             relaxation path. Set it to True for a solver binary that predates
             that record. Such a binary stops with an error on kappax.dat rather
             than returning a wrong answer.
-        source_type : str, optional
-            How the source drives the field. "hard_released_after", the default,
-            assigns the source pressure while the drive signal plays, then lets the
-            source cells evolve freely. "hard" assigns it for the whole run, so the
-            cells stay at zero pressure after the signal ends. "soft" adds the signal
-            to the field. ``use_ultra`` follows the same three values.
+        source_type : str | None, optional
+            How the source drives the field. None, the default, takes the type of the
+            ``transducer`` when one is given, and "hard_released_after" otherwise. A
+            value that differs from the transducer's type raises ValueError.
+            "hard_released_after" assigns the source pressure while the drive signal
+            plays, then lets the source cells evolve freely. "hard" assigns it for the
+            whole run, so the cells stay at zero pressure after the signal ends.
+            "soft" adds the signal to the field. ``use_ultra`` follows the same three values.
         use_ultra : bool, optional
             Experimental. Run a user-supplied fullwave2-ultra binary (not shipped; pass it
             as ``path_fullwave_simulation_bin`` or set ``FW2U_BATCH_BIN``): ``bench_2d_batch``
@@ -620,6 +626,13 @@ class Solver:
             Width of the absorbing sponge of the ``use_ultra`` backend, in cells.
             None, the default, gives 6 wavelengths in 2D and 4 wavelengths in 3D.
             Used only with ``use_ultra=True``.
+        ultra_attenuation_parameters : str | Path, optional
+            Power-law attenuation for the ``use_ultra`` backend. Give "centered", "author",
+            or the path of a parameter file. Needs ``use_ultra=True`` and
+            ``use_exponential_attenuation=False``.
+        ultra_unlimited_materials : bool, optional
+            If True, allow any number of distinct materials (uses more GPU memory). Needs
+            ``ultra_attenuation_parameters``.
 
         Raises
         ------
@@ -630,9 +643,28 @@ class Solver:
             and transducer) are defined simultaneously.
 
         """
+        source_type = self._resolve_source_type(source_type=source_type, transducer=transducer)
         self.ultra = None
+        power_law_attenuation.check_unlimited_materials(
+            unlimited_materials=ultra_unlimited_materials,
+            parameters=ultra_attenuation_parameters,
+            use_ultra=use_ultra,
+        )
+        if ultra_attenuation_parameters is not None:
+            request = power_law_attenuation.check_request(
+                parameters=ultra_attenuation_parameters,
+                use_ultra=use_ultra,
+                use_exponential_attenuation=use_exponential_attenuation,
+                binary=path_fullwave_simulation_bin,
+                is_3d=grid.is_3d,
+                unlimited_materials=ultra_unlimited_materials,
+            )
+            ultra_attenuation_parameters = request.parameter_file
+            path_fullwave_simulation_bin = request.binary
         if use_ultra:
             self._init_ultra(
+                attenuation_parameters=ultra_attenuation_parameters,
+                unlimited_materials=ultra_unlimited_materials,
                 work_dir=work_dir,
                 grid=grid,
                 medium=medium,
@@ -813,7 +845,12 @@ class Solver:
             logger.error(error_msg)
             raise ValueError(error_msg)
         self.source_type = source_type
-        if is_soft(source_type) and self.source.p0_additive is not None:
+        source_is_the_transducers = source is None and transducer is not None
+        if is_soft(source_type) and source_is_the_transducers:
+            logger.info(
+                "source_type=%s, the transducer's source is driven by addition", source_type
+            )
+        elif is_soft(source_type) and self.source.p0_additive is not None:
             error_msg = (
                 "this source already carries an additive signal. source_type='soft' "
                 "converts a hard source into a soft one, and this source holds no "
@@ -824,7 +861,7 @@ class Solver:
             raise ValueError(error_msg)
         if not is_soft(source_type) and self.source.p0_additive is not None:
             self._warn_if_the_additive_signal_was_not_scaled()
-        if is_soft(source_type):
+        if is_soft(source_type) and not source_is_the_transducers:
             self.source = as_additive_source(
                 self.source,
                 self.grid,
@@ -898,11 +935,15 @@ class Solver:
         verify_gpu: bool,
         nbdy: int | None,
         options: dict,
+        attenuation_parameters: Path | None,
+        unlimited_materials: bool,
     ) -> None:
         """Set up the experimental fullwave2-ultra backend (see ``fullwave.ultra``)."""
         backend.warn_experimental()
         backend.warn_ppw_above_speed_optimum(ppw=grid.ppw)
-        backend.check_solver_options(**options)
+        backend.check_solver_options(
+            **options, has_attenuation_parameters=attenuation_parameters is not None
+        )
         binary_name = binary.BINARY_NAME_3D if grid.is_3d else binary.BINARY_NAME_2D
         ultra_binary = binary.resolve_binary(path_fullwave_simulation_bin, name=binary_name)
         self._check_input(grid, medium, source, sensor, transducer, ultra_binary)
@@ -924,8 +965,48 @@ class Solver:
             cuda_device_id=cuda_device_id,
             verify_gpu=verify_gpu,
             source_type=options["source_type"],
+            attenuation_parameters=attenuation_parameters,
+            unlimited_materials=unlimited_materials,
         )
 
+    @staticmethod
+    def _resolve_source_type(
+        *, source_type: str | None, transducer: fullwave.Transducer | None
+    ) -> str:
+        """Return the source type of the run.
+
+        Parameters
+        ----------
+        source_type : str | None
+            The Solver's own argument.
+        transducer : fullwave.Transducer | None
+            The transducer that drives the run, if any.
+
+        Returns
+        -------
+        str
+            The transducer's type when the argument is None and a transducer is given,
+            the argument when it is given, and "hard_released_after" otherwise.
+
+        Raises
+        ------
+        ValueError
+            If the argument differs from the transducer's type.
+        """
+        if transducer is None:
+            return HARD_RELEASED_AFTER if source_type is None else source_type
+        if source_type is None:
+            return transducer.source_type
+        if source_type != transducer.source_type:
+            error_msg = (
+                f"Solver source_type {source_type!r} differs from the transducer's "
+                f"source_type {transducer.source_type!r}. Set the source type in one "
+                "place, on the Transducer, and leave the Solver's source_type unset."
+            )
+            logger.error(error_msg)
+            raise ValueError(error_msg)
+        return source_type
+
     def _warn_if_the_additive_signal_was_not_scaled(self) -> None:
         """Say so when an additive signal was built by hand and may carry no scale.
 
@@ -1541,8 +1622,10 @@ class Solver:
         Parameters
         ----------
         sources : Sequence[fullwave.Source]
-            The transmits, in order. Each one must have the same source coordinates,
-            the same signal kinds and the same signal length as the Solver's source.
+            The transmits, in order. Each one must have the same source coordinates
+            and the same signal kinds as the Solver's source. The signals may differ in
+            length and are padded with trailing zeros to the longest drive; with
+            ``use_ultra=True`` they must have one length.
             The Solver's ``source_type`` applies to every transmit.
         simulation_dir_name : str | Path
             The directory name of the simulation under the work directory.
@@ -1604,7 +1687,7 @@ class Solver:
                 highpass_cutoff_mhz=highpass_cutoff_mhz,
                 bandpass_cutoff_mhz=bandpass_cutoff_mhz,
             )
-        members = self._batch_members(sources)
+        members = self._batch_members(self._pad_to_longest_drive(sources))
         # The sensor and the sizing below need the extended grid and medium.
         self.pml_builder.run(use_pml=self.use_pml)
         sensor = self._output_sensor(
@@ -1647,6 +1730,43 @@ class Solver:
             return [path for run_paths in outputs for path in run_paths]
         return np.concatenate(outputs, axis=0)
 
+    def _pad_to_longest_drive(self, sources: Sequence[fullwave.Source]) -> list[fullwave.Source]:
+        """Return the transmits with every signal padded with zeros to the longest drive.
+
+        The longest drive is the longest signal among the transmits and the Solver's
+        source. The transmits are copied; the given sources stay as they are.
+
+        Parameters
+        ----------
+        sources : Sequence[fullwave.Source]
+            The transmits, in order.
+
+        Returns
+        -------
+        list[fullwave.Source]
+            The transmits, with signals of equal length.
+
+        """
+        names = ("p0", "p0_additive", "u0", "v0", "w0")
+        reference = [self.source] if getattr(self, "source", None) is not None else []
+        padded = []
+        for source in sources:
+            member = copy.copy(source)
+            for name in names:
+                signal = getattr(member, name, None)
+                if signal is None:
+                    continue
+                length = max(
+                    np.shape(getattr(other, name, None))[-1]
+                    for other in [*sources, *reference]
+                    if getattr(other, name, None) is not None
+                )
+                if np.shape(signal)[-1] < length:
+                    pad = [(0, 0)] * (np.ndim(signal) - 1) + [(0, length - np.shape(signal)[-1])]
+                    setattr(member, name, np.pad(signal, pad))
+            padded.append(member)
+        return padded
+
     def _batch_members(self, sources: Sequence[fullwave.Source]) -> list[fullwave.Source]:
         """Check the transmits of a batch against the Solver's source and return them.
 
@@ -1730,7 +1850,10 @@ class Solver:
                 return f"the {kind} signal is present in only one of them"
             if expected is None:
                 continue
-            if np.shape(found) != np.shape(expected):
+            if (
+                np.shape(found)[:-1] != np.shape(expected)[:-1]
+                or np.shape(found)[-1] < np.shape(expected)[-1]
+            ):
                 return f"the {kind} signal shape {np.shape(found)} != {np.shape(expected)}"
             expected_coords = getattr(self.source, coords, None)
             found_coords = getattr(member, coords, None)