Usage¶

`Scalar`¶

class deepwave.Scalar(v: Tensor, grid_spacing: Union[int, float, List[float], Tensor], v_requires_grad: bool = False)¶

A Module wrapper around scalar().

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

Note that a copy will be made of the provided wavespeed. Gradients will not backpropagate to the initial guess wavespeed that is provided. You can use the module’s v attribute to access the wavespeed.

Parameters:

v – A 2D Tensor containing an initial guess of the wavespeed.
grid_spacing – The spatial grid cell size, specified with a single real number (used for both dimensions) or a List or Tensor of length two (the length in each of the two dimensions).
v_requires_grad – Optional bool specifying how to set the requires_grad attribute of the wavespeed, and so whether the necessary data should be stored to calculate the gradient with respect to v during backpropagation. Default False.

forward(dt: float, source_amplitudes: Optional[Tensor] = None, source_locations: Optional[Tensor] = None, receiver_locations: Optional[Tensor] = None, accuracy: int = 4, pml_width: Union[int, List[int]] = 20, pml_freq: Optional[float] = None, max_vel: Optional[float] = None, survey_pad: Optional[Union[int, List[Optional[int]]]] = None, wavefield_0: Optional[Tensor] = None, wavefield_m1: Optional[Tensor] = None, psiy_m1: Optional[Tensor] = None, psix_m1: Optional[Tensor] = None, zetay_m1: Optional[Tensor] = None, zetax_m1: Optional[Tensor] = None, origin: Optional[List[int]] = None, nt: Optional[int] = None, model_gradient_sampling_interval: int = 1) → Tuple[Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor]¶

Perform forward propagation/modelling.

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

`scalar`¶

deepwave.scalar(v: Tensor, grid_spacing: Union[int, float, List[float], Tensor], dt: float, source_amplitudes: Optional[Tensor] = None, source_locations: Optional[Tensor] = None, receiver_locations: Optional[Tensor] = None, accuracy: int = 4, pml_width: Union[int, List[int]] = 20, pml_freq: Optional[float] = None, max_vel: Optional[float] = None, survey_pad: Optional[Union[int, List[Optional[int]]]] = None, wavefield_0: Optional[Tensor] = None, wavefield_m1: Optional[Tensor] = None, psiy_m1: Optional[Tensor] = None, psix_m1: Optional[Tensor] = None, zetay_m1: Optional[Tensor] = None, zetax_m1: Optional[Tensor] = None, origin: Optional[List[int]] = None, nt: Optional[int] = 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.

Parameters:

v – A 2D Tensor containing the wavespeed model. Unlike the module interface (Scalar), in this functional interface a copy is not made of the model, so gradients will propagate back into the provided Tensor.
grid_spacing – The spatial grid cell size, specified with a single real number (used for both dimensions) or a List or Tensor of length two (the length in each of the two dimensions).
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 Tensor with dimensions [shot, source, time]. If two shots are being propagated simultaneously, each containing three sources of one hundred time samples, it would have shape [2, 3, 100]. The time length will be 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 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).
receiver_locations – A 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 Tensor will be empty. If backpropagation will be performed, the location of each receiver must be unique within the same shot.
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 – An int or list of four ints specifying the width (in number of cells) of the PML that prevents reflections from the edges of the model. If a single integer is provided, that value will be used for all edges. If a list is provided, it should contain the integer values for the edges in the following order: [the beginning of the first dimension, the end of the first dimension, the beginning of the second dimension, the end of the 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: [towards the beginning of the first dimension, towards the end of the first dimension, towards the beginning of the second dimension, towards the end of the second dimension] allows the padding in each direction to be controlled. 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 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 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 – Tensor specifying the initial value for this PML-related wavefield at time step -1. See the entry for wavefield_0 for more details.
psix_m1 – Tensor specifying the initial value for this PML-related wavefield at time step -1. See the entry for wavefield_0 for more details.
zetay_m1 – Tensor specifying the initial value for this PML-related wavefield at time step -1. See the entry for wavefield_0 for more details.
zetax_m1 – Tensor specifying the initial value for this PML-related wavefield at time step -1. See the entry for wavefield_0 for more details.
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:: A Tensor containing the wavefield at the final time step.
wavefield_ntm1:: A Tensor containing the wavefield at the second-to-last time step (using Deepwave’s internal time interval, which may be smaller than the user provided one to obey the CFL condition).
psiy_ntm1, psix_ntm1, zetay_ntm1, zetax_ntm1:: Tensor containing the wavefield related to the PML at the second-to-last time step.
receiver_amplitudes:: A Tensor of dimensions [shot, receiver, time] containing the receiver amplitudes recorded at the provided receiver locations. If no receiver locations were specified then this Tensor will be empty.

Return type:

Tuple[Tensor]

`ScalarBorn`¶

class deepwave.ScalarBorn(v: Tensor, scatter: Tensor, grid_spacing: Union[int, float, List[float], Tensor], 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 2D Tensor containing an initial guess of the wavespeed.
scatter – A 2D Tensor containing an initial guess of the scattering potential.
grid_spacing – The spatial grid cell size, specified with a single real number (used for both dimensions) or a List or Tensor of length two (the length in each of the two dimensions).
v_requires_grad – Optional bool specifying how to set the requires_grad attribute of the wavespeed, and so whether the necessary data should be stored to calculate the gradient with respect to v during backpropagation. Default False.
scatter_requires_grad – Similar, for the scattering potential.

forward(dt: float, source_amplitudes: Optional[Tensor] = None, source_locations: Optional[Tensor] = None, receiver_locations: Optional[Tensor] = None, bg_receiver_locations: Optional[Tensor] = None, accuracy: int = 4, pml_width: Union[int, List[int]] = 20, pml_freq: Optional[float] = None, max_vel: Optional[float] = None, survey_pad: Optional[Union[int, List[Optional[int]]]] = None, wavefield_0: Optional[Tensor] = None, wavefield_m1: Optional[Tensor] = None, psiy_m1: Optional[Tensor] = None, psix_m1: Optional[Tensor] = None, zetay_m1: Optional[Tensor] = None, zetax_m1: Optional[Tensor] = None, wavefield_sc_0: Optional[Tensor] = None, wavefield_sc_m1: Optional[Tensor] = None, psiy_sc_m1: Optional[Tensor] = None, psix_sc_m1: Optional[Tensor] = None, zetay_sc_m1: Optional[Tensor] = None, zetax_sc_m1: Optional[Tensor] = None, origin: Optional[List[int]] = None, nt: Optional[int] = None, model_gradient_sampling_interval: int = 1) → Tuple[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 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.

`scalar_born`¶

deepwave.scalar_born(v: Tensor, scatter: Tensor, grid_spacing: Union[int, float, List[float], Tensor], dt: float, source_amplitudes: Optional[Tensor] = None, source_locations: Optional[Tensor] = None, receiver_locations: Optional[Tensor] = None, bg_receiver_locations: Optional[Tensor] = None, accuracy: int = 4, pml_width: Union[int, List[int]] = 20, pml_freq: Optional[float] = None, max_vel: Optional[float] = None, survey_pad: Optional[Union[int, List[Optional[int]]]] = None, wavefield_0: Optional[Tensor] = None, wavefield_m1: Optional[Tensor] = None, psiy_m1: Optional[Tensor] = None, psix_m1: Optional[Tensor] = None, zetay_m1: Optional[Tensor] = None, zetax_m1: Optional[Tensor] = None, wavefield_sc_0: Optional[Tensor] = None, wavefield_sc_m1: Optional[Tensor] = None, psiy_sc_m1: Optional[Tensor] = None, psix_sc_m1: Optional[Tensor] = None, zetay_sc_m1: Optional[Tensor] = None, zetax_sc_m1: Optional[Tensor] = None, origin: Optional[List[int]] = None, nt: Optional[int] = 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]¶

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:

scatter – A 2D Tensor containing an initial guess of the scattering potential. Unlike the module interface (ScalarBorn), in this functional interface a copy is not made of the model, so gradients will propagate back into the provided Tensor.
bg_receiver_locations – A 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 Tensor will be empty. If backpropagation will be performed, the location of each background receiver must be unique within the same shot.
wavefield_sc_0 – The equivalent of wavefield_0, etc., for the scattered wavefield.
wavefield_sc_m1 – The equivalent of wavefield_0, etc., for the scattered wavefield.
psiy_sc_m1 – The equivalent of psiy_m1, etc., for the scattered wavefield.
psix_sc_m1 – The equivalent of psiy_m1, etc., for the scattered wavefield.
zetay_sc_m1 – The equivalent of psiy_m1, etc., for the scattered wavefield.
zetax_sc_m1 – The equivalent of psiy_m1, etc., for the scattered wavefield.

Returns:

wavefield_nt:: A Tensor containing the non-scattered wavefield at the final time step.
wavefield_ntm1:: A Tensor containing the non-scattered wavefield at the second-to-last time step.
psiy_ntm1, psix_ntm1, zetay_ntm1, zetax_ntm1:: Tensor containing the wavefield related to the PML at the second-to-last time step for the non-scattered wavefield.
wavefield_sc_nt, wavefield_sc_ntm1:: Tensor containing the scattered wavefield.
psiy_sc_ntm1, psix_sc_ntm1, zetay_sc_ntm1, zetax_sc_ntm1:: Tensor containing the wavefield related to the scattered wavefield PML.
bg_receiver_amplitudes:: A Tensor of dimensions [shot, receiver, time] containing the receiver amplitudes recorded at the provided receiver locations, extracted from the background wavefield. If no receiver locations were specified then this Tensor will be empty.
receiver_amplitudes:: A Tensor of dimensions [shot, receiver, time] containing the receiver amplitudes recorded at the provided receiver locations, extracted from the scattered wavefield. If no receiver locations were specified then this Tensor will be empty.

Return type:

Tuple[Tensor]

`Elastic`¶

class deepwave.Elastic(lamb: Tensor, mu: Tensor, buoyancy: Tensor, grid_spacing: Union[int, float, List[float], Tensor], lamb_requires_grad: bool = False, mu_requires_grad: bool = False, buoyancy_requires_grad: bool = False)¶

A Module wrapper around elastic().

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

Note that a copy will be made of the provided models. Gradients will not backpropagate to the initial guess models that are provided. You can use the module’s lamb, mu, and buoyancy attributes to access the models.

Parameters:

lamb – A 2D Tensor containing an initial guess of the first Lamé parameter (lambda).
mu – A 2D Tensor containing an initial guess of the second Lamé parameter.
buoyancy – A 2D Tensor containing an initial guess of the buoyancy (1/density).
grid_spacing – The spatial grid cell size, specified with a single real number (used for both dimensions) or a List or Tensor of length two (the length in each of the two dimensions).
lamb_requires_grad – Optional bool specifying how to set the requires_grad attribute of lamb, and so whether the necessary data should be stored to calculate the gradient with respect to lamb during backpropagation. Default False.
mu_requires_grad – Same as lamb_requires_grad, but for mu.
buoyancy_requires_grad – Same as lamb_requires_grad, but for buoyancy.

forward(dt: float, source_amplitudes_y: Optional[Tensor] = None, source_amplitudes_x: Optional[Tensor] = None, source_locations_y: Optional[Tensor] = None, source_locations_x: Optional[Tensor] = None, receiver_locations_y: Optional[Tensor] = None, receiver_locations_x: Optional[Tensor] = None, receiver_locations_p: Optional[Tensor] = None, accuracy: int = 4, pml_width: Union[int, List[int]] = 20, pml_freq: Optional[float] = None, max_vel: Optional[float] = None, survey_pad: Optional[Union[int, List[Optional[int]]]] = None, vy_0: Optional[Tensor] = None, vx_0: Optional[Tensor] = None, sigmayy_0: Optional[Tensor] = None, sigmaxy_0: Optional[Tensor] = None, sigmaxx_0: Optional[Tensor] = None, m_vyy_0: Optional[Tensor] = None, m_vyx_0: Optional[Tensor] = None, m_vxy_0: Optional[Tensor] = None, m_vxx_0: Optional[Tensor] = None, m_sigmayyy_0: Optional[Tensor] = None, m_sigmaxyy_0: Optional[Tensor] = None, m_sigmaxyx_0: Optional[Tensor] = None, m_sigmaxxx_0: Optional[Tensor] = None, origin: Optional[List[int]] = None, nt: Optional[int] = None, model_gradient_sampling_interval: int = 1) → 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`¶

deepwave.elastic(lamb: Tensor, mu: Tensor, buoyancy: Tensor, grid_spacing: Union[int, float, List[float], Tensor], dt: float, source_amplitudes_y: Optional[Tensor] = None, source_amplitudes_x: Optional[Tensor] = None, source_locations_y: Optional[Tensor] = None, source_locations_x: Optional[Tensor] = None, receiver_locations_y: Optional[Tensor] = None, receiver_locations_x: Optional[Tensor] = None, receiver_locations_p: Optional[Tensor] = None, accuracy: int = 4, pml_width: Union[int, List[int]] = 20, pml_freq: Optional[float] = None, max_vel: Optional[float] = None, survey_pad: Optional[Union[int, List[Optional[int]]]] = None, vy_0: Optional[Tensor] = None, vx_0: Optional[Tensor] = None, sigmayy_0: Optional[Tensor] = None, sigmaxy_0: Optional[Tensor] = None, sigmaxx_0: Optional[Tensor] = None, m_vyy_0: Optional[Tensor] = None, m_vyx_0: Optional[Tensor] = None, m_vxy_0: Optional[Tensor] = None, m_vxx_0: Optional[Tensor] = None, m_sigmayyy_0: Optional[Tensor] = None, m_sigmaxyy_0: Optional[Tensor] = None, m_sigmaxyx_0: Optional[Tensor] = None, m_sigmaxxx_0: Optional[Tensor] = None, origin: Optional[List[int]] = None, nt: Optional[int] = 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 Tensors.

For computational performance, multiple shots may be propagated simultaneously.

This propagator uses a staggered grid. See https://ausargeo.com/deepwave/elastic for a description.

Parameters:

lamb – A 2D Tensor containing the first Lamé parameter model, lambda. Unlike the module interface (Elastic), in this functional interface a copy is not made of the model, so gradients will propagate back into the provided Tensor.
mu – A 2D Tensor containing the second Lamé parameter model.
buoyancy – A 2D Tensor containing the buoyancy (1/density) model.
grid_spacing – The spatial grid cell size, specified with a single real number (used for both dimensions) or a List or Tensor of length two (the length in each of the two dimensions).
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_y – A Tensor with dimensions [shot, source, time] containing time samples of the source wavelets for sources oriented in the first spatial dimension. If two shots are being propagated simultaneously, each containing three sources, oriented in the first spatial dimension, of one hundred time samples, it would have shape [2, 3, 100]. The time length will be the number of time steps in the simulation. Optional. If provided, source_locations_y must also be specified. If not provided (and source_amplitudes_x is also not specified), nt must be specified.
source_amplitudes_x – A Tensor containing source wavelet time samples for sources oriented in the second spatial dimension. If source_amplitudes_y is also specified, both must have the same length in the shot and time dimensions.
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. Optional. Must be provided if source_amplitudes_y is. It should have torch.long (int64) datatype. The location of each source oriented in the same dimension must be unique within the same shot (you cannot have two sources oriented in the first dimension in the same shot that both have location [1, 2], for example).
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. Optional. It should have torch.long (int64) datatype. If not provided, the output receiver_amplitudes_y Tensor will be empty. If backpropagation will be performed, the location of each receiver with the same orientation must be unique within the same shot.
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 – An int specifying the finite difference order of accuracy. Possible values are 2 and 4, with larger numbers resulting in more accurate results but greater computational cost. Optional, with a default of 4.
pml_width – An int or list of four ints specifying the width (in number of cells) of the PML that prevents reflections from the edges of the model. If a single integer is provided, that value will be used for all edges. If a list is provided, it should contain the integer values for the edges in the following order: [the beginning of the first dimension, the end of the first dimension, the beginning of the second dimension, the end of the 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 model values in the PML region are 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: [towards the beginning of the first dimension, towards the end of the first dimension, towards the beginning of the second dimension, towards the end of the second dimension] allows the padding in each direction to be controlled. 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). This option is disregarded if any initial wavefields are provided, as those will instead be used to determine the simulation domain. Optional, default None.
vy_0 – A Tensor specifying the initial vy (velocity in the first dimension) wavefield at time step -1/2 (using Deepwave’s internal time step interval, which may be smaller than the user provided one to obey the CFL condition). 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 vy_0 should be of shape [2, 23, 37]. Optional, default all zeros.
vx_0 – A Tensor specifying the initial vx (velocity in the second dimension) wavefield. See the entry for vy_0 for more details.
sigmayy_0 – A Tensor specifying the initial value for the stress field at time step 0.
sigmaxy_0 – A Tensor specifying the initial value for the stress field at time step 0.
sigmaxx_0 – A Tensor specifying the initial value for the stress field at time step 0.
m_vyy_0 – A Tensor specifying the initial value for the “memory variable” for the velocity, used in the PML.
m_vyx_0 – A Tensor specifying the initial value for the “memory variable” for the velocity, used in the PML.
m_vxy_0 – A Tensor specifying the initial value for the “memory variable” for the velocity, used in the PML.
m_vxx_0 – A Tensor specifying the initial value for the “memory variable” for the velocity, used in the PML.
m_sigmayyy_0 – A Tensor specifying the initial value for the “memory variable” for the stress, used in the PML.
m_sigmaxyy_0 – A Tensor specifying the initial value for the “memory variable” for the stress, used in the PML.
m_sigmaxyx_0 – A Tensor specifying the initial value for the “memory variable” for the stress, used in the PML.
m_sigmaxxx_0 – A Tensor specifying the initial value for the “memory variable” for the stress, used in the PML.
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].
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:

vy, vx:: A Tensor containing the final velocity wavefield of the simulation.
sigmayy, sigmaxy, sigmaxx:: A Tensor containing the final stress field of the simulation.
m_vyy_0, m_vyx_0, m_vxy_0, m_vxx_0:: A Tensor containing the final value for the “memory variable” for the velocity, used in the PML.
m_sigmayyy_0, m_sigmaxyy_0, m_sigmaxyx_0, m_sigmaxxx_0:: A Tensor containing the final value for the “memory variable” for the stress, used in the PML.
receiver_amplitudes_p:: A Tensor containing the receiver amplitudes for pressure receivers.
receiver_amplitudes_y:: A Tensor of dimensions [shot, receiver, time] containing the receiver amplitudes recorded at the provided receiver locations for receivers oriented in the first spatial dimension. If no such receiver locations were specified then this Tensor will be empty.
receiver_amplitudes_x:: A Tensor containing the receiver amplitudes for receivers oriented in the second spatial dimension.

Return type:

Tuple[Tensor]

`cosine_taper_end`¶

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

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

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

Parameters:

signal – The 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`¶

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 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 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. Default 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. Default 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`¶

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 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 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. Default 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. Default 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. Default 0.0.

Returns:

The signal after downsampling.

`cfl_condition`¶

deepwave.common.cfl_condition(dy: float, dx: float, dt: float, max_vel: float, eps: float = 1e-15) → Tuple[float, int]¶

Calculates the time step interval to obey the CFL condition.

The output time step will be a factor of the input time step.

Parameters:

dy – The grid spacing in the first dimension.
dx – The grid spacing in the second dimension.
dt – The time step interval.
max_vel – The maximum wavespeed in the model.
eps – A small quantity to prevent division by zero. Default 1e-15.

Returns:

inner_dt:: A time step interval that obeys the CFL condition.
step_ratio:: The integer dt / inner_dt.

Return type:

Tuple[float, int]

`vpvsrho_to_lambmubuoyancy`¶

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 Tensor containing the p wavespeed.
vs – A Tensor containing the s wavespeed.
rho – A Tensor containing the density.
eps – An optional float to avoid division by zero. Default 1e-15.

Returns:

lambda:: A Tensor containing the first Lamé parameter.
mu:: A Tensor containing the second Lamé parameter.
buoyancy:: A Tensor containing the reciprocal of density.

Return type:

Tuple[Tensor, Tensor, Tensor]

`lambmubuoyancy_to_vpvsrho`¶

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:

lambda – A Tensor containing the first Lamé parameter.
mu – A Tensor containing the second Lamé parameter.
buoyancy – A Tensor containing the reciprocal of density.
eps – An optional float to avoid division by zero. Default 1e-15.

Returns:

vp:: A Tensor containing the p wavespeed.
vs:: A Tensor containing the s wavespeed.
rho:: A Tensor containing the density.

Return type:

Tuple[Tensor, Tensor, Tensor]

`Hicks`¶

class deepwave.location_interpolation.Hicks(locations: Tensor, halfwidth: int = 4, free_surfaces: Optional[List[bool]] = None, model_shape: Optional[List[int]] = None, monopole: Union[Tensor, bool] = True, dipole_dim: Union[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 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]. [True, False, False, True] therefore means that the beginning of the first dimension and end of the second dimension are free surfaces, while the other two edges are not, for example. The default is for no edges to be 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 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 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: Optional[Tensor] = 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 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 Tensor containing the interpolated locations.

receiver(amplitudes: Tensor, shot_idxs: Optional[Tensor] = None) → Tensor¶

Convert receiver amplitudes from interpolated to original locations.

Parameters:

amplitudes – A Tensor containing the amplitudes recorded at interpolated receiver locations.
shot_idxs – A 1D 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: Optional[Tensor] = None) → Tensor¶

Calculate the amplitudes of the interpolated sources.

Parameters:

amplitudes – A Tensor containing the amplitudes of the sources at the original locations.
shot_idxs – A 1D 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`¶

deepwave.wavelets.ricker(freq: float, length: int, dt: float, peak_time: float, dtype: Optional[dtype] = None) → Tensor¶

Return a Ricker wavelet with the specified central frequency.

Parameters:

freq – A float specifying the central frequency
length – An int specifying the number of time samples
dt – A float specifying the time sample spacing
peak_time – A float specifying the time (in secs) of the peak amplitude
dtype – The PyTorch datatype to use. Optional, defaults to PyTorch’s default (float32).

Usage¶

`Scalar`¶

`scalar`¶

`ScalarBorn`¶

`scalar_born`¶

`Elastic`¶

`elastic`¶

`cosine_taper_end`¶

`upsample`¶

`downsample`¶

`cfl_condition`¶

`vpvsrho_to_lambmubuoyancy`¶

`lambmubuoyancy_to_vpvsrho`¶

`Hicks`¶

`ricker`¶

Deepwave

Navigation

Related Topics