Skip to content

vibration.structural.building_response

Predicting the fundamental frequency of a building (ISO 4866 Annex D).

A vibration measurement on a building is read against the building’s own response, and that response starts with one number: the lowest natural frequency of the fundamental translation mode. Measure it when you can, says ISO 4866; Annex D is what to do when a direct measurement cannot be made, or when high damping, subcomponent resonances or other practical problems limit how useful it is.

The annex offers four empirical predictors and is candid about all of them. The simplest is the storey count, hertz, the same rule DIN 4150-3 prints in its 6.4 and this library already publishes as story_fundamental_frequency. The other three are the forms the period takes in national codes, each with a coefficient the codes disagree about:

with the height and the width parallel to the force, both in metres. The coefficients range over 0.014 to 0.03, over 0.087 to 0.109 and over 0.06 to 0.08 respectively, so the choice of code moves the answer by more than a factor of two in the first form alone.

D.2 closes by fitting one curve to measurements instead of to codes: hertz ( seconds) from a sample of 163 rectangular-plan buildings, printed as Figure D.1 with the data around it. Errors of ± 50 % are not uncommon, and D.2 says that is typical of what an empirical formula can do. D.3 then says something worth repeating, since it is the opposite of what a reader expects: computer models correlate worse with measured frequencies than does, because the model is only as good as its idea of what the building is made of.

Damping (D.4) has no predictor at all. Measured values between 0.5 % and 2.1 % of critical are what the annex reports for buildings where soil-structure interaction was negligible, and the two orthogonal translation modes of one building can differ widely. Damping is partly a function of how the building was put together, so anticipate large errors.

Everything here is an estimate with a stated error, which is the only honest way to use it: as the answer to “is the excitation anywhere near the building’s own frequency”, not as a frequency to design against.

Auto-generated from the source docstrings by scripts/generate_api_docs.py (make api-docs). Do not edit by hand.

BuildingFrequencyEstimate(
frequency_hz: float,
period_s: float,
model: Literal['stories', 'height', 'height_width', 'slenderness'],
coefficient: float | None,
height_m: float | None,
)

One predicted fundamental frequency, with the error it carries.

Attributes

Name Description
frequency_hz The predicted fundamental frequency.
period_s The same prediction as a period.
model Which of PERIOD_MODELS produced it. One of "stories", "height", "height_width" or "slenderness".
coefficient The code coefficient used, or None for the storey model, which has none.
height_m The height it was computed from, where the model uses one.

property

The ± 50 % band of D.2 around frequency_hz.

BuildingFrequencyEstimate.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Draw Figure D.1 with this estimate on it.

The f = 46/h line against height on logarithmic axes, the ± 50 % band around it, and this estimate as a point.

Requires matplotlib (the [plot] extra); returns the Axes.

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to phonometry._plot.vibration.plot_building_frequency.

Raises

Exception When
ValueError If the estimate came from the storey model, which has no height to place a point at.

Constant (tuple).

DAMPING_RATIO_RANGE = (0.005, 0.021)
empirical_frequency_bounds(frequency_hz: float) -> tuple[float, float]

The ± 50 % band D.2 puts around an empirical prediction, in hertz.

Parameters

Name Description
frequency_hz A predicted fundamental frequency, in hertz.

Returns: (lower, upper), the band the annex says is not uncommon.

Raises

Exception When
ValueError If the frequency is not positive and finite.
TypeError if frequency_hz is not a single number.

Constant (float).

EMPIRICAL_FREQUENCY_ERROR = 0.5
estimate_fundamental_frequency(
model: Literal['stories', 'height', 'height_width', 'slenderness'],
*,
n_stories: int | np.integer[Any] | None = None,
height_m: float | None = None,
width_m: float | None = None,
coefficient: float | None = None,
) -> BuildingFrequencyEstimate

One prediction, bundled with the coefficient and the error band.

Parameters

Name Description
model One of PERIOD_MODELS. One of "stories", "height", "height_width" or "slenderness".
n_stories Number of storeys n, for the storey model.
height_m Height h above the base, in metres.
width_m Width b parallel to the force, in metres.
coefficient The code coefficient, or None for the midpoint.

Returns: The prediction, as a BuildingFrequencyEstimate.

Raises

Exception When
ValueError For anything fundamental_period refuses.
TypeError if coefficient is not a single number, or model is not a text. height_m is refused the same way when it is not one real number.
fundamental_frequency(
model: Literal['stories', 'height', 'height_width', 'slenderness'],
*,
n_stories: int | np.integer[Any] | None = None,
height_m: float | None = None,
width_m: float | None = None,
coefficient: float | None = None,
) -> float

The reciprocal of fundamental_period, in hertz.

Arguments and errors are that function’s; this exists because the annex states two of its four predictors as frequencies and two as periods, and a reader should not have to remember which.

Parameters

Name Description
model One of PERIOD_MODELS. One of "stories", "height", "height_width" or "slenderness".
n_stories Number of storeys n, for the storey model.
height_m Height h above the base, in metres.
width_m Width b parallel to the force, in metres.
coefficient The code coefficient, or None for the midpoint.

Returns: The fundamental frequency, in hertz.

Raises

Exception When
TypeError if model is not a text.
fundamental_period(
model: Literal['stories', 'height', 'height_width', 'slenderness'],
*,
n_stories: int | np.integer[Any] | None = None,
height_m: float | None = None,
width_m: float | None = None,
coefficient: float | None = None,
) -> float

The fundamental translation period of a building, in seconds (D.2).

Four predictors, and which arguments are needed depends on which:

  • "stories" needs n_stories: .
  • "height" needs height_m: .
  • "height_width" needs both and width_m: .
  • "slenderness" needs both: .

The coefficient defaults to the midpoint of the range D.2 prints for that form, since the annex gives a range and no way to choose inside it; state coefficient to use the value of a particular code.

Parameters

Name Description
model One of PERIOD_MODELS. One of "stories", "height", "height_width" or "slenderness".
n_stories Number of storeys n, for the storey model.
height_m Height h above the base, in metres.
width_m Width b parallel to the force, in metres.
coefficient The code coefficient, or None for the midpoint of PERIOD_COEFFICIENT_RANGES. Not accepted by the storey model, which has no coefficient to choose.

Returns: The fundamental period, in seconds.

Raises

Exception When
ValueError If the model is not one of the four, if an argument the model needs is missing or not positive, or if an argument the model does not use is given.
TypeError if model is not a text, or coefficient, height_m or width_m is not a single number.

Constant (float).

HEIGHT_FREQUENCY_CONSTANT_HZ_M = 46.0
height_fundamental_frequency(
height_m: float | np.floating[Any] | np.integer[Any],
) -> float
height_fundamental_frequency(
height_m: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
height_fundamental_frequency(
height_m: NumericArrayLike,
) -> float | NDArray[np.float64]

The f = 46/h fit D.2 closes with, in hertz.

Fitted to 163 rectangular-plan buildings rather than taken from a code, which is why it is here on its own: D.3 goes on to report that computed frequencies correlate with measurement worse than this line does.

Parameters

Name Description
height_m Height h above the base, in metres (scalar or array).

Returns: The predicted fundamental frequency, in hertz; a float for a number; an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If a height is not positive and finite.
TypeError if height_m holds a text or a value that is not a real number.

Constant (float).

HEIGHT_PERIOD_COEFFICIENT_S_PER_M = 0.022

Constant (mapping).

PERIOD_COEFFICIENT_RANGES = {'height': (0.014, 0.03), 'height_width': (0.087, 0.109), 'slenderness': (0.06, 0.08)}

Constant (tuple).

PERIOD_MODELS = ('stories', 'height', 'height_width', 'slenderness')

Constant (float).

STORY_PERIOD_COEFFICIENT_S = 0.1