Skip to content

Commit 162e590

Browse files
jsh9jsh9
authored
Update documentations
* Update README.md and index.rst * Use requirements.txt * Add comments to setup.py * Update index.rst * Update docstrings on boundary and motion types * Update doc theme etc * Fix type in filename * Add index.rst to doc folder * Update doc config * Update contributing guide * Remove .readthedocs.yaml; etc. * Rename "doc" folder to "docs" * Revert some requirements config * Remove docs/requirements.txt * Move doc requirements to "docs" * Limit numba version max * Update some doc config * Update doc rst and many docstrings * Update contributing instructions * Update shell scripts * v0.4.7 -> v0.4.8 * Update some docstrings * Update casing of a word * Pin doc building dependency versions * Update style of some unit tests * Fix typos
1 parent 11ea531 commit 162e590

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

66 files changed

+240
-268
lines changed

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,8 @@ instance/
6565

6666
# Sphinx documentation
6767
docs/_build/
68+
docs/build/
69+
docs/source/api/
6870

6971
# PyBuilder
7072
target/

‎CONTRIBUTING.md‎

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,30 @@
11
# Contributing Instructions
22

3-
- In general, contributors should make code changes on a branch, and then [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to have the changes merged
3+
## 1. General guideline
4+
5+
In general, contributors should make code changes on a branch, and then [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to have the changes merged.
6+
7+
## 2. Install the library for development
8+
49
- It is strongly recommended that contributors work on code changes in an isolated Python environment
5-
+ Use `pip install -e .` to install this library locally, so that any local code changes are reflected immediately in your current Python environment
6-
- To make sure your code style is compliant, run `./run_linting.sh` locally on your computer to check style violations
10+
- Use `pip install -e .` to install this library locally, so that any local code changes are reflected immediately in your current Python environment
11+
12+
## 3. Running local tests and linting
13+
14+
Make sure to run the following checks on your local computer, before pushing any code to GitHub:
15+
- Code style: run `./run_linting.sh`
716
+ You might want to run `chmod +x run_linting.sh` to make `run_linting.sh` executable
8-
- Please also run all unit tests by running `./run_tests.sh` before committing code to GitHub
17+
- Unit tests: run `./run_tests.sh`
918
+ You might want to run `chmod +x run_tests.sh` to make `run_tests.sh` executable
10-
- Even if you don't run unit tests and check code styles locally, unit tests and code styles are checked on every push at GitHub
19+
20+
(Even if you forget to run the checking above on your local computer, unit tests and code styles are checked on every push at GitHub.)
21+
22+
## 4. Update the documentations
23+
24+
If you would like to make changes to the documentations of this library, you need to install the dependencies for building documentations with the following command (from the root directory):
25+
26+
```
27+
pip install -r docs/requirements.txt
28+
```
29+
30+
To build the documentation HTML pages locally, navigate to the `docs` folder, and run `make clean html`. To view the generated HTML documentation, open the file `docs/build/html/index.html` in the browser.

‎PySeismoSoil/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
# Author: Jian Shi
22

3-
__version__ = 'v0.4.7'
3+
__version__ = 'v0.4.8'

‎PySeismoSoil/class_curves.py‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -734,8 +734,10 @@ def get_curve_matrix(
734734
self, GGmax_filler_value=1.0, save_to_file=False, full_file_name=None,
735735
):
736736
"""
737-
Based on the damping data defined in objects of this class, produce a
738-
full "curve matrix" in the following format:
737+
Produce a full "curve matrix" based on the damping data defined in
738+
objects of this class.
739+
740+
The "curve matrix" will be in the following format:
739741
+------------+--------+------------+-------------+-------------+--------+-----+
740742
| strain [%] | G/Gmax | strain [%] | damping [%] | strain [%] | G/Gmax | ... |
741743
+============+========+============+=============+=============+========+=====+
@@ -1136,8 +1138,10 @@ def get_curve_matrix(
11361138
self, damping_filler_value=1.0, save_to_file=False, full_file_name=None,
11371139
):
11381140
"""
1139-
Based on the G/Gmax data defined in objects of this class, produce a
1140-
full "curve matrix" in the following format:
1141+
Produce a full "curve matrix" based on the G/Gmax data defined in
1142+
objects of this class.
1143+
1144+
The full "curve matrix" will be in the following format:
11411145
+------------+--------+------------+-------------+-------------+--------+-----+
11421146
| strain [%] | G/Gmax | strain [%] | damping [%] | strain [%] | G/Gmax | ... |
11431147
+============+========+============+=============+=============+========+=====+
@@ -1324,6 +1328,9 @@ def get_curve_matrix(self):
13241328
return hlp.merge_curve_matrices(mgc_matrix, mdc_matrix)
13251329

13261330
def plot(self):
1331+
"""
1332+
Plot the G/Gmax and damping curves.
1333+
"""
13271334
mgc, mdc = self.get_MGC_MDC_objects()
13281335
mgc.plot(ylabel='$G/G_{\max}$')
13291336
mdc.plot(ylabel='Damping [%]')

‎PySeismoSoil/class_ground_motion.py‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -785,8 +785,8 @@ def highpass(self, cutoff_freq, show_fig=False, filter_order=4, padlen=150):
785785
"""
786786
Zero-phase-shift high-pass filtering.
787787
788-
Pameters
789-
--------
788+
Parameters
789+
----------
790790
cutoff_freq : float
791791
Cut-off frequency (unit: Hz).
792792
filter_order : int
@@ -811,8 +811,8 @@ def bandpass(self, cutoff_freq, show_fig=False, filter_order=4, padlen=150):
811811
"""
812812
Zero-phase-shift band-pass filtering.
813813
814-
Pameters
815-
--------
814+
Parameters
815+
----------
816816
cutoff_freq : [float, float]
817817
Cut-off frequencies (in Hz), from low to high.
818818
filter_order : int
@@ -837,8 +837,8 @@ def bandstop(self, cutoff_freq, show_fig=False, filter_order=4, padlen=150):
837837
"""
838838
Zero-phase-shift band-stop filtering.
839839
840-
Pameters
841-
--------
840+
Parameters
841+
----------
842842
cutoff_freq : [float, float]
843843
Cut-off frequencies (in Hz), from low to high.
844844
filter_order : int

‎PySeismoSoil/class_simulation.py‎

Lines changed: 30 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -28,17 +28,20 @@ class Simulation:
2828
soil_profile : class_Vs_profile.Vs_Profile
2929
Soil profile.
3030
input_motion : class_ground_motion.Ground_Motion
31-
Input ground motion.
31+
Input ground motion. It should be the "rock outrcop" motion if
32+
``boundary`` is set to ``"elastic"``, and it should be the recorded
33+
motion at the bottom of the Vs profile (i.e., the "borehole" motion)
34+
if ``boundary`` is set to ``"rigid"``.
3235
boundary : {'elastic', 'rigid'}
33-
Boundary condition. 'Elastic' means that the input motion is the
34-
"rock outcrop" motion, and 'rigid' means that the input motion is
35-
the recorded motion at the bottom of the Vs profile.
36+
Boundary condition. "Elastic" means that the boundary allows waves to
37+
propagate through. "Rigid" means that all downgoing waves are reflected
38+
back to the soil medium.
3639
G_param : class_parameters.HH_Param_Multi_Layer or MKZ_Param_Multi_Layer
3740
Parameters that describe the G/Gmax curves.
3841
xi_param : class_parameters.HH_Param_Multi_Layer or MKZ_Param_Multi_Layer
3942
Parameters that describe the damping curves.
4043
GGmax_and_damping_curves : class_curves.Multiple_GGmax_Damping_Curves
41-
G/Gmax and damping curves.
44+
G/Gmax and damping curves of every soil layer.
4245
4346
Attributes
4447
----------
@@ -97,11 +100,14 @@ class Linear_Simulation(Simulation):
97100
soil_profile : class_Vs_profile.Vs_Profile
98101
Soil profile.
99102
input_motion : class_ground_motion.Ground_Motion
100-
Input ground motion.
103+
Input ground motion. It should be the "rock outrcop" motion if
104+
``boundary`` is set to ``"elastic"``, and it should be the recorded
105+
motion at the bottom of the Vs profile (i.e., the "borehole" motion)
106+
if ``boundary`` is set to ``"rigid"``.
101107
boundary : {'elastic', 'rigid'}
102-
Boundary condition. 'Elastic' means that the input motion is the
103-
"rock outcrop" motion, and 'rigid' means that the input motion is
104-
the recorded motion at the bottom of the Vs profile.
108+
Boundary condition. "Elastic" means that the boundary allows waves to
109+
propagate through. "Rigid" means that all downgoing waves are reflected
110+
back to the soil medium.
105111
106112
Attributes
107113
----------
@@ -216,13 +222,16 @@ class Equiv_Linear_Simulation(Simulation):
216222
soil_profile : class_Vs_profile.Vs_Profile
217223
Soil profile.
218224
input_motion : class_ground_motion.Ground_Motion
219-
Input ground motion.
225+
Input ground motion. It should be the "rock outrcop" motion if
226+
``boundary`` is set to ``"elastic"``, and it should be the recorded
227+
motion at the bottom of the Vs profile (i.e., the "borehole" motion)
228+
if ``boundary`` is set to ``"rigid"``.
220229
GGmax_and_damping_curves : class_curves.Multiple_GGmax_Damping_Curves
221-
G/Gmax and damping curves of every layer.
230+
G/Gmax and damping curves of every soil layer.
222231
boundary : {'elastic', 'rigid'}
223-
Boundary condition. 'Elastic' means that the input motion is the
224-
"rock outcrop" motion, and 'rigid' means that the input motion is
225-
the recorded motion at the bottom of the Vs profile.
232+
Boundary condition. "Elastic" means that the boundary allows waves to
233+
propagate through. "Rigid" means that all downgoing waves are reflected
234+
back to the soil medium.
226235
"""
227236
def __init__(
228237
self, soil_profile, input_motion, GGmax_and_damping_curves,
@@ -325,15 +334,18 @@ class Nonlinear_Simulation(Simulation):
325334
soil_profile : class_Vs_profile.Vs_Profile
326335
Soil profile.
327336
input_motion : class_ground_motion.Ground_Motion
328-
Input ground motion.
337+
Input ground motion. It should be the "rock outrcop" motion if
338+
``boundary`` is set to ``"elastic"``, and it should be the recorded
339+
motion at the bottom of the Vs profile (i.e., the "borehole" motion)
340+
if ``boundary`` is set to ``"rigid"``.
329341
G_param : class_parameters.HH_Param_Multi_Layer or MKZ_Param_Multi_Layer
330342
Parameters that describe the G/Gmax curves.
331343
xi_param : class_parameters.HH_Param_Multi_Layer or MKZ_Param_Multi_Layer
332344
Parameters that describe the damping curves.
333345
boundary : {'elastic', 'rigid'}
334-
Boundary condition. 'Elastic' means that the input motion is the
335-
"rock outcrop" motion, and 'rigid' means that the input motion is
336-
the recorded motion at the bottom of the Vs profile.
346+
Boundary condition. "Elastic" means that the boundary allows waves to
347+
propagate through. "Rigid" means that all downgoing waves are reflected
348+
back to the soil medium.
337349
338350
Attributes
339351
----------

‎PySeismoSoil/class_site_factors.py‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,8 @@ def get_amplification(
8686
"""
8787
Get site amplification factors.
8888
89-
Parmeters
90-
---------
89+
Parameters
90+
----------
9191
method : {'nl_hh', 'eq_hh'}
9292
Which site response simulation method was used to calculate the
9393
amplification factors. 'nl_hh' uses the results from nonlinear site
@@ -130,8 +130,8 @@ def get_phase_shift(self, method='eq_hh', show_interp_plots=False):
130130
"""
131131
Get site amplification factors
132132
133-
Parmeters
134-
---------
133+
Parameters
134+
----------
135135
method : {'eq_hh'}
136136
Which site response simulation method was used to calculate the
137137
amplification factors. Currently, only 'eq_hh' is valid.
@@ -160,8 +160,8 @@ def get_both_amplf_and_phase(self, method='nl_hh', show_interp_plots=False):
160160
"""
161161
Get both amplification and phase-shift factors
162162
163-
Parmeters
164-
---------
163+
Parameters
164+
----------
165165
method : {'nl_hh', 'eq_hh'}
166166
Which site response simulation method was used to calculate the
167167
amplification factors. 'nl_hh' is recommended.

‎PySeismoSoil/helper_generic.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -570,8 +570,9 @@ def extract_from_curve_format(curves, ensure_non_negative=True):
570570

571571
def extract_from_param_format(params):
572572
"""
573-
Extract soil constitutive model parameters from a 2D numpy array, which
574-
follows the following format:
573+
Extract soil constitutive model parameters from a 2D numpy array.
574+
575+
The 2D numpy array should follow the following format:
575576
+----------------+-----------------+-----------------+-----+
576577
| param_layer_1 | param_layer_2 | param_layer_3 | ... |
577578
+================+=================+=================+=====+

‎PySeismoSoil/helper_hh_calibration.py‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@
2929
|--- __find_x_t_and_d()
3030
|--- helper_hh_model.tau_FKZ()
3131
|--- helper_generic.find_closest_index()
32+
33+
Note: functions whose names have leading underscores are not user-facing, so
34+
they are not shown in the documentation page.
3235
"""
3336

3437
import os

‎PySeismoSoil/helper_hh_model.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,8 @@ def tau_FKZ(gamma, *, Gmax, mu, d, Tmax):
2424
+ mu = shape parameter
2525
+ Tmax = shear strength of soil
2626
27-
Parmeters
28-
---------
27+
Parameters
28+
----------
2929
gamma : numpy.ndarray
3030
The shear strain array. Must be a 1D array. Its unit should be '1',
3131
rather than '%'.

0 commit comments

Comments
 (0)