adds scattering perturbations feature, lunar projections (LTM/LPS) & Moon example

CONTRIBUTING.md

@@ -1,29 +1,29 @@
-# Contributing to SPECFEM3D
+# Contributing to SPECFEM3D Cartesian
 
-You want to contribute to the SPECFEM code? Great, let's check out this set of simple guidelines to follow for contributions.
+You want to contribute to the SPECFEM3D Cartesian code? Great, let's check out this set of simple guidelines to follow for contributions.
 
 ## Contributing as a user
 
 Software needs constant maintaining and updating to keep up with newest hardware and compilers.
-You found an issue when running the code? Please consider creating a "*New issue*" on the [SPECFEM3D Issues github page](https://github.com/SPECFEM/specfem3d/issues).
+You found an issue when running the code? Please consider creating a "*New issue*" on the [SPECFEM3D Cartesian Issues github page](https://github.com/SPECFEM/specfem3d/issues).
 
 Describe the problem as detailed as possible to help us reproduce the error. You can also attach console outputs from the executables to make it easier for debugging. Feel free to add an appropriate label to highlight the issue by checking out "*Labels*" on the right side of the page. Once done, click the button "*Submit new issue*". Catching bugs is always welcome, many thanks to you for improving the code!
 
 ## Contributing as a developer
 
 You have a new feature, bug fix, or other modification you want to contribute to the code? In this case, consider submitting a "*Pull request*" to the **devel branch** of our github code repository.
 
-This will require a few steps to setup your own github fork and be able to create a PR to the official devel version of the SPECFEM code (**note that only Pull requests towards devel are accepted**). The most basic setup looks the following:
+This will require a few steps to setup your own github fork and be able to create a PR to the official devel version of the SPECFEM3D Cartesian code (**note that only Pull requests towards devel are accepted**). The most basic setup looks the following:
 
 #### 1. Create your fork of the repository:
-Go to the main [SPECFEM3D github repository](https://github.com/SPECFEM/specfem3d) and click the "*Fork*" button at the top of the page. This will create a copy of the SPECFEM3D repository in your personal GitHub account.
+Go to the main [SPECFEM3D Cartesian github repository](https://github.com/SPECFEM/specfem3d) and click the "*Fork*" button at the top of the page. This will create a copy of the SPECFEM3D repository in your personal GitHub account.
 
 #### 2. Clone your fork to your local workstation/laptop:
 ```
 git clone --recursive --branch devel https://github.com/<your-github-account-name>/specfem3d.git
 ```
 Once you change into your local folder `cd specfem3d/`, all git commands will be recognized.  
-Now, add the remote address of the SPECFEM3D repository:
+Now, add the remote address of the SPECFEM3D Cartesian repository:
 ```
 git remote add upstream https://github.com/SPECFEM/specfem3d.git
 ```
@@ -77,7 +77,7 @@ In the "*Open a pull request*" page, double-check that the base repository is: *
 #### 6. Final merge:
 We'll do the rest by reviewing your code changes, checking if the Github Actions, Travis and Azure checks all look okay. We might follow up with you by commenting on the PR, as you can still fix smaller issues in the PR by committing them to your github fork version.<br>
 
-Finally, if the are no merge conflicts, the new version still compiles and tests pass, we'll merge your PR into the SPECFEM devel version - **with big thanks to you from the maintainers and the whole community!**
+Finally, if the are no merge conflicts, the new version still compiles and tests pass, we'll merge your PR into the SPECFEM3D Cartesian devel version - **with big thanks to you from the maintainers and the whole community!**
 
 
 ## Further informations

EXAMPLES/applications/cmt_force_hybrid/README.md

@@ -3,13 +3,13 @@
 This example provides a simple guide for the simultaneous use of point-force and moment-tensor sources in SEM simulations.
 
 
-1. **Enable Hybrid `FORCESOLUTION` and `CMTSOLUTION`**  
-   In `DATA/Par_file`, set:  
+1. **Enable Hybrid `FORCESOLUTION` and `CMTSOLUTION`**
+   In `DATA/Par_file`, set:
    ```fortran
    USE_CMT_AND_FORCE_SOURCE = .true.`
 The program will then read both `FORCESOLUTION` and `CMTSOLUTION` from the `DATA` directory and run a simulation using both point force and CMT sources.
 
-2. **Use Binary Source Files**  
+2. **Use Binary Source Files**
 when
 ```fortran
 USE_BINARY_SOURCE_FILE  = .true.
@@ -18,7 +18,7 @@ is set in `DATA/Par_file`, all source attributes and source time functions must
   ```fortran
   access='stream'
   ```
-  in the `write` statement.  
+  in the `write` statement.
 - When both options are enabled, the program ignores `FORCESOLUTION` and `CMTSOLUTION` and instead reads from SOLUTION.bin.
 - The format of SOLUTION.bin is illustrated in the Fortran snippet below:
 ```fortran
@@ -49,7 +49,7 @@ enddo
 ```
 you can also refer to `write_binary_source.f90` for a small example.
 
-3. **Use an External Source Time Function**  
+3. **Use an External Source Time Function**
 In `DATA/Par_file`, enable:
 ```fortran
 USE_EXTERNAL_SOURCE_FILE = .true.

EXAMPLES/applications/cmt_force_hybrid/step2_get_binary_source.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
 gfortran write_binary_source.f90 -o write_source
 
-./write_source 
+./write_source
 \rm write_source

EXAMPLES/applications/cmt_force_hybrid/step3_run_simulations.sh

@@ -7,17 +7,17 @@
 # function to change Par_file
 change_parfile() {
     local param=$1
-    local value=$2 
+    local value=$2
     local file="DATA/Par_file"
 
     local oldstr=`grep "^$param " $file`
     local newstr="$param     =       $value"
 
     sed  "s?$oldstr?$newstr?g" $file  > tmp
-    mv tmp $file 
+    mv tmp $file
 }
 
-set -e 
+set -e
 
 # USER DEFINED VARIABLES
 GPU_MODE=.TRUE.
@@ -30,28 +30,28 @@ change_parfile USE_FORCE_POINT_SOURCE .true.
 change_parfile USE_CMT_AND_FORCE_SOURCE .true.
 change_parfile USE_BINARY_SOURCE_FILE .false.
 change_parfile USE_EXTERNAL_SOURCE_FILE  .true.
-bash run.sh 
+bash run.sh
 mv OUTPUT_FILES OUTPUT_FILES.txt
 
 #run binary source
 change_parfile USE_FORCE_POINT_SOURCE .true.
 change_parfile USE_CMT_AND_FORCE_SOURCE .true.
 change_parfile USE_BINARY_SOURCE_FILE .true.
 change_parfile USE_EXTERNAL_SOURCE_FILE  .true.
-bash run.sh 
+bash run.sh
 mv OUTPUT_FILES OUTPUT_FILES.bin
 
 #seperate run
 change_parfile USE_FORCE_POINT_SOURCE .true.
 change_parfile USE_CMT_AND_FORCE_SOURCE .false.
 change_parfile USE_BINARY_SOURCE_FILE .false.
 change_parfile USE_EXTERNAL_SOURCE_FILE  .true.
-bash run.sh 
+bash run.sh
 mv OUTPUT_FILES OUTPUT_FILES.force
 
 change_parfile USE_FORCE_POINT_SOURCE .false.
 change_parfile USE_CMT_AND_FORCE_SOURCE .false.
 change_parfile USE_BINARY_SOURCE_FILE .false.
 change_parfile USE_EXTERNAL_SOURCE_FILE  .true.
-bash run.sh 
+bash run.sh
 mv OUTPUT_FILES OUTPUT_FILES.moment

EXAMPLES/applications/cmt_force_hybrid/write_binary_source.f90

@@ -1,16 +1,16 @@
 subroutine linspace(n,xmin,xmax,arr)
   implicit none
-  integer,intent(in) :: n 
-  real,intent(in) :: xmin,xmax 
+  integer,intent(in) :: n
+  real,intent(in) :: xmin,xmax
   double precision,intent(inout) :: arr(n)
 
-  !local 
+  !local
   integer :: i
 
-  if(n == 1) then 
+  if (n == 1) then
     arr(1) = xmin
-  else 
-    do i = 0,n-1 
+  else
+    do i = 0,n-1
       arr(i + 1) = xmin + (xmax - xmin) / (n-1) * i
     enddo
   endif
@@ -32,21 +32,21 @@ program main
   integer,parameter :: IO = 123, IO_TXT = 12114 ! FILE number
   integer,parameter ::  NSTEP= 3000
   integer :: isource,it,i
-  logical :: USE_EXTERNAL_SOURCE = .TRUE.
+  logical :: USE_EXTERNAL_SOURCE = .true.
 
   ! allocate space for force
   integer,dimension(NS_FORCE) :: force_stf ! source time function flag
-  double precision,dimension(NS_FORCE) :: lat_f,lon_f,depth_f,hdur_f,shift_f,&
-                                          factor_f,fe,fn,fzup 
+  double precision,dimension(NS_FORCE) :: lat_f,lon_f,depth_f,hdur_f,shift_f, &
+                                          factor_f,fe,fn,fzup
   real :: external_stf_force(NSTEP,NS_FORCE)
-  
+
   ! allocate space for cmt
   double precision,dimension(NS_CMT) :: lat_c,lon_c,depth_c,hdur_c,shift_c
   double precision, dimension(6,NS_CMT) :: mt ! Mrr Mtt Mpp Mrt Mrp Mtp
   real :: external_stf_cmt(NSTEP,NS_CMT)
 
-  !filename 
-  character(len=128) :: filename 
+  !filename
+  character(len=128) :: filename
 
   ! set value for FORCE, same as FORCESOLUTION
   force_stf = 0
@@ -59,9 +59,9 @@ program main
   do isource = 1,NS_FORCE
     write(filename,'(a,i0,a)') './DATA/stf.force.',isource-1,'.txt'
     open(IO_TXT,file=trim(filename))
-    do it=1,NSTEP 
+    do it = 1,NSTEP
       read(IO_TXT,*) external_stf_force(it,isource)
-    enddo; 
+    enddo;
     close(IO_TXT)
   enddo
 
@@ -74,14 +74,14 @@ program main
 
   do i = 1,NS_CMT
     lat_c(i) = -523.131 + 1000. / (NS_CMT - 1) * (i-1)
-  enddo 
+  enddo
 
   do isource = 1,NS_CMT
     write(filename,'(a,i0,a)') './DATA/stf.cmt.',isource-1,'.txt'
     open(IO_TXT,file=trim(filename))
-    do it=1,NSTEP 
+    do it = 1,NSTEP
       read(IO_TXT,*) external_stf_cmt(it,isource)
-    enddo; 
+    enddo;
     close(IO_TXT)
   enddo
 
@@ -94,23 +94,23 @@ program main
   do isource = 1,NS_CMT
     write(IO) shift_c(isource),hdur_c(isource),lat_c(isource),lon_c(isource),depth_c(isource)
     write(IO) mt(:,isource) !  Mrr Mtt Mpp Mrt Mrp Mtp
-    if(USE_EXTERNAL_SOURCE) write(IO) external_stf_cmt(:,isource)
+    if (USE_EXTERNAL_SOURCE) write(IO) external_stf_cmt(:,isource)
 
 
-    ! txt file 
+    ! txt file
     write(IO_TXT,*)'PDE  1999 01 01 00 00 00.00  67000 67000 -25000 4.2 4.2 hom_explosion'
     write(IO_TXT,*) 'event name:       hom_explosion'
     write(IO_TXT,*) 'time shift:', shift_c(isource)
     write(IO_TXT,*) 'half duration:',   hdur_c(isource)
     write(IO_TXT,*) 'latorUTM:',       lat_c(isource)
     write(IO_TXT,*) 'longorUTM:',      lon_c(isource)
     write(IO_TXT,*) 'depth:',           depth_c(isource)
-    write(IO_TXT,*) 'Mrr:',  mt(1,isource)    
-    write(IO_TXT,*) 'Mtt:',  mt(2,isource)      
-    write(IO_TXT,*) 'Mpp:',  mt(3,isource)       
-    write(IO_TXT,*) 'Mrt:',  mt(4,isource)      
-    write(IO_TXT,*) 'Mrp:',  mt(5,isource)       
-    write(IO_TXT,*) 'Mtp:',  mt(6,isource)  
+    write(IO_TXT,*) 'Mrr:',  mt(1,isource)
+    write(IO_TXT,*) 'Mtt:',  mt(2,isource)
+    write(IO_TXT,*) 'Mpp:',  mt(3,isource)
+    write(IO_TXT,*) 'Mrt:',  mt(4,isource)
+    write(IO_TXT,*) 'Mrp:',  mt(5,isource)
+    write(IO_TXT,*) 'Mtp:',  mt(6,isource)
     write(filename,'(a,i0,a)') './DATA/stf.cmt.',isource-1,'.txt'
     write(IO_TXT,*) trim(filename)
   enddo
@@ -122,7 +122,7 @@ program main
     write(IO) shift_f(isource),hdur_f(isource),lat_f(isource),lon_f(isource),depth_f(isource)
     write(IO) force_stf(isource)
     write(IO) factor_f(isource),fe(isource),fn(isource),fzup(isource)
-    if(USE_EXTERNAL_SOURCE) write(IO) external_stf_force(:,isource)
+    if (USE_EXTERNAL_SOURCE) write(IO) external_stf_force(:,isource)
 
     !txt file
     write(IO_TXT,*) 'FORCE  001'

EXAMPLES/applications/homogeneous_acoustic/MESH-default/nummaterial_velocity_file

@@ -1 +1,31 @@
+! note: format of nummaterial_velocity_file must be
+!
+! #(1)material_domain_id #(2)material_id  #(3)rho  #(4)vp   #(5)vs   #(6)Q_kappa   #(7)Q_mu  #(8)anisotropy_flag
+!
+! where
+!     material_domain_id : 1=acoustic / 2=elastic
+!     material_id        : POSITIVE integer identifier corresponding to the identifier of material block
+!     rho                : density
+!     vp                 : P-velocity
+!     vs                 : S-velocity
+!     Q_kappa            : 9999 = no Q_kappa attenuation
+!     Q_mu               : 9999 = no Q_mu attenuation
+!     anisotropy_flag    : 0=no anisotropy/ 1,2,.. check with implementation in aniso_model.f90
+!
+!example:
+!2   1 2300 2800 1500 9999.0 9999.0 0
+!
+!or
+!
+! #(1)material_domain_id #(2)material_id  tomography elastic  #(3)tomography_filename #(4)positive_unique_number
+!
+! where
+!     material_domain_id : 1=acoustic / 2=elastic
+!     material_id        : NEGATIVE integer identifier corresponding to the identifier of material block
+!     tomography_filename: filename of the tomography file
+!     positive_unique_number: a positive unique identifier
+!
+!example:
+!2  -1 tomography elastic tomo.xyz 1
+
 1   1          2300.000000          2800.000000          0.000000    9999.00000  9999.00000  0

EXAMPLES/applications/homogeneous_acoustic/REF_KERNEL/output.log

@@ -15,7 +15,7 @@ decomposing mesh...
    using NGNOD =            8
    linear elements
 
- total number of nodes: 
+ total number of nodes:
    nnodes =        23273
  total number of spectral elements:
    nspec =        20736
@@ -83,7 +83,7 @@ decomposing mesh...
    load per partition: imbalance =    1.53374231     %
                        (0% being totally balanced, 100% being unbalanced)
 
- partitions: 
+ partitions:
    num         =            4
    ninterfaces =            6
 
@@ -105,7 +105,7 @@ forward simulation
 #########################################################
 (running forward simulation with saving forward wavefield)
 
-Changed simulation_type to 1 and save_forward = .true. in Par_file 
+Changed simulation_type to 1 and save_forward = .true. in Par_file
 
 running solver on  4 processors...
 
@@ -128,23 +128,23 @@ gfortran  -o xcreate_adjsrc_traveltime create_adjsrc_traveltime.o rw_ascfile_c.o
 running adjoint source creation
 
  xcreate_adjsrc_traveltime:
-   measurement window start/end =    9.0000000000000000      /   26.000000000000000     
+   measurement window start/end =    9.0000000000000000      /   26.000000000000000
    component ifile =            1   lrot =  F
-  
+
  reading asc file DB.X20.MXX.semp ...
  reading asc file DB.X20.MXY.semp ...
  reading asc file DB.X20.MXZ.semp ...
-  
- start time:  -6.0000000000000000     
- time step:  0.11359978000000037     
+
+ start time:  -6.0000000000000000
+ time step:  0.11359978000000037
  number of steps:         300
-  
- i =            1 norm =    51519175283406.109     
- i =            2 norm =    51519175283406.109     
+
+ i =            1 norm =    51519175283406.109
+ i =            2 norm =    51519175283406.109
    component set to zero
- i =            3 norm =    51519175283406.109     
+ i =            3 norm =    51519175283406.109
    component set to zero
-  
+
  write to asc file DB.X20.MXX.adj
  write to asc file DB.X20.MXY.adj
  write to asc file DB.X20.MXZ.adj
@@ -157,7 +157,7 @@ kernel simulation
 #########################################################
 (running kernel simulation: SIMULATION_TYPE == 3)
 
-Changed simulation_type to 3 in Par_file 
+Changed simulation_type to 3 in Par_file
 
 running solver (kernel run) on  4 processors...