simdesign 1.2.1__tar.gz → 1.2.2__tar.gz

{simdesign-1.2.1 → simdesign-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simdesign
-Version: 1.2.1
+Version: 1.2.2
 Summary: The built environment data (BED) framework for enhancing seismic vulnerability modeling through simulated design.
 License: AGPL-3.0-or-later
 License-File: LICENSE

{simdesign-1.2.1 → simdesign-1.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "simdesign"
-version = "1.2.1"
+version = "1.2.2"
 description = "The built environment data (BED) framework for enhancing seismic vulnerability modeling through simulated design."
 authors = [
     "Volkan Ozsarac <volkan.ozsarac@iusspavia.it>",

{simdesign-1.2.1 → simdesign-1.2.2}/simdesign/rcmrf/bcim/factory.py

@@ -314,7 +314,7 @@ class BCIM:
     beta : List[float]
         Design lateral load factor.
     beta_v : List[float | None]
-        Vertical load factor.
+        Design vertical seismic load factor.
     num_storeys : List[int]
         Number of storeys.
     design_class : List[str]

{simdesign-1.2.1 → simdesign-1.2.2}/simdesign/rcmrf/bcim/parametrization.py

@@ -117,9 +117,12 @@ class TypicalStoreyHeight(BaseModel):
     Attributes
     ----------
     cv : float
-        Coefficient of variation (sigma/mu).
+        Coefficient of variation (standard deviation / mean) of the
+        log-normal distribution before truncation.
     mu : float
-        Mean value for the typical storey heights.
+        Mean (arithmetic) of the log-normal distribution before truncation.
+        The mean of the sampled typical storey heights differs from it
+        because of the truncation.
     lower_bound : float
         Lower bound value.
     upper_bound : float
@@ -153,24 +156,29 @@ class StandardBayWidth(BaseModel):
     Attributes
     ----------
     corr_coeff_xy : float
-        Correlation coefficient between bay widths in two principal
-        horizontal directions (-X and -Y).
+        Correlation coefficient between the standard normal variables from
+        which the bay widths in the two principal horizontal directions
+        (-X and -Y) are obtained (Gaussian copula). Because of the
+        truncation, the correlation between the bay widths themselves is
+        close to, but not equal to, it.
     lower_bound_x : float
         Lower bound of truncated log-normal distribution (-X).
     upper_bound_x : float
         Upper bound of truncated log-normal distribution (-X).
     theta_x : float
-        Median of log-normal distribution (-X).
+        Median of log-normal distribution before truncation (-X).
     sigma_x : float
-        Logarithmic standard deviation of the lognormal distribution (-X).
+        Logarithmic standard deviation of the lognormal distribution before
+        truncation (-X).
     lower_bound_y : float
         Lower bound of truncated log-normal distribution (-Y).
     upper_bound_y : float
         Upper bound of truncated log-normal distribution (-Y).
     theta_y : float
-        Median of log-normal distribution (-Y).
+        Median of log-normal distribution before truncation (-Y).
     sigma_y : float
-        Logarithmic standard deviation of the lognormal distribution (-Y).
+        Logarithmic standard deviation of the lognormal distribution before
+        truncation (-Y).
     """
     corr_coeff_xy: float
     lower_bound_x: float
@@ -235,7 +243,7 @@ class InputData(BaseModel):
     beta : float
         Design lateral load factor.
     beta_v : float | None
-        Vertical load factor.
+        Design vertical seismic load factor.
     num_storeys : int
         Number of storeys in the building.
     design_class : str

{simdesign-1.2.1 → simdesign-1.2.2}/simdesign/rcmrf/bcim/randomization.py

@@ -125,15 +125,20 @@ class Sampler:
         """Set staircase span lengths.
 
         Staircase span lengths are represented by uniform distribution.
+        The samples are rounded to 0.05 m.
 
         Parameters
         ----------
         lower_bound : float
             Lower boundary of the output interval.
-            All values generated will be greater than or equal to lower bound.
         upper_bound : float
             Upper boundary of the output interval.
-            All values generated will be less than or equal to upper bound.
+
+        Notes
+        -----
+        The samples are drawn from [lower_bound, upper_bound) and then
+        rounded to 0.05 m, so they may fall slightly outside the bounds
+        when these are not multiples of 0.05 m.
 
         Returns
         -------
@@ -162,21 +167,24 @@ class Sampler:
         Typical span lengths are represented with truncated log-normal
         distribution. It is assumed that span lengths are correlated.
         The samples are generated from multivariate truncated lognormal
-        distribution.
+        distribution, and rounded to 0.05 m.
 
         Parameters
         ----------
         corr_coeff : float
-            Correlation coefficient (between span lengths x and y).
+            Correlation coefficient between the standard normal variables
+            from which the span lengths in x and y are obtained (Gaussian
+            copula). Because of the truncation, the correlation between
+            the span lengths themselves is close to, but not equal to, it.
         lower_bound : Tuple[float]
             Lower bound for truncated log-normal distribution (x, y).
         upper_bound : Tuple[float]
             Upper bound for truncated log-normal distribution (x, y).
         theta : Tuple[float]
-            Median of log-normal distribution.
+            Median of the log-normal distribution before truncation (x, y).
         std_ln : Tuple[float]
             Logarithmic standard deviation of the log-normal
-            distribution (x, y).
+            distribution before truncation (x, y).
 
         Notes
         -----
@@ -248,14 +256,17 @@ class Sampler:
         """Set typical storey heights.
 
         Typical storey heights are represented with truncated log-normal
-        distribution.
+        distribution. The samples are rounded to 0.05 m.
 
         Parameters
         ----------
         cv : float
-            Coefficient of variation, s/mu.
+            Coefficient of variation (standard deviation / mean) of the
+            log-normal distribution before truncation.
         mu : float
-            Mean of normal distribution.
+            Mean (arithmetic, not logarithmic) of the log-normal
+            distribution before truncation. The mean of the samples
+            differs from it because of the truncation.
         lower_bound : float
             Lower bound of truncated log-normal distribution.
         upper_bound : float
@@ -310,8 +321,9 @@ class Sampler:
 
         Notes
         -----
-        1. `ground_storey_height = min(factor * typical_storey_heights,
-        max_height)`
+        1. `ground_storey_height = min(round_005(factor *
+        typical_storey_heights), max_height)`, where `round_005` rounds to
+        0.05 m.
         2. Factors have different probabilities.
 
         Examples
@@ -370,7 +382,7 @@ class Sampler:
         Composite slabs with pre-fabricated joists and ceramic blocks (3: HS).
         2. Slab type is assigned as HS, if minimum span length is greater than
         the upper limit for minimum solid slab span length
-        (minimum span length <= `max_ss_short_span`).
+        (minimum span length > `max_ss_short_span`).
         3. Otherwise, if the ratio of maximum to minimum span lengths is
         greater or equal to `max_ss2_aspect_ratio`, slab type is
         randomly as SS1 or HS based on `ss1_prob_given_ss1_or_hs`.

{simdesign-1.2.1 → simdesign-1.2.2}/simdesign/rcmrf/bdim/baselib/building.py

@@ -70,7 +70,7 @@ class TaxonomyData:
     design_class : str
         Building design class selected.
     beta_v : float, optional
-        Vertical load factor. By default None.
+        Design vertical seismic load factor. By default None.
     staircase_slab_depth : float, optional
         Depth of the staircase slabs. By default None.
     slab_thickness : float, optional

{simdesign-1.2.1 → simdesign-1.2.2}/simdesign/rcmrf/bdim/tr_post18_dch/loads.py

@@ -115,13 +115,19 @@ class Loads(LoadsBase):
         beta_v : float | None
             Vertical seismic coefficient. If None, it is taken as 0.0, i.e.,
             the vertical load effect is neglected.
+
+        Notes
+        -----
+        Seismic loading is added in vertical direction based on Sections
+        4.4.3.2 and 4.4.4.1 of TBEC-2018. Here, ``beta_v`` refers to the
+        short-period design spectral acceleration coefficient (SDS).
         """
         if beta_v is None:
             beta_v = 0.0
         seismic_strs = ["E+X", "E-X", "E+Y", "E-Y"]
         for combo in self.combinations:
             if any(item in seismic_strs for item in combo.loads.keys()):
-                if combo.loads.get("G") == 1.0:
+                if combo.loads.get("G") == 1.0:  # Eqn. 4.11
                     combo.loads["G"] = round(1.0 + 0.3 * (2/3) * beta_v, 2)
-                elif combo.loads.get("G") == 0.9:
+                elif combo.loads.get("G") == 0.9:  # Eqn. 4.12
                     combo.loads["G"] = round(0.9 - 0.3 * (2/3) * beta_v, 2)

{simdesign-1.2.1 → simdesign-1.2.2}/simdesign/rcmrf/bdim/tr_post18_dcm/loads.py

@@ -115,13 +115,19 @@ class Loads(LoadsBase):
         beta_v : float | None
             Vertical seismic coefficient. If None, it is taken as 0.0, i.e.,
             the vertical load effect is neglected.
+
+        Notes
+        -----
+        Seismic loading is added in vertical direction based on Sections
+        4.4.3.2 and 4.4.4.1 of TBEC-2018. Here, ``beta_v`` refers to the
+        short-period design spectral acceleration coefficient (SDS).
         """
         if beta_v is None:
             beta_v = 0.0
         seismic_strs = ["E+X", "E-X", "E+Y", "E-Y"]
         for combo in self.combinations:
             if any(item in seismic_strs for item in combo.loads.keys()):
-                if combo.loads.get("G") == 1.0:
+                if combo.loads.get("G") == 1.0:  # Eqn. 4.11
                     combo.loads["G"] = round(1.0 + 0.3 * (2/3) * beta_v, 2)
-                elif combo.loads.get("G") == 0.9:
+                elif combo.loads.get("G") == 0.9:  # Eqn. 4.12
                     combo.loads["G"] = round(0.9 - 0.3 * (2/3) * beta_v, 2)

{simdesign-1.2.1 → simdesign-1.2.2}/simdesign/utils/stats.py

@@ -69,7 +69,7 @@ def random_truncated_lognormal(size: int, mu: np.ndarray, sigma: np.ndarray,
 
 def truncated_lognormal_cdf_inv(
     cdf: np.ndarray, mu: np.ndarray, sigma: np.ndarray,
-    lower: np.ndarray, upper: float
+    lower: np.ndarray, upper: np.ndarray
 ) -> np.ndarray:
     """Inverts the truncated (lower-upper) log-normal CDF.
 
@@ -78,9 +78,10 @@ def truncated_lognormal_cdf_inv(
     cdf : np.ndarray
         The value of the cumulative distribution.
     mu : np.ndarray
-        Mean of the log-normal PDF.
+        Mean of the log-normal distribution in log-space, i.e., of ln(X).
     sigma : np.ndarray
-        Standard deviation of the log-normal PDF.
+        Standard deviation of the log-normal distribution in log-space,
+        i.e., of ln(X).
     lower : np.ndarray
         Lower truncation limit.
     upper : np.ndarray
@@ -265,8 +266,10 @@ def random_multivariate_truncated_lognormal(
     size : int
         Number of samples to generate.
     rho : np.ndarray
-        Correlation matrix (n x n) describing the relationships between
-        variables.
+        Correlation matrix (n x n) of the standard normal variables from
+        which the samples are obtained (Gaussian copula). Because of the
+        truncation, the correlations between the samples themselves are
+        close to, but not equal to, these values.
     lower_bound : np.ndarray
         Lower bounds for the truncated log-normal distributions.
     upper_bound : np.ndarray
@@ -292,7 +295,7 @@ def random_multivariate_truncated_lognormal(
     if not (rho.shape == (n, n)):
         raise ValueError("Correlation matrix must be square and match the "
                          "dimension of the input parameters.")
-    if not (len(lower_bound) == len(upper_bound) == n):
+    if not (len(lower_bound) == len(upper_bound) == len(std_ln) == n):
         raise ValueError(
             "Bounds, theta, and std_ln must all have the same length.")