Usage

Scalar Class

class deepwave.Scalar(v: Tensor, grid_spacing: float | Sequence[float], v_requires_grad: bool = False)

Convenience nn.Module wrapper for scalar wave propagation.

Stores v and grid_spacing. Gradients do not propagate to the provided wavespeed. Use the module’s v attribute to access the wavespeed.

forward(dt: float, source_amplitudes: Tensor | None = None, source_locations: Tensor | None = None, receiver_locations: Tensor | None = None, accuracy: int = 4, pml_width: int | Sequence[int] = 20, pml_freq: float | None = None, max_vel: float | None = None, survey_pad: int | Sequence[int | None] | None = None, wavefield_0: Tensor | None = None, wavefield_m1: Tensor | None = None, psiy_m1: Tensor | None = None, psix_m1: Tensor | None = None, zetay_m1: Tensor | None = None, zetax_m1: Tensor | None = None, origin: Sequence[int] | None = None, nt: int | None = None, model_gradient_sampling_interval: int = 1, freq_taper_frac: float = 0.0, time_pad_frac: float = 0.0, time_taper: bool = False) → Tuple[Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor]

Performs forward propagation/modelling.

See scalar() for details.

Scalar Function

deepwave.scalar(v: Tensor, grid_spacing: float | Sequence[float], dt: float, source_amplitudes: Tensor | None = None, source_locations: Tensor | None = None, receiver_locations: Tensor | None = None, accuracy: int = 4, pml_width: int | Sequence[int] = 20, pml_freq: float | None = None, max_vel: float | None = None, survey_pad: int | Sequence[int | None] | None = None, wavefield_0: Tensor | None = None, wavefield_m1: Tensor | None = None, psiy_m1: Tensor | None = None, psix_m1: Tensor | None = None, zetay_m1: Tensor | None = None, zetax_m1: Tensor | None = None, origin: Sequence[int] | None = None, nt: int | None = None, model_gradient_sampling_interval: int = 1, freq_taper_frac: float = 0.0, time_pad_frac: float = 0.0, time_taper: bool = False) → Tuple[Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor]

Scalar wave propagation (functional interface).

This function performs forward modelling with the scalar wave equation. The outputs are differentiable with respect to the wavespeed, the source amplitudes, and the initial wavefields.

For computational performance, multiple shots may be propagated simultaneously.

The function returns the final wavefields and the data recorded at the specified receiver locations. All returned torch.Tensors are differentiable with respect to the float torch.Tensors in the input.

Parameters:

  • v – A torch.Tensor containing the wavespeed model.

  • grid_spacing – The spatial grid cell size. It can be a single number that will be used for all dimensions, or a number for each dimension.

  • dt – A float specifying the time step interval of the input and output (internally a smaller interval may be used in propagation to obey the CFL condition for stability).

  • source_amplitudes – A torch.Tensor with dimensions [shot, source, time]. For example, if two shots are propagated simultaneously, each containing three sources of one hundred time samples, the shape would be [2, 3, 100]. The time dimension length determines the number of time steps in the simulation. Optional. If provided, source_locations must also be specified. If not provided, nt must be specified.

  • source_locations – A torch.Tensor with dimensions [shot, source, 2], containing the index in the two spatial dimensions of the cell that each source is located in, relative to the origin of the model. Optional. Must be provided if source_amplitudes is. It should have torch.long (int64) datatype. The location of each source must be unique within the same shot (you cannot have two sources in the same shot that both have location [1, 2], for example). Setting both coordinates to deepwave.IGNORE_LOCATION will result in the source being ignored.

  • receiver_locations – A torch.Tensor with dimensions [shot, receiver, 2], containing the coordinates of the cell containing each receiver. Optional. It should have torch.long (int64) datatype. If not provided, the output receiver_amplitudes torch.Tensor will be empty. If backpropagation will be performed, the location of each receiver must be unique within the same shot. Setting both coordinates to deepwave.IGNORE_LOCATION will result in the receiver being ignored.

  • accuracy – An int specifying the finite difference order of accuracy. Possible values are 2, 4, 6, and 8, with larger numbers resulting in more accurate results but greater computational cost. Optional, with a default of 4.

  • pml_width –

    A single number, or two numbers for each dimension, specifying the width (in number of cells) of the PML that prevents reflections from the edges of the model. If a single value is provided, it will be used for all edges. If a sequence is provided, it should contain values for the edges in the following order:

    • beginning of first dimension

    • end of first dimension

    • beginning of second dimension

    • end of second dimension

    Larger values result in smaller reflections, with values of 10 to 20 being typical. For a reflective or “free” surface, set the value for that edge to be zero. For example, if your model is oriented so that the surface that you want to be reflective is the beginning of the second dimension, then you could specify pml_width=[20, 20, 0, 20]. The wavespeed in the PML region is obtained by replicating the values on the edge of the model. Optional, default 20.

  • pml_freq – A float specifying the frequency that you wish to use when constructing the PML. This is usually the dominant frequency of the source wavelet. Choosing this value poorly will result in the edges becoming more reflective. Optional, default 25 Hz (assuming dt is in seconds).

  • max_vel – A float specifying the maximum velocity, which is used when applying the CFL condition and when constructing the PML. If not specified, the actual maximum absolute wavespeed in the model (or portion of it that is used) will be used. The option to specify this is provided to allow you to ensure consistency between runs even if there are changes in the wavespeed. Optional, default None.

  • survey_pad –

    A single value or list of four values, all of which are either an int or None, specifying whether the simulation domain should be restricted to a region surrounding the sources and receivers. If you have a large model, but the sources and receivers of individual shots only cover a small portion of it (such as in a towed streamer survey), then it may be wasteful to simulate wave propagation over the whole model. This parameter allows you to specify what distance around sources and receivers you would like to extract from the model to use for the simulation. A value of None means that no restriction of the model should be performed in that direction, while an integer value specifies the minimum number of cells that the edge of the simulation domain should be from any source or receiver in that direction (if possible). If a single value is provided, it applies to all directions, so specifying None will use the whole model for every simulation, while specifying 10 will cause the simulation domain to contain at least 10 cells of padding in each direction around sources and receivers if possible. The padding will end if the edge of the model is encountered. Specifying a list, in the following order, allows the padding in each direction to be controlled:

    • beginning of first dimension

    • end of first dimension

    • beginning of second dimension

    • end of second dimension

    Ints and None may be mixed, so a survey_pad of [5, None, None, 10] means that there should be at least 5 cells of padding towards the beginning of the first dimension, no restriction of the simulation domain towards the end of the first dimension or beginning of the second, and 10 cells of padding towards the end of the second dimension. If the simulation contains one source at [20, 15], one receiver at [10, 15], and the model is of shape [40, 50], then the extracted simulation domain with this value of survey_pad would cover the region [5:40, 0:25]. The same simulation domain will be used for all shots propagated simultaneously, so if this option is used then it is advisable to propagate shots that cover similar regions of the model simultaneously so that it provides a benefit (if the shots cover opposite ends of a dimension, then that whole dimension will be used regardless of what survey_pad value is used). Optional, default None. Cannot be specified if origin is also specified.

  • wavefield_0 – A torch.Tensor specifying the initial wavefield at time step 0. It should have three dimensions, with the first dimension being shot and the subsequent two corresponding to the two spatial dimensions. The spatial shape should be equal to the simulation domain, which is the extracted model plus the PML. If two shots are being propagated simultaneously in a region of size [20, 30] extracted from the model for the simulation, and pml_width=[1, 2, 3, 4], then wavefield_0 should be of shape [2, 23, 37]. Optional, default all zeros.

  • wavefield_m1 – A torch.Tensor specifying the initial wavefield at time step -1 (using Deepwave’s internal time step interval, which may be smaller than the user provided one to obey the CFL condition). See the entry for wavefield_0 for more details.

  • psiy_m1 – PML-related wavefield at time step -1.

  • psix_m1 – PML-related wavefield at time step -1.

  • zetay_m1 – PML-related wavefield at time step -1.

  • zetax_m1 – PML-related wavefield at time step -1.

  • origin – A list of ints specifying the origin of the provided initial wavefields relative to the origin of the model. Only relevant if initial wavefields are provided. The origin of a wavefield is the cell where the extracted model used for the simulation domain began. It does not include the PML. So if a simulation is performed using the model region [10:20, 15:30], the origin is [10, 15]. Optional, default [0, 0]. Cannot be specified if survey_pad is also specified.

  • nt – If the source amplitudes are not provided then you must instead specify the number of time steps to run the simulation for by providing an integer for nt. You cannot specify both the source amplitudes and nt.

  • model_gradient_sampling_interval – An int specifying the number of time steps between contributions to the model gradient. The gradient with respect to the model is an integral over the backpropagation time steps. The time sampling frequency of this integral should be at least the Nyquist frequency of the source or data (whichever is greater). If this Nyquist frequency is substantially less than 1/dt, you may wish to reduce the sampling frequency of the integral to reduce computational (especially memory) costs. Optional, default 1 (integral is sampled every time step interval dt).

  • freq_taper_frac – A float specifying the fraction of the end of the source and receiver amplitudes (if present) in the frequency domain to cosine taper if they are resampled due to the CFL condition. This might be useful to reduce ringing. A value of 0.1 means that the top 10% of frequencies will be tapered. Default 0.0 (no tapering).

  • time_pad_frac – A float specifying the amount of zero padding that will be added to the source and receiver amplitudes (if present) before resampling and removed afterwards, if they are resampled due to the CFL condition, as a fraction of their length. This might be useful to reduce wraparound artifacts. A value of 0.1 means that zero padding of 10% of the number of time samples will be used. Default 0.0.

  • time_taper – A bool specifying whether to apply a Hann window in time to source and receiver amplitudes (if present). This is useful during correctness tests of the propagators as it ensures that signals taper to zero at their edges in time, avoiding the possibility of high frequencies being introduced.

Returns:

  • wavefield_nt: The wavefield at the final time step.

  • wavefield_ntm1: The wavefield at the second-to-last time step.

  • psiy_ntm1: PML-related wavefield.

  • psix_ntm1: PML-related wavefield.

  • zetay_ntm1: PML-related wavefield.

  • zetax_ntm1: PML-related wavefield.

  • receiver_amplitudes: The receiver amplitudes. Empty if no receivers were specified.

Return type:

Tuple

ScalarBorn Class

class deepwave.ScalarBorn(v: Tensor, scatter: Tensor, grid_spacing: float | Sequence[float], v_requires_grad: bool = False, scatter_requires_grad: bool = False)

A Module wrapper around scalar_born().

This is a convenience module that allows you to only specify v, scatter, and grid_spacing once. They will then be added to the list of arguments passed to scalar_born() when you call the forward method.

Note that a copy will be made of the provided v and scatter. Gradients will not backpropagate to the initial guess wavespeed and scattering potential that are provided. You can use the module’s v and scatter attributes to access them.

Parameters:

  • v – A torch.Tensor containing an initial guess of the wavespeed.

  • scatter – A torch.Tensor containing an initial guess of the scattering potential.

  • grid_spacing – The spatial grid cell size. It can be a single number that will be used for all dimensions, or a number for each dimension.

  • v_requires_grad – A bool specifying whether the requires_grad attribute of the wavespeed should be set, and thus whether the necessary data should be stored to calculate the gradient with respect to v during backpropagation. Defaults to False.

  • scatter_requires_grad – A bool specifying whether the requires_grad attribute of the scattering potential should be set, and thus whether the necessary data should be stored to calculate the gradient with respect to scatter during backpropagation. Defaults to False.

forward(dt: float, source_amplitudes: Tensor | None = None, source_locations: Tensor | None = None, receiver_locations: Tensor | None = None, bg_receiver_locations: Tensor | None = None, accuracy: int = 4, pml_width: int | Sequence[int] = 20, pml_freq: float | None = None, max_vel: float | None = None, survey_pad: int | Sequence[int | None] | None = None, wavefield_0: Tensor | None = None, wavefield_m1: Tensor | None = None, psiy_m1: Tensor | None = None, psix_m1: Tensor | None = None, zetay_m1: Tensor | None = None, zetax_m1: Tensor | None = None, wavefield_sc_0: Tensor | None = None, wavefield_sc_m1: Tensor | None = None, psiy_sc_m1: Tensor | None = None, psix_sc_m1: Tensor | None = None, zetay_sc_m1: Tensor | None = None, zetax_sc_m1: Tensor | None = None, origin: Sequence[int] | None = None, nt: int | None = None, model_gradient_sampling_interval: int = 1, freq_taper_frac: float = 0.0, time_pad_frac: float = 0.0, time_taper: bool = False) → Tuple[Tensor, ...]

Perform forward propagation/modelling.

The inputs are the same as for scalar_born() except that v, scatter, and grid_spacing do not need to be provided again. See scalar_born() for a description of the inputs and outputs.

ScalarBorn Function

deepwave.scalar_born(v: Tensor, scatter: Tensor, grid_spacing: float | Sequence[float], dt: float, source_amplitudes: Tensor | None = None, source_locations: Tensor | None = None, receiver_locations: Tensor | None = None, bg_receiver_locations: Tensor | None = None, accuracy: int = 4, pml_width: int | Sequence[int] = 20, pml_freq: float | None = None, max_vel: float | None = None, survey_pad: int | Sequence[int | None] | None = None, wavefield_0: Tensor | None = None, wavefield_m1: Tensor | None = None, psiy_m1: Tensor | None = None, psix_m1: Tensor | None = None, zetay_m1: Tensor | None = None, zetax_m1: Tensor | None = None, wavefield_sc_0: Tensor | None = None, wavefield_sc_m1: Tensor | None = None, psiy_sc_m1: Tensor | None = None, psix_sc_m1: Tensor | None = None, zetay_sc_m1: Tensor | None = None, zetax_sc_m1: Tensor | None = None, origin: Sequence[int] | None = None, nt: int | None = None, model_gradient_sampling_interval: int = 1, freq_taper_frac: float = 0.0, time_pad_frac: float = 0.0, time_taper: bool = False) → Tuple[Tensor, ...]

Scalar Born wave propagation (functional interface).

This function performs Born forward modelling with the scalar wave equation. The outputs are differentiable with respect to the wavespeed, the scattering potential, the source amplitudes, and the initial wavefields.

For computational performance, multiple shots may be propagated simultaneously.

Most arguments and returns are the same as those of scalar(), so only those that are different will be described here.

Parameters:

  • v – A torch.Tensor containing the wavespeed.

  • scatter – A torch.Tensor containing the scattering potential.

  • grid_spacing – The spatial grid cell size.

  • dt – The temporal grid cell size.

  • source_amplitudes – A torch.Tensor containing the source amplitudes.

  • source_locations – A torch.Tensor containing the source locations.

  • receiver_locations – A torch.Tensor containing the receiver locations.

  • bg_receiver_locations – A torch.Tensor with dimensions [shot, receiver, 2], containing the coordinates of the cell containing each receiver of the background wavefield. Optional. It should have torch.long (int64) datatype. If not provided, the output bg_receiver_amplitudes torch.Tensor will be empty. If backpropagation will be performed, the location of each background receiver must be unique within the same shot. Setting both coordinates to deepwave.IGNORE_LOCATION will result in the receiver being ignored.

  • accuracy – The spatial accuracy of the finite difference stencil.

  • pml_width – The width of the PML in grid cells.

  • pml_freq – The frequency of the PML.

  • max_vel – The maximum velocity of the model.

  • survey_pad – The padding to apply to the survey area.

  • wavefield_0 – The wavefield at time step 0.

  • wavefield_m1 – The wavefield at time step -1.

  • psiy_m1 – The PML wavefield in the y direction at time step -1.

  • psix_m1 – The PML wavefield in the x direction at time step -1.

  • zetay_m1 – The PML wavefield in the y direction at time step -1.

  • zetax_m1 – The PML wavefield in the x direction at time step -1.

  • wavefield_sc_0 – The scattered wavefield at time step 0.

  • wavefield_sc_m1 – The scattered wavefield at time step -1.

  • psiy_sc_m1 – The scattered PML wavefield in the y direction at time step -1.

  • psix_sc_m1 – The scattered PML wavefield in the x direction at time step -1.

  • zetay_sc_m1 – The scattered PML wavefield in the y direction at time step -1.

  • zetax_sc_m1 – The scattered PML wavefield in the x direction at time step -1.

  • origin – The origin of the grid.

  • nt – The number of time steps.

  • model_gradient_sampling_interval – The sampling interval for the model gradient.

  • freq_taper_frac – The fraction of the frequency to taper.

  • time_pad_frac – The fraction of the time to pad.

  • time_taper – Whether to taper the time.

Returns:

  • wavefield_nt: The non-scattered wavefield at the final time step.

  • wavefield_ntm1: The non-scattered wavefield at the second-to-last time step.

  • psiy_ntm1: The wavefield related to the PML at the second-to-last time step for the non-scattered wavefield.

  • psix_ntm1: The wavefield related to the PML at the second-to-last time step for the non-scattered wavefield.

  • zetay_ntm1: The wavefield related to the PML at the second-to-last time step for the non-scattered wavefield.

  • zetax_ntm1: The wavefield related to the PML at the second-to-last time step for the non-scattered wavefield.

  • wavefield_sc_nt: The scattered wavefield.

  • wavefield_sc_ntm1: The scattered wavefield.

  • psiy_sc_ntm1: The wavefield related to the scattered wavefield PML.

  • psix_sc_ntm1: The wavefield related to the scattered wavefield PML.

  • zetay_sc_ntm1: The wavefield related to the scattered wavefield PML.

  • zetax_sc_ntm1: The wavefield related to the scattered wavefield PML.

  • bg_receiver_amplitudes: The receiver amplitudes recorded at the provided receiver locations, extracted from the background wavefield.

  • receiver_amplitudes: The receiver amplitudes recorded at the provided receiver locations, extracted from the scattered wavefield.

Return type:

Tuple

Elastic Class

class deepwave.Elastic(lamb: Tensor, mu: Tensor, buoyancy: Tensor, grid_spacing: float | Sequence[float], lamb_requires_grad: bool = False, mu_requires_grad: bool = False, buoyancy_requires_grad: bool = False)

A PyTorch Module for elastic wave propagation.

This Module provides a convenient way to perform elastic wave propagation. It stores the Lamé parameters (lamb and mu) and buoyancy (buoyancy) as torch.nn.Parameter objects, allowing gradients to be computed with respect to them if desired.

Parameters:

  • lamb – A torch.Tensor containing the first Lamé parameter.

  • mu – A torch.Tensor containing the second Lamé parameter (mu).

  • buoyancy – A torch.Tensor containing the buoyancy (1/density).

  • grid_spacing – The spatial grid cell size. It can be a single number (for isotropic grids) or a sequence of numbers (for anisotropic grids).

  • lamb_requires_grad – A bool specifying whether gradients should be computed for lamb. Defaults to False.

  • mu_requires_grad – A bool specifying whether gradients should be computed for mu. Defaults to False.

  • buoyancy_requires_grad – A bool specifying whether gradients should be computed for buoyancy. Defaults to False.

forward(dt: float, source_amplitudes_y: Tensor | None = None, source_amplitudes_x: Tensor | None = None, source_locations_y: Tensor | None = None, source_locations_x: Tensor | None = None, receiver_locations_y: Tensor | None = None, receiver_locations_x: Tensor | None = None, receiver_locations_p: Tensor | None = None, accuracy: int = 4, pml_width: int | Sequence[int] = 20, pml_freq: float | None = None, max_vel: float | None = None, survey_pad: int | Sequence[int | None] | None = None, vy_0: Tensor | None = None, vx_0: Tensor | None = None, sigmayy_0: Tensor | None = None, sigmaxy_0: Tensor | None = None, sigmaxx_0: Tensor | None = None, m_vyy_0: Tensor | None = None, m_vyx_0: Tensor | None = None, m_vxy_0: Tensor | None = None, m_vxx_0: Tensor | None = None, m_sigmayyy_0: Tensor | None = None, m_sigmaxyy_0: Tensor | None = None, m_sigmaxyx_0: Tensor | None = None, m_sigmaxxx_0: Tensor | None = None, origin: Sequence[int] | None = None, nt: int | None = None, model_gradient_sampling_interval: int = 1, freq_taper_frac: float = 0.0, time_pad_frac: float = 0.0, time_taper: bool = False) → Tuple[Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor]

Perform forward propagation/modelling.

The inputs are the same as for elastic() except that lamb, mu, buoyancy, and grid_spacing do not need to be provided again. See elastic() for a description of the inputs and outputs.

Elastic Function

deepwave.elastic(lamb: Tensor, mu: Tensor, buoyancy: Tensor, grid_spacing: float | Sequence[float], dt: float, source_amplitudes_y: Tensor | None = None, source_amplitudes_x: Tensor | None = None, source_locations_y: Tensor | None = None, source_locations_x: Tensor | None = None, receiver_locations_y: Tensor | None = None, receiver_locations_x: Tensor | None = None, receiver_locations_p: Tensor | None = None, accuracy: int = 4, pml_width: int | Sequence[int] = 20, pml_freq: float | None = None, max_vel: float | None = None, survey_pad: int | Sequence[int | None] | None = None, vy_0: Tensor | None = None, vx_0: Tensor | None = None, sigmayy_0: Tensor | None = None, sigmaxy_0: Tensor | None = None, sigmaxx_0: Tensor | None = None, m_vyy_0: Tensor | None = None, m_vyx_0: Tensor | None = None, m_vxy_0: Tensor | None = None, m_vxx_0: Tensor | None = None, m_sigmayyy_0: Tensor | None = None, m_sigmaxyy_0: Tensor | None = None, m_sigmaxyx_0: Tensor | None = None, m_sigmaxxx_0: Tensor | None = None, origin: Sequence[int] | None = None, nt: int | None = None, model_gradient_sampling_interval: int = 1, freq_taper_frac: float = 0.0, time_pad_frac: float = 0.0, time_taper: bool = False) → Tuple[Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor]

Elastic wave propagation (functional interface).

This function performs forward modelling with the elastic wave equation. The outputs are differentiable with respect to the input float torch.Tensors.

For computational performance, multiple shots may be propagated simultaneously.

This propagator uses a staggered grid. See the documentation for a description of the grid layout.

Parameters:

  • lamb – The first Lamé parameter model, lambda.

  • mu – The second Lamé parameter model.

  • buoyancy – The buoyancy (1/density) model.

  • grid_spacing – The spatial grid cell size. It can be a single number that will be used for all dimensions, or a number for each dimension.

  • dt – The time step interval of the input and output (internally a smaller interval may be used in propagation to obey the CFL condition for stability).

  • source_amplitudes_y – A Tensor with dimensions [shot, source, time] containing time samples of the source wavelets for sources oriented in the first spatial dimension.

  • source_amplitudes_x – A Tensor containing source wavelet time samples for sources oriented in the second spatial dimension.

  • source_locations_y – A Tensor with dimensions [shot, source, 2], containing the index in the two spatial dimensions of the cell that each source oriented in the first spatial dimension is located in, relative to the origin of the model. Setting both coordinates to deepwave.IGNORE_LOCATION will result in the source being ignored.

  • source_locations_x – A Tensor containing the locations of sources oriented in the second spatial dimension.

  • receiver_locations_y – A Tensor with dimensions [shot, receiver, 2], containing the coordinates of the cell containing each receiver oriented in the first spatial dimension. Setting both coordinates to deepwave.IGNORE_LOCATION will result in the receiver being ignored.

  • receiver_locations_x – A Tensor containing the coordinates of the receivers oriented in the second spatial dimension.

  • receiver_locations_p – A Tensor containing the coordinates of the pressure receivers.

  • accuracy – The finite difference order of accuracy. Possible values are 2 and 4. Default 4.

  • pml_width –

    A single number, or a sequence of numbers for each side, specifying the width (in number of cells) of the PML that prevents reflections from the edges of the model. If a single value is provided, it will be used for all edges. If a sequence is provided, it should contain values for the edges in the following order:

    • beginning of first dimension

    • end of first dimension

    • beginning of second dimension

    • end of second dimension

    Larger values result in smaller reflections, with values of 10 to 20 being typical. For a reflective or “free” surface, set the value for that edge to be zero. The wavespeed in the PML region is obtained by replicating the values on the edge of the model. Optional, default 20.

  • pml_freq – The frequency to use when constructing the PML. This is usually the dominant frequency of the source wavelet. Optional, default 25 Hz (if dt is in seconds).

  • max_vel – The maximum velocity, used for the CFL condition and PML. If not specified, the actual maximum P-wave and S-wave velocities in the model will be used. Optional, default None.

  • survey_pad – Padding to apply around sources and receivers to restrict the simulation domain. See the documentation for the scalar propagator for a full description.

  • vy_0 – Initial vy (velocity in the first dimension) wavefield at time step -1/2.

  • vx_0 – Initial vx (velocity in the second dimension) wavefield.

  • sigmayy_0 – Initial value for the yy component of the stress field at time step 0.

  • sigmaxy_0 – Initial value for the xy component of the stress field at time step 0.

  • sigmaxx_0 – Initial value for the xx component of the stress field at time step 0.

  • m_vyy_0 – Initial value for the “memory variable” for the yy component of the velocity, used in the PML.

  • m_vyx_0 – Initial value for the “memory variable” for the yx component of the velocity, used in the PML.

  • m_vxy_0 – Initial value for the “memory variable” for the xy component of the velocity, used in the PML.

  • m_vxx_0 – Initial value for the “memory variable” for the xx component of the velocity, used in the PML.

  • m_sigmayyy_0 – Initial value for the “memory variable” for the yyy component of the stress, used in the PML.

  • m_sigmaxyy_0 – Initial value for the “memory variable” for the xyy component of the stress, used in the PML.

  • m_sigmaxyx_0 – Initial value for the “memory variable” for the xyx component of the stress, used in the PML.

  • m_sigmaxxx_0 – Initial value for the “memory variable” for the xxx component of the stress, used in the PML.

  • origin – The origin of the provided initial wavefields relative to the origin of the model.

  • nt – If the source amplitudes are not provided then you must instead specify the number of time steps to run the simulation for.

  • model_gradient_sampling_interval – The number of time steps between contributions to the model gradient.

  • freq_taper_frac – The fraction of the end of the source and receiver amplitudes in the frequency domain to cosine taper if they are resampled due to the CFL condition.

  • time_pad_frac – The amount of zero padding that will be added to the source and receiver amplitudes before resampling and removed afterwards, if they are resampled due to the CFL condition, as a fraction of their length.

  • time_taper – Whether to apply a Hann window in time to source and receiver amplitudes.

Returns:

  • vy: Final velocity wavefield in the y-dimension.

  • vx: Final velocity wavefield in the x-dimension.

  • sigmayy: Final stress wavefield (yy component).

  • sigmaxy: Final stress wavefield (xy component).

  • sigmaxx: Final stress wavefield (xx component).

  • m_vyy: Final velocity memory variable for the PML.

  • m_vyx: Final velocity memory variable for the PML.

  • m_vxy: Final velocity memory variable for the PML.

  • m_vxx: Final velocity memory variable for the PML.

  • m_sigmayyy: Final stress memory variable for the PML.

  • m_sigmaxyy: Final stress memory variable for the PML.

  • m_sigmaxyx: Final stress memory variable for the PML.

  • m_sigmaxxx: Final stress memory variable for the PML.

  • receiver_amplitudes_p: Recorded pressure receiver amplitudes.

  • receiver_amplitudes_y: Recorded y-component receiver amplitudes.

  • receiver_amplitudes_x: Recorded x-component receiver amplitudes.

Return type:

Tuple

cosine_taper_end Function

deepwave.common.cosine_taper_end(signal: Tensor, n_taper: int) → Tensor

Tapers the end of the final dimension of a torch.Tensor using a cosine.

A half period, shifted and scaled to taper from 1 to 0, is used.

Parameters:

  • signal – The torch.Tensor that will have its final dimension tapered.

  • n_taper – The length of the cosine taper, in number of samples.

Returns:

The tapered signal.

upsample Function

deepwave.common.upsample(signal: Tensor, step_ratio: int, freq_taper_frac: float = 0.0, time_pad_frac: float = 0.0, time_taper: bool = False) → Tensor

Upsamples the final dimension of a torch.Tensor by a factor.

Low-pass upsampling is used to produce an upsampled signal without introducing higher frequencies than were present in the input. The Nyquist frequency of the input will be zeroed.

Parameters:

  • signal – The torch.Tensor that will have its final dimension upsampled.

  • step_ratio – The integer factor by which the signal will be upsampled. The input signal is returned if this is 1 (freq_taper_frac, time_pad_frac, and time_taper will be ignored).

  • freq_taper_frac – A float specifying the fraction of the end of the signal amplitude in the frequency domain to cosine taper. This might be useful to reduce ringing. A value of 0.1 means that the top 10% of frequencies will be tapered before upsampling. Defaults to 0.0 (no tapering).

  • time_pad_frac – A float specifying the amount of zero padding that will be added to the signal before upsampling and removed afterwards, as a fraction of the length of the final dimension of the input signal. This might be useful to reduce wraparound artifacts. A value of 0.1 means that zero padding of 10% of the length of the signal will be used. Defaults to 0.0.

  • time_taper – A bool specifying whether to apply a Hann window in time. This is useful during correctness tests of the propagators as it ensures that signals taper to zero at their edges in time, avoiding the possibility of high frequencies being introduced.

Returns:

The signal after upsampling.

downsample Function

deepwave.common.downsample(signal: Tensor, step_ratio: int, freq_taper_frac: float = 0.0, time_pad_frac: float = 0.0, time_taper: bool = False, shift: float = 0.0) → Tensor

Downsamples the final dimension of a torch.Tensor by a factor.

Frequencies higher than or equal to the Nyquist frequency of the downsampled signal will be zeroed before downsampling.

Parameters:

  • signal – The torch.Tensor that will have its final dimension downsampled.

  • step_ratio – The integer factor by which the signal will be downsampled. The input signal is returned if this is 1 and shift is 0 (freq_taper_frac, time_pad_frac, and time_taper will be ignored).

  • freq_taper_frac – A float specifying the fraction of the end of the signal amplitude in the frequency domain to cosine taper. This might be useful to reduce ringing. A value of 0.1 means that the top 10% of frequencies will be tapered after downsampling. Defaults to 0.0 (no tapering).

  • time_pad_frac – A float specifying the amount of zero padding that will be added to the signal before downsampling and removed afterwards, as a fraction of the length of the final dimension of the output signal. This might be useful to reduce wraparound artifacts. A value of 0.1 means that zero padding of 10% of the length of the output signal will be used. Defaults to 0.0.

  • time_taper – A bool specifying whether to apply a Hann window in time. This is useful during correctness tests of the propagators as it ensures that signals taper to zero at their edges in time, avoiding the possibility of high frequencies being introduced.

  • shift – Amount (in units of time samples) to shift the data in time before downsampling. Defaults to 0.0.

Returns:

The signal after downsampling.

cfl_condition Function

deepwave.common.cfl_condition(dy: float, dx: float, *args: Any, **kwargs: Any) → Tuple[float, int]

Calculates the time step interval for 2D models.

This is a convenience wrapper around cfl_condition_n for 2D models.

Parameters:

  • dy – The grid spacing in the y-dimension.

  • dx – The grid spacing in the x-dimension.

  • *args – Additional positional arguments to pass to cfl_condition_n.

  • **kwargs – Additional keyword arguments to pass to cfl_condition_n.

Returns:

  • inner_dt: A time step interval that obeys the CFL condition.

  • step_ratio: The integer dt / inner_dt.

Return type:

Tuple

vpvsrho_to_lambmubuoyancy Function

deepwave.common.vpvsrho_to_lambmubuoyancy(vp: Tensor, vs: Tensor, rho: Tensor, eps: float = 1e-15) → Tuple[Tensor, Tensor, Tensor]

Converts vp, vs, rho to lambda, mu, buoyancy.

All input Tensors must have the same shape.

Parameters:

  • vp – A torch.Tensor containing the p wavespeed.

  • vs – A torch.Tensor containing the s wavespeed.

  • rho – A torch.Tensor containing the density.

  • eps – An optional float to avoid division by zero. Default 1e-15.

Returns:

  • lambda: A torch.Tensor containing the first Lamé parameter.

  • mu: A torch.Tensor containing the second Lamé parameter.

  • buoyancy: A torch.Tensor containing the reciprocal of density.

Return type:

Tuple

lambmubuoyancy_to_vpvsrho Function

deepwave.common.lambmubuoyancy_to_vpvsrho(lamb: Tensor, mu: Tensor, buoyancy: Tensor, eps: float = 1e-15) → Tuple[Tensor, Tensor, Tensor]

Converts lambda, mu, buoyancy to vp, vs, rho.

All input Tensors must have the same shape.

Parameters:

  • lamb – A torch.Tensor containing the first Lamé parameter.

  • mu – A torch.Tensor containing the second Lamé parameter.

  • buoyancy – A torch.Tensor containing the reciprocal of density.

  • eps – An optional float to avoid division by zero. Default 1e-15.

Returns:

  • vp: A torch.Tensor containing the p wavespeed.

  • vs: A torch.Tensor containing the s wavespeed.

  • rho: A torch.Tensor containing the density.

Return type:

Tuple

Hicks Class

class deepwave.location_interpolation.Hicks(locations: Tensor, halfwidth: int = 4, free_surfaces: List[bool] | None = None, free_surface_locs: List[float] | None = None, model_shape: List[int] | None = None, monopole: Tensor | bool = True, dipole_dim: Tensor | int = 0, dtype: dtype = torch.float32, eps: float = 1e-05)

Location interpolation onto grid using method of Hicks.

Hicks (2002, https://doi.org/10.1190/1.1451454) proposed using a Kaiser windowed sinc function to interpolate source and receiver locations onto a grid when they are not centred on a grid point. This class implements this approach. It can also be used to create dipole sources and receivers.

Parameters:

  • locations – A three dimensional torch.Tensor [shot, per_shot, 2] specifying the locations to interpolate, provided as float values in units of cells relative to the origin of the grid, so [[[0.5, 0.5]]] corresponds to the point half a cell from the origin in both dimensions.

  • halfwidth – An integer specifying the halfwidth of the window that will be used to interpolate each point onto the grid. A halfwidth of 4 (the default) means that an 8x8 window will be used. Possible values are in [1, 10].

  • free_surfaces – A list of four booleans specifying whether the corresponding edge of the grid is a free surface, in the order: [beginning of first dimension, end of first dimension, beginning of second dimension, end of second dimension]. For example, [True, False, False, True] means that the beginning of the first dimension and end of the second dimension are free surfaces, while the other two edges are not. Defaults to no edges being free surfaces.

  • model_shape – A list of two integers specifying the size of the grid. This is only used when the model contains free surfaces.

  • monopole – A boolean or torch.Tensor of booleans (of shape [shot, per_shot]) specifying whether the source/receiver is a monopole. If False, the point will be a dipole. Default True.

  • dipole_dim – An integer or torch.Tensor of integers (of shape [shot, per_shot]) of value 0 or 1 specifying the dimension in which the dipole is oriented. This is only used for points that are dipoles (not monopoles). Default 0.

  • dtype – The datatype to use. Default torch.float.

  • eps – A small value to prevent division by zero. Points closer to a grid cell centre than this will be rounded to the grid cell. Default 1e-5.

get_locations(shot_idxs: Tensor | None = None) → Tensor

Get the interpolated locations.

The interpolated locations can be provided to a Deepwave propagator as the source or receiver locations.

Parameters:

shot_idxs – A 1D torch.Tensor containing the indices of the shots that amplitudes are being provided for, within the locations provided at initialisation. This is useful if shots are being used in batches, so only some of the shots are needed now. Default (None) means all shots.

Returns:

A torch.Tensor containing the interpolated locations.

receiver(amplitudes: Tensor, shot_idxs: Tensor | None = None) → Tensor

Convert receiver amplitudes from interpolated to original locations.

Parameters:

  • amplitudes – A torch.Tensor containing the amplitudes recorded at interpolated receiver locations.

  • shot_idxs – A 1D torch.Tensor containing the indices of the shots that amplitudes are being provided for, within the locations provided at initialisation. This is useful if shots are being used in batches, so only some of the shots are needed now. Default (None) means all shots.

Returns:

The amplitudes of receivers at the original locations.

source(amplitudes: Tensor, shot_idxs: Tensor | None = None) → Tensor

Calculate the amplitudes of the interpolated sources.

Parameters:

  • amplitudes – A torch.Tensor containing the amplitudes of the sources at the original locations.

  • shot_idxs – A 1D torch.Tensor containing the indices of the shots that amplitudes are being provided for, within the locations provided at initialisation. This is useful if shots are being used in batches, so only some of the shots are needed now. Default (None) means all shots.

Returns:

The amplitudes of the interpolated sources, ready to be provided to a Deepwave propagator.

ricker Function

deepwave.wavelets.ricker(freq: float, length: int, dt: float, peak_time: float, dtype: dtype | None = None) → Tensor

Return a Ricker wavelet with the specified central frequency.

Parameters:

  • freq – The central frequency.

  • length – The number of time samples.

  • dt – The time sample spacing.

  • peak_time – The time (in secs) of the peak amplitude.

  • dtype – The PyTorch datatype to use. Optional, defaults to PyTorch’s default (float32).

Returns:

A PyTorch tensor representing the Ricker wavelet.