changes to docs

README.md

@@ -2,7 +2,7 @@
 [![Build Status](https://github.com/JuliaGeodynamics/LaMEM.jl/workflows/CI/badge.svg)](https://github.com/JuliaGeodynamics/LaMEM.jl/actions)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://juliageodynamics.github.io/LaMEM.jl/dev/)
 
-This is the Julia interface to [LaMEM](https://bitbucket.org/bkaus/lamem) (Lithosphere and Mantle Evolution Model), which is the easiest way to install LaMEM on any system, allows you to start a (parallel) LaMEM simulation, and read back the output files to julia for further processing.
+This is the Julia interface to [LaMEM](https://bitbucket.org/bkaus/lamem) (Lithosphere and Mantle Evolution Model), which is the easiest way to install LaMEM on any system. It allows you to start a (parallel) LaMEM simulation, and read back the output files to julia for further processing.
 
 ### 1. Installation
 Go to the package manager & install it with:
@@ -45,7 +45,7 @@ Time stepping parameters:
 ```
 The last parameter are optional PETSc command-line options. By default it runs on one processor.
 
-Please note that you will have to be in the correct directory (the same one as where the LaMEM parameter file is located). If you are in a different directory, the easiest way to change to the correct one is by using the `changefolder` function (on Windows and Mac):
+Please note that you will have to be in the correct directory or indicate where that directory is. If you are in a different directory, the easiest way to change to the correct one is by using the `changefolder` function (on Windows and Mac):
 ```julia
 julia> changefolder()
 ```
@@ -61,51 +61,35 @@ use the Backspace key to return to the julia REPL.
 Once you have performed a simulation, you can look at the results by opening the `*.pvd` files with Paraview. In this example, that would be `FB_multigrid.pvd` and `FB_multigrid_phase.pvd`.
 
 ### 3. Reading LaMEM output back into julia
-If you want to quantitatively do something with the results, there is an easy way to read the output of a LaMEM timestep back into julia. Yet, first you have to install the `PythonCall` package as we rely on a python package to read the LaMEM (`*.vtr`) output files:
-If you want to quantitatively do something with the results, there is an easy way to read the output of a LaMEM timestep back into julia. 
+If you want to quantitatively do something with the results, there is an easy way to read the output of a LaMEM timestep back into julia. All routines related to that are part of the `LaMEM.IO` module.
+
 ```julia
 julia> using LaMEM
-Adding PythonCall dependencies to read LaMEM timesteps
 ```
-Make sure you are in the directory where the simulation was run and read a timestep with:
+You can first read the `*.pvd` file in the directory to see which timesteps are available:
 ```julia
-julia> FileName="FB_multigrid.pvtr"
-julia> DirName = "Timestep_00000001_6.72970343e+00"
-julia> data    = Read_VTR_File(DirName, FileName)
-CartData 
-    size    : (33, 33, 33)
-    x       ϵ [ 0.0 : 1.0]
-    y       ϵ [ 0.0 : 1.0]
-    z       ϵ [ 0.0 : 1.0]
-    fields  : (:phase, :visc_total, :visc_creep, :velocity, :pressure, :strain_rate, :j2_dev_stress, :j2_strain_rate)
-  attributes: ["note"]
+julia> FileName="FB_multigrid"
+julia> DirName ="test"
+julia> Timestep, Filenames, Time = Read_LaMEM_simulation(FileName, DirName)
+([0, 1], ["Timestep_00000000_0.00000000e+00/FB_multigrid.pvtr", "Timestep_00000001_6.72970343e+00/FB_multigrid.pvtr"], [0.0, 6.729703])
 ```
-The output is in a `CartData` structure (as defined in GeophysicalModelGenerator).
-
-Please note that you will have to be in the correct directory (see above).
-Once you have performed a simulation, you can look at the results by opening the `*.pvd` files with Paraview. In this example, that would be `FB_multigrid.pvd` and `FB_multigrid_phase.pvd`.
-
-### 3. Reading LaMEM output back into julia
-If you want to quantitatively do something with the results, there is an easy way to read the output of a LaMEM timestep back into julia.  Make sure you are in the directory where the simulation was run and read a timestep with:
+We can read a particular timestep (say 1) with:
 ```julia
-julia> FileName="FB_multigrid.pvtr"
-julia> DirName = "Timestep_00000001_6.72970343e+00"
-julia> data    = Read_VTR_File(DirName, FileName)
-CartData 
+julia> data, time = Read_LaMEM_timestep(FileName, 1, DirName)
+(CartData 
     size    : (33, 33, 33)
     x       ϵ [ 0.0 : 1.0]
     y       ϵ [ 0.0 : 1.0]
     z       ϵ [ 0.0 : 1.0]
     fields  : (:phase, :visc_total, :visc_creep, :velocity, :pressure, :strain_rate, :j2_dev_stress, :j2_strain_rate)
   attributes: ["note"]
+, [6.729703])
 ```
 The output is in a `CartData` structure (as defined in GeophysicalModelGenerator).
+More details are given in the documentation.
 
 ### 4. Dependencies
 We rely on the following packages:
 - [GeophysicalModelGenerator](https://github.com/JuliaGeodynamics/GeophysicalModelGenerator.jl) - Data structure in which we store the info of a LaMEM timestep. The package can also be used to generate setups for LaMEM.
 - [LaMEM_jll](https://github.com/JuliaRegistries/General/tree/master/L/LaMEM_jll) - this contains the LaMEM binaries, precompiled for most systems. Note that on windows, the MUMPS parallel direct solver is not available.
-
-And for reading files, we rely on the optional package
-- [PythonCall](https://github.com/cjdoris/PythonCall.jl) - installs a local python version and the VTK toolbox, used to read the output files. We make this an optional dependency as this involves installing quite a few additional packages, which have been broken at some times in the past. If you experience problems, you can try installing an earlier version of [MicroMamba](https://github.com/cjdoris/MicroMamba.jl) first (e.g. `pkg> add [email protected]`), before installing `PythonCall` .  
-
+- [ReadVTK](https://github.com/JuliaVTK/ReadVTK.jl) - This reads the LaMEM `*.vtk` files (or the rectilinear and structured grid versions of it)  baxck into julia.

docs/make.jl

@@ -10,6 +10,8 @@ makedocs(;
     pages=[
         "Home" => "index.md",
         "Installation" => "man/installation.md",
+        "Run LaMEM" => "man/runlamem.md",
+        "Reading timesteps" => "man/readtimesteps.md",
         "List of functions" => "man/listfunctions.md",
     ],
 )

docs/src/index.md

@@ -4,4 +4,4 @@ This is the julia interface to LaMEM, which does a number of handy things:
 
 - It will automatically download a binary installation of LaMEM, along with the correct version of PETSc and mpiexec for your system. You can also use these binaries directly from your terminal, so you are not limited to julia. Gone are the days where you had to first spend hours or days to install PETSc on your system!
 - We provide a simple function to run LaMEM from julia (also in parallel).
-- We provide functions to read info from timesteps back into julia. 
+- We provide functions to read timesteps back into julia. 

docs/src/man/installation.md

@@ -12,22 +12,13 @@ You can test if it works on your machine with
 pkg> test LaMEM
 ```
 
-If you also want to read LaMEM output files back to julia, you need to install the `PythonCall` package:
-```julia
-julia> ]
-pkg> add PythonCall
-```
-
-### Running LaMEM from julia
+### Running LaMEM from the julia REPL
 Running LaMEM from within julia can be done with the `run_lamem` function:
 
 ```@docs
 LaMEM.run_lamem
 ```
 
-
-
-
 ### Running LaMEM from outside julia
 If you, for some reason, do not want to run LaMEM through julia but instead directly from the terminal or powershell, you will have to add the required dynamic libraries and executables.
 Do this with:

docs/src/man/listfunctions.md

@@ -1,7 +1,13 @@
 # List of all functions
 
-These are all functions that are available in the package:
+These are all functions that are available in the package, which can roughly be divided inton two groups (running & reading LaMEM)
 
+## Running LaMEM
 ```@autodocs
-Modules = [LaMEM]
+Modules = [LaMEM.Run]
+
+```
+## Reading LaMEM output back into julia
+```@autodocs
+Modules = [LaMEM.IO]
 ```

docs/src/man/readtimesteps.md

@@ -0,0 +1,58 @@
+# Read timesteps back into LaMEM
+If you want to quantitatively do something with the results, there is an easy way to read the output of a LaMEM timestep back into julia. All routines related to that are part of the `LaMEM.IO` module.
+
+```julia
+julia> using LaMEM
+```
+You can first read the `*.pvd` file in the directory to see which timesteps are available:
+```julia
+julia> FileName="FB_multigrid"
+julia> DirName ="test"
+julia> Timestep, Filenames, Time = Read_LaMEM_simulation(FileName, DirName)
+([0, 1], ["Timestep_00000000_0.00000000e+00/FB_multigrid.pvtr", "Timestep_00000001_6.72970343e+00/FB_multigrid.pvtr"], [0.0, 6.729703])
+```
+We can read a particular timestep (say 1) with:
+```julia
+julia> data, time = Read_LaMEM_timestep(FileName, 1, DirName)
+(CartData 
+    size    : (33, 33, 33)
+    x       ϵ [ 0.0 : 1.0]
+    y       ϵ [ 0.0 : 1.0]
+    z       ϵ [ 0.0 : 1.0]
+    fields  : (:phase, :visc_total, :visc_creep, :velocity, :pressure, :strain_rate, :j2_dev_stress, :j2_strain_rate)
+  attributes: ["note"]
+, [6.729703])
+```
+The output is in a `CartData` structure (as defined in GeophysicalModelGenerator).
+
+If you do not indicate a directory name (`DirName`) it'll look in your current directory. The default above will load the main LaMEM simulation output. Alternatively, you can also load the `phase` information by specify the optional keyword `phase=true`:
+```julia
+julia> data, time = Read_LaMEM_timestep(FileName, 1, DirName, phase=true)
+(CartData 
+    size    : (96, 96, 96)
+    x       ϵ [ 0.0052083334885537624 : 0.9947916269302368]
+    y       ϵ [ 0.0052083334885537624 : 0.9947916269302368]
+    z       ϵ [ 0.0052083334885537624 : 0.9947916269302368]
+    fields  : (:phase,)
+  attributes: ["note"]
+, [6.729703])
+```
+In the same way, you can load the internal free surface with `surf=true` (if that was saved), or passive tracers (`passive_tracers=true`).
+If you don't want to load all the fields in the file back to julia, you can check which fields are available:
+
+```julia
+julia> Read_LaMEM_fieldnames(FileName, DirName)
+("phase [ ]", "visc_total [ ]", "visc_creep [ ]", "velocity [ ]", "pressure [ ]", "strain_rate [ ]", "j2_dev_stress [ ]", "j2_strain_rate [ ]")
+```
+and load only part of those:
+```julia
+julia> data, time = Read_LaMEM_timestep(FileName, 1, DirName, fields=("phase [ ]", "visc_total [ ]","velocity [ ]"))
+(CartData 
+    size    : (33, 33, 33)
+    x       ϵ [ 0.0 : 1.0]
+    y       ϵ [ 0.0 : 1.0]
+    z       ϵ [ 0.0 : 1.0]
+    fields  : (:phase, :visc_total, :velocity)
+  attributes: ["note"]
+, [6.729703])
+```

docs/src/man/runlamem.md

@@ -0,0 +1,55 @@
+# Run LaMEM
+Go to the package manager & install it with:
+```julia
+julia>]
+pkg>add LaMEM
+```
+It will automatically download a binary version of LaMEM which runs in parallel (along with the correct PETSc version). This will work on linux, mac and windows.
+
+### Starting a simulation
+As usual, you need a LaMEM (`*.dat`) input file, which you can run in parallel (here on 4 cores) with:
+```julia
+julia> ParamFile="input_files/FallingBlock_Multigrid.dat";
+julia> run_lamem(ParamFile, 4,"-time_end 1")
+-------------------------------------------------------------------------- 
+                   Lithosphere and Mantle Evolution Model                   
+     Compiled: Date: Sep 10 2022 - Time: 06:21:30           
+-------------------------------------------------------------------------- 
+        STAGGERED-GRID FINITE DIFFERENCE CANONICAL IMPLEMENTATION           
+-------------------------------------------------------------------------- 
+Parsing input file : input_files/FallingBlock_Multigrid.dat 
+   Adding PETSc option: -snes_type ksponly
+   Adding PETSc option: -js_ksp_monitor
+   Adding PETSc option: -crs_pc_type bjacobi
+Finished parsing input file : input_files/FallingBlock_Multigrid.dat 
+--------------------------------------------------------------------------
+Time stepping parameters:
+   Simulation end time          : 1. [ ] 
+   Maximum number of steps      : 10 
+   Time step                    : 10. [ ] 
+   Minimum time step            : 1e-05 [ ] 
+   Maximum time step            : 100. [ ] 
+   Time step increase factor    : 0.1 
+   CFL criterion                : 0.5 
+   CFLMAX (fixed time steps)    : 0.5 
+   Output time step             : 0.2 [ ] 
+   Output every [n] steps       : 1 
+   Output [n] initial steps     : 1 
+--------------------------------------------------------------------------
+```
+The last parameter are optional PETSc command-line options. By default it runs on one processor.
+
+Please note that you will have to be in the correct directory or indicate where that directory is. If you are in a different directory, the easiest way to change to the correct one is by using the `changefolder` function (on Windows and Mac):
+```julia
+julia> changefolder()
+```
+
+Alternatively, you can use the build-in terminal/shell in julia, which you can access with:
+```julia
+julia>;
+shell>cd ~/LaMEM/input_models/BuildInSetups/
+```
+use the Backspace key to return to the julia REPL.
+
+
+Once you have performed a simulation, you can look at the results by opening the `*.pvd` files with Paraview. In this example, that would be `FB_multigrid.pvd` and `FB_multigrid_phase.pvd`.

src/read_timestep.jl

@@ -395,7 +395,7 @@ end
 
 
 """ 
-    FileNames, Time, Timestep = Read_LaMEM_simulation(FileName::String, DirName::String=""; phase=false, surf=false, passive_tracers=false)
+    Timestep, FileNames, Time = Read_LaMEM_simulation(FileName::String, DirName::String=""; phase=false, surf=false, passive_tracers=false)
 
 Reads a LaMEM simulation `FileName` in directory `DirName` and returns the timesteps, times and filenames of that simulation.
 """

src/run_lamem.jl

@@ -10,24 +10,18 @@ This starts a LaMEM simulation, for using the parameter file `ParamFile` on `cor
 Optional additional command-line parameters can be specified with `args`.
 
 # Example:
-The first step is to ensure that `LaMEM_jll` is installed on your system. You only need to do this once, or once LaMEM_jll is updated. 
-```julia
-julia> import Pkg
-julia> Pkg.add("LaMEM_jll")
-```
-
-Next you can call LaMEM with:
+You can call LaMEM with:
 ```julia
+julia> using LaMEM
 julia> ParamFile="../../input_models/BuildInSetups/FallingBlock_Multigrid.dat";
 julia> run_lamem(ParamFile)
 ```
 
-Do the same on 2 cores with
+Do the same on 2 cores with a command-line argument as:
 ```julia
 julia> ParamFile="../../input_models/BuildInSetups/FallingBlock_Multigrid.dat";
 julia> run_lamem(ParamFile, 2, "-nstep_max = 1")
 ```
-
 """
 function run_lamem(ParamFile::String, cores::Int64=1, args::String="")
 

src/run_lamem_save_grid.jl

@@ -43,19 +43,14 @@ function get_line_containing(stringarray::Vector{SubString{String}}, lookfor::St
 end
 
 """ 
-    run_lamem_save_grid(ParamFile::String, cores::Int64=1)
+	ProcessorPartFile = run_lamem_save_grid(ParamFile::String, cores::Int64=1)
 This calls LaMEM simulation, for using the parameter file `ParamFile` 
 and creates processor paritioning file "ProcessorPartitioning_`cores`cpu_X.Y.Z.bin" for `cores` number of cores. 
 # Example:
-The first step is to ensure that `LaMEM_jll` is installed on your system. You only need to do this once, or once LaMEM_jll is updated. 
-```julia
-julia> import Pkg
-julia> Pkg.add("LaMEM_jll")
-```
-Next you can call LaMEM with:
 ```julia
+julia> using LaMEM
 julia> ParamFile="../../input_models/BuildInSetups/FallingBlock_Multigrid.dat";
-julia> run_lamem_save_grid(ParamFile, 2)
+julia> ProcessorPartFile = run_lamem_save_grid(ParamFile, 2)
 ```
 """
 function run_lamem_save_grid(ParamFile::String, cores::Int64=1)

src/utils_IO.jl

@@ -75,6 +75,6 @@ function changefolder()
         cd(chomp(read(`osascript -e $command`, String)))
         println(pwd())
     else
-        exit()
+        error("This only works on windows and mac")
     end
 end