Results

PulsedResult dataclass

Bases: Result

A base container for holding the results of a pulsed simulation.

This class should not be instantiated, use PulsedResult2D or PulsedResult3D.

Parameters:

Name	Type	Description	Default
scenario	scenario.Scenario	the scenario from which this result came.	required
center_frequency	float	the center frequency (in hertz) of the sources.	required
effective_dt	float	the effective time step (in seconds) along the time axis of the wavefield. This can differ from the simulation dt if the recording undersampling factor is larger than 1.	required
pde	stride.Operator	the stride Operator that was executed to run the simulation.	required
shot	stride.Shot	the stride Shot which was used for the simulation.	required
wavefield	npt.NDArray[np.float_]	an array containing the resulting simulation data.	required
traces	stride.Traces	the stride Traces object returned from executing the pde.	required

PulsedResult2D

Bases: PulsedResult

A container for holding the results of a 2D pulsed simulation.

Parameters:

Name	Type	Description	Default
scenario	scenarios.Scenario2D	the 2D scenario from which this result came.	required
center_frequency	float	the center frequency (in hertz) of the sources.	required
effective_dt	float	the effective time step (in seconds) along the time axis of the wavefield. This can differ from the simulation dt if the recording downsampling factor is larger than 1.	required
pde	stride.Operator	the stride Operator that was executed to run the simulation.	required
shot	stride.Shot	the stride Shot which was used for the simulation.	required
wavefield	npt.NDArray[np.float_]	a 3 dimensional array (two axes for space and one for time) containing the resulting simulation data.	required
traces	stride.Traces	the stride Traces object returned from executing the pde.	required

create_video_file(file_name, show_sources=True, show_target=True, show_material_outlines=True, n_frames_undersampling=1, time_lim=None, norm='linear', fps=25, dpi=100, bitrate=2500, overwrite=False)

Save a mp4 animation file to disk with the results of the simulation.

Currently only mp4 format supported. ffmpeg command line tools needs to be installed.

Parameters:

Name	Type	Description	Default
file_name	str	the file with path an extension where the animation would be saved. Currently only supports mp4 extension.	required
show_sources	bool	whether or not to show the source transducer layer.	True
show_target	bool	whether or not to show the target layer.	True
show_material_outlines	bool	whether or not to display a thin white outline of the transition between different materials.	True
n_frames_undersampling	int	the number of time steps to be skipped when creating the animation.	1
time_lim	tuple[np.float_, np.float_] | None	the input time limit tuple to validate. The expected format is (minimum_time, maximum_time).	None
norm	str	the normalization method used to scale scalar data to the [0, 1] range before mapping to colors using cmap. For a list of available scales, call matplotlib.scale.get_scale_names().	'linear'
fps	int	the frames per second in the animation.	25
dpi	int	the number of dots per inch in the frames of the animation.	100
bitrate	int	the bitrate for the saved movie file, which is one way to control the output file size and quality.	2500
overwrite	bool	a boolean that allows the animation to be saved with the same file name that is already exists.	False

render_pulsed_simulation_animation(show_sources=True, show_target=True, show_material_outlines=True, n_frames_undersampling=1, time_lim=None, norm='linear')

Create a matplotlib animation with the time evolution of the wavefield.

The created animation will be displayed as an interactive widget in a IPython or Jupyter Notebook environment. In a non-interactive environment (script) the result of this animation would be lost. Use create_video_file method instead.

Parameters:

Name	Type	Description	Default
show_sources	bool	whether or not to show the source transducer layer.	True
show_target	bool	whether or not to show the target layer.	True
show_material_outlines	bool	whether or not to display a thin white outline of the transition between different materials.	True
n_frames_undersampling	int	the number of time steps to be skipped when creating the animation.	1
time_lim	tuple[np.float_, np.float_] | None	the input time limit tuple to validate. The expected format is (minimum_time, maximum_time).	None
norm	str	the normalization method used to scale scalar data to the [0, 1] range before mapping to colors using cmap. For a list of available scales, call matplotlib.scale.get_scale_names().	'linear'

Returns:

Type	Description
FuncAnimation	An matplotlib animation object.

PulsedResult3D

Bases: PulsedResult

A container for holding the results of a 3D pulsed simulation.

Parameters:

Name	Type	Description	Default
scenario	scenarios.Scenario3D	the 3D scenario from which this result came.	required
center_frequency	float	the center frequency (in hertz) of the sources.	required
effective_dt	float	the effective time step (in seconds) along the time axis of the wavefield. This can differ from the simulation dt if the recording downsampling factor is larger than 1.	required
pde	stride.Operator	the stride Operator that was executed to run the simulation.	required
shot	stride.Shot	the stride Shot which was used for the simulation.	required
wavefield	npt.NDArray[np.float_]	a 4 dimensional array (three axes for space and one for time) containing the resulting simulation data.	required
traces	stride.Traces	the stride Traces object returned from executing the pde.	required

create_video_file(file_name, show_sources=True, show_target=True, show_material_outlines=True, n_frames_undersampling=1, slice_axis=None, slice_position=None, time_lim=None, norm='linear', fps=25, dpi=100, bitrate=2500, overwrite=False)

Save a mp4 animation file to disk with the results of the simulation.

Currently only mp4 format supported. ffmpeg command line tools needs to be installed.

Parameters:

Name	Type	Description	Default
file_name	str	the file with path an extension where the animation would be saved. Currently only supports mp4 extension.	required
show_sources	bool	whether or not to show the source transducer layer.	True
show_target	bool	whether or not to show the target layer.	True
show_material_outlines	bool	whether or not to display a thin white outline of the transition between different materials.	True
n_frames_undersampling	int	the number of time steps to be skipped when creating the animation.	1
slice_axis	int | None	the axis along which to slice.	None
slice_position	float | None	the position (in meters) along the slice axis at which the slice should be made.	None
time_lim	tuple[np.float_, np.float_] | None	the input time limit tuple to validate. The expected format is (minimum_time, maximum_time).	None
norm	str	the normalization method used to scale scalar data to the [0, 1] range before mapping to colors using cmap. For a list of available scales, call matplotlib.scale.get_scale_names().	'linear'
fps	int	the frames per second in the animation.	25
dpi	int	the number of dots per inch in the frames of the animation.	100
bitrate	int	the bitrate for the saved movie file, which is one way to control the output file size and quality.	2500
overwrite	bool	a boolean that allows the animation to be saved with the same file name that is already exists.	False

render_pulsed_simulation_animation(show_sources=True, show_target=True, show_material_outlines=True, n_frames_undersampling=1, time_lim=None, norm='linear')

Create a matplotlib animation with the time evolution of the wavefield.

The created animation will be displayed as an interactive widget in a IPython or Jupyter Notebook environment. In a non-interactive environment (script) the result of this animation would be lost. Use create_video_file method instead.

Parameters:

Name	Type	Description	Default
show_sources	bool	whether or not to show the source transducer layer.	True
show_target	bool	whether or not to show the target layer.	True
show_material_outlines	bool	whether or not to display a thin white outline of the transition between different materials.	True
n_frames_undersampling	int	the number of time steps to be skipped when creating the animation.	1
time_lim	tuple[np.float_, np.float_] | None	the input time limit tuple to validate. The expected format is (minimum_time, maximum_time).	None
norm	str	the normalization method used to scale scalar data to the [0, 1] range before mapping to colors using cmap. For a list of available scales, call matplotlib.scale.get_scale_names().	'linear'

Returns:

Type	Description
FuncAnimation	An matplotlib animation object.

Result dataclass

Bases: abc.ABC

A base container for holding the results of a simulation.

This class should not be instantiated, use SteadyStateResult2D, SteadyStateResult3D, PulsedResult2D, or PulsedResult3D.

Parameters:

Name	Type	Description	Default
scenario	scenarios.Scenario	the scenario from which this result came.	required
center_frequency	float	the center frequency (in hertz) of the sources.	required
effective_dt	float	the effective time step (in seconds) along the time axis of the wavefield. This can differ from the simulation dt if the recording undersampling factor is larger than 1.	required
pde	stride.Operator	the stride Operator that was executed to run the simulation.	required
shot	stride.Shot	the stride Shot which was used for the simulation.	required
wavefield	npt.NDArray[np.float_]	an array containing the resulting simulation data.	required
traces	stride.Traces	the stride Traces object returned from executing the pde.	required

save_to_disk(filepath)

Save the result to a tarball containing the data as a gzip compressed file.

The resulting tarball will contain two files:

• data.gz: gzip compressed file which is a pickle object.
• VERSION: a text file containing the neurotechdevkit version.

Warning

This functionality is experimental, so do do not be surprised if you encounter issues calling this function.

This function is particularly useful if simulation is performed in the cloud but the user would like to download the results in order to visualize them locally in 3D.

Parameters:

Name	Type	Description	Default
filepath	str | pathlib.Path	the path to the file where the results should be exported. Usually a .tar.gz file.	required

SteadyStateResult dataclass

Bases: Result

A base container for holding the results of a steady-state simulation.

This class should not be instantiated, use SteadyStateResult2D or SteadyStateResult3D.

Parameters:

Name	Type	Description	Default
scenario	scenario.Scenario	the scenario from which this result came.	required
center_frequency	float	the center frequency (in hertz) of the sources.	required
effective_dt	float	the effective time step (in seconds) along the time axis of the wavefield. This can differ from the simulation dt if the recording undersampling factor is larger than 1.	required
pde	stride.Operator	the stride Operator that was executed to run the simulation.	required
shot	stride.Shot	the stride Shot which was used for the simulation.	required
wavefield	npt.NDArray[np.float_]	an array containing the resulting simulation data.	required
traces	stride.Traces	the stride Traces object returned from executing the pde.	required

metrics: dict[str, dict[str, str | float | int | tuple]] property

A dictionary containing metrics and their descriptions.

The keys for the dictionary are the names of the metrics. The value for each metric is another dictionary containing the following:

• value: the value of the metric.
• unit-of-measurement: the unit of measurement for the metric.
• description: A text description of the metric.

get_steady_state()

Return the steady-state array and while computing it if necessary.

Returns:

Type	Description
npt.NDArray[np.float_]	An array containing steady-state pressure wave amplitudes (in pascals).

SteadyStateResult2D

Bases: SteadyStateResult

A container for holding the results of a 2D steady-state simulation.

Parameters:

Name	Type	Description	Default
scenario	scenarios.Scenario2D	the 2D scenario from which this result came.	required
center_frequency	float	the center frequency (in hertz) of the sources.	required
effective_dt	float	the effective time step (in seconds) along the time axis of the wavefield. This can differ from the simulation dt if the recording downsampling factor is larger than 1.	required
pde	stride.Operator	the stride Operator that was executed to run the simulation.	required
shot	stride.Shot	the stride Shot which was used for the simulation.	required
wavefield	npt.NDArray[np.float_]	a 3 dimensional array (two axes for space and one for time) containing the resulting simulation data.	required
traces	stride.Traces	the stride Traces object returned from executing the pde.	required

render_steady_state_amplitudes(show_sources=True, show_target=True, show_material_outlines=True)

Create a matplotlib figure with the steady-state pressure wave amplitude.

The grid can be turned on via: plt.grid(True)

Parameters:

Name	Type	Description	Default
show_sources	bool	whether or not to show the source transducer layer.	True
show_target	bool	whether or not to show the target layer.	True
show_material_outlines	bool	whether or not to display a thin white outline of the transition between different materials.	True

SteadyStateResult3D

Bases: SteadyStateResult

A container for holding the results of a 3D steady-state simulation.

Parameters:

Name	Type	Description	Default
scenario	scenarios.Scenario3D	the 3D scenario from which this result came.	required
center_frequency	float	the center frequency (in hertz) of the sources.	required
effective_dt	float	the effective time step (in seconds) along the time axis of the wavefield. This can differ from the simulation dt if the recording downsampling factor is larger than 1.	required
pde	stride.Operator	the stride Operator that was executed to run the simulation.	required
shot	stride.Shot	the stride Shot which was used for the simulation.	required
wavefield	npt.NDArray[np.float_]	a 4 dimensional array (three axes for space and one for time) containing the resulting simulation data.	required
traces	stride.Traces	the stride Traces object returned from executing the pde.	required

get_steady_state_result_2d(slice_axis=None, slice_position=None)

Return a 2D steady-state result from a 3D steady-state result.

This function will take a slice of the 3D steady-state result and return a 2D steady-state result of the slice. A slice through the scenario can be specified via slice_axis and slice_position. Eg. to take a slice at z=0.01 m, use slice_axis=2 and slice_position=0.01. If slice_axis and slice_position are not specified, the slice will be taken along the scenario's slice_axis and slice_position.

Warning

When taking a 2D slice of a 3D steady-state result, the sources and target are not being accounted for and will not be preserved in the 2D result.

Parameters:

Name	Type	Description	Default
slice_axis	Optional[SliceAxis]	The axis along which to slice the 3D field to be recorded. If None, then the complete field will be recorded. Use 0 for X axis, 1 for Y axis and 2 for Z axis. Defaults to None.	None
slice_position	Optional[float]	The position (in meters) along the slice axis at which the slice of the 3D field should be made. Position must be within the slice axis range. Eg. for a slice with origin -0.035 and extent 0.07, the valid range is [-0.035, 0.035]. Defaults to None.	None

Returns:

Type	Description
SteadyStateResult2D	A SteadyStateResult2D object containing the 2D slice of the 3D steady-state
SteadyStateResult2D	simulation results.

render_steady_state_amplitudes(show_sources=True, show_target=True, show_material_outlines=True)

Create a matplotlib figure with the steady-state pressure wave amplitude.

In order to visualize the 3D scenario in a 2D plot, a slice through the scenario needs to be specified via slice_axis and slice_position. Eg. to take a slice at z=0.01 m, use slice_axis=2 and slice_position=0.01.

The grid can be turned on via: plt.grid(True)

Parameters:

Name	Type	Description	Default
show_sources	bool	whether or not to show the source transducer layer.	True
show_target	bool	whether or not to show the target layer.	True
show_material_outlines	bool	whether or not to display a thin white outline of the transition between different materials.	True

render_steady_state_amplitudes_3d()

Render the steady-state simulation results in 3D using napari.

This function requires the napari package to be installed.

Warning

Integration with napari is experimental, and do not be surprised if you encounter issues calling this function.

This will open up the napari interactive GUI in a separate window. The GUI contains many different controls for controlling the view of the data as well as the rendering of the layers. Among these, you can drag the scenario to view it from different angles, zoom in our out, and turn layers on or off.

See the napari documentation for more information on the GUI.

create_pulsed_result(scenario, center_frequency, effective_dt, pde, shot, wavefield, traces, recorded_slice=None)

Create results from pulsed simulations.

Creates a PulsedResult2D or PulsedResult3D depending on the number of wavefield spatial dimensions. If the ndim of the wavefield is N, then the wavefield has N-1 spatial dimensions and 1 time dimension.

Parameters:

Name	Type	Description	Default
scenario	Union[scenarios.Scenario2D, scenarios.Scenario3D]	the scenario from which this result came.	required
center_frequency	float	the center frequency (in hertz) of the sources.	required
effective_dt	float	the effective time step (in seconds) along the time axis of the wavefield. This can differ from the simulation dt if the recording downsampling factor is larger than 1.	required
pde	stride.Operator	the stride Operator that was executed to run the simulation.	required
shot	stride.Shot	the stride Shot which was used for the simulation.	required
wavefield	npt.NDArray[np.float_]	an array containing the resulting simulation data.	required
traces	stride.Traces	the stride Traces object returned from executing the pde.	required

Raises:

Type	Description
ValueError	if the ndim of the wavefield is less than 3 or more than 4.

Returns:

Name	Type	Description
Result	Union[PulsedResult2D, PulsedResult3D]	a PulsedResult2D or PulsedResult3D, depending on the wavefield shape.

create_steady_state_result(scenario, center_frequency, effective_dt, pde, shot, wavefield, traces)

Create a steady state result.

Creates a SteadyStateResult2D or SteadyStateResult3D depending on the number of wavefield spatial dimensions. If the ndim of the wavefield is N, then the wavefield has N-1 spatial dimensions and 1 time dimension.

Parameters:

Name	Type	Description	Default
scenario	Union[scenarios.Scenario2D, scenarios.Scenario3D]	the scenario from which this result came.	required
center_frequency	float	the center frequency (in hertz) of the sources.	required
effective_dt	float	the effective time step (in seconds) along the time axis of the wavefield. This can differ from the simulation dt if the recording downsampling factor is larger than 1.	required
pde	stride.Operator	the stride Operator that was executed to run the simulation.	required
shot	stride.Shot	the stride Shot which was used for the simulation.	required
wavefield	npt.NDArray[np.float_]	an array containing the resulting simulation data.	required
traces	stride.Traces	the stride Traces object returned from executing the pde.	required

Raises:

Type	Description
ValueError	if the ndim of the wavefield is less than 3 or more than 4.

Returns:

Name	Type	Description
Result	SteadyStateResult	a SteadyStateResult2D or SteadyStateResult3D, depending on the wavefield shape.

load_result_from_disk(filepath)

Load a result from the tarball file stored on disk.

Warning

This functionality is experimental, so do do not be surprised if you encounter issues calling this function.

Load a file that was saved to disk via Result.save_to_disk.

If the object saved in filepath is the result from a steady-state simulation the results will contain only the steady-state amplitudes. Instead, for pulsed simulations the result object will contain the original wavefield.

This function is particularly useful if simulation is performed in the cloud but the user would like to download the results in order to visualize them locally in 3D.

Parameters:

Name	Type	Description	Default
filepath	str | pathlib.Path	the path to an existing result file previously saved via Result.save_to_disk.	required

Returns:

Type	Description
Result	A Results object (SteadyStateResult or PulsedResult)