edg_acoustics.acoustics_simulation

This module provides the AcousticsSimulation class, which includes the data structure for running a DG acoustics simulation. The AcousticsSimulation class sets up the DG finite element discretization for the solution to the acoustic wave propagation problem.

Note that objects enclosed by square brackets (e.g., [dimension1, dimension2]) denotes a matrix of dimension [dimension1, dimension2].

Module Contents

Classes

AcousticsSimulation

Acoustics simulation data structure for running a DG acoustics simulation.

Attributes

NODETOL

Tolerance used to determine if a node lies on a facet.
edg_acoustics.acoustics_simulation.NODETOL = 1e-07[source]

Tolerance used to determine if a node lies on a facet.

Type:

float

class edg_acoustics.acoustics_simulation.AcousticsSimulation(rho0, c0, Nx, mesh, BC_list, node_tolerance=NODETOL)[source]

Acoustics simulation data structure for running a DG acoustics simulation.

AcousticsSimulation contains the domain discretization and sets up the DG finite element discretisation for the solution to the acoustic wave propagation.

Parameters:

  • rho0 (float) – the density of the medium in which the acoustic wave propagates.

  • c0 (float) – the speed of sound in the medium in which the acoustic wave propagates.

  • Nx (int) – the polynomial degree of the approximating DG finite element space used to solve the acoustic wave propagation problem.

  • mesh (edg_acoustics.Mesh) – the mesh object containing the mesh information for the domain discretisation.

  • BC_list (dict[str, int]) – a dictionary containing the definition of the boundary conditions that are present in the mesh. BC_list must contain the same keys as edg_acoustics.Mesh.BC_triangles, i.e., all boundary conditions in the mesh must have an associated boundary condition definition.

  • node_tolerance (float) – the tolerance used to check if a node belongs to a facet or not. <default>: edg_acoustics.acoustics_simulation.NODETOL

Raises:

ValueError – If BC_list[‘my_label’] is not present in the mesh, an error is raised. If a label is present in the mesh but not in BC_list, an error is raised.

BC_list

a dictionary containing the definition of the boundary conditions that are present in the mesh. BC_list must contain the same keys as edg_acoustics.Mesh.BC_triangles, i.e., all boundary conditions in the mesh must have an associated boundary condition definition.

Type:

dict[str, int]

BCnode

List of boundary map nodes, each element being a dictionary with keys (values) [‘label’ (int), ‘map’ (numpy.ndarray), ‘vmap’ (numpy.ndarray)].

Type:

list[dict]

c0

the speed of sound in the medium in which the acoustic wave propagates.

Type:

float

Dr

the reference element differentiation matrices containing the discrete representation of \(\frac{\partial}{\partial r}\), in the rst reference element coordinate system.

Type:

numpy.ndarray

Ds

the reference element differentiation matrices containing the discrete representation of \(\frac{\partial}{\partial s}\), in the rst reference element coordinate system.

Type:

numpy.ndarray

Dt

the reference element differentiation matrices containing the discrete representation of \(\frac{\partial}{\partial t}\), in the rst reference element coordinate system.

Type:

numpy.ndarray

dim

the geometric dimension of the space where the acoustic problem is solved. Always set to 3.

Type:

int

dtscale

the time step scale based on the mesh size measure, is set to the minimum diameter of the inscribed spheres in all elements.

Type:

float

Fmask

[4, Nfp] array containing indices of nodes per surface of the tetrahedron.

Type:

numpy.ndarray

Fscale

[4*Nfp, N_tets] ratio of surface to volume Jacobian of facial node.

Type:

numpy.ndarray

J

[Np, N_tets] The determinant of the Jacobian matrix for the coordinate transformation, at the collocation nodes.

Type:

numpy.ndarray

lift

[Np, 4*Nfp] an array containing the product of inverse of the mass matrix (3D) with the face-mass matrices (2D).

Type:

numpy.ndarray

mesh

the mesh object containing the mesh information for the domain discretisation.

Type:

edg_acoustics.Mesh

Nfp

number of collocation nodes in a face.

Type:

int

Np

number of collocation nodes in an element.

Type:

int

N_tets

number of tetrahedra in the mesh.

Type:

int

Nx

the polynomial degree of the approximating DG finite element space used to solve the acoustic wave propagation problem.

Type:

int

node_tolerance

the tolerance used to check if a node belongs to a facet or not. <default>: edg_acoustics.acoustics_simulation.NODETOL.

Type:

float

rho0

the density of the medium in which the acoustic wave propagates.

Type:

float

rst

the reference element coordinates \((r, s, t)\) of the collocation points. Physical coordinates xyz are obtained by mapping for each element the rst coordinates of the reference element into the physical domain. rst[0] contains the r-coordinates, rst[1] contains the s-coordinates, rst[2] contains the t-coordinates.

Type:

numpy.ndarray

rst_xyz

[3, 3, Np, N_tets] The derivative of the local coordinates \(R = (r, s, t)\) with respect to the physical coordinates \(X = (x, y, z)\), i.e., \(\frac{\partial R}{\partial X}\), at the collocation nodes. Specifically:

  • rst_xyz[0, 0]: rx (numpy.ndarray): [Np, N_tets] The derivative of the local coordinates \(r\) with respect to the physical coordinates \(x\), i.e., \(\frac{\partial r}{\partial x}\), at the collocation nodes.

  • rst_xyz[1, 0]: sx (numpy.ndarray): [Np, N_tets] The derivative of the local coordinates \(s\) with respect to the physical coordinates \(x\), i.e., \(\frac{\partial s}{\partial x}\), at the collocation nodes.

  • rst_xyz[2, 0]: tx (numpy.ndarray): [Np, N_tets] The derivative of the local coordinates \(t\) with respect to the physical coordinates \(x\), i.e., \(\frac{\partial t}{\partial x}\), at the collocation nodes.

  • rst_xyz[0, 1]: ry (numpy.ndarray): [Np, N_tets] The derivative of the local coordinates \(r\) with respect to the physical coordinates \(y\), i.e., \(\frac{\partial r}{\partial y}\), at the collocation nodes.

  • rst_xyz[1, 1]: sy (numpy.ndarray): [Np, N_tets] The derivative of the local coordinates \(s\) with respect to the physical coordinates \(y\), i.e., \(\frac{\partial s}{\partial y}\), at the collocation nodes.

  • rst_xyz[2, 1]: ty (numpy.ndarray): [Np, N_tets] The derivative of the local coordinates \(t\) with respect to the physical coordinates \(y\), i.e., \(\frac{\partial t}{\partial y}\), at the collocation nodes.

  • rst_xyz[0, 2]: rz (numpy.ndarray): [Np, N_tets] The derivative of the local coordinates \(r\) with respect to the physical coordinates \(z\), i.e., \(\frac{\partial r}{\partial z}\), at the collocation nodes.

  • rst_xyz[1, 2]: sz (numpy.ndarray): [Np, N_tets] The derivative of the local coordinates \(s\) with respect to the physical coordinates \(z\), i.e., \(\frac{\partial s}{\partial z}\), at the collocation nodes.

  • rst_xyz[2, 2]: tz (numpy.ndarray): [Np, N_tets] The derivative of the local coordinates \(t\) with respect to the physical coordinates \(z\), i.e., \(\frac{\partial t}{\partial z}\), at the collocation nodes.

Type:

numpy.ndarray

sJ

[4*Nfp, N_tets] The determinant of the surface Jacobian matrix at each of the collocation nodes, for each of the 4 faces of the N_tets elements.

Type:

numpy.ndarray

V

[Np, Np] vandermonde matrix of the orthonormal basis functions on the reference simplex element. Polynomial basis can exactly represent polynomials up to degree Nx. Consider the set of Np 3D nodes, with the coordinates of each node \(i\) equal to \((r_{i}, s_{i}, t_{i})\), in rst, and the set of \(m\) orthonormal basis functions, the vandermonde matrix will be \(V_{i,j} = f_{j}(r_{i}, s_{i}, t_{i})\).

Type:

numpy.ndarray

xyz

[3, Np, N_tets] the physical space coordinates \((x, y, z)\) of the collocation points of each element of the mesh. xyz[0] contains the x-coordinates, xyz[1] contains the y-coordinates, xyz[2] contains the z-coordinates.

Type:

numpy.ndarray

n_xyz

[3, 4*Np, N_tets] the outwards normals \(\vec{n}= (n_x, n_y, n_z)\) at each collocation point on the element faces. Specifically:

  • n_xyz[0, :] (numpy.ndarray): nx [4*Nfp, N_tets] The \(x\)-component of the outward normal \(\vec{n}\) at each of the Nfp nodes on each of the 4 facets of each of the N_tets elements.

  • n_xyz[1, :] (numpy.ndarray): ny [4*Nfp, N_tets] The \(y\)-component of the outward normal \(\vec{n}\) at each of the Nfp nodes on each of the 4 facets of each of the N_tets elements.

  • n_xyz[2, :] (numpy.ndarray): nz [4*Nfp, N_tets] The \(z\)-component of the outward normal \(\vec{n}\) at each of the Nfp nodes on each of the 4 facets of each of the N_tets elements.

Type:

numpy.ndarray

vmapM

[4*Nfp*N_tets, 1] an array containing the global indices for interior values.

Type:

numpy.ndarray

vmapP

[4*Nfp*N_tets, 1] an array containing the global indices for exterior values.

Type:

numpy.ndarray

init_local_system()[source]

Call the methods to initialise the local system and compute all the attributes of the AcousticsSimulation object.

static compute_Np(Nx)[source]

Computes the number of collocation nodes for basis of polynomial degree Nx.

Parameters:

Nx (int) – see Nx.

Returns:

Np (int) – see Np.

static compute_Nfp(Nx)[source]

Computes the number of collocation nodes lying on a face of the elements for basis of polynomial degree Nx.

Parameters:

Nx (int) – see Nx.

Returns:

Nfp (int) – see Nfp.

static compute_Nx_from_Np(Np)[source]

Computes the polynomial degree Nx of basis from the number of collocation points Np.

Parameters:

Np (int) – see Np.

Returns:

Nx (int) – see Nx.

static check_BC_list(BC_list, mesh)[source]

Check if BC_list is compatible with mesh. Given a mesh with a set of boundary conditions specified in mesh.BC_triangles, check if the list of boundary conditions specification, BC_list, is compatible. By compatible we mean that all boundary conditions (keys) in BC_list exist in mesh.BC_labels, and vice-versa.

Parameters:
Returns:

is_compatible (bool) – a flag specifying if BC_list is compatible with the mesh or not.

static compute_collocation_nodes(EToV, vertices, Nx, dim=3)[source]

Compute reference element \((r, s, t)\) coordinates of collocation points rst and the physical domain xyz coordinates for each element.

Parameters:
Returns:

  • rst (numpy.ndarray) – see rst.

  • xyz (numpy.ndarray) – see xyz.

static compute_van_der_monde_matrix(Nx, rst, dim=3)[source]
Compute vandermonde matrix of the orthonormal basis functions on the reference simplex element. Polynomial basis

can exactly represent polynomials up to degree Nx. Consider the set of Np 3D nodes, with the coordinates of each node \(i\) equal to \((r_{i}, s_{i}, t_{i})\), in rst, and the set of \(m\) orthonormal basis functions, the vandermonde matrix will be \(V_{i,j} = f_{j}(r_{i}, s_{i}, t_{i})\).

Parameters:
Returns:

V (numpy.ndarray) – see V.

Return type:

numpy.ndarray

static compute_derivative_matrix(Nx, rst, dim=3)[source]

Compute the derivative matrix on the reference element.

Parameters:
Returns:

  • Dr (numpy.ndarray) – see Dr.

  • Ds (numpy.ndarray) – see Ds.

  • Dt (numpy.ndarray) – see Dt.

static compute_Fmask(rst, node_tol)[source]

Find all the :attr:Nfp face nodes that lie on each surface.

Parameters:
Returns:

Fmask (numpy.ndarray) – see Fmask.

static compute_lift(V, rst, Fmask)[source]

Compute the lift matrix.

Parameters:
Returns:

lift (numpy.ndarray) – see lift.

static geometric_factors_3d(xyz, Dr, Ds, Dt)[source]

Compute the metric elements for the local mappings of the elements.

Parameters:
Returns:

  • rst_xyz (numpy.ndarray) – see rst_xyz.

  • J (numpy.ndarray) – see J.

static normals_3d(xyz, rst_xyz, J, Fmask)[source]

Compute outward pointing normals at element’s faces as well as surface Jacobians.

Parameters:
Returns:

  • n_xyz (numpy.ndarray) – see n_xyz.

  • sJ (numpy.ndarray) – see sJ.

static build_maps_3d(xyz, EToE, EToF, Fmask, node_tol)[source]

Find connectivity for nodes given per surface in all elements

Parameters:
Returns:

  • vmapM (numpy.ndarray) – see vmapM.

  • vmapP (numpy.ndarray) – see vmapP.

static ismember_col(a, b)[source]

find the indices of the columns of a that are in b

Parameters:
Returns:

indices (numpy.ndarray) – boolean indices of the columns of a that are in b

static build_BCmaps_3d(BC_list, EToV, vmapM, BC_triangles, Nx)[source]

Build specialized nodal maps for various types of boundary conditions,specified in BC_list

Parameters:
Returns:

BCnode (list[dict]) – see BCnode.

static diameter_3d(Fscale)[source]

Compute the minimum diameter of the inscribed spheres in all elements.

Parameters:

Fscale (numpy.ndarray) – see Fscale.

Returns:

diameter (float) – minimum diameter of the inscribed spheres in all elements.

grad_3d(U, axis)[source]

Compute partial derivative dU/dx, dU/dy, dU/dz, or gradient dU/dx + dU/dy + dU/dz

Parameters:

  • U (numpy.ndarray) – [Np, N_tets] the acoustic variables that needs to be differentiated.

  • axis (str) – the axis to be differentiated w.r.t, e.g. ‘x’, ‘y’, ‘z’, ‘xyz’

Returns:

  • dUdx (numpy.ndarray) – [Np, N_tets] derivatives \(\frac{\partial U}{\partial x}\) at every nodal point, if axis is ‘x’.

  • dUdy (numpy.ndarray) – [Np, N_tets] derivatives \(\frac{\partial U}{\partial y}\) at every nodal point, if axis is ‘y’.

  • dUdz (numpy.ndarray) – [Np, N_tets] derivatives \(\frac{\partial U}{\partial z}\) at every nodal point, if axis is ‘z’.

  • Tuple of gradient (numpy.ndarray) – [Np, N_tets] gradient (\(\frac{\partial U}{\partial x}, \frac{\partial U}{\partial y}, \frac{\partial U}{\partial z}\)), if axis is ‘xyz’.

static locate_simplex(node_coordinates, EToV, rec, methodLocate='scipy')[source]

Locate the simplices containing the sample points.

Parameters:
Returns:

nodeindex (numpy.ndarray) – indices of simplices containing the N_rec microphone points

sample3D(methodLocate='scipy')[source]

Compute interpolation weights required to interpolate the nodal data to the sample (i.e., microphone location)

Parameters:

methodLocate (str) – search method to locate the simplices containing the sample points. Available methods are ‘scipy’ and ‘brute_force’. brutal force approach, adopted from https://stackoverflow.com/questions/25179693/how-to-check-whether-the-point-is-in-the-tetrahedron-or-not/60745339#60745339

Returns:

  • sampleWeight (numpy.ndarray) – [N_rec, Np] interpolation weights required to interpolate the nodal data to the sample (i.e., microphone location).

  • nodeindex (numpy.ndarray) – [N_rec, ] index of simplices that contatin the sample (microphone) points.

init_IC(IC)[source]

setup the initial condition and save it to the AcousticsSimulation class.

Parameters:

IC (edg_acoustics.InitialCondition) – the initial condition object.

init_BC(BC)[source]

load the boundary condition and save it to the AcousticsSimulation class.

Parameters:

BC (edg_acoustics.BoundaryCondition) – the boundary condition object.

init_rec(rec, methodLocate='scipy')[source]

load the receiver locations and save it to the AcousticsSimulation class. Then compute the interpolation weights required to interpolate the nodal data to the sample (i.e., microphone location).

Parameters:
init_Flux(Flux)[source]

load the interior flux calculation and save it to the AcousticsSimulation class.

Parameters:

Flux (edg_acoustics.Flux) – the flux object.

init_TimeIntegrator(time_integrator)[source]

load the time integrator to be used to and save it to the AcousticsSimulation class.

Parameters:

time_integrator (edg_acoustics.TimeIntegrator)

RHS_operator(P, Vx, Vy, Vz, BCvar)[source]

Compute the right-hand side of the linear acoustic equations with the DG discretization.

Parameters:
Returns:

  • RHS_P (numpy.ndarray) – Right-hand side values for pressure.

  • RHS_Vx (numpy.ndarray) – Right-hand side values for velocity in the x-direction.

  • RHS_Vy (numpy.ndarray) – Right-hand side values for velocity in the y-direction.

  • RHS_Vz (numpy.ndarray) – Right-hand side values for velocity in the z-direction.

  • BCvar (list[dict]) – updated boundary condition variables.

time_integration(**kwargs)[source]

Perform time integration for the acoustics simulation. Additional keyword arguments are optional and can vary:

Parameters:

  • n_time_steps (int) – number of time steps to be performed.

  • total_time (float) – total simulation time to be performed, determines the number of time steps given the current time step.

  • delta_step (int) – print solution every delta_step time steps.

  • save_step (int) – save solution every save_step time steps.

  • format (str) – the format of the file to save the results. Can be either ‘mat’ or ‘npy’. The default format is ‘mat’.

Returns:

prec (numpy.ndarray) – Pressure field at the microphone locations.

save_results_on_the_run(format='mat')[source]

Save the temporary simulation results to a file.

Parameters:

format (str) – the format of the file to save the results. Can be either ‘mat’ or ‘npy’. The default format is ‘mat’.