Merge pull request #100 from slimgroup/refactor-22

Major refactor and cleanup

.github/workflows/ci-examples.yml

@@ -64,6 +64,10 @@ jobs:
           version: ${{ matrix.version }}
           arch: x64
 
+      - name: Set julia python
+        run: |
+          PYTHON=$(which python3) julia -e 'using Pkg;Pkg.add("PyCall");Pkg.build("PyCall")'
+
       - name: Build JUDI
         uses: julia-actions/julia-buildpkg@latest
 
@@ -74,4 +78,4 @@ jobs:
 
       - name: Run examples
         working-directory: examples/scripts/
-        run: julia -p 2 ${{ matrix.example }}
+        run: julia -p 2 ${{ matrix.example }}

.github/workflows/ci-judi.yml

@@ -17,7 +17,6 @@ jobs:
     env:
       DEVITO_ARCH: gcc-7
       DEVITO_LANGUAGE: "openmp"
-      DEVITO_BACKEND: "core"
       OMP_NUM_THREADS: 4
       GROUP: "JUDI"
 
@@ -32,6 +31,15 @@ jobs:
       - name: Checkout JUDI
         uses: actions/checkout@v2
 
+      - name: Cache julia install
+        uses: actions/cache@v2
+        env:
+          cache-name: cache-julia-pkgs
+        with:
+          # julia is installed in ~/.julia
+          path: ~/.julia
+          key: ${{ matrix.os }}-${{ matrix.version }}-${{ env.cache-name }}
+
       - name: Setup julia
         uses: julia-actions/setup-julia@v1
         with:

.github/workflows/ci-op.yml

@@ -17,7 +17,6 @@ jobs:
     env:
       DEVITO_ARCH: gcc-9
       DEVITO_LANGUAGE: "openmp"
-      DEVITO_BACKEND: "core"
       DEVITO_LOGGING: "ERROR"
       OMP_NUM_THREADS: ${{ matrix.omp }}
       GROUP: ${{ matrix.op }}
@@ -60,16 +59,25 @@ jobs:
         if : runner.os == 'macOS'
         run : brew install gcc@9
 
-      - name: Set julia python
-        run: |
-          PYTHON=$(which python3) julia -e 'using Pkg;Pkg.add("PyCall");Pkg.build("PyCall")'
+      - name: Cache julia install
+        uses: actions/cache@v2
+        env:
+          cache-name: cache-julia-pkgs
+        with:
+          # julia is installed in ~/.julia
+          path: ~/.julia
+          key: ${{ matrix.os }}-${{ matrix.version }}-${{ env.cache-name }}
 
       - name: Setup julia
         uses: julia-actions/setup-julia@v1
         with:
           version: ${{ matrix.version }}
           arch: x64
 
+      - name: Set julia python
+        run: |
+          PYTHON=$(which python3) julia -e 'using Pkg;Pkg.add("PyCall");Pkg.build("PyCall")'
+
       - name: Build JUDI
         uses: julia-actions/julia-buildpkg@latest
 

Project.toml

@@ -1,7 +1,7 @@
 name = "JUDI"
 uuid = "f3b833dc-6b2e-5b9c-b940-873ed6319979"
 authors = ["Philipp Witte, Mathias Louboutin"]
-version = "2.6.9"
+version = "3.0.0"
 
 [deps]
 DSP = "717857b8-e6f2-59f4-9121-6e50c889abd2"
@@ -11,26 +11,29 @@ FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
 JOLI = "bb331ad6-a1cf-11e9-23da-9bcb53c69f6f"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 PyCall = "438e738f-606a-5dbb-bf0a-cddfbfd45ab0"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 SegyIO = "157a0f19-4d44-4de5-a0d0-07e2f0ac4dfa"
 
 [compat]
+Aqua = "0.5"
 DSP = "0.6, 0.7"
 Dierckx = "0.4, 0.5"
 FFTW = "1"
 JOLI = "0.7"
 PyCall = "1.18, 1.90, 1.91, 1.62"
 Reexport = "0.2, 1"
 SegyIO = "0.7.7"
-julia = "1"
 TimerOutputs = "0.5"
+julia = "1"
 
 [extras]
+Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
 ArgParse = "c7e460c6-2fb9-53a9-8c5b-16f535851c63"
 JLD2 = "033835bb-8acc-5ee8-8aae-3f567f8a3819"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 TimerOutputs = "a759f4b9-e2f1-59dc-863e-4aeb61b1ea8f"
 
 [targets]
-test = ["Test", "ArgParse", "Printf", "JLD2", "TimerOutputs"]
+test = ["Aqua", "ArgParse", "JLD2", "Printf", "Test", "TimerOutputs"]

README.md

@@ -1,9 +1,9 @@
 # The Julia Devito Inversion framework (JUDI)
 
-[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://slimgroup.github.io/JUDI.jl) 
-[![Build Status ](https://github.com/slimgroup/JUDI.jl/workflows/CI-tests/badge.svg)](https://github.com/slimgroup/JUDI.jl/actions/workflows/ci-op.yml)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3878711.svg)](https://doi.org/10.5281/zenodo.3878711)
-[![codecov](https://codecov.io/gh/slimgroup/JUDI.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/slimgroup/JUDI.jl)
+| **Documentation**     | **Build Status**    |                      |
+|:--------------------------------------:|:-----------------------------------------------:|:----------------------------------------------------:|
+| [![][docs-stable-img]][docs-stable-status] [![][docs-dev-img]][docs-dev-status] | [![][build-img]][build-status] [![][codecov-img]][codecov-status] [![][aqua-img]][aqua-status] | [![][license-img]][license-status] [![][zenodo-img]][zenodo-status] |
+
 
 ## Overview
 
@@ -52,7 +52,7 @@ export DEVITO_PLATFORM=nvidiaX
 
 ## Running with Docker
 
-If you do not want to install JUDI, you can run [JUDI] as a [docker image](https://hub.docker.com/repository/docker/mloubout/judi). The first possibility is to run the docker container as a Jupyter notebook. [JUDI] provides two docker images for the latest [JUDI] release for Julia versions `1.6` (LTS) and `1.7` (latest stable version). The images names are `mloubout/judi:JVER-latest` where `JVER` is the Julia version. This docker images contains pre-installed compilers for CPUs (gcc 10) and Nvidia GPUs (nvc) vi the nvidia HPC sdk. The environment is automatically set for [Devito] based on the hardware available. 
+If you do not want to install JUDI, you can run [JUDI] as a [docker image](https://hub.docker.com/repository/docker/mloubout/judi). The first possibility is to run the docker container as a Jupyter notebook. [JUDI] provides two docker images for the latest [JUDI] release for Julia versions `1.6` (LTS) and `1.7` (latest stable version). The images names are `mloubout/judi:JVER-latest` where `JVER` is the Julia version. This docker images contain pre-installed compilers for CPUs (gcc-10) and Nvidia GPUs (nvc) via the nvidia HPC sdk. The environment is automatically set for [Devito] based on the hardware available. 
 
 **Note**: If you wish to use your gpu, you will need to install [nvidia-docker](https://docs.nvidia.com/ai-enterprise/deployment-guide/dg-docker.html) and run `docker run --gpus all` in order to make the GPUs available at runtime from within the image.
 
@@ -72,8 +72,7 @@ Inside the container, all examples are located in the directory `/app/judi/examp
 
 **Previous versions**: As of version `v2.6.7` of JUDI, we also ship version-tagged images as `mloubout/judi:JVER-ver` where `ver` is the version of [JUDI] wanted, for example the current [JUDI] version with Julia 1.7 is `mloubout/judi:1.7-v2.6.7`
 
-**Development version**: Additionaly, we provide two images corresponding to the latest development version of [JUDI] (latest state of the master branch). These images are called `mloubout/judi:JVER-dev` and can be used in ta similar way.
-
+**Development version**: Additionally, we provide two images corresponding to the latest development version of [JUDI] (latest state of the master branch). These images are called `mloubout/judi:JVER-dev` and can be used in a similar way.
 
 
 ## Testing
@@ -88,12 +87,12 @@ via:
 By default, only the [JUDI] base API will be tested. However, the testing suite supports other modes controlled via the environment variable `GROUP` such as:
 
 ```Julia
-	GROUP=[JUDI] Julia --project -e 'using Pkg;Pkg.test(coverage=false)'
+	GROUP=JUDI Julia --project -e 'using Pkg;Pkg.test(coverage=false)'
 ```
 
 The supported modes are:
 
-- [JUDI] : Only the base API (linear operators, vectors, ...)
+- JUDI : Only the base API (linear operators, vectors, ...)
 - BASICS: Generic modeling and inversion tests such as out of core behavior
 - ISO_OP : Isotropic acoustic operators
 - ISO_OP_FS : Isotropic acoustic operators with free surface
@@ -230,7 +229,7 @@ To speed up the convergence of our imaging example, we set up a basic preconditi
 ```Julia
 # Set up matrix-free linear operators
 opt = Options(optimal_checkpointing = true)    # set to false to disable optimal checkpointing
-F = judiModeling(info, model0, q.geometry, dD.geometry; options=opt)
+F = judiModeling(model0, q.geometry, dD.geometry; options=opt)
 J = judiJacobian(F, q)
 
 # Right-hand preconditioners (model topmute)
@@ -313,8 +312,26 @@ eprint = {https://doi.org/10.1190/geo2018-0174.1}
 
 Also visit the Devito homepage at <https://www.devitoproject.org/publications> for more information and references.
 
-Contact authors via: [email protected] and [email protected].
+Contact authors via: [email protected].
+
+
+[docs-stable-img]:https://img.shields.io/badge/docs-stable-blue.svg
+[docs-stable-status]:https://slimgroup.github.io/JUDI.jl
+
+[docs-dev-img]:https://img.shields.io/badge/docs-dev-blue.svg
+[docs-dev-status]:https://slimgroup.github.io/JUDI.jl/dev
+
+[build-img]:https://github.com/slimgroup/JUDI.jl/workflows/CI-tests/badge.svg
+[build-status]:https://github.com/slimgroup/JUDI.jl/actions?query=workflow%3ACI-tests
+
+[codecov-img]:https://codecov.io/gh/slimgroup/JUDI.jl/branch/master/graph/badge.svg
+[codecov-status]:https://codecov.io/gh/slimgroup/JUDI.jl
+
+[aqua-img]:https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg
+[aqua-status]:https://github.com/JuliaTesting/Aqua.jl
 
+[zenodo-img]:https://zenodo.org/badge/DOI/10.5281/zenodo.3878711.svg
+[zenodo-status]:https://doi.org/10.5281/zenodo.3878711
 
-[Devito]:https://github.com/devitocodes/devito
-[JUDI]:https://github.com/slimgroup/JUDI.jl
+[license-img]:http://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat
+[license-status]:LICENSE.md

docker/Dockerfile.JUDI

@@ -18,4 +18,4 @@ RUN for d in ${JULIA_DEPOT_PATH}/dev/* ; do \
         julia --project -e "using Pkg; Pkg.update()" && \
         PD="$(basename $d)" && julia -e "using $PD"; \
       fi; \
-    done
+    done

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Weave = "44d3d7a6-8a23-5bf8-98c5-b353f8df5ec9"
 
 [compat]
 Documenter = "0.25"

docs/make.jl

@@ -1,23 +1,42 @@
-using Documenter, JUDI
+using Documenter, JUDI, Weave
 
+import JUDI: judiMultiSourceVector
+import Base.show
+
+# Some dispatch needed for Weave
+show(io::IO, ::MIME, ms::judiMultiSourceVector) = println(io, "$(typeof(ms)) wiht $(ms.nsrc) sources")
+show(io::IO, ::MIME, m::Model) = print(io, "Model (n=$(m.n), d=$(m.d), o=$(m.o)) with parameters $(keys(m.params))")
+show(io::IO, ::MIME, A::PhysicalParameter) = println(io, "$(typeof(A)) of size $(A.n) with origin $(A.o) and spacing $(A.d)")
+show(io::IO, ::MIME, G::Geometry) = println(io, "$(typeof(G)) wiht $(length(G.nt)) sources")
+
+# Convert example to documentation markdown file
+ex_path = "$(JUDI.JUDIPATH)/../examples/scripts"
+weave("$(ex_path)/modeling_basic_2D.jl"; out_path="src/tutorials/05_quickstart.md", doctype="github")
+
+# Create documentation
 makedocs(sitename="JUDI documentation",
          doctest=false, clean=true,
          authors="Mathias Louboutin",
          pages = Any[
              "Home" => "index.md",
              "About" => "about.md",
              "Installation" => "installation.md",
-             "Abstract vectors" => "abstract_vectors.md",
-             "Data Structures" => "data_structures.md",
-             "Linear Operators" => "linear_operators.md",
-             "Input/Output" => "io.md",
-             "Helper Functions" => "helper.md",
+             "JUDI API" => Any[
+                "Abstract vectors" => "abstract_vectors.md",
+                "Data Structures" => "data_structures.md",
+                "Linear Operators" => "linear_operators.md",
+                "Input/Output" => "io.md",
+                "Helper Functions" => "helper.md"],
+             "Getting Started" => "basics.md",
              "Inversion" => "inversion.md",
-             "Tutorial" => "tutorials.md",
-             "Devito backend reference" => "pysource.md"],
+             "Tutorials" => map(
+                s -> "tutorials/$(s)",
+                sort(filter(x->endswith(x, ".md"), readdir(joinpath(@__DIR__, "src/tutorials/"))))),
+              "Devito backend reference" => "pysource.md"],
          format = Documenter.HTML(
                 # assets = ["assets/slim.css"],
                 prettyurls = get(ENV, "CI", nothing) == "true"),
         )
 
+# Deploy documentation
 deploydocs(repo="github.com/slimgroup/JUDI.jl")

docs/src/abstract_vectors.md

@@ -6,6 +6,10 @@ JUDI provides abstract vector types that encapsulate seismic related objects. In
 Pages = ["abstract_vectors.md"]
 ```
 
+At the core of JUDI's vector types is the abstract type `judiMultiSourceVector` that represent a dimensionalized `Vector{Array}` where each sub-array correspond to a single source. All JUDI vector types inhert from this abstract type that implements most of the arithmetic and julia core utilities. As an abstract types, `judiMultiSourceVector` should not be instantiated but new concrete types based on it should be created if one desire to create its own JUDI multi-source vector type.
+
+All sub-type of `judiMultiSourceVector` must implement the following methods to be compatible with JUDI. The following JUDI core types are examples of sub-types.
+
 ## judiVector
 
 The class `judiVector` is the basic data structure for seismic shot records or seismic sources. From JUDI's perspective, both are treated the same and can be multiplied with modeling operators.
@@ -84,10 +88,9 @@ Abstract vector class for wavefields.
 **Construction:**
 
 ```@docs
- judiWavefield(info,dt::Real,data::Union{AbstractArray, String};  vDT::DataType=Float32)
+ judiWavefield
 ```
 
-
 **Access fields:**
 
 ```julia
@@ -126,8 +129,8 @@ Abstract vector class for a right-hand-side (RHS). A RHS has the size of a full
 
 **Construction:**
 
-```@docs
-judiRHS(info, geometry, data;vDT::DataType=Float32)
+```julia
+rhs = judiRHS(geometry, data)
 ```
 
 A JUDI RHS can also be constructed by multplying a `judiVector` and the corresponding transpose of a `judiProjection` operator:
@@ -178,34 +181,3 @@ w.weights[i]
 **Operations:**
 
 Supports the same arithmetric operations as a `judiVector`.
-
-
-## judiExtendedSource
-
-Abstract data vector for an extended source. This data structure is the equivalent type of `judiRHS` for extended source modeling. A `judiExtendedSource` has the dimension of the full wavefield, but only contains the 1D wavelet and the 2D/3D spatially varying weights in memory.
-
-**Construction:**
-
-Construction from weights and source wavelets:
-
-```@docs
-judiExtendedSource(info,wavelet,weights;vDT::DataType=Float32)
-```
-
-Or alternatively, construction from a `judiWeights` vector and a `judiLRWF` injection operator:
-
-```julia
-ex_src = Pw'*w
-```
-
-where `Pw` is a `judiLRWF` operator and `w` is a `judiWeights` vector.
-
-**Access fields:**
-
-```julia
-# Access weights of i-th source location
-ex_src.weights[i]
-
-# Access wavelet of i-th source location
-ex_src.wavelet[i]
-```