seidart.routines.classes module

class seidart.routines.classes.AnimatedGif(size=(640, 480))

Bases: object

A class to create an animated GIF from a series of images.

Parameters:

size (Tuple[int, int], optional) – The size of the animated GIF in pixels (width, height), defaults to (640, 480)

fig

The figure object for the animation.

Type:

matplotlib.figure.Figure

images

A list of image frames to be included in the GIF.

Type:

List

background

Background image data.

Type:

List

source_location

The location of the source point in

Type:

List[int, int]

the plot.
nx

Width of the plot.

Type:

int

nz

Height of the plot.

Type:

int

output_format

Format of the output file. 0 for GIF, 1 for other

Type:

int

formats.
add(image, label='', extent=None)

Adds an image to the animation sequence.

Parameters:

  • image (np.ndarray) – The image data to add.

  • label (str, optional) – The label to add to the image, defaults to ‘’.

  • extent (Tuple[int, int, int, int], optional) – The extent of the image, defaults to None.

save(filename, frame_rate=50)

Save the animated GIF.

Parameters:

  • filename (str) – The name of the output file.

  • frame_rate (int, optional) – The frame rate of the animation, defaults to 50.

class seidart.routines.classes.Domain

Bases: object

Simulation-domain parameters loaded from a SeidarT project file.

A Domain stores grid dimensions, grid spacing, CPML settings, geometry labels, and flags indicating whether seismic or electromagnetic models are enabled.

build()

Initialize domain attributes to default empty values.

This method is called during construction and can be reused to reset a Domain object before loading a project file.

parameter_check()

Validate required domain settings and update exit_status.

The method checks for geometry, grid spacing, CPML thickness, and 2.5D y-direction defaults. A nonzero exit_status indicates missing or inconsistent domain parameters.

class seidart.routines.classes.Material

Bases: object

A class to manage materials for simulation purposes.

material_list

An array to store the list of materials. A flag indicating whether the materials were read in successfully.

Type:

pd.DataFrame

material

Stores material information.

Type:

numpy.ndarray or None

rgb

Stores RGB values for materials (not used currently).

Type:

numpy.ndarray or None

temp

Stores temperature values for materials.

Type:

numpy.ndarray or None

rho

Stores density values for materials.

Type:

numpy.ndarray or None

porosity

Stores porosity values for materials.

Type:

numpy.ndarray or None

lwc

Stores liquid water content values for materials.

Type:

numpy.ndarray or None

is_anisotropic

Indicates if the material is anisotropic.

Type:

numpy.ndarray or None

angfile

Stores ANG file paths for anisotropic materials.

Type:

numpy.ndarray or None

functions

Stores material processing functions.

Type:

Any

build() → None

Initializes the material attributes with default values.

parameter_check() → None

Checks the parameters of the material list for completeness.

It ensures that necessary fields are provided and checks for the presence of .ANG files for anisotropic materials.

sort_material_list() → None

Sorts the material list based on the material properties.

class seidart.routines.classes.Model

Bases: object

A class to manage the simulation model configuration.

dt

The time step size.

Type:

float or None

time_steps

The total number of time steps in the simulation.

Type:

int or None

x

The x-coordinate of the source location.

Type:

float or None

y

The y-coordinate of the source location. Optional, defaults to None.

Type:

float or None

z

The z-coordinate of the source location.

Type:

float or None

f0

The source frequency.

Type:

float or None

theta

The angle of incidence in the xz-plane. Optional, defaults to 0 if unspecified.

Type:

float or None

phi

The angle of incidence in the xy-plane. Optional, defaults to 0 if y is specified and phi is unspecified.

Type:

float or None

src

The source information. Type is unspecified.

Type:

Any

tensor_coefficients

The tensor coefficients for the simulation. Optional, but required for tensor-based simulations.

Type:

numpy.ndarray or None

compute_coefficients

A flag indicating whether to compute coefficients. Defaults to True.

Type:

bool

attenuation_coefficients

The attenuation coefficients for the simulation. Optional.

Type:

numpy.ndarray or None

fref

The reference frequency for attenuation. Optional.

Type:

float or None

attenuation_fadjust

Flag to adjust frequency for attenuation. Optional.

Type:

bool or None

exit_status

Status code to indicate the success or failure of parameter checks.

Type:

int

add_noise(domain, scalar_amplitude: float = 1.0)
Parameters:

  • domain (Domain) – The domain instance

  • scalar_amplitude (float) – The scalar value to multiply the noise by. The range of noise values are between 0 and 1.

append_coefficients(tensor: ndarray, tensor_name: str = None)

Appends coefficients to the JSON dictionary based on the provided tensor.

Parameters:

  • tensor (np.ndarray) – A numpy array containing the tensor coefficients to append.

  • tensor_name – The parameter that the tensor describes. Available options are Stiffness, Permittivity, Conductivity

Returns:

None

atten2dat(tensor, domain, eta_max=None)

Write per-material attenuation (gamma) coefficients to Fortran binary .dat files, extended into the CPML ghost-cell region.

The last column of tensor is the reference frequency and is skipped (it is not written as a spatial field).

Supports 2 / 2.5D and true 3D domains.

build(material: Material, domain: Domain, recompute_tensors: bool = True, write_tensor: bool = True) → None

Checks the status of the modeling classes and appends coefficients to the project file if necessary.

Parameters:

  • material (Material) – The material class instance.

  • domain (Domain) – The domain class instance.

  • append_to_json (bool) – Flag to append coefficients to the project file. Defaults to True.

compute_christoffel_directions(material_index, n_theta=30, n_phi=60)

Compute eigenvectors from the Christoffel matrix over a grid of directions.

Parameters:

  • material_index (int) – Index of the material from stiffness_coefficients.

  • n_theta (int) – Number of points in inclination (from 0 to pi/2, lower hemisphere).

  • n_phi (int) – Number of azimuthal angles (from 0 to 2*pi).

  • Stores

  • ------

  • self.christoffel_solutions (list of dict) – Each dict contains direction vector, eigenvectors, eigenvalues, velocities.

compute_max_velocities(dim=2, directions=None)

Loop over all materials in the model and compute the maximum phase velocity for each material using the Christoffel matrix.

Parameters:

directions – List of direction keys to use. Defaults to [‘x’, ‘y’, ‘z’, ‘xy’, ‘xz’, ‘yz’].

Returns:

Dictionary {material_id: max_velocity}

get_christoffel_matrix(material_indice, direction)

Compute direction-dependent wave properties for one material.

For seismic models this delegates to seidart.routines.materials.get_christoffel_matrix(). For electromagnetic models it delegates to seidart.routines.materials.get_complex_refractive_index().

Parameters:

  • material_indice (int) – Row index of the material coefficient table.

  • direction (str or numpy.ndarray) – Propagation direction, such as "x", "y", "z", or a supported direction vector.

Returns:

Direction-dependent matrix/eigenvalue information returned by the underlying materials helper.

Return type:

tuple

kband_check(domain)

Check to make sure the discretization values of the domain satisfy the wavenumber bandlimiter as described in Volvcan et al. (2024).

Parameters:
parameter_check() → None

Performs parameter checks for essential simulation settings and updates the exit status accordingly.

parameter_profile_1d(domain, material, indice: int, parameter: str = 'velocity', direction='z')

Extract a one-dimensional parameter profile from the model.

The profile is sampled along the z-direction at a fixed x-index. The parameter argument selects velocity or a material property such as temperature, density, liquid-water content, porosity, or conductivity.

Parameters:

  • domain (Domain) – Domain object containing geometry and grid spacing.

  • material (Material) – Material object containing material-property tables.

  • indice (int) – X-index where the vertical profile is extracted.

  • parameter (str) – Parameter to extract. Common values are "velocity", "temperature", "density", "lwc", "porosity", and "conductivity".

  • direction (str) – Propagation direction used when computing velocity.

Returns:

Profile values for the requested parameter.

Return type:

numpy.ndarray

plot_lower_hemisphere_polarizations()

Plot lower hemisphere projections of P, SV, and SH polarization directions using previously computed Christoffel solutions.

Returns:

fig, axs

Return type:

Matplotlib figure and axes objects.

plot_unit_sphere_wave_speeds(material_indice, num_samples=100)

Plot wave speeds on a unit sphere for a given material.

Parameters:

  • self – The class containing material properties and methods.

  • material_indice (int) – Index of the material in the DataFrame.

  • num_samples (int) – Number of unit sphere sample points.

Returns:

None (displays figure).

plotsource()
run(num_threads=1, jsonfile=None)
save_to_json(jsonfile=None)

Write model coefficient tables back into a project JSON file.

Parameters:

jsonfile (str, optional) – Project file to update. If omitted, self.project_file is used.

Returns:

None

Return type:

None

tensor2dat(tensor, domain)

Write per-material tensor coefficients to individual Fortran binary .dat files, extended into the CPML ghost-cell region by repeating the outermost interior value on every face.

Supports 2 / 2.5D (geometry shape (nx, nz)) and true 3D (geometry shape (nx, ny, nz)).

tensor_test()

Test for positive definiteness and ellipticity so that we can ensure that our domain is physically stable in the continuum mechanics sense

writemask(material: Material, domain: Domain)

Write a binary geometry mask to geometry_mask.dat. Cells that belong to fluid-like materials (air, water, oil) are set to 1; all others are 0. Supports 2 / 2.5D and true 3D domains.