seidart.routines.definitions module

class seidart.routines.definitions.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.definitions.Domain

Bases: object

build()
para_check()
class seidart.routines.definitions.Material

Bases: object

A class to manage materials for simulation purposes.

material_list

An array to store the list of materials.

Type:

numpy.ndarray

material_flag

A flag indicating whether the materials were read in successfully.

Type:

bool

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

angfiles

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.

para_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.definitions.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

build() → None

Initializes the simulation model attributes with default values.

para_check() → None

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

tensor_check() → None

Checks if tensor coefficients are specified and valid. Disables coefficient computation if valid.

seidart.routines.definitions.agc(ts, k, agctype)

Applies auto-gain control (AGC) normalization to a time series using a specified window length and type.

Parameters:

  • ts (np.ndarray) – The input time series as a numpy array.

  • k (int) – The length of the window used for normalization.

  • agctype (str) – The type of normalization to apply, choices are “std”, “mean”, or “median”.

Returns:

The time series after applying AGC normalization.

Return type:

np.ndarray

This function normalizes the input time series using a running window approach, with the normalization type determined by agctype. It supports standard deviation (“std”), mean (“mean”), or median (“median”) based normalization. The function modifies the series to have a uniform amplitude characteristic over time.

seidart.routines.definitions.airsurf(material: Material, domain: Domain, N: int = 2) → ndarray

Generates a gradient matrix to simulate the air surface in a domain, based on material properties.

This function calculates a gradient matrix representing the transition between air and non-air materials within a domain. It is particularly useful for creating a surface with variable density or other properties near the air-material interface.

Parameters:

  • material (Material) – The material object containing material lists and properties.

  • domain (Domain) – The domain object containing the geometry of the simulation area.

  • N (int) – The number of gradational steps in the air surface simulation, defaults to 2.

Returns:

A gradient matrix representing the air surface within the domain.

Return type:

np.ndarray

The function uses the domain’s geometry to determine air interfaces and applies a gradational approach to simulate the air surface effect. The gradient matrix can be used to adjust physical properties like density near the surface.

seidart.routines.definitions.append_coefficients(prjfile: str, tensor: ndarray, CP: str = None, dt: float = 1.0)

Appends coefficients to a project file based on the provided tensor, optionally using a line identifier.

This function reads a project file, appending new coefficients derived from a tensor to it. The coefficients are appended based on a line identifier (CP), which specifies the type of modeling (e.g., ‘C’ for stiffness, ‘P’ for permittivity). The function also appends the time step (dt) for each modeling type specified by CP.

Note: The project file is updated in place, with the original file replaced by the modified one. The tensor can be either a complex or a real numpy array. The function handles these differently when appending to the file. This function relies on an external command (mv) to replace the original file, which requires that the script has permissions to execute system commands.

Parameters:

  • prjfile (str) – The path to the project file to be modified.

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

  • CP (str, optional) – The line identifier indicating the type of modeling (‘C’ or ‘P’), optional.

  • dt (float) – The time step to append for the modeling type, defaults to 1.

Returns:

None

seidart.routines.definitions.coefs2prj(model_object, material, domain, modeltype)
seidart.routines.definitions.coherdt(alpha: float, v: float, n: int, dx: float, loc: str = 'left') → ndarray

Calculates a vector of time delays based on the angle of incidence, velocity, and spatial discretization.

This function determines the time delay for coherent addition of traces based on the propagation angle (alpha), velocity (v), and the discretization in space (dx) along the domain length.

Parameters:

  • alpha (float) – The angle of incidence in degrees, counter clockwise from the x-plane. Range: (-90, 90).

  • v (float) – Velocity in meters/second.

  • n (int) – The number of spatial points in the domain.

  • dx (float) – The spatial discretization in meters.

  • loc (str) – Specifies the reference point’s location for time delay calculation, defaults to ‘left’.

Returns:

A numpy array containing the time delays for each spatial point in the domain.

Return type:

np.ndarray

The function adjusts angles outside the (-90, 90) range and calculates time delays accordingly.

seidart.routines.definitions.coherstf(timediff: ndarray, source_function: ndarray, dt: float, m: int, n: int, cpml: int, bottom: bool = False) → None

Applies time shifts to a source time function along the domain and saves it as an m-by-n-by-p matrix.

Parameters:

  • timediff (np.ndarray) – A numpy array containing time differences for time shifting the source function.

  • sf (np.ndarray) – The source time function as a numpy array.

  • dt (float) – The time interval between successive samples in the source function.

  • m (int) – Number of indices in the y-direction (height of the domain).

  • n (int) – Number of indices in the x-direction (width of the domain).

  • cpml (int) – The size of the Convolutional Perfectly Matched Layer (CPML) padding.

  • bottom (bool) – Specifies whether to place the source at the bottom of the domain. Defaults to False.

Returns:

None

This function time shifts the source time function for each node in the x-direction, considering CPML adjustments.

‘topleft’ origin is (0,0), ‘topright’ origin is (x_n, 0) ‘bottomleft’ origin is (0, y_n), ‘bottomright’ origin is (x_n, y_n)

seidart.routines.definitions.complex2str(complex_vector: ndarray) → str

Convert a numpy array of complex numbers into a string representation, with the first element representing an identifier and the subsequent elements representing complex numbers.

This function extracts the real and imaginary parts of each complex number in the input vector, converts them to strings, and concatenates them with ‘j’ as the delimiter. The first real number of the input vector is treated as an identifier (ID) and is converted separately.

Parameters:

complex_vector (np.ndarray) – A numpy array of complex numbers where the first element is an ID.

Returns:

A string representation of the ID followed by the complex numbers in the vector.

Return type:

str

The returned string format is ‘ID,real1jimag1,real2jimag2,…’ where ID is the integer ID, and realN and imagN are the real and imaginary parts of the Nth complex number, respectively.

seidart.routines.definitions.image2int(image_filename: str) → ndarray

Convert an image file into an integer array where each unique RGB color is mapped to a unique integer.

This function reads an image from a file, converts RGB colors to a single integer value by combining the RGB channels, then maps each unique color in the image to a unique integer. This can be useful for image analysis tasks where colors represent different categories or labels.

Parameters:

image_filename (str) – The path to the image file.

Returns:

A 2D array where each element represents a unique integer mapping of the original RGB colors.

Return type:

np.ndarray

The conversion of RGB to a single value is performed using the formula: 65536*red + 255*green + blue. Note that this function assumes the input image is in a format readable by matplotlib.image.imread (e.g., PNG, JPG), and that it has three color channels (RGB).

seidart.routines.definitions.indvar(model_object: Model, domain: Domain) → tuple[ndarray, ndarray | None, ndarray, ndarray]

Generates spatial and temporal grids based on domain and model object attributes.

Parameters:

  • model_object – An object containing model-specific parameters, including time steps and time interval (dt).

  • domain – An object containing domain-specific parameters such as spatial dimensions (nx, ny, nz) and discretizations (dx, dy, dz).

Returns:

A tuple of numpy arrays representing the grids in x, y (None if ny is not set), z, and t dimensions.

Return type:

tuple

The function calculates the spatial grid points in the x, z, and optionally y dimensions, and temporal grid points based on the provided domain and model parameters. The y-dimension grid is generated only if the domain parameters include ‘ny’.

seidart.routines.definitions.loadproject(project_file: str, domain: Domain, material: Material, seismic: Model, electromag: Model) → tuple[Domain, Material, Model, Model]

Loads project settings from a project file and assigns values to domain, material, seismic, and electromagnetic objects.

This function parses a specified project file, reading configurations and parameters for the domain, materials, seismic modeling, and electromagnetic properties. These parameters are then assigned to the provided objects.

Parameters:

  • project_file (str) – The path to the project configuration file.

  • domain – An object to hold domain-specific parameters and configurations.

  • material – An object to hold material-specific parameters and configurations.

  • seismic – An object to hold seismic modeling parameters and configurations.

  • electromag – An object to hold electromagnetic modeling parameters and configurations.

Returns:

A tuple containing the updated domain, material, seismic, and electromagnetic objects.

Return type:

tuple

The function assumes the project file contains specific prefixes for different types of configurations (e.g., ‘I’ for images, ‘D’ for domain configurations, ‘S’ for seismic modeling parameters, etc.).

seidart.routines.definitions.movingsrc(sf: ndarray, txlocs: ndarray) → None

Simulates a moving source given a stationary source time function.

Parameters:

  • sf (np.ndarray) – The stationary source time function as a numpy array.

  • txlocs (np.ndarray) – A numpy array containing the transmission locations over time.

Returns:

None

This function is intended as a placeholder to simulate a moving source by manipulating the stationary source time function according to the provided transmission locations.

seidart.routines.definitions.prepme(model_object: Model, domain: Domain, complex_tensor: bool = True) → tuple

Prepare modeling objects and domain configurations for simulation, ensuring that all parameters are in the correct format for Fortran processing.

This function adjusts the type of various parameters in the modeling and domain objects, such as converting time steps to integers or ensuring that tensor coefficients are in the correct numerical format (complex or float). Additionally, it arranges source and domain parameters in the correct order based on the dimensionality of the domain.

Parameters:

  • model_object – The modeling object containing simulation parameters and configurations.

  • domain – The domain object containing spatial configurations and parameters.

  • complex_tensor (bool) – A flag indicating whether the tensor coefficients should be treated as complex numbers.

Returns:

A tuple containing the updated modeling object and domain object.

Return type:

tuple

The function specifically adjusts parameters for compatibility with Fortran-based simulation engines, accounting for differences in array indexing and data types.

seidart.routines.definitions.rcxgen(rgb: list, domain: Domain, material: Material, filename: str = 'receivers.xyz')

Creates a receiver list from a specified RGB value found in the model image, outputting to a CSV file.

This function searches the domain’s geometry for occurrences of a given RGB value (specified as a list of integers representing red, green, and blue components). It then generates a list of receiver coordinates based on the locations where the RGB value is found. Currently, the function is set up for 2D receivers only, with Y-coordinates set to zero.

Parameters:

  • rgb (list) – A list of three integers representing the RGB value to search for in the domain’s geometry.

  • domain – An object representing the domain, including its geometry and spatial discretization parameters (dz, dx).

  • material – An object containing the material list and associated RGB values.

  • filename (str) – The name of the output CSV file containing the receiver coordinates, defaults to ‘receivers.xyz’.

Returns:

A numpy array of receiver coordinates where each row represents [Z, Y, X] coordinates.

Return type:

np.ndarray

The function converts the RGB list into a string format, looks up the

corresponding integer value from the

material list, finds all occurrences in the domain’s geometry, and outputs

the coordinates to a specified CSV file.

seidart.routines.definitions.read_dat(fn: str, channel: str, domain: Domain, is_complex: bool, single: bool = False) → ndarray

Read data from an unformatted Fortran binary file and return it as a numpy array. This function supports reading data in single or double precision, and can handle complex data.

The domain parameter is expected to be an object with attributes

dim, nx, ny, and nz.

These are used to determine the shape of the returned numpy array.

Parameters:

  • fn (str) – The filename of the data file to read.

  • channel (str) – Specifies the data channel (‘Ex’, ‘Ey’, ‘Ez’, etc.) to read.

  • domain (Domain) – The domain object that contains dimensions (dim, nx, ny, nz) of the data.

  • is_complex (bool) – A flag indicating if the data is complex.

  • single (bool) – A flag indicating if the data should be read in single precision. Defaults to False (double precision).

Returns:

The data read from the file, reshaped according to the domain dimensions.

Return type:

np.ndarray

seidart.routines.definitions.stfvec2mat(source_function: ndarray, xind: int, zind: int, m: int, n: int, cpml: int, yind: int = None) → None

Converts a source time function vector to a matrix for 2D or 3D simulations.

Parameters:

  • sf (np.ndarray) – The source time function vector.

  • xind (int) – The index in the x-direction where the source is located.

  • zind (int) – The index in the z-direction where the source is located.

  • m (int) – The number of indices in the y-direction (height of the domain).

  • n (int) – The number of indices in the x-direction (width of the domain).

  • cpml (int) – The size of the Convolutional Perfectly Matched Layer (CPML) padding.

  • yind (Optional[int]) – The index in the y-direction where the source is located, for 3D simulations. Defaults to None for 2D simulations.

Returns:

None

This function arranges the source time function in the spatial domain and applies CPML padding.

seidart.routines.definitions.str2complex(strsplit: list) → ndarray

Convert a list of strings into a numpy array of complex numbers, where the first string is treated as an identifier (ID) and the subsequent strings represent complex numbers.

The function splits each string by ‘j’ to separate the real and imaginary parts of each complex number, then constructs a numpy array of complex numbers from these parts. The first element of the array is the ID.

Parameters:

strsplit (list) – A list of strings, where the first string is an ID and the remaining strings represent complex numbers in ‘realjimag’ format.

Returns:

A numpy array of complex numbers with the ID as the first element.

Return type:

np.ndarray

Note that the input list should follow the format [‘ID’, ‘real1jimag1’, ‘real2jimag2’, …], where ‘ID’ is an integer identifier, and ‘realNjimagN’ are the real and imaginary parts of the Nth complex number.