Vs_Profile#

class PySeismoSoil.class_Vs_profile.Vs_Profile(data: str | numpy.ndarray, *, damping_unit: Literal['1', '%'] = '1', density_unit: Literal['kg/m^3', 'g/cm^3', 'kg/m3', 'g/cm3'] = 'kg/m^3', sep: str = '\t', add_halfspace: bool = False, xi_rho_formula: Literal[1, 2, 3] = 3, **kwargs_to_genfromtxt: dict[Any, Any])[source]#

Bases: object

Class implementation of a Vs profile

Parameters:

  • data (str | np.ndarray) –

    If str: the full file name on the hard drive containing the data. If np.ndarray: the numpy array containing the Vs profile data. The provided data needs to have either 2 or 5 columns.

    The correct format for a Vs profile should be:

    Thickness (m)

    Vs (m/s)

    Damping

    Density

    Material Number

    …

    …

    …

    …

    …

    Note that the surface layer is recommended to have a thickness of at least 1.0 meter, to ensure realistic overburden pressure.

    (The “material numbers” are integer indices that map each layer to their G/Gmax and damping curves.)

  • damping_unit (Literal['1', '%']) – The unit for the damping ratio.

  • density_unit (Literal['kg/m^3', 'g/cm^3', 'kg/m3', 'g/cm3']) – The unit for the mass density of soils.

  • sep (str) – Delimiter character for reading the text file. If data is supplied as a numpy array, this parameter is ignored.

  • add_halfspace (bool) – If True, add a “half space” (represented by a layer of 0 m thickness) at the bottom of the profile, if such a layer does not already exist.

  • xi_rho_formula (Literal[1, 2, 3]) – The formula identifier to determine damping and mass density. See the documentation of helper_site_response.get_xi_rho() for the definitions of these three identifiers.

  • **kwargs_to_genfromtxt (dict[Any, Any]) – Any extra keyword arguments will be passed to numpy.genfromtxt() function for loading the data from the hard drive (if applicable).

vs_profile#

The full 5-column Vs profile data. If the supplied Vs profile only has 2 columns, damping and density and material numbers are automatically filled in. The damping and density values are automatically converted to have SI units.

Type:

np.ndarray

vs30#

The Vs30 value of this profile. (Definition of Vs30: reciprocal of the weighted average travel time through the top 30 m.) Unit: m/s.

Type:

float

damping_unit#

Same meaning as the input parameter.

Type:

str

density_unit#

Same meaning as the input parameter.

Type:

str

z_max#

Maximum depth of the profile. Unit: m.

Type:

float

n_layer#

Number of soil layers (not including the half space).

Type:

int

Raises:

ValueError – When the value of input arguments is incorrect or invalid

Methods Summary

get_ampl_function([show_fig, ...])

Get amplification function of the Vs profile.

get_basin_depth([bedrock_Vs])

Query the depth of the basin as indicated in the Vs profile data.

get_depth_array()

Return the depth array.

get_f0_BH()

Return the borehole fundamental frequency.

get_f0_RO()

Return the rock-outcrop fundamental frequency.

get_slowness()

Get "slowness" (reciprocal of wave velocity) as a 2D numpy array (including the thickness array).

get_transfer_function([show_fig, ...])

Get transfer function (complex-valued) of the Vs profile.

get_z1()

Get z1 (the depth to Vs = 1000 m/s).

output_as_km_unit()

Output the Vs profile in km and km/s unit.

plot([fig, ax, figsize, dpi])

Plot Vs profile.

query_Vs_at_depth(depth[, as_profile, show_fig])

Query Vs values at given depth values.

query_Vs_given_thk(thk[, n_layers, ...])

Query Vs values from a thickness layer thk.

summary()

Display the Vs profile on the console and plot Vs profile.

to_txt(fname[, sep, precision])

Write Vs profile to a text file.

truncate([depth, Vs])

Truncate Vs profile at a given depth, and "glue" the truncated profile to a given Vs.

Methods Documentation

get_ampl_function(show_fig: bool = False, freq_resolution: float = 0.05, fmax: float = 30.0) → tuple[PySeismoSoil.class_frequency_spectrum.Frequency_Spectrum, PySeismoSoil.class_frequency_spectrum.Frequency_Spectrum, PySeismoSoil.class_frequency_spectrum.Frequency_Spectrum][source]#

Get amplification function of the Vs profile.

Parameters:

  • show_fig (bool) – Whether show figures of the amplification function.

  • freq_resolution (float) – Frequency resolution of the frequency spectrum.

  • fmax (float) – Maximum frequency of interest.

Returns:

  • af_RO (Frequency_Spectrum) – Amplification function between soil surface and rock outcrop.

  • af_BH (Frequency_Spectrum) – Amplification function between soil surface and borehole.

  • af_IN (Frequency_Spectrum) – Amplification function between soil surface and incident motion.

get_basin_depth(bedrock_Vs: float = 1000.0) → float[source]#

Query the depth of the basin as indicated in the Vs profile data. The basin is defined as the material whose Vs is at least bedrock_Vs.

Parameters:

bedrock_Vs (float) – The shear-wave velocity that you consider as the bedrock.

Returns:

basin_depth – The basin depth. If no Vs values in the profile reaches bedrock_Vs, return total depth (bottom) of the profile.

Return type:

float

get_depth_array() → ndarray[source]#

Return the depth array.

Returns:

dep – The depth array of the Vs profile.

Return type:

np.ndarray

get_f0_BH() → float[source]#

Return the borehole fundamental frequency.

Returns:

f0_BH – Borehole fundamental frequency.

Return type:

float

get_f0_RO() → float[source]#

Return the rock-outcrop fundamental frequency.

Returns:

f0_RO – Rock-outcrop fundamental frequency.

Return type:

float

get_slowness() → ndarray[source]#

Get “slowness” (reciprocal of wave velocity) as a 2D numpy array (including the thickness array).

Returns:

slowness – The slowness array.

Return type:

np.ndarray

get_transfer_function(show_fig: bool = False, freq_resolution: float = 0.05, fmax: float = 30.0) → tuple[PySeismoSoil.class_frequency_spectrum.Frequency_Spectrum, PySeismoSoil.class_frequency_spectrum.Frequency_Spectrum, PySeismoSoil.class_frequency_spectrum.Frequency_Spectrum][source]#

Get transfer function (complex-valued) of the Vs profile.

Parameters:

  • show_fig (bool) – Whether show figures of the transfer function.

  • freq_resolution (float) – Frequency resolution of the frequency spectrum.

  • fmax (float) – Maximum frequency of interest.

Returns:

  • tf_RO (Frequency_Spectrum) – Transfer function between soil surface and rock outcrop.

  • tf_BH (Frequency_Spectrum) – Transfer function between soil surface and borehole.

  • tf_IN (Frequency_Spectrum) – Transfer function between soil surface and incident motion.

get_z1() → float[source]#

Get z1 (the depth to Vs = 1000 m/s).

Returns:

z1 – The depth to Vs = 1000 m/s.

Return type:

float

output_as_km_unit() → ndarray[source]#

Output the Vs profile in km and km/s unit.

Returns:

The Vs profile in km and km/s unit.

Return type:

np.ndarray

plot(fig: matplotlib.figure.Figure | None = None, ax: matplotlib.axes._axes.Axes | None = None, figsize: tuple[float, float] = (2.6, 3.2), dpi: float = 100, **kwargs: dict[Any, Any]) → tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes, matplotlib.lines.Line2D][source]#

Plot Vs profile.

Parameters:

  • fig (Figure | None) – Figure object. If None, a new figure will be created.

  • ax (Axes | None) – Axes object. If None, a new axes will be created.

  • figsize (tuple[float, float]) – Figure size in inches, as a tuple of two numbers. The figure size of fig (if not None) will override this parameter.

  • dpi (float) – Figure resolution. The dpi of fig (if not None) will override this parameter.

  • **kwargs (dict[Any, Any]) – Extra keyword arguments to be passed to the function helper_site_response.plot_Vs_profile().

Returns:

  • fig (Figure) – The figure object being created or being passed into this function.

  • ax (Axes) – The axes object being created or being passed into this function.

  • h_line (Line2D) – The line object.

query_Vs_at_depth(depth: float | numpy.ndarray, as_profile: bool = False, show_fig: bool = False) → float | numpy.ndarray | PySeismoSoil.class_Vs_profile.Vs_Profile[source]#

Query Vs values at given depth values. If the given depth values happen to be at layer interfaces, return the Vs of the layer below the interface.

Parameters:

  • depth (float | np.ndarray) – Value(s) of depths to query the Vs value at. Unit should be m.

  • as_profile (bool) – If True, return a Vs profile object. If False, only return the array of Vs.

  • show_fig (bool) – Whether to show a figure

Returns:

vs_array – Vs values corresponding to the given depths. Its type depends on the type of depth.

Return type:

float | np.ndarray | Vs_Profile

Raises:

ValueError – When the values of some input arguments are incorrect or invalid

query_Vs_given_thk(thk: float | numpy.ndarray, n_layers: int | None = None, as_profile: bool = False, at_midpoint: bool = True, add_halfspace: bool = True, show_fig: bool = False) → numpy.ndarray | PySeismoSoil.class_Vs_profile.Vs_Profile[source]#

Query Vs values from a thickness layer thk. The starting point of querying is the ground surface.

Parameters:

  • thk (float | np.ndarray) – Thickness array, or a single value that means a constant thickness.

  • n_layers (int | None) – Number of layers to query. This parameter has no effect if thk is a numpy array (because the number of layers can be inferred from thk). If None, it is automatically inferred from thk and the maximum depth of the profile.

  • as_profile (bool) – If True, return a Vs profile object. If False, only return the array of Vs.

  • at_midpoint (bool) – If True, the Vs values are queried at the mid-point depths of each layer. If False, at the top of each layer.

  • add_halfspace (bool) – If True, add a “half space” (represented by a layer of 0 m thickness) at the bottom, if such a layer does not already exist.

  • show_fig (bool) – Whether to show a figure

Returns:

vs_array – Vs values corresponding to the given depths. Its type depends on as_profile.

Return type:

np.ndarray | Vs_Profile

summary() → None[source]#

Display the Vs profile on the console and plot Vs profile.

to_txt(fname: str, sep: str = '\t', precision: tuple[str, str, str, str, str] = ('%.2f', '%.2f', '%.4g', '%.5g', '%d')) → None[source]#

Write Vs profile to a text file.

Parameters:

  • fname (str) – File name (including path).

  • sep (str) – Delimiter for the output file.

  • precision (tuple[str, str, str, str, str]) – A list of precision specifiers, each for the five columns of the Vs profile.

Raises:

  • TypeError – When precision is not a list

  • ValueError – When the length of precision is not 5

truncate(depth: float | None = None, Vs: float = 1000.0) → Vs_Profile[source]#

Truncate Vs profile at a given depth, and “glue” the truncated profile to a given Vs.

Parameters:

  • depth (float | None) – The depth at which to truncate the original Vs profile. It can be deeper than z_max (total depth).

  • Vs (float) – The velocity of the bedrock.

Returns:

truncated – The truncated Vs profile.

Return type:

Vs_Profile

Raises:

ValueError – When the value of the input argument is incorrect or invalid