TransferFunction

TransferFunction(soil_profile: List[Dict] = None, rock: Dict = None, f_max: float = 20.0, n_freqs: int = 2000)

Initialize the transfer function calculator.

This constructor sets up the transfer function calculator with the given soil profile
and rock properties. The transfer function is computed immediately upon initialization.
Since this is a singleton, subsequent initializations with different parameters will
update the existing instance.

Args:
    soil_profile (List[Dict]): List of dictionaries containing soil layer properties.
        Each dictionary must contain:
        - h (float): Layer thickness in meters
        - vs (float): Shear wave velocity in m/s
        - rho (float): Mass density in kg/m³
        - damping (float, optional): Material damping ratio (default: 0.0)
    rock (Dict): Dictionary containing rock properties:
        - vs (float): Shear wave velocity in m/s
        - rho (float): Mass density in kg/m³
        - damping (float, optional): Material damping ratio (default: 0.0)
    f_max (float, optional): Highest frequency of interest in Hz. Defaults to 20.0.
    n_freqs (int, optional): Number of frequency points. Defaults to 2000.

Raises:
    ValueError: If required properties are missing in soil_profile or rock
    TypeError: If input types are incorrect

Example:

soil_profile = [ {"h": 2.0, "vs": 200.0, "rho": 1500.0, "damping": 0.05}, {"h": 54.0, "vs": 400.0, "rho": 1500.0, "damping": 0.05} ] rock = {"vs": 850.0, "rho": 1500.0, "damping": 0.05} tf = TransferFunction(soil_profile, rock, f_max=25.0)

Attributes

_instance `class-attribute` `instance-attribute`

_instance = None

_initialized `class-attribute` `instance-attribute`

_initialized = False

soil_profile `instance-attribute`

soil_profile = soil_profile

rock `instance-attribute`

rock = rock

f_max `instance-attribute`

f_max = f_max

n_freqs `instance-attribute`

n_freqs = n_freqs

f `instance-attribute`

f = None

TF_uu `instance-attribute`

TF_uu = None

TF_inc `instance-attribute`

TF_inc = None

computed `instance-attribute`

computed = False

Methods:

new

__new__(soil_profile: List[Dict] = None, rock: Dict = None, f_max: float = 20.0, n_freqs: int = 2000)

Create or return the singleton instance of TransferFunction.

_get_DRM_points `staticmethod`

_get_DRM_points(mesh: UnstructuredGrid, props: Dict[str, Any]) -> np.ndarray

Extract DRM points from a mesh. Args: mesh (UnstructuredGrid): The mesh from which to extract points. Props (Dict[str, Any]): Dictionary containing properties of the mesh. - 'shape': Shape of the mesh (e.g., 'box', 'cylinder')

Returns:

Type	Description
`ndarray`	np.ndarray: Array of DRM points.

_get_DRM_soil_profile

_get_DRM_soil_profile(coords: ndarray)

Refine the soil profile based on the coordinates of the mesh.

Parameters:

Name	Type	Description	Default
`coords`	`ndarray`	Array of coordinates from the mesh.	required

Returns:

Type	Description
	List[Dict]: Refined soil profile.

createDRM

createDRM(mesh: UnstructuredGrid, props: Dict[str, Any], time_history: TimeHistory, filename: str = 'drmload.h5drm', pad_factor: float = 0.05, progress_bar: Optional[tqdm] = None) -> None

Generates a Dynamic Response Modification (DRM) load file for use in OpenSees simulations. This method computes the DRM loads by applying a transfer function to the input acceleration time history, processes the resulting acceleration, velocity, and displacement histories, and writes the results to an HDF5 file. Parameters

UnstructuredGrid

The finite element mesh representing the domain for which the DRM loads are to be computed.

props : Dict[str, Any] Dictionary containing the shape and other properties of the mesh. time_history : TimeHistory Object containing the acceleration time history and related metadata (e.g., time step, units). filename : str, optional Name of the output HDF5 file to store the DRM loads (default is "drmload.h5drm"). pad_factor : float, optional Fraction of the time history length to use for zero-padding at the beginning and end (default is 0.05). progress_bar : Optional[tqdm], optional Progress bar object for tracking computation progress. If None, a new tqdm progress bar is created. Returns

None Raises

Notes

The method applies zero-padding to the acceleration time history to minimize edge effects in the frequency domain.
The transfer function is computed for all soil layers and applied in the frequency domain.
Baseline correction and trend removal are performed on the displacement history.
The resulting acceleration, velocity, and displacement histories are written to an HDF5 file compatible with OpenSees DRM input.

_write_h5drm

_write_h5drm(acc, h, time, vel, disp, coords, internal, filename: str = 'drmload.h5drm')

    Writes DRM (Domain Reduction Method) data to an H5DRM file in HDF5 format.
    This method organizes and stores acceleration, velocity, displacement, and coordinate data,
    along with relevant metadata, into a structured HDF5 file for use in DRM-based simulations.
        acc (np.ndarray): Acceleration data array of shape (n_layers, n_timesteps).
        h (np.ndarray): Layer thicknesses or heights, used to compute cumulative depth.
        time (np.ndarray): 1D array of time steps.
        vel (np.ndarray): Velocity data array of shape (n_layers, n_timesteps).
        disp (np.ndarray): Displacement data array of shape (n_layers, n_timesteps).
        coords (np.ndarray): Array of node coordinates, shape (n_nodes, 3).
        internal (np.ndarray): Boolean array indicating internal nodes, shape (n_nodes,).
    Raises:
        ValueError: If any coordinate's depth does not match a DRM depth within a tolerance.
    Note:
        - The output file is overwritten if it exists.
        - Data is organized into two main groups: "DRM_Data" (containing the main arrays)
          and "DRM_Metadata" (containing simulation and box metadata).
        - Only the x-component of input data is used; y and z components are set to zero.
        - The function assumes that the input arrays are properly shaped and consistent.
Write the DRM data to an H5DRM file.

Args:

: Parameters for writing the DRM data.

Returns:
    None

compute_surface_motion

compute_surface_motion(time_history: TimeHistory, freqFlag: bool = False, acc_fftFlag: bool = False, surface_fftFlag: bool = False, pad_factor: float = 0.1) -> Dict[str, np.ndarray]

Compute surface motion using the transfer function.

Parameters:

Name	Type	Description	Default
`time_history`	`TimeHistory`	Input time history.	required
`freqFlag`	`bool`	If True, include frequency array in result.	`False`
`acc_fftFlag`	`bool`	If True, include input FFT in result.	`False`
`surface_fftFlag`	`bool`	If True, include output FFT in result.	`False`
`pad_factor`	`float`	Zero-padding factor (0 to 1, default 0.02).	`0.1`

Returns:

Type	Description
`Dict[str, ndarray]`	Dict[str, np.ndarray]: Dictionary with results.

_convolve

_convolve(time_history: TimeHistory, soil_profile: List[Dict] = None, return_all: bool = False) -> TimeHistory

Convolve the time history with the transfer function to get the surface motion.

Parameters:

Name	Type	Description	Default
`time_history`	`TimeHistory`	Input time history.	required
`soil_profile`	`List[Dict]`	Soil profile to use for convolution. If None, uses the default soil profile.	`None`

Returns: TimeHistory: Convolved time history object containing the surface motion.

plot_convolved_motion

plot_convolved_motion(time_history: TimeHistory, soil_profile: List[Dict] = None) -> matplotlib.figure.Figure

Plot the convolved motion from the incident wave to the surface motion. Args: time_history (TimeHistory): Input time history. soil_profile (List[Dict], optional): Soil profile to use for convolution. If None, uses the default soil profile. Returns: matplotlib.figure.Figure: The figure object containing the plot.

_deconvolve

_deconvolve(time_history: TimeHistory, soil_profile: List[Dict] = None, return_all: bool = False) -> TimeHistory

Deconvolve the time history from the surface motion to get the incident wave. Args: time_history (TimeHistory): Input time history. Returns: TimeHistory: Deconvolved time history object containing the incident wave.

plot_deconvolved_motion

plot_deconvolved_motion(time_history: TimeHistory, soil_profile: List[Dict] = None) -> matplotlib.figure.Figure

Plot the deconvolved motion from the surface motion to the incident wave. Args: time_history (TimeHistory): Input time history. soil_profile (List[Dict], optional): Soil profile to use for deconvolution. If None, uses the default soil profile. Returns: matplotlib.figure.Figure: The figure object containing the plot.

plot_surface_motion

plot_surface_motion(time_history: TimeHistory, soil_profile: List[Dict] = None, fig=None, **kwargs) -> matplotlib.figure.Figure

Plot the surface motion.

Parameters:

Name	Type	Description	Default
`time_history`	`TimeHistory`	Input time history.	required
`fig`	`Figure`	Existing figure to plot into. If None, a new figure will be created.	`None`
`**kwargs`		Additional plotting parameters	`{}`

Returns:

Type	Description
`Figure`	matplotlib.figure.Figure: The figure object containing the plot

compute

compute(frequency: ndarray = None, soil_profile: List[Dict] = None) -> Tuple[np.ndarray, np.ndarray, np.ndarray]

Compute the transfer functions for the soil profile using the transfer matrix method.

Returns:

Type	Description
`Tuple[ndarray, ndarray, ndarray]`	Tuple[np.ndarray, np.ndarray, np.ndarray]: - Frequencies in Hz - TF_uu: u_top/u_base - TF_inc: u_top/u_incident

compute_all_layers

compute_all_layers(frequency: ndarray = None, soil_profile: List[Dict] = None) -> Tuple[np.ndarray, np.ndarray, np.ndarray]

Compute the transfer functions for all layers in the soil profile. This method computes the transfer functions for all layers in the soil profile using the transfer matrix method. It returns the frequencies, transfer function matrices.

Parameters:

Name	Type	Description	Default
`frequency`	`ndarray`	Array of frequencies in Hz. If None, uses default frequency range.	`None`
`soil_profile`	`List[Dict]`	List of dictionaries containing soil layer properties. If None, uses the current soil profile.	`None`

Returns:

Type	Description
`Tuple[ndarray, ndarray, ndarray]`	Tuple[np.ndarray, np.ndarray, np.ndarray]: - Frequencies in Hz - TF_uu: Transfer function for u_top/u_base - TF_inc: Transfer function for u_top/u_incident

plot_soil_profile

plot_soil_profile(ax=None, **kwargs) -> matplotlib.figure.Figure

Plot the soil profile.

Parameters:

Name	Type	Description	Default
`ax`	`Axes`	Existing axes to plot into. If None, a new figure and axes will be created	`None`
`**kwargs`		Additional plotting parameters passed to matplotlib.pyplot	`{}`

Returns:

Type	Description
`Figure`	matplotlib.figure.Figure: The figure object containing the plot

add_layer

add_layer(layer: Dict, position: Optional[int] = None) -> None

Add a new soil layer to the profile.

This method adds a new soil layer to the profile at the specified position
and recomputes the transfer function.

Args:
    layer (Dict): Dictionary containing layer properties:
        - h (float): Layer thickness in meters
        - vs (float): Shear wave velocity in m/s
        - rho (float): Mass density in kg/m³
        - damping (float, optional): Material damping ratio
    position (Optional[int]): Position to insert the layer (0-based).
        If None, adds to the bottom of the profile.

Raises:
    ValueError: If required layer properties are missing
    IndexError: If position is out of range

Example:

tf.add_layer({"h": 5.0, "vs": 300.0, "rho": 1500.0, "damping": 0.05}) tf.add_layer({"h": 3.0, "vs": 250.0, "rho": 1500.0}, position=0)

remove_layer

remove_layer(position: int) -> None

Remove a soil layer from the profile.

This method removes a soil layer from the profile at the specified position
and recomputes the transfer function.

Args:
    position (int): Position of the layer to remove (0-based)

Raises:
    IndexError: If position is out of range

Example:

tf.remove_layer(0) # Remove the top layer

modify_layer

modify_layer(position: int, **properties) -> None

Modify properties of an existing soil layer.

This method updates the properties of a soil layer at the specified position
and recomputes the transfer function.

Args:
    position (int): Position of the layer to modify (0-based)
    **properties: Layer properties to update:
        - h (float): Layer thickness in meters
        - vs (float): Shear wave velocity in m/s
        - rho (float): Mass density in kg/m³
        - damping (float): Material damping ratio

Raises:
    IndexError: If position is out of range

Example:

tf.modify_layer(0, vs=250.0, damping=0.06) tf.modify_layer(1, h=10.0, rho=1600.0)

update_soil_profile

update_soil_profile(soil_profile: List[Dict]) -> None

Update the soil profile.

_check_soil_profile

_check_soil_profile(soil_profile: List[Dict]) -> bool

Check if the soil profile is valid. Args: soil_profile (List[Dict]): The soil profile to check.

Returns:

Name	Type	Description
`bool`	`bool`	True if the soil profile is valid, False otherwise.

Raises:

Type	Description
`ValueError`	If the soil profile is not valid.

update_rock

update_rock(rock: Dict) -> None

Update the rock properties.

_check_rock

_check_rock(rock: Dict) -> bool

Check if the rock properties are valid.

update_frequency

update_frequency(f_max: float) -> None

Update the maximum frequency of interest.

Args:
    f_max (float): New maximum frequency in Hz

Example:

tf.update_frequency(30.0)

get_total_depth

get_total_depth() -> float

Get the total depth of the soil profile.

Returns:
    float: Total depth of the soil profile in meters

Example:

depth = tf.get_total_depth() print(f"Total depth: {depth:.2f} m")

get_fundamental_frequency

get_fundamental_frequency() -> float

Estimate the fundamental frequency of the soil profile.

This method estimates the fundamental frequency by finding the frequency
at which the transfer function has its maximum amplification.

Returns:
    float: Fundamental frequency in Hz

Example:

f0 = tf.get_fundamental_frequency() print(f"Fundamental frequency: {f0:.2f} Hz")

get_amplification_factor

get_amplification_factor() -> float

Get the maximum amplification factor.

This method returns the maximum amplification factor from the transfer function,
which represents the maximum ratio of surface to base motion.

Returns:
    float: Maximum amplification factor

Example:

max_amp = tf.get_amplification_factor() print(f"Maximum amplification: {max_amp:.2f}")

get_layer_properties

get_layer_properties(position: int) -> Dict

Get properties of a specific layer.

This method returns a copy of the properties of the layer at the specified position.

Args:
    position (int): Position of the layer (0-based)

Returns:
    Dict: Dictionary containing layer properties:
        - h (float): Layer thickness in meters
        - vs (float): Shear wave velocity in m/s
        - rho (float): Mass density in kg/m³
        - damping (float): Material damping ratio

Raises:
    IndexError: If position is out of range

Example:

props = tf.get_layer_properties(0) print(f"Layer properties: {props}")

get_rock_properties

get_rock_properties() -> Dict

Get properties of the rock layer.

This method returns a copy of the properties of the underlying rock layer.

Returns:
    Dict: Dictionary containing rock properties:
        - vs (float): Shear wave velocity in m/s
        - rho (float): Mass density in kg/m³
        - damping (float): Material damping ratio

Example:

rock_props = tf.get_rock_properties() print(f"Rock properties: {rock_props}")

get_profile_summary

get_profile_summary() -> Dict

Get a comprehensive summary of the soil profile.

This method returns a dictionary containing various properties and
characteristics of the soil profile.

Returns:
    Dict: Dictionary containing:
        - total_depth (float): Total depth of the soil profile in meters
        - num_layers (int): Number of soil layers
        - layer_thicknesses (List[float]): List of layer thicknesses
        - fundamental_frequency (float): Fundamental frequency in Hz
        - max_amplification (float): Maximum amplification factor

Example:

summary = tf.get_profile_summary() print(f"Profile summary: {summary}")

TransferFunction