vibration.structural.building_damage
La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.
Effects of vibration on structures (DIN 4150-3:1999-02).
A pile driver, a passing tram or a blast puts vibration into the ground, and the question the neighbours ask is whether the building will crack. DIN 4150-3 answers it the way an engineering practice can afford to: not with a stress calculation, but with guideline values (Anhaltswerte) for one measured quantity, the peak particle velocity, drawn from a large body of measurements on real buildings. Keep under them and damage of the kind the standard defines has not been observed; exceed them and it does not follow that damage occurs, only that the cheap check no longer settles the question and Clauses 4.2 to 4.4 have to be done properly.
What is measured (5.1). At the foundation, the largest of the three components , , of the particle velocity, as a peak, each treated on its own; the standard calls it and then writes it . In the topmost floor plane, the larger of the two horizontal components, measured at the outside wall, which is the building’s horizontal answer to the foundation excitation rather than a new excitation.
Short-term vibration (Clause 5) is vibration that does not occur often enough for resonance to build up in the structure. Table 1 gives its guideline values by building class, and at the foundation they depend on frequency: a building tolerates a fast wiggle better than a slow one, so the value rises from 1 Hz to 100 Hz. Between the printed frequencies the guideline is read off Bild 1, which joins the corner values by straight lines on a linear frequency axis; above 100 Hz the 100 Hz value may be used. In the topmost floor plane one value covers all frequencies.
Long-term vibration (Clause 6, Dauererschütterungen) is the opposite case: often enough for the structure to respond at its own frequencies. Table 3 drops to a single value per class in the topmost floor plane, roughly a quarter of the short-term one, and prints no frequency dependence at all.
Buried pipelines (5.3) are judged on their own Table 2 by pipe material, measured on the pipe, and long-term vibration halves those values (6.3).
Three sizing rules travel with the tables and are here because a reader who has the tables needs them in the same breath:
- Ceilings and floors (5.2) are separately covered by a vertical mm/s at the point of largest vibration, usually mid-span.
- Massive engineering structures such as reinforced-concrete abutments and block foundations may take twice the row 1 values of Table 1 (5.1).
- The lowest horizontal natural frequency of a building of five storeys or
more is roughly with the storey count
(6.4), which is the estimate that tells you whether the topmost floor plane
will be excited at all. DIN 4150-1 prints it as Formula (4) and ISO 4866 in
D.2, and
story_fundamental_frequencyis the one function for all three.
Clause 6.2 turns a measured velocity into a bending stress for a beam or a one-way slab vibrating in one mode, which is the bridge from this guideline check to the stress calculation of 4.2:
The guideline values are not limits in the legal sense and not an acceptance specification. They are where experience says the question stops being worth asking.
Auto-generated from the source docstrings by
scripts/generate_api_docs.py(make api-docs). Do not edit by hand.
assess_building_vibration
Section titled “assess_building_vibration”assess_building_vibration( velocity_mm_s: float, *, building_class: Literal['commercial', 'residential', 'sensitive'], frequency_hz: float | None = None, location: Literal['foundation', 'top_floor'] = 'foundation', duration: Literal['short_term', 'long_term'] = 'short_term', massive_structure: bool = False,) -> DamageAssessmentCompare one measured peak velocity with its guideline value.
Parameters
| Name | Description |
|---|---|
velocity_mm_s |
The measured peak velocity, in millimetres per second; see DamageAssessment for which component it is. Zero is accepted and keeps to every guideline value. |
building_class |
One of BUILDING_CLASSES. One of "commercial", "residential" or "sensitive". |
frequency_hz |
Frequency of the dominant component, in hertz. Required for the short-term foundation case. |
location |
"foundation" (default) or "top_floor". |
duration |
"short_term" (default) or "long_term". |
massive_structure |
See guideline_velocity. |
Returns: The comparison, as a DamageAssessment.
Raises
| Exception | When |
|---|---|
| ValueError | If the velocity is negative or not finite, or for any reason guideline_velocity raises. |
| TypeError | if velocity_mm_s is not a single number, or building_class, duration or location is not a text. frequency_hz is refused the same way when it is not one real number. |
bending_stress
Section titled “bending_stress”bending_stress( peak_velocity_m_s: float | np.floating[Any] | np.integer[Any], *, dynamic_modulus_pa: float, density: float, load_ratio: float = 1.0, mode_factor: float = 1.0,) -> float
bending_stress( peak_velocity_m_s: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]], *, dynamic_modulus_pa: float, density: float, load_ratio: float = 1.0, mode_factor: float = 1.0,) -> NDArray[np.float64]
bending_stress( peak_velocity_m_s: NumericArrayLike, *, dynamic_modulus_pa: float, density: float, load_ratio: float = 1.0, mode_factor: float = 1.0,) -> float | NDArray[np.float64]Peak bending stress from a peak velocity, Formula (1) of 6.2.
For a beam or a one-way slab of full rectangular section, constant stiffness and uniform mass, vibrating in one mode, the peak bending stress follows from the peak velocity alone:
The system dimensions do not enter, which is the point of the formula: a velocity measured where the amplitude is largest is enough. The mode factor lies between 1 and 1.3 in the technically important cases, so it moves the answer by less than a third.
Parameters
| Name | Description |
|---|---|
peak_velocity_m_s |
Peak velocity over the beam length, in metres per second (scalar or array). Note the unit: the guideline tables are in millimetres per second and this formula is not. |
dynamic_modulus_pa |
Dynamic modulus of elasticity , in pascals. |
density |
Material density , in kilograms per cubic metre. |
load_ratio |
The load coefficient , the beam’s own weight plus any uniformly distributed load it carries over its own weight. 1 for a beam carrying nothing else. |
mode_factor |
The mode coefficient , dimensionless. |
Returns: The peak bending stress, in pascals; a float for a number; an array for a sequence or an array, a zero-dimensional one included.
Raises
| Exception | When |
|---|---|
| ValueError | If a material property, the load ratio or the mode factor is not positive and finite, or a velocity is negative. |
| TypeError | if density, dynamic_modulus_pa, load_ratio or mode_factor is not a single number, or peak_velocity_m_s holds a text or a value that is not a real number. |
BENDING_STRESS_CONSTANT
Section titled “BENDING_STRESS_CONSTANT”Constant (float).
BENDING_STRESS_CONSTANT = 1.73BUILDING_CLASSES
Section titled “BUILDING_CLASSES”Constant (tuple).
BUILDING_CLASSES = ('commercial', 'residential', 'sensitive')BuildingDamageWarning
Section titled “BuildingDamageWarning”A DIN 4150-3 rule is used outside the range the standard offers it for.
Raised by story_fundamental_frequency below
STORY_FREQUENCY_MIN_STORIES. The estimate is still returned:
DIN 4150-3 6.4 offers 10 / n from about five storeys up, DIN 4150-1
Formula (4) for five and more, ISO 4866 D.2 for tall buildings, and below
five none of them says anything, so the number is an extrapolation
rather than the rule.
DamageAssessment
Section titled “DamageAssessment”DamageAssessment( velocity_mm_s: float, building_class: Literal['commercial', 'residential', 'sensitive'], location: Literal['foundation', 'top_floor'], duration: Literal['short_term', 'long_term'], frequency_hz: float | None, *, massive_structure: bool = False,)One measured velocity against the guideline value it is judged by.
Attributes
| Name | Description |
|---|---|
velocity_mm_s |
The measured peak velocity, in millimetres per second: the largest of the three components at the foundation, or the larger of the two horizontal components in the topmost floor plane. |
building_class |
The row of Table 1 or Table 3 that was used. One of "commercial", "residential" or "sensitive". |
location |
Where the velocity was measured. One of "foundation" or "top_floor". |
duration |
Which clause the guideline came from. One of "short_term" or "long_term". |
frequency_hz |
The frequency the guideline was read at, or None where the guideline does not depend on frequency. |
massive_structure |
Whether the row 1 values were raised by MASSIVE_STRUCTURE_FACTOR, the allowance 5.1 leaves to the assessor for a massive engineering structure. |
The guideline value (guideline_mm_s) is read from Table 1 or
Table 3 with those, so an assessment cannot be built against another
value.
DamageAssessment.guideline_mm_s
Section titled “DamageAssessment.guideline_mm_s”property
The guideline value the velocity is compared with, in mm/s.
DamageAssessment.plot()
Section titled “DamageAssessment.plot()”DamageAssessment.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesDraw Bild 1 with this measurement on it.
The three foundation curves of Table 1 against frequency, and the measured velocity as a point, so the margin is read rather than computed.
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_damage_assessment. |
DamageAssessment.ratio
Section titled “DamageAssessment.ratio”property
The measured velocity as a fraction of the guideline value.
DamageAssessment.within_guideline
Section titled “DamageAssessment.within_guideline”property
Whether the measured velocity keeps to the guideline value.
True is the whole of what the standard promises: damage of the kind 4.5 defines has not, in the experience the tables are drawn from, been observed. False is not the converse, and 5.1 says so: exceeding a guideline value does not mean damage occurs, it means the question has to be answered by 4.2 to 4.4 instead.
FLOOR_VERTICAL_MM_S
Section titled “FLOOR_VERTICAL_MM_S”Constant (float).
FLOOR_VERTICAL_MM_S = 20.0FOUNDATION_FREQUENCIES_HZ
Section titled “FOUNDATION_FREQUENCIES_HZ”Constant (tuple).
FOUNDATION_FREQUENCIES_HZ = (1.0, 10.0, 50.0, 100.0)foundation_guideline_curve
Section titled “foundation_guideline_curve”foundation_guideline_curve( building_class: Literal['commercial', 'residential', 'sensitive'], frequency: NumericArrayLike | None = None,) -> GuidelineCurveBild 1 as two arrays: frequency and guideline velocity.
The corner points of Table 1 by default, which is the polyline Bild 1 draws; pass frequency to sample the same polyline elsewhere.
Parameters
| Name | Description |
|---|---|
building_class |
One of BUILDING_CLASSES. One of "commercial", "residential" or "sensitive". |
frequency |
Frequency or frequencies to sample at, in hertz, or None for the four corners of Table 1. |
Returns: The frequencies and the guideline velocities, as a GuidelineCurve.
Raises
| Exception | When |
|---|---|
| ValueError | If the class is not one of the three, or a frequency is not positive and finite. |
| TypeError | if building_class is not a text, or frequency holds a text or a value that is not a real number. |
guideline_velocity
Section titled “guideline_velocity”guideline_velocity( building_class: Literal['commercial', 'residential', 'sensitive'], frequency: float | np.floating[Any] | np.integer[Any] | None = None, *, location: Literal['foundation', 'top_floor'] = 'foundation', duration: Literal['short_term', 'long_term'] = 'short_term', massive_structure: bool = False,) -> float
guideline_velocity( building_class: Literal['commercial', 'residential', 'sensitive'], frequency: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]], *, location: Literal['foundation', 'top_floor'] = 'foundation', duration: Literal['short_term', 'long_term'] = 'short_term', massive_structure: bool = False,) -> NDArray[np.float64]
guideline_velocity( building_class: Literal['commercial', 'residential', 'sensitive'], frequency: NumericArrayLike | None = None, *, location: Literal['foundation', 'top_floor'] = 'foundation', duration: Literal['short_term', 'long_term'] = 'short_term', massive_structure: bool = False,) -> float | NDArray[np.float64]The guideline peak velocity of Table 1 or Table 3, in mm/s.
At the foundation for short-term vibration the guideline is a function of frequency, read off Bild 1: constant below 10 Hz, then two straight segments joining the corner values of Table 1 on a linear frequency axis, and constant again above 100 Hz, since 5.1 allows the 100 Hz value to be used for anything faster. Everywhere else Table 1 and Table 3 print one number for all frequencies, and frequency is then not needed.
Parameters
| Name | Description |
|---|---|
building_class |
One of BUILDING_CLASSES. One of "commercial", "residential" or "sensitive". |
frequency |
Frequency of the dominant component, in hertz (scalar or array). Required for the short-term foundation case, and refused for every other one, where the printed value is the same at every frequency and a frequency would govern nothing. |
location |
"foundation" (default) or "top_floor". |
duration |
"short_term" (Table 1, default) or "long_term" (Table 3). |
massive_structure |
Raise the row 1 values by MASSIVE_STRUCTURE_FACTOR, which is the most 5.1 allows a massive engineering structure. The allowance is written for row 1 of Table 1 alone, so it applies to the commercial class and to short-term vibration, and is refused anywhere else. |
Returns: The guideline peak velocity, in millimetres per second: a float without a frequency or for a number; an array for a sequence or an array, a zero-dimensional one included.
Raises
| Exception | When |
|---|---|
| ValueError | If a name is not one of its choices, if the short-term foundation case is asked for without a frequency, if a frequency is given for a case that does not read one, if a frequency is not positive and finite, or if massive_structure is asked for outside row 1 of Table 1. |
| TypeError | if building_class, duration or location is not a text, or frequency holds a text or a value that is not a real number. |
GuidelineCurve
Section titled “GuidelineCurve”GuidelineCurve( frequencies: NDArray[np.float64], velocities_mm_s: NDArray[np.float64],)A guideline velocity polyline of DIN 4150-3 Bild 1, sampled.
What foundation_guideline_curve returns: the frequencies and the
guideline velocities, named, where a (frequency_hz, guideline_mm_s)
tuple used to be unpacked by position.
Attributes
| Name | Description |
|---|---|
frequencies |
The frequencies, in hertz. |
velocities_mm_s |
The guideline velocity at each, in mm/s. |
LONG_TERM_TOP_FLOOR_MM_S
Section titled “LONG_TERM_TOP_FLOOR_MM_S”Constant (mapping).
LONG_TERM_TOP_FLOOR_MM_S = {'commercial': 10.0, 'residential': 5.0, 'sensitive': 2.5}MASSIVE_STRUCTURE_FACTOR
Section titled “MASSIVE_STRUCTURE_FACTOR”Constant (float).
MASSIVE_STRUCTURE_FACTOR = 2.0pipeline_guideline_velocity
Section titled “pipeline_guideline_velocity”pipeline_guideline_velocity( material: Literal['welded_steel', 'concrete_or_flanged_metal', 'masonry_or_plastic'], *, duration: Literal['short_term', 'long_term'] = 'short_term',) -> floatThe guideline peak velocity on a buried pipeline (Table 2), in mm/s.
Measured on the pipe itself; a substitute measurement at the ground surface above it only estimates the value (5.3, D.1). Long-term vibration halves the table, which is what 6.3 allows without further evidence.
Parameters
| Name | Description |
|---|---|
material |
One of PIPELINE_MATERIALS. One of "welded_steel", "concrete_or_flanged_metal" or "masonry_or_plastic". |
duration |
"short_term" (default) or "long_term". |
Returns: The guideline peak velocity, in millimetres per second.
Raises
| Exception | When |
|---|---|
| ValueError | If a name is not one of its choices. |
| TypeError | if duration or material is not a text. |
PIPELINE_LONG_TERM_FACTOR
Section titled “PIPELINE_LONG_TERM_FACTOR”Constant (float).
PIPELINE_LONG_TERM_FACTOR = 0.5PIPELINE_MATERIALS
Section titled “PIPELINE_MATERIALS”Constant (tuple).
PIPELINE_MATERIALS = ('welded_steel', 'concrete_or_flanged_metal', 'masonry_or_plastic')PIPELINE_MM_S
Section titled “PIPELINE_MM_S”Constant (mapping).
PIPELINE_MM_S = {'welded_steel': 100.0, 'concrete_or_flanged_metal': 80.0, 'masonry_or_plastic': 50.0}SHORT_TERM_FOUNDATION_MM_S
Section titled “SHORT_TERM_FOUNDATION_MM_S”Constant (mapping).
SHORT_TERM_FOUNDATION_MM_S = {'commercial': (20.0, 20.0, 40.0, 50.0), 'residential': (5.0, 5.0, 15.0, 20.0), 'sensitive': (3.0, 3.0, 8.0, 10.0)}SHORT_TERM_TOP_FLOOR_MM_S
Section titled “SHORT_TERM_TOP_FLOOR_MM_S”Constant (mapping).
SHORT_TERM_TOP_FLOOR_MM_S = {'commercial': 40.0, 'residential': 15.0, 'sensitive': 8.0}STORY_FREQUENCY_MIN_STORIES
Section titled “STORY_FREQUENCY_MIN_STORIES”Constant (int).
STORY_FREQUENCY_MIN_STORIES = 5STORY_FREQUENCY_NUMERATOR_HZ
Section titled “STORY_FREQUENCY_NUMERATOR_HZ”Constant (float).
STORY_FREQUENCY_NUMERATOR_HZ = 10.0story_fundamental_frequency
Section titled “story_fundamental_frequency”story_fundamental_frequency(n_stories: int | np.integer[Any]) -> floatThe rough lowest horizontal natural frequency of a building.
f ~ 10 / n, offered for buildings from about five storeys up. Three
documents print the same estimate: DIN 4150-3:1999-02 6.4 (the
Stockwerkgleichung, from about five storeys), DIN 4150-1:2001-06
Formula (4) (five storeys and more) and ISO 4866:2010 D.2 (the simplest
of the empirical formulae for tall buildings), so this is the one
function for all three. It is a rough estimate and the standards say so;
its use is to tell whether the excitation is anywhere near the frequency
at which the topmost floor plane will answer.
Parameters
| Name | Description |
|---|---|
n_stories |
The number of storeys n. |
Returns: The estimated lowest horizontal natural frequency, in hertz.
Raises
| Exception | When |
|---|---|
| TypeError | If n_stories is a bool, a text or an array rather than a number. |
| ValueError | If the storey count is not a whole number of at least 1. |
Warns
| Warning | When |
|---|---|
| BuildingDamageWarning | Below STORY_FREQUENCY_MIN_STORIES, where the estimate is an extrapolation of a rule the standard offers for taller buildings. |