QDYN release 3.0.0

.github/workflows/tests.yml

@@ -0,0 +1,36 @@
+name: Test QDYN
+
+on: [push]
+
+jobs:
+  test-linux:
+    runs-on: ubuntu-latest
+    strategy:
+      max-parallel: 3
+      fail-fast: true
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.10"
+    - name: Install dependencies
+      run: |
+        pip install --upgrade pip
+        pip install numpy "scipy>=1.9.0" matplotlib pandas termcolor ipython
+        pip install -e .
+    - name: Install compiler
+      run: sudo apt install -y gfortran libopenmpi-dev
+    - name: Copy mymakedepend
+      run: cp ./qdyn/utils/devel_tools/mymakedepend.perl ./qdyn
+    - name: Compile FORTRAN code
+      working-directory: ./qdyn
+      run: |
+        chmod +x mymakedepend.perl
+        ./mymakedepend.perl
+        make clean && make test
+    - name: Run test suite
+      working-directory: ./test
+      run: python test_suite.py
+

.gitignore

@@ -1,19 +1,21 @@
 # ignore objects and archives, anywhere in the tree.
 
 mymakedepend.perl
-!utils/devel_tools/mymakedepend.perl
+!qdyn/utils/devel_tools/mymakedepend.perl
 
 # Fortran compiled files
-qdyn
+qdyn/qdyn
 *.mod
 *.o
 
 # Output files
 fort.*
 output_iasp
 output_ot_*
-output_ox
+output_ox*
 output_vmax
+output_fault
+log*
 
 # Simulation products
 *.in
@@ -28,9 +30,17 @@ _site/
 __pycache__/
 .ipynb_checkpoints/
 *.pyc
+*.egg-info/
 
 # PyCharm files
 .idea/
 
 # Atom files
 .atom-build.json
+
+# VS Code
+.vscode/
+
+# others
+._.DS_Store
+.DS_Store

docs/_data/navigation.yml

@@ -47,13 +47,21 @@
     - name: Examples
       anchor: examples
 
-- name: 5. Optimizing performance
+- name: 5. Advanced features
+  link: advanced_features.html
+  subitems:
+    - name: Simulation restarts
+      anchor: simulation-restarts
+    - name: Complex geometries
+      anchor: complex-geometries
+
+- name: 6. Optimizing performance
   link: optimizing_performance.html
 
 # - name: Coupling with SPECFEM3D
 #   link: #
 
-- name: 6. Tutorials
+- name: 7. Tutorials
   link: tutorials.html
   sublinks:
     - name: RSF spring-block
@@ -67,8 +75,8 @@
     - name: Double asperity
       link: tutorial_double_asperity_python.html
 
-- name: 7. Developer notes
+- name: 8. Developer notes
   link: developer_notes.html
 
-- name: 8. Citing QDYN
+- name: 9. Citing QDYN
   link: cite.html

docs/advanced_features.md

@@ -0,0 +1,35 @@
+---
+layout: default
+title: Advanced features
+mathjax: true
+---
+
+# Advanced features
+
+## Simulation restarts
+
+(See `examples/notebooks/restart_simulation.ipynb` for an example of how to restart a QDYN simulation)
+
+Sometimes it can be useful to break a simulation into multiple phases, for instance if cluster CPU time is capped, or if a parametric study is performed starting from a (steady-state) reference simulation. To facilitate this, QDYN will generate a special snapshot file (`output_ox_last`) with full spatial resolution at the end of the simulation run. This snapshot contains the exact state of the fault, which serves as the starting point for the next simulation.
+
+To commence a simulation restart, first run the initial simulation until the end (so that `output_ox_last` is created). Optionally, modify the model/simulation/mesh parameters through the wrapper, followed by `qdyn.run(restart=True)`. By specifying `restart=True`, the contents of `output_ox_last` will be read and a new `qdyn.in` input file is created (including the optional changes made to the simulation parameters). Internally, the wrapper will call the compiled `qdyn` executable with the `restart` flag to communicate our intention to restart the simulation. The simulation will then continue from this new initial state, and the simulation output is appended to the output files generated by the previous simulation.
+
+One strategy to spawn numerous simulations from a single reference simulation on a cluster (e.g. for a parametric study) is as follows:
+
+1. Run a reference simulation.
+2. Create separate directories for each parameter value.
+3. Copy the reference simulation output into each directory.
+4. For each parameter, use the wrapper to modify the simulation settings and call `qdyn.run(restart=True, run=False)` to create a new `qdyn.in` file with the desired parameters, but without immediately launching the simulation. Either copy this `qdyn.in` file to each directory, or run the wrapper script directly in a given directory.
+5. Call `qdyn restart` from each directory using the protocol used by the cluster (e.g. torque)
+
+Steps 2-5 can be performed over a loop by a simple batch script.
+
+## Complex geometries
+
+(See `examples/notebooks/3D_mesh_builder.ipynb` and `examples/notebooks/intersecting_faults` for examples of how to use the mesh builder for (multiple) non-planar fault geometries)
+
+For 2D faults embedded in 3D media, it is possible to construct non-planar and discontinuous fault meshes. As currently implemented in the QDYN code, a Fourier Transformation is applied in the along-strike direction of the mesh. This requires that the mesh be continuous, evenly spaced, and co-linear along this dimension, and that the number of mesh elements be an integer power of 2. These restrictions do not apply in the along-dip direction, allowing the user some freedom in creating non-planar mesh geometries. For instance, one could create a curved fault to simulate a subduction thrust geometry, or create multiple disjoint fault segments. 
+
+By default, a uniform planar mesh is generated upon calling `qdyn.generate_mesh()`. The mesh node coordinates, size, and orientation (strike/dip) can then be adjusted by the user, similar to setting specific frictional properties or initial conditions over the fault. The wrapper contains a helper tool (`qdyn.compute_mesh_coords()`) to re-construct a mesh with user-specific variable dip angle and spacing values. After that, the user can decide to split the mesh along the dip direction into several independent faults and adjust their positions according to the desired fault geometry (see `examples/notebooks/3D_mesh_builder.ipynb`). Even though this approach permits a lot of freedom for designing custom fault geometries, the restrictions pointed out above still apply: the newly generated fault mesh needs to be uniform and co-linear along the along-strike direction. Currently there are no internal checks to automatically verify that these conditions are satisfied.
+
+It is possible to approximate a scenario with along-strike variations in the fault geometry if free-surface effects are negligible. In a homogeneous elastic medium, there is no concrete notion of up-down or left-right, and so the definition of strike and dip are arbitrary. In the absence of a free surface that breaks this symmetry, the user can simply rotate the fault by 90°, effectively swapping what is "along-strike" and "along-dip". The `intersecting_faults.ipynb` example notebook demonstrates how this trick can be leveraged to simulate two intersecting strike-slip faults with constant dip (vertical). To ensure the validity of the results, the faults are put at an arbitrarily large depth away from the free surface.

docs/developer_notes.md

@@ -12,7 +12,7 @@ The QDYN team welcomes contributions from the community, which is facilitated by
 - Push the commits to your forked repository
 - Create a pull request to merge your code with that in the QDYN repository
 
-When the pull request is made, [Travis CI](https://travis-ci.com/) will assess the validity of the code by compiling the code and running the testing suite. The core developers will ensure that the pull request will be merged with the appropriate branch (e.g. `release/2.3.4`).
+When the pull request is made, a GitHub Actions workflow will be triggered to assess the validity of the code by compiling the code and running the testing suite. The core developers will ensure that the pull request will be merged with the appropriate branch (e.g. `release/2.3.4`).
 
 For large modifications or new features, please contact the QDYN team or [open an issue](https://github.com/ydluo/qdyn/issues) on GitHub to discuss the implementation strategy.
 
@@ -27,7 +27,7 @@ The following items are under active development and will be included in the sta
 - Surface deformation to compare with GPS data
 - Slip-dependent friction law
 - 3D kernel for faults in infinite media
-- Variable strike
+- Variable strike (including free surface)
 - Layered media: EDKS (Luis Rivera), Relax (Sylvain Barbot)
 - Heterogeneous media: import kernel from Relax, Pylith, or SPECFEM3D?
 - Triangular mesh elements: e.g. Meade ([2007](https://doi.org/10.1016/j.cageo.2006.12.003)), Gimbutas et al. ([2012](https://doi.org/10.1785/0120120127)), Pan et al. ([2014](https://doi.org/10.1785/0120140161)), Nikkhoo & Walter ([2015](https://doi.org/10.1093/gji/ggv035))

docs/getting_started.md

@@ -12,13 +12,13 @@ title: Getting started
 
 - MPI (e.g. [MPICH](https://www.mpich.org/) or [Open MPI](https://www.open-mpi.org/)) linked to your Fortran compiler (`mpif90`)
 
-- Python 3+, MATLAB, or Octave. The Python wrapper relies on [NumPy](http://www.numpy.org/)/[SciPy](https://scipy.org/) and [Pandas](https://pandas.pydata.org/). The Python test suite (optional but recommended for developers) additionally requires [matplotlib](https://matplotlib.org/) and [termcolor](https://pypi.org/project/termcolor/). These dependencies are conveniently acquired through [`pip`](https://pypi.org/project/pip/):<br />
+- Python 3+. The Python wrapper relies on [NumPy](http://www.numpy.org/)/[SciPy](https://scipy.org/) and [Pandas](https://pandas.pydata.org/). The Python test suite (optional but recommended for developers) additionally requires [matplotlib](https://matplotlib.org/) and [termcolor](https://pypi.org/project/termcolor/). These dependencies are conveniently acquired through [`pip`](https://pypi.org/project/pip/):<br />
   ```
-  pip install numpy scipy pandas matplotlib termcolor
+  pip install numpy "scipy>=1.9.0" matplotlib pandas termcolor ipython
   ```
   or through [Anaconda](https://www.anaconda.com/):<br />
   ```
-  conda create -n QDYN python=3.7 numpy scipy matplotlib pandas termcolor
+  conda create -n QDYN numpy "scipy>=1.9.0" matplotlib pandas termcolor ipython
   conda activate QDYN
   ```
 
@@ -31,22 +31,21 @@ title: Getting started
 QDYN is hosted on [GitHub](https://github.com/ydluo/qdyn). To download for the first time the stable version of QDYN, execute the following git command:
 
 ```
-git clone https://github.com/ydluo/qdyn qdyn-read-only
+git clone git@github.com:ydluo/qdyn.git
 ```
 
-This creates a directory  `qdyn-read-only` which contains the whole QDYN package. You can create a directory with a different name. The code contained by the `master` branch (default) is tested and stable, but other development branches may be available. Consult the GitHub repository for the availability of
-development code.
-
+This creates a directory `qdyn` which contains the whole QDYN package. You can create a directory with a different name. The code contained by the `master` branch (default) is tested and stable, but other development branches may be available. Consult the GitHub repository for the availability of development code.
 
 
 ## Installing QDYN
 
-1. Navigate to the `src` directory
-2. Modify the section "User Settings" of the  `Makefile` following the instructions and examples therein:
-    *  In section 1, set the variable `EXEC_PATH = [target path to your executable file]`. If you set the default value (recommended) the executable file `qdyn` is placed in the `src` directory. If you change this variable, you must set the `EXEC_PATH` input variable accordingly when calling `qdyn` from the wrappers (`qdyn.m` or `pyqdyn.py`).
+1. Install the QDYN Python package by running `pip install -e .` (including the dot) from the QDYN root directory
+2. Navigate to the `qdyn` directory
+3. Modify the section "User Settings" of the  `Makefile` following the instructions and examples therein:
+    *  In section 1, set the variable `EXEC_PATH = [target path to your executable file]`. If you set the default value (recommended) the executable file `qdyn` is placed in the `qdyn` directory. If you change this variable, you must set the `EXEC_PATH` input variable accordingly when calling `qdyn` from the wrapper (`pyqdyn.py`).
     *  In section 2, adjust your Fortran compiler settings: set the variables `F90 = [your compiler]`, `OPT = [your compiler optimization flags]` and `PREPROC = [your compiler preprocessing flags]`. Settings for several commonly used compilers are provided. Note that the specific optimization flags need to be set to enable parallelization through OpenMP.
-3. Set the parameters in the section "User Settings" of `constants.f90` following the instructions therein
-4. Run `make`
+4. Set the parameters in the section "User Settings" of `constants.f90` following the instructions therein
+5. Run `make`
 
 
 
@@ -75,11 +74,13 @@ As of 2017, Windows 10 officially supports a bash command line environment by in
 
 3. Download QDYN as instructed above. Note that Windows does not have access to the Linux file system, so in order to exchange files between the subsystem and Windows, it is recommended to download QDYN to (and run simulations from) a local Windows directory (e.g. C:\Users\bob\qdyn). The Windows file system can be accessed in the Linux subsystem as:  `cd /mnt/c/Users/bob/qdyn`
 
-4. Navigate to the QDYN `src` directory and compile QDYN as described above
+4. Navigate to the QDYN root directory and install the Python package: `pip install -e .` (including the dot)
+
+5. Navigate to the QDYN `qdyn` directory and compile QDYN as described above
 
-5. In the case that the required Python or command line MATLAB/Octave packages are installed on the Linux subsystem, QDYN can be called directly from a wrapper. If none of these software packages are available, generate a `qdyn.in` file in Windows (through a wrapper), navigate within the subsystem to the location of  `qdyn.in` (e.g.  `cd /mnt/c/Users/bob/test_simulation`) and run: `/mnt/c/Users/bob/qdyn/src/qdyn`
+6. In the case that the required Python packages are installed on the Linux subsystem, QDYN can be called directly from a wrapper. If none of these software packages are available, generate a `qdyn.in` file in Windows (through a wrapper), navigate within the subsystem to the location of  `qdyn.in` (e.g. `cd /mnt/c/Users/bob/test_simulation`) and run: `/mnt/c/Users/bob/qdyn/src/qdyn`
 
-6. QDYN should now be running within the Linux subsystem, creating output files in C:\Users\bob\test_simulation that can be accessed by Windows for further processing.
+7. QDYN should now be running within the Linux subsystem, creating output files in C:\Users\bob\test_simulation that can be accessed by Windows for further processing.
 
-7. The Python wrapper (`pyqdyn.py`) also has built-in functionalities to call the subsystem directly from a Windows 10 environment. In order to set-up and run QDYN simulations from the Python wrapper, set
+8. The Python wrapper (`pyqdyn.py`) also has built-in functionalities to call the subsystem directly from a Windows 10 environment. In order to set-up and run QDYN simulations from the Python wrapper, set
     `qdyn.W10_bash = True`. When doing so, the wrapper will automatically switch between the Windows and Linux environments.