pro-QUAD4M

pro-QUAD4M is a set of Python scripts, together with necessary input-files, essential libraries and optional utilities, that are intended to help user executing finite-elements analyses through QUAD4M [1].

pro-QUAD4M contains two main scripts:

pre-processor pre_QUAD4M.py, which generates: 1) files MDL.Q4I and SG.DAT (along with acceleration time-histories WFX.ACC and WFY.ACC) designed as input to execute QUAD4M finite-elements computer program, 2) some graphical-outputs in SVG format (Scalable Vector Graphics) which can be useful to check if QUAD4M input-files are correctly generated, 3) file borders.txt, that is due for QUAD4M post-processor execution, and 4) a copy of the JSON-file containing the model parameters (see below about this file)
post-processor post_QUAD4M.py, to be executed after the QUAD4M finite-elements analysis, which generates: 1) a serie of graphical-outputs in SVG format derived from QUAD4M outputs, and 2) three files, whose extension are .sd.txt, .fft.txt and .fft.ko.txt, containing, respectively, the acceleration time-histories produced by QUAD4M in spectral terms, as displacement responses (5% damped), and non-smoothed and smoothed Fourier amplitudes (smoothing is performed using the Konno and Ohmachi operator with b=40 [2]).

Both these scripts require a JSON-file containing the model parameters has to be passed as argument, whose detailed description is reported below at section "JSON-file". A sample JSON-file is provided within pro-QUAD4M with the name model.json. Furthermore:

pre-processor requires horizontal and vertical acceleration time-histories to be passed as arguments. Sample-files are provided within pro-QUAD4M with the names time-history.xacc and time-history.yacc. Parameters of waveforms, such as the time-step and the conversion-factor to g, have to be specified in the JSON-file within the block waveforms. With the aim to limit the computational effort of the finite-elements analysis, waveforms can be manipulated through a strong-motion processing service (e.g., [3] avalaible at [4]) in order to keep just the strong-motion part of the waveform and to apply a sampling interval choerent with the "maximum_frequency" parameter in the "modelling_parameters" block of the JSON-file
post-processor requires that some outputs produced by QUAD4M execution have to be passed as arguments: in particular, the script asks for main output file Q4O and acceleration output file Q4A to be passed (see QUAD4M user's manual to identify these files). Furthermore, file borders.txt which is generated by pre-processor has to be passed

Both scripts will save their outputs in the directory var: herein a directory will be created if not existent, whose name is specified in the JSON-file within field job_folder.

It shall be noted that the file QUAD4M.EXE is essential in order to execute QUAD4M finite-elements analyses. This software, together with its manual, is available at "The Earthquake Engineering Online Archive - NISEE e-Library" after purchasing a $25 annual membership [5].

References

[1] Hudson M., Idriss I. M., Beikae M. (1994). User's manual for QUAD4M - A computer program to evaluate the seismic response of soil structures using finite element procedures and incorporating a compliant base. University of California, Davis, California.

[2] Konno K., and Ohmachi T. (1998). Ground-motion characteristic estimated from spectral ratio between horizontal and vertical components of microtremor. Bulletin of the Seismological Society of America 88, 228–241.

[3] Puglia R., Russo E., Luzi L., D’Amico M., Felicetta C., Pacor F., Lanzano G. (2018). Strong-motion processing service: a tool to access and analyse earthquakes strong-motion waveforms. Bull Earthquake Eng. https://doi.org/10.1007/s10518-017-0299-z

[4] https://esm.mi.ingv.it/processing/ (last accessed on 2020 January 31st)

[5] https://nisee.berkeley.edu/elibrary/ (last accessed on 2020 January 31st)

Project Upgrade and Migration

This project, originally named "pro-QUAD4M," was cloned from its source at https://gitlab.rm.ingv.it/rodolfo.puglia/pro-quad4m, where it was developed to support Python 2.7. We have upgraded the codebase to be fully compatible with Python 3.13, ensuring it leverages modern Python features and maintains compatibility with current systems.

The updated version is now hosted on GitHub. Contributions, issues, and feedback are welcome!

Key Changes

Migrated from Python 2.7 to Python 3.13.
Updated syntax and libraries to align with Python 3.x standards.

For installation and usage instructions, refer to the sections below (updated as needed for Python 3.13 compatibility).

Installation

Scripts within pro-QUAD4M are written in Python 3.13 and need the following external Python-modules to be installed: jsonschema, matplotlib, numpy, scipy and shapely.

`Windows`

The installation procedure illustrated in the following has been successfully performed on both windows 7 (64bit) and windows 10 (64bit) platforms, so it should work even for other windows platform, such as Windows 8, if running at 64-bit.

step #1 - installing `Python 3.13`

Follow URL [A] (see section "URLs and notes" below), find the latest Windows x86-64 Python 3.13 MSI installer and execute it: on 2020 January 31st, the version to be installed was python-3.13.1-amd64.exe (a direct link to this file can be found in note [B]). Installing the file as administrator, with the default choices, Python program base-folder should be C:\Users\USER\AppData\Local\Programs\Python\Python313. Otherwise, any command in the following steps containing this path have to be replaced with the actual Python program base-folder.

step #2 - check if `Python 3.13` is correctly installed

Open a command-prompt and type > python.exe -V, the system should answer Python 3.13.*.

step #3 - installing Python-modules

Type on command-prompt:

> pip install numpy
> pip install scipy
> pip install matplotlib
> pip install jsonschema
> pip install shapely

`Linux`

The installation procedure has been tested on several Debian-based Linux platforms [F]. On Linux environments, differently from Windows, the use of pip is not preferrable, being many Linux distributions have these Python-modules already available as packages in their default repositories. In pratice, since Python 3.13 should be already present in most of Linux distributions (check it typing $ python -V in Linux terminal: the answer should be Python 3.13.*), use first $ aptitude search ... and, then, # apt-get install ... (or $ sudo apt-get install ...) to install missing Python-modules. On a typical Debian-based Linux distribution, pakages to be installed via apt-get are: python-numpy, python-scipy, python-matplotlib, python-jsonschema and python-shapely. Furthermore, Wine [G] should be installed in order to run the Windows application QUAD4M.EXE: the installation can be performed through # apt-get install wine or following specific how-to for the Linux distrubution in hand. This procedure should be enough to have in place a working environment for pro-QUAD4M and QUAD4M.EXE on Linux.

URLs and notes

[A] https://www.python.org/downloads/

[B] https://www.python.org/ftp/python/3.13.1/python-3.13.1-amd64.exe

[C] https://gis.stackexchange.com/questions/329987/error-installing-shapely-package-using-pip-command

[D] https://stackoverflow.com/questions/13144158/python-geos-and-shapely-on-windows-64

[E] https://www.lfd.uci.edu/~gohlke/pythonlibs/#shapely

[F]

Linux Mint 19.3 Tricia (5.3.0-40-generic)

needs Wine istallation is performed following one of the many specific guide which can be found on the internet

Devuan GNU/Linux 2.1 ascii (4.9.0-8-amd64)

# apt-get install wine works perfectly!

Ubuntu *

several systems have been tested under this environment, most requiring Wine istallation is performed following specific guides found on the internet, while # apt-get install wine works in some cases

[G] https://www.winehq.org

Usage

This section would help users in order to acquire confidence executing pre_QUAD4M.py (step #4), QUAD4M.EXE (step #5) and post_QUAD4M.py (step #6), i.e. performing a QUAD4M finite-elements analysis with the help of pro-QUAD4M. Finally, on step #7, how to reiterate the finite-elements analysis is shown.

`Windows`

step #4 - pre-processor `pre_QUAD4M.py`

Open a command-prompt and change directory to the pro-QUAD4M folder. Once here (typing > dir, the two main scripts pre_QUAD4M.py and post_QUAD4M.py should be listed), typing the command:

> python.exe pre_QUAD4M.py --help

the corresponding help is displayed, while typing:

> python.exe pre_QUAD4M.py model.json time-history.xacc time-history.yacc

the execution of the pre-processor starts using sample-inputs provided within pro-QUAD4M. At the end of execution, the mesh is generated, along with graphical outputs and QUAD4M inputs, within the folder var. Graphical outputs, in SVG format, can easly been displayed using a browser (e.g., firefox).

step #5 - QUAD4M finite-elements analysis

If model.json has not been modified still, results are saved in folder var\test_1. The program QUAD4M.EXE should be present within this folder: so, copy it here if missing. Then, type:

> cd var\test_1

changing directory to the results folder, and, in order to execute the finite elements analysis, type:

> QUAD4M.EXE

and the following lines are displayed (enter input, soil-data and output filenames when requested):

         ****************************************************
         ****************************************************
         ** QUAD4M   A COMPUTER PROGRAM FOR EVALUATING THE **
         **          SEISMIC RESPONSE OF SOIL STRUCTURES   **
         **                 U.C.Davis, 1993                **
         **              by Martin Byrd Hudson,            **
         **                 I.M.Idriss,                    **
         **                 and Mohsen Beikae              **
         **    MODIFIED FROM QUAD4, 1973                   **
         **              by I.M.Idriss,                    **
         **                 J. Lysmer,                     **
         **                 R. Hwang and                   **
         **                 H. Bolton Seed                 **
         ****************************************************
         ****************************************************

Enter Input File Name:
MDL.Q4I
Enter Soil Data File Name:
SG.DAT
Enter Output directory (with ending\) (.\ for current dir):
.\
Output File Name (without directory name):
MDL.Q4O
 Read Header Lines...

step #6 - post-processor `post_QUAD4M.py`

Navigate back to pro-QUAD4M folder (e.g., typing > cd .. twice) and type:

> python.exe post_QUAD4M.py --help

to display the help, and:

> python.exe post_QUAD4M.py model.json var\test_1\MDL.Q4O var\test_1\SG.Q4A var\test_1\borders.txt

to execute the post-processing. Results are then created in folder var\test_1.

step #7 - upgrade JSON-file

Open JSON-file model.json using an editor (such as "geany" or "notepad++"), and replace strings "job_folder": "test_1" with "job_folder": "test_2" and "rearrange_nodes_tf": true with "rearrange_nodes_tf": false. Then, repeating steps #4, #5 and #6 of this sample session, finite-elements analyses have been performed for two different meshes: the results of the first are in folder var\test_1 and of the the second in var\test_2 (be careful on steps #5 and #6, since, for each command, var\test_2 have to be specified instead of var\test_1).

`Linux`

Commands to be executed on Linux terminal are very similar to those presented at steps #4, #5, #6 and #7 in the previous Windows section. For each command, just replace any python.exe with python, any \ with / (except the one during QUAD4M.EXE execution), dir with ls and QUAD4M.EXE with wine QUAD4M.EXE (...and, of course, any > with <span>$</span>).

JSON-file

Main input JSON-file has the following structure:

{
   "modelling_parameters": { [...] },
   "stratum001": { [...] }, "stratum002": { [...] }, [...], "stratum-N": { [...] },
   "mesh_generation": { [...] },
   "waveforms": { [...] },
   "plot_parameters": { [...] }
}

Each of these blocks, togheter with their internal JSON-structure, is analysed in the next sub-sections, referring to the sample JSON-file model.json.

block `modelling_parameters`

"modelling_parameters": {
   "job_title": "test #1",
   "job_folder": "test_1",
   "strata": 6,
   "nodal_points": {
      "1": [-100, 193],
      "2": [10, 193],
      [...]
      "61": [-100, 0]
   },
   "NUMB_iteration": 4,
   "half_space_VP_m_s": 3200,
   "half_space_VS_m_s": 1350,
   "half_space_RHO_N_m_3": 22000,
   "boundary_conditions": {
      "vertical-right": {"value": 2, "position": 500},
      "horizontal": {"value": 4, "position": 0},
      "vertical-left": {"value": 2, "position": -100}
   },
  "acceleration_output": {
     "X_direction": {"inside": null, "ground": null},
     "Y_direction": {"inside": null, "ground": null},
     "XY_direction": {
        "inside": [[200, 164.5], [200, 145], [200, 113]],
        "ground": [0, 25, 50, 75, 100, 125, 150, 175, 200, 225, 250, 275, 300, 325, 350, 375, 400]
     }
  }
}

job_title: model name; it is written in the first line of the Q4I file (further information about this file can be found in QUAD4M user's manual)
job_folder: name of the directory where outputs are saved (it will be created if missing within the var directory)
strata ($S$): number of strata of the model
inner-block nodal_points: cf. nodal points in Fugure 1

Figure 1: nodal points (depicted as red dots) composing the strata plot

NUMB_iteration: number of iteration on soil properties to be performed in QUAD4M analysis
half_space_VP_m_s, half_space_VS_m_s and half_space_RHO_N_m_3: half-space properties (below the compliant base), respectively P and S wave-velocity in [m/s], and average unit weight in [N/m³]

inner-block boundary_conditions: conditions have to be applied to three boundaries: vertical-right, horizontal, and vertical-left (conditioned boundaries are horizontal and verticals, this implies that a diagonal boundary is not allowed):
- value: according to QUAD4M user's manual, it can be:
  - 1: input horizontal seismic motion applied, free in vertical direction
  - 2: input vertical seismic motion applied, free in horizontal direction
  - 3: input horizontal and vertical seismic motion applied
  - 4: transmitting base node
- position: coordinate of nodes where the condition is applied: x-coordinate for verticals boundaries or y-coordinate for the horizontal one

acceleration_output: nodes where QUAD4M will generate acceleration output time-histories:
- after the QUAD4M-mesh is generated, a search will be performed in order to identify its closest mesh-node to each pair of coordinates specified here (inside) or its closest mesh-ground-node to each X-coordinate (ground)
- X_direction, Y_direction and XY_direction respectively means that horizontal, vertical or both acceleration time-histories will be saved at each selected node
- inside and ground respectively means that both X- and Y-coordinates or just X-coordinate have to be specified
- no time-histories will be saved if null value is specified

blocks `stratum001`, `stratum002`, ..., `stratum-N`

"stratum001": {
   "name": "st. 1",
   "nodes": [1, 2, 3, 4, 5, 6, 7, 8, 27, 28, 29, 35, 36, 37, 38, 39, 40, 41, 42, 59, 58, 57, 56, 55, 54, 52, 53, 22, 23, 24, 25, 26, 60, 61],
   "DENS_N_m_3": {"value": 22000, "min_value": null, "uncentanty": 0, "log_normal_tf": false},
   "PO_ratio": {"value": 0.392, "min_value": null, "uncentanty": 0, "log_normal_tf": false},
   "GMX_kN_m_3": {"value": 4907000, "min_value": 4498000, "uncentanty": 204400, "log_normal_tf": false},
   "G_kN_m_3": {"percent_of_GMX": 100},
   "XL_decimal": {"value": 0.005, "min_value": null, "uncentanty": 0, "log_normal_tf": false},
   "soil_TYPE": {
      "G_GMX": null,
      "XL": null
   },
   "model_G_GMX_XL": {
      "model_G_GMX_XL_tf": false,
      "depth_of_water_table_m": 0.0,
      "coef_of_lateral_earth_pressure_K0": 0.5,
      "mean_effective_stress_atm": null,
      "plasticity_index_PI_percent": 0.0,
      "over_consolidation_ratio_OCR": 1.0,
      "XL_uncentanty": true
   }
}

"stratum002": {
   "name": "st. 2",
   "nodes": [52, 54, 55, 56, 57, 58, 59, 42, 43, 44, 45, 46, 50, 51],
   "DENS_N_m_3": {"value": 21200, "min_value": null, "uncentanty": 0, "log_normal_tf": false},
   "PO_ratio": {"value": 0.481, "min_value": null, "uncentanty": 0, "log_normal_tf": false},
   "GMX_kN_m_3": {"value": 440600, "min_value": 363600, "uncentanty": 18360, "log_normal_tf": false},
   "G_kN_m_3": {"percent_of_GMX": 90},
   "XL_decimal": {"value": 0.025, "min_value": 0.023, "uncentanty": 0.001, "log_normal_tf": false},
   "soil_TYPE": {
      "G_GMX": [[0.0001, 1.0], [0.0091, 0.99], [0.0119, 0.98], [0.0139, 0.97], [0.0157, 0.96], [0.0173, 0.95], [0.0208, 0.925], [0.0211, 0.9221], [0.0227, 0.91], [0.0239, 0.9], [0.0252, 0.89], [0.0264, 0.88], [0.0503, 0.7], [0.0689, 0.6], [0.0959, 0.5], [0.1389, 0.4], [0.2176, 0.3], [0.3971, 0.2]],
      "XL": [[0.0001, 2.5], [0.0127, 2.8103], [0.0181, 3.1206], [0.0224, 3.4309], [0.0262, 3.7412], [0.0296, 4.0515], [0.0376, 4.8273], [0.0384, 4.9172], [0.0421, 5.29], [0.045, 5.6], [0.048, 5.91], [0.0509, 6.22], [0.1118, 11.81], [0.1619, 14.91], [0.2367, 18.01], [0.3606, 21.12], [0.5964, 24.22], [0.6906, 25.0]]
   },
   "model_G_GMX_XL": {
      "model_G_GMX_XL_tf": false,
      "depth_of_water_table_m": 0.0,
      "coef_of_lateral_earth_pressure_K0": 0.5,
      "mean_effective_stress_atm": null,
      "plasticity_index_PI_percent": 0.0,
      "over_consolidation_ratio_OCR": 1.0,
      "XL_uncentanty": true
   }
}

"stratum003": {
   "name": "st. 3",
   "nodes": [29, 30, 31, 32, 33, 34, 16, 17, 49, 48, 47, 46, 45, 44, 43, 42, 41, 40, 39, 38, 37, 36, 35],
   "DENS_N_m_3": {"value": 21200, "min_value": null, "uncentanty": null, "log_normal_tf": false},
   "PO_ratio": {"value": 0.477, "min_value": null, "uncentanty": null, "log_normal_tf": false},
   "GMX_kN_m_3": {"value": 594100, "min_value": 490200, "uncentanty": 24760, "log_normal_tf": false},
   "G_kN_m_3": {"percent_of_GMX": 90},
   "XL_decimal": {"value": null, "min_value": null, "uncentanty": null, "log_normal_tf": false},
   "soil_TYPE": {
      "G_GMX": null, 
      "XL": null
   },
   "model_G_GMX_XL": {
      "model_G_GMX_XL_tf": true,
      "depth_of_water_table_m": 0.0,
      "coef_of_lateral_earth_pressure_K0": 0.5,
      "mean_effective_stress_atm": null,
      "plasticity_index_PI_percent": 0.0,
      "over_consolidation_ratio_OCR": 1.0,
      "XL_uncentanty": false
   }
}

Sequence of stratum-blocks has to be coherent with the strata variable $S$ (see block modelling_parameters above), e.g., being $S$ equal to 12, stratum-blocks sequence has to be stratum001, stratum002, ..., stratum011, stratum012.

name: formation name (in results it is associated to the soil formation)
nodes: ordered list of indexes (relevant to field nodal_points of block modelling_parameters above) that describes the stratum (order can be either in clockwise or counterclockwise direction)

inner-block DENS_N_m_3: total unit weight in [N/M³]
- value: mean-value
- min_value: minimum threshold value, i.e. the minimum value that can be assumed for the soil-property (it truncate distribution below the value); in case null is given, a non-truncated distribution is used
- uncentanty: standard-deviation; in case null is given, standard-deviation is considered equal to 0 or 1 for normal or log-normal distribution, respectively, and aforementioned field min_value is ignored
- log_normal_tf: [true|false]: if false, then a normal (Gaussian) distribution, otherwise, a log-normal one is adopted
In case of normal (Gaussian) distribution, values below zero are non-allowed for option uncentanty; in case of log-normal distribution, standard-deviation is constrained within the interval [1; 5].

inner-block PO_ratio: Poisson's ratio
- same option list as inner-block DENS_N_m_3

inner-block GMX_kN_m_3: shear-modulus at small strains in [kN/m²]
- same option list as inner-block DENS_N_m_3

inner-block G_kN_m_3:
- percent_of_GMX: shear-modulus for 1st iteration, expressed as [percent] of the shear-modulus at small strains

inner-block XL_decimal: initial fraction of critical damping as [decimal]
- same option list as inner-block DENS_N_m_3
As a special case, the key-field value within inner-block XL_decimal is settable as null if model_G_GMX_XL_tf within inner-block model_G_GMX_XL (see below) is set as true (in fact, this latter setting implies any value within inner-block XL_decimal to be overwritten).

inner-block soil_TYPE: dynamic soil properties:
- G_GMX: degradation with shear-strain in [percent] of normalized shear-modulus (ratio between shear-moduli: actual vs. at-small-strain)
- XL: degradation with shear-strain in [percent] of equivalent damping ratio as [percent]
- if G_GMX or XL is null then corresponding GMX_kN_m_3 and XL_decimal values are assumed as constants with strain

inner-block model_G_GMX_XL: eventually rewrite, with initial fraction of critical damping and degradation of dynamic soil properties, the aforementioned inner-blocks XL_decimal and soil_TYPE, following the Darendeli (2001) approach as explained in the note below.
- model_G_GMX_XL_tf: [true|false]: if true, then inner-blocks XL_decimal and soil_TYPE are overwritten
- depth_of_water_table_m: depth of water table in [m] from the ground of the model; the parameter is used to evaluate vertical effective stress $σ^{\prime}_{V0}$ (it is assumed that DENS_N_m_3 represent the weight of the soil completely saturated with water)
- coef_of_lateral_earth_pressure_K0: coefficient of lateral earth pressure $K_0$: it is used to estimate mean effective stress:
  $\color{white}{\tiny \cdot}\ \hspace*{6em} \color{black}{ σ^{\prime}0 = \cfrac{1+2K_0}{3} \space σ^{\prime}{V0} } \\color{white}{\tiny \cdot}$
  from vertical effective stress
- mean_effective_stress_atm: mean effective stress $σ^{\prime}_0$ [atm]: if null, then the value is estimated by the code, following an element-wise basis, using the aforementioned parameters DENS_N_m_3, depth_of_water_table_m and coef_of_lateral_earth_pressure_K0; otherwise, values in depth_of_water_table_m and coef_of_lateral_earth_pressure_K0 are ignored by the code
- plasticity_index_PI_percent: plasticity index in [percent]
- over_consolidation_ratio_OCR: over-consolidation ratio
- XL_uncentanty: [true|false]: if false uncentanty within inner-block XL_decimal is set to 0.0, otherwise Darendeli (2001) approach is used to fill the field uncentanty
Inner-block model_G_GMX_XL permits to estimate normalized modulus reduction curve and damping curve together with its uncentanty (respectively, eq. 12.1a, 12.1b and 12.2f in Darendeli, 2001) and to replace, with these estimations, any value within inner-blocks XL_decimal and soil_TYPE. Notes on the actual implementation:
- the variables are mean_effective_stress_atm, plasticity_index_PI_percent and over_consolidation_ratio_OCR;
- curvature coefficient (set to 0.9190) together with the other coefficients used in the aforementioned equations are reported in section 9.2 of Darendeli (2001);
- ten cycles of loading at 1 Hz is hard-coded, so that the loading conditions represent the characteristics of an earthquake;
- in case mean_effective_stress_atm is set to null, for the sake of simplicity, the representative vertical effective stress of the soil formation is calculated after step "5) attribution of soil parameters to the mesh", but excluding step "2) deformation procedure of the initial-grid", even if rearrange_nodes_tf is set to true (cf. section "Methods" below); step "4) mesh downsampling" is also excluded, although it does not influence the estimation of the vertical effective stress;
- within inner-block XL_decimal, lower bound of distribution (min_value) is fixed to one-fifth of the initial fraction of critical damping (value) modeled by Darendeli (2001).
References
Further details on the Darendeli (2001) implementation can be found in: chapter 6 and following of Darendeli (2001) PhD thesis and in section 2.1.3 of the manual for Strata by Kottke, Wang and Rathje (both online resources have been last accessed on 2020 June 25nd).

block `mesh_generation`

"mesh_generation": {
   "maximum_frequency": 15.0,
   "maximum_element_shape_factor": {"H/V": 4.0, "V/H": 1.5},
   "uniform_initial_grid": false,
   "rearrange_nodes": { [...] },
   "boundaries_triangular_elements_tf": true,
   "mesh downsampling": { [...] }
}

See detailed discussion about this block in section "Methods" below.

block `waveforms`

"waveforms": {
   "N1EQ_first_time_step_for_last_iteration": 1,
   "KGEQ_last_time_step_for_last_iteration": 2250,
   "N2EQ_first_time_step_for_first_iterations": 300,
   "N3EQ_last_time_step_for_first_iterations": 1300,
   "DTEQ_time_step_s": 0.02,
   "HDRX_header_lines_in_horizontal_input_time_history": 64,
   "HDRY_header_lines_in_vertical_input_time_history": 64,
   "multiplier_factor_to_g": 0.0010197,
   "PRINPUT_period_corresponding_to_maximum_spectral_acceleration_of_horizontal_input_motion_s": 0.22
}

N1EQ_...: number of first time-step for the last QUAD4M iteration
KGEQ_...: number of last time-step for the last QUAD4M iteration
N2EQ_...: number of first time-step for first QUAD4M iterations
N3EQ_...: number of last time-step for first QUAD4M iterations
DTEQ_time_step_s: waveforms time-step in [s] (this value should be set coherently with maximum_frequency in block mesh_generation, e.g., using concepts of the Nyquist frequency)
HDRX_...: number of header lines in horizontal input waveform file
HDRY_...: number of header lines in vertical input waveform file
multiplier_factor_to_g: multiplier factor to convert input waveforms to [g]; e.g., if the physical unit of input waveforms is [cm/s²], the multiplier_factor_to_g is 0.0010197
PRINPUT_...: period, in [s], corresponding to the maximum spectral acceleration of the horizontal input motion (it is used to define the higher frequecy in the two frequencies scheme for damping adopted in QUAD4M); in case it is set as null, PRINPUT_... value is estimated within the script

block `plot_parameters`

"plot_parameters": {
   "BW_scale_tf": false,
   "profile_SA_max_width": 30.0,
   "profile_SA_BW_scale_tf": false,
   "profile_ACC_max_width": 45.0,
   "profile_FFT_lower_limit_Hz": 0.07,
   "scale": {
      "symbols": 0.7,
      "fonts": 0.7,
      "line_thicknesses": 0.7
   },
   "save_PNG_tf": true
}

BW_scale_tf: [true|false]: if true, then black-and-white scale is adopted for all plots, with the exception of plot "profile_SA"
profile_SA_max_width: max width in [m] for the acceleration response spectra shown in plot "profile_SA"
profile_SA_BW_scale_tf: [true|false]: if true, then black-and-white scale is adopted in plot "profile_SA"
profile_ACC_max_width: max width in [m] for the waveforms shown in plot "profile_ACC"
profile_FFT_lower_limit_Hz: lower limit in [Hz] for the Fourier spectra shown in plot "profile_FFT"
scale: scale factor for plot elements symbols, fonts and line_thicknesses
save_PNG_tf: [true|false]: if true, then the PNG-version of files SVG is generated

Methods

This section is intended to explain: 1) creation of the initial-grid, 2) deformation procedure of the initial-grid, 3) generation of QUAD4M-mesh, 4) mesh downsampling and 5) attribution of soil parameters to the mesh. Finally, last chapter of this section shows some sample-meshes for QUAD4M finite-elements analyses.

1) creation of the initial-grid

The initial-grid is the starting quadrilateral-elements grid, e.g., the one shown in Figure 2. In other words, the initial-grid is the grid before any manipulation made by the pre-processing to obtain the final mesh is applied.

Figure 2: initial-grid

Creation of the initial-grid is regulated by parameters of block mesh_generation hereafter.

"maximum_frequency": 12.0
"maximum_element_shape_factor": {"H/V": 2.0, "V/H": 1.5}
"uniform_initial_grid": false

maximum_frequency ($f_{MAX}$): input-waveforms highest-frequency in [Hz] to be reproduced by the mesh: maximum thickness of elements, $h_{MAX}$ in [m], is then defined according to the well-known condition by Kuhlemeyer and Lysmer (1973), as:
$\color{white}{\tiny \cdot}\ \hspace*{6em} \color{black}{ h_{MAX} = \cfrac{V_S}{ 8 \cdot f_{MAX} } } \\color{white}{\tiny \cdot}$
being $V_S$ the shear-wave velocity of each stratum in [m/s], which is calculated from the reference shear-modulus relevant to each stratum. The reference shear-modulus is equal to value - (uncentanty*2) in case of normal (Gaussian) distribution, or to value/(uncentanty²) in case of log-normal distribution (the fields value and uncentanty are located within inner-block GMX_kN_m_3 of the stratum-block in hand), in both cases, further reduced by percent_of_GMX (within inner-block G_kN_m_3). Of course, the expected degradation of the shear-modulus in the field percent_of_GMX have to be correctly set, e.g. after a trial run of QUAD4M analysis, considering an averaged value for each stratum of the elements strain and, then, set-up a percent_of_GMX value equal or lower than the corresponding degradation of the shear-modulus.

In pratice, the shear-wave velocity used to estimate the maximum thickness of elements for the stratum (and so, the maximum frequency reproducible by the model), is two standard deviations lower than its mean-value and further corrected considering the expected degradation of shear-modulus. This implies that setting a threshold value for the shear-modulus in the field min_value as (value - (uncentanty*2))*(percent_of_GMX/100) in case of normal distribution, or as (value/(uncentanty²))*(percent_of_GMX/100) in case of log-normal distribution, ensures that the 100% of elements are capable to reproduce the given maximum_frequency (instead of the 97.5% of the elements if a non-truncated distribution is adopted setting min_value as null).

It shall be also noted that acceleration input time-histories should have a time-step coherent with maximum_frequency, in order to limit the computational effort of the QUAD4M analysis.
maximum_element_shape_factor: maximum ratios between height-and-width (H/V) and width-and-height (V/H) applied to each element composing the initial-grid
uniform_initial_grid: [true|false]: if true, then a uniform grid is adopted as initial grid, i.e. quadrilateral elements composing the initial grid have all the same height and width. Selected height and width are derived from the stratum with the lowest shear-modulus at small strains, minimizing the values of thickness and V/H, which are, respectively, relevant to the field maximum_frequency and the inner-block maximum_element_shape_factor aforementioned.

In some cases, e.g. in complex geotechnical model, downsampling the mesh (cf. section "mesh downsampling" below) can result in sizes of elements quite heterogeneous within a single stratum; the problem can be avoided setting option uniform_initial_grid as true, although the generation of the mesh will require higher processing time.

2) deformation procedure of the initial-grid

Deformation of the initial-grid is an optional step, it is performed just in case rearrange_nodes_tf is equal to true. If this is the case, the initial-grid parameter $h_{MAX}$ is reduced by scaling_factor value, in order to take into account the deformation procedure of quadrilateral-elements that is to be performed.

In pratice, during the deformation, nodes of quadrilateral-elements composing the intial-grid are moved towards strata-elements described by indexes in nodes for each stratum-block. Executing it in an iterative manner (i.e. at each step, moving the node of a quadrilateral-element just for a fraction of the distance between the node closer to strata-element and the strata-element itself), guarantees for a uniform deformation of the whole grid.

Deformation is regulated by inner-block rearrange_nodes hereafter. Set these parameters using a trial-and-error approach, visully inspecting the output images by pre-processor, with particular attention to the "mesh" plot.

"rearrange_nodes": {
   "rearrange_nodes_tf": true,
   "scaling_factor": 0.95,
   "iterations": 20,
   "vertical_deformation_coefficient": 0.30,
   "horizontal_deformation_coefficient": 0.15,
   "distance_threshold_m": 50.0,
   "exponents": {"inline": 1.5, "inline_extremities": 1.0, "orthogonal": 2.0},
   "overall_exponent": null
}

rearrange_nodes_tf: [true|false]: if true, then initial-grid is deformed
scaling_factor: scaling factor (less or equal than 1) applied to quadrilateral-elements of the initial-grid to reduce their size before deformation procedure
iterations ($t$): number of iteration on grid deformation
vertical_deformation_coefficient ($L^V$): vertical deformation coefficient (being its typical values between 0.05 and 0.5)
horizontal_deformation_coefficient ($L^H$): horizontal deformation coefficient: typically (since H/V is usually greater than V/H within inner-block maximum_element_shape_factor), it is lower than vertical one; could be a convenient approach to initially set horizontal_deformation_coefficient to 0.0: in order to first adjust parameters of block mesh_generation for vertical-deformation and then add the horizontal one
distance_threshold_m ($d_T$): maximum distance in [m] at which the displacement of a node affects the displacement of nearby nodes

exponents:
- inline ($u$): in-line exponent
- inline_extremities ($v$): line-extremities exponent
- orthogonal ($w$): orthogonal exponent

overall_exponent: it can be null or a real-number greater than zero: if number, then exponents (inline, inline_extremities and orthogonal) are overwritten by this value

Definitions

See Definitions for further information.

Algorithm

See Algorithm for further information.

Remarks

It shall be noted that QUAD4M requires elements in Q4I (main QUAD4M input file) have to be expressed in counter-clockwise order. Rearranging nodes in pro-QUAD4M can deform elements until they are not anymore in counter-clockwise order: to avoid this, a check is in place giving an error message if this happens.

3) generation of QUAD4M-mesh

Either if initial-grid has been deformed or not, this step will generate the mesh to perform QUAD4M finite-elements analysis. In pratice, the grid is transformed into the mesh eliminating elements which are not inside the soil-model and assigning a soil-identifier to the others. A grid-element is assigned to a stratum whether the center of that element is contained within the closed-polygonal-chain $B_z$ of that stratum.

The JSON-file parameter which affects the QUAD4M-mesh generation is contained within block mesh_generation, in the field boundaries_triangular_elements_tf hereafter.

"boundaries_triangular_elements_tf": true

boundaries_triangular_elements_tf: [true|false]: if true, then the mesh is generated using both quadrilateral and triangular elements (possibly, in order to better follow the strata geometries, triangular elements are used in proximity of the boundaries between two strata), else if false, then just quadrilateral elements are used

4) mesh downsampling

Downsampling of mesh-elements is an optional step, it is performed just in case mesh_downsampling_tf is equal to true. If this is the case, eventually, some mesh-elements are joined together, while others are separated further and joined together, with the aim to diminuish the total number of elements/nodes composing the mesh.

Downsampling is regulated by inner-block rearrange_nodes hereafter.

"mesh_downsampling": {
 "mesh_downsampling_tf": true,
 "minimum_module_length": 6,
 "element_shape_factor_multiplier": {"H/V": 2.2, "V/H": 1.5},
 "triangular_extremities_tf": true
}

mesh_downsampling_tf: [true|false]: if true, then the mesh is downsampled
minimum_module_length ($T$): minimum length of the module of quadrilateral elements (Figure 4) which is interested by the reshaping procedure

$$\begin{matrix} &&&F_0&&F_1&&F_2&&\ldots&&F_{T^+-1}&&F_{T^+}&&(T^{+}\ge T)\\\ &&&&&&&&&&&&&&&\\\ &&\circ&\text{---}&\circ&\text{---}&\circ&\text{---}&\circ&&\circ&\text{---}&\circ&\text{---}&\circ&\\\ &&\mid&&\mid&&\mid&&\mid&&\mid&&\mid&&\mid&\\\ &&\circ&\text{---}&\circ&\text{---}&\circ&\text{---}&\circ&\ldots&\circ&\text{---}&\circ&\text{---}&\circ&\bold{(a)}\\\ &&\mid&&\mid&&\mid&&\mid&&\mid&&\mid&&\mid&\\\ P^*&\Rarr&\circ&\text{---}&\circ&\text{---}&\circ&\text{---}&\circ&&\circ&\text{---}&\circ&\text{---}&\circ&\\\ &&&&&&&&&&&&&&&\\\ &&&&&&&&&\Darr&&&&&&\\\ &&&&&&&&&&&&&&&\\\ &&\circ&\text{---}&\circ&\text{---}&\circ&\text{---}&\circ&&\circ&\text{---}&\circ&\text{---}&\circ&\\\ &&\mid&\diagup&&&&&&&&&&\diagdown&\mid&\\\ &&\circ&&\mid&&\mid&&\mid&\ldots&\mid&&\mid&&\circ&\bold{(b)}\\\ &&\mid&\color{cyan}{\diagdown}&&&&&&&&&&\color{cyan}{\diagup}&\mid&\\\ P^*&\Rarr&\circ&\text{---}&\circ&\text{---}&\circ&\text{---}&\circ&&\circ&\text{---}&\circ&\text{---}&\circ&\\\ \end{matrix}$$

Figure 4: schematic procedure of reshaping from quadrilateral-elements-module (a) to elements-module (b), which is composed by both triangular and quadrilateral elements; in figure, circles represent nodes, lines are bounds of elements and $P^$ is a generic polygonal-chain (cf. Figure 3); cyan bounds in (b) are used if triangular_extremities_tf is set as true, otherwise they are omitted*

element_shape_factor_multiplier: multiplier-factors for H/V and V/H fields of maximum_element_shape_factor to be used in mesh-downsampling

Multiplier-factors permit to closely follow strata-boundaries – e.g.: using lower values for inner-block maximum_element_shape_factor in creation of the initial-grid –, even using larger elements in mesh-downsampling – e.g.: relaxing shape-factor coinstraints using multiplier-factors greater than one during mesh-downsampling.
triangular_extremities_tf: [true|false]: each module (a) extremity is reshaped as: if true, three triangular elements, if false, one quadirateral and one triangular elements; bounds to eventually be omitted are depicted in cyan in Figure 4b

Algorithm

See Algorithm for further information.

5) attribution of soil parameters to the mesh

Stratum-parameters value (mean), uncentanty (standard-deviation) and min_value (truncating value) for weight, Poisson's ratio, shear-modulus at small strains and initial damping (cf. blocks stratum001, stratum002, ..., stratum-N) are associated to each element thankful to the soil-identifier (cf. section "generation of QUAD4M-mesh"). So, corresponding soil properties are associated to the element drawing random samples from the relevant normal-distributions. It shall be noted that the shear-modulus used in 1st QUAD4M iteration is the specified percentage (cf. field G_kN_m_3 of the stratum-block) of the actual mesh-element value for the shear-modulus at small strains. Degradation of dynamic soil properties (inner-block soil_TYPE) are finally associated to each stratum of the mesh for QUAD4M finite-elements analysis.

6) examples for QUAD4M-mesh

mesh #1 has been produced (cf. step #4) using JSON-file model.json as it is provided by pro-QUAD4M.
mesh #2 has been produced replacing strings "job_folder": "test_1" with "job_folder": "test_2" and "mesh_downsampling_tf": true with "mesh_downsampling_tf": false in the JSON-file.
mesh #3 has been produced replacing strings "job_folder": "test_2" with "job_folder": "test_3" and "rearrange_nodes_tf": true with "rearrange_nodes_tf": false in the JSON-file.
mesh #4 has been produced replacing strings "job_folder": "test_3" with "job_folder": "test_4" and "boundaries_triangular_elements_tf": true with "boundaries_triangular_elements_tf": false in the JSON-file.
mesh #5 has been produced replacing strings "job_folder": "test_4" with "job_folder": "test_5" and "mesh_downsampling_tf": false with "mesh_downsampling_tf": true in the JSON-file.
mesh #6 has been produced replacing strings "job_folder": "test_5" with "job_folder": "test_6" and "triangular_extremities_tf": true with "triangular_extremities_tf": false in the JSON-file.
mesh #7 has been produced replacing strings "job_folder": "test_6" with "job_folder": "test_7" and "uniform_initial_grid": false with "uniform_initial_grid": true in the JSON-file.

Sample graphical-outputs

Using sample input-files model.json, time-history.xacc and time-history.yacc as they are provided within pro-QUAD4M, below are listed some of the graphical-outputs produced by:

pre-processor pre_QUAD4M.py: unit weight, shear-modulus at small strains, Poisson's ratio, initial fraction of critical damping, input waveforms, normalized shear-modulus, damping and, of course, the mesh
post-processor post_QUAD4M.py:
- peak elements stress, strain and horizontal acceleration
- ground time-histories, peak acceleration, peak velocity, Arias intensity, Housner intensity, acceleration response spectra and smoothed Fourier spectra amplitude

Versions

pro-QUAD4M:
– 0.1: beta version published.
– 0.2: a check has been added to prevent an accidental overwritting of the previous execution.
– 0.3: a bug in reading Q4A file has been fixed.
– 0.4.1: another bug in reading Q4A file has been fixed.
– 0.4.2: distance_threshold_m assumes a different significance.
– 0.4.3: filters on distance have been uniformed (same functional form, but different exponent).
– 0.4.4: a) exponents of filters on distance have been changed; b) a check has been added to prevent reading by post_QUAD4M.py of QUAD4M files relevant to a different run.
– 0.5.0: exponents of filters on distance have been moved to the JSON-model.
– 0.5.1: overall_exponent of filters on distance has been added to the JSON-model.
– 0.6.0: deformation coefficient has been splitted to vertical and horizontal ones.
– 0.7.0: structure of main input file JSON-model has been modified.
– 0.8.0: element_shape_factor in JSON-model has been changed to maximum_element_shape_factor.
– 0.9.0: *_total_deformation_coefficient in JSON-model has been changed to *_deformation_coefficient.
– 0.9.1: value and uncertanty in strata-blocks of JSON-model has become 'mean' and 'standard-deviation' of a normal-distribution, respectively.
– 0.9.2: in case of normal-distribution of inner-block GMX_kN_m_3 is given (i.e. the uncentanty value is different from 0.0), a bug on the estimation of "h_MAX" has been fixed.
– 0.10.0: min_value has been added in stratum-blocks of JSON-model, permitting to fix a lower limit for each soil-property (useful if normal-distribution is given).
– 0.11.0: scale, profile_ACC_max_width and save_PNG_tf has been added in block plot_parameters of JSON-model, giving more controls on plots.
– 0.11.1: procedure to save Fourier spectra (both smoothed and non-smoothed) has been added.
– 0.11.2: smoothed Fourier spectra plot has been added.
– 0.11.3: input waveforms copied in directory var (within the relevant results folder).
– 0.12.0: mesh-downsampling procedure has been added.
– 0.12.1: option downsampling_mode has been deleted from JSON-model.
– 0.12.2: all references about option downsampling_mode have been deleted from scripts.
– 0.12.3: workflow has been modified, associating the soil-identifier to each element before mesh-downsampling.
– 0.12.4: in JSON-model, triangular_elements_tf has been renamed to boundaries_triangular_elements_tf.
– 0.13.0: a) method to estimate shear-modulus reduction (G/G0) and damping ratio (D) curves to shear strain through Darendeli (2001) and b) new mesh-downsampling mode (module extremities can be reshaped both as three triangular elements or one tiangular and one quadrilateral elements) have been added.
– 0.13.1: acceleration_output_* and G_max in JSON-model have been changed to acceleration_output and GMX.
– 0.13.2: PRINPUT_... in JSON-model is settable as null: if this is the case, PRINPUT_... value is estimated within the script.
– 0.13.3: in JSON-model, a) in case min_value is set to null, a log-normal distribution (instead of a normal one) is used for the soil-property in hand, b) parameters depth_of_water_table_m and mean_effective_stress_atm can be set for each formation (the former is moved from block modelling_parameters, the latter is added).
– 0.13.4: option uniform_initial_grid has been added in JSON-model.
– 0.14.0: key-field value within inner-block XL_decimal is settable as null in JSON-model.
– 0.14.1: log_normal_tf has been added in stratum-blocks of JSON-model, it permits to adopt either a normal-Gaussian or a log-normal distribution for the soil-property.
– 0.14.2: percent_of_GMX (within JSON-model) has been added as parameter in the calculation of maximum-height for elements.
– 0.14.3: normalized shear-modulus and damping plots have been added.

Copyright and License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name "pro-QUAD4M" nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright owner or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.idea		.idea
gitlab_version		gitlab_version
lib		lib
utils		utils
var		var
README.md		README.md
addendum_2_algorithm.md		addendum_2_algorithm.md
addendum_2_definitions.md		addendum_2_definitions.md
addendum_4_algorithm.md		addendum_4_algorithm.md
model.json		model.json
post_QUAD4M.py		post_QUAD4M.py
pre_QUAD4M.py		pre_QUAD4M.py
time-history.xacc		time-history.xacc
time-history.yacc		time-history.yacc

Folders and files

Latest commit

History

Repository files navigation

pro-QUAD4M

References

Project Upgrade and Migration

Key Changes

Installation

Windows

step #1 - installing Python 3.13

step #2 - check if Python 3.13 is correctly installed

step #3 - installing Python-modules

Linux

URLs and notes

Usage

Windows

step #4 - pre-processor pre_QUAD4M.py

step #5 - QUAD4M finite-elements analysis

step #6 - post-processor post_QUAD4M.py

step #7 - upgrade JSON-file

Linux

JSON-file

block modelling_parameters

blocks stratum001, stratum002, ..., stratum-N

block mesh_generation

block waveforms

block plot_parameters

Methods

1) creation of the initial-grid

2) deformation procedure of the initial-grid

Definitions

Algorithm

Remarks

3) generation of QUAD4M-mesh

4) mesh downsampling

Algorithm

5) attribution of soil parameters to the mesh

6) examples for QUAD4M-mesh

Sample graphical-outputs

Versions

Copyright and License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`Windows`

step #1 - installing `Python 3.13`

step #2 - check if `Python 3.13` is correctly installed

`Linux`

`Windows`

step #4 - pre-processor `pre_QUAD4M.py`

step #6 - post-processor `post_QUAD4M.py`

`Linux`

block `modelling_parameters`

blocks `stratum001`, `stratum002`, ..., `stratum-N`

block `mesh_generation`

block `waveforms`

block `plot_parameters`

Packages