Improved Julia documentation (#1705)

* multinode multi process and hybrid jobs

* julia minor and major version, fixes

* activate project when spawning new worker process

* improved threads code, restructuring

* improved description, web interface

* restructuring titles

* restructuring

* improvements

* added julia tutorial to list, title and description

* moved pkg.instantiate to batch scripts

* restructuring

* improvement

* fix

* Fixed misspelling of 'everywhere'

* added julia web interface documentation

* grammar

* refactoring, julia on lumi available

* refactoring, LUMI examples

* changed gpu example

* single node mahti example using interactive partition

* fixed typo

* improvements

* threading, mkl, linear algebra

* glossary, grammar

* glossary

* fixed sbatch option

---------

Co-authored-by: Jaan Tollander de Balsch <jaan.tollander.de.balsch@csc.fi>
Co-authored-by: Joonas Somero <joonas.somero@csc.fi>
Co-authored-by: Rasmus Kronberg <43936697+rkronberg@users.noreply.github.com>
Co-authored-by: Joonas Somero <50655931+joonas-somero@users.noreply.github.com>

Author: 4 people

csc-overrides/assets/glossaries/hpc.md

@@ -52,5 +52,6 @@
 *[HTTP]: Hypertext Transfer Protocol
 *[HTTPS]: Hypertext Transfer Protocol Secure
 *[SQL]: Structured Query Language
+*[REPL]: Read–Eval–Print Loop
 *[GCD]: Graphics Compute Die
-*[PME]: Particle-Mesh Ewald
+*[PME]: Particle-Mesh Ewald

docs/apps/julia.md

@@ -1,4 +1,4 @@
----
+
 tags:
   - Free
 ---
@@ -16,7 +16,15 @@ Julia language is licensed under free and open source [MIT license](https://gith
 
 
 ## Available
-Julia language is available on Puhti and Mahti using the [module system](../computing/modules.md).
+Julia language is available on Puhti, Mahti, and LUMI using the [module system](../computing/modules.md).
+On Puhti and Mahti, the Julia module is included on the module path by default.
+On LUMI, we must add the module files under CSC's local directory to the module path as follows.
+
+```bash
+module use /appl/local/csc/modulefiles
+```
+
+We can check the available versions as follows.
 
 ```bash
 module avail julia
@@ -55,31 +63,56 @@ Julia's REPL and Pkg, the package manager, are two important packages within the
 The [Pkg documentation](https://pkgdocs.julialang.org/) provides more information on how to use Julia's package manager.
 
 
+### More information
+We can print details about paths and environment variables set by the Julia module as follows.
+
+```bash
+module show julia
+```
+
+We can also print useful information about the Julia version, platform and environment in the REPL as follows.
+
+```julia
+using InteractiveUtils  # automatically load in the REPL
+versioninfo()
+```
+
+
 ### Using environments
 Julia manages dependencies of projects using environments.
 An environment consists of two files, `Project.toml` and `Manifest.toml`, which specify dependencies for the environment.
-We define project metadata, dependencies, and compatibility constraints in `Project.toml` file.
+We define project metadata, dependencies, and compatibility constraints in the `Project.toml` file.
 Adding or removing packages using the package manager manipulates the `Project.toml` file in the active environment.
-Furthermore, the package manager maintains a full list of dependencies in `Manifest.toml` file.
+Furthermore, the package manager maintains a full list of dependencies in the `Manifest.toml` file.
 It creates both of these files if they don't exist.
 Let's consider a Julia project structured as follows.
 
 ```
-project
+project/
 ├── script.jl
 ├── Project.toml
 └── Manifest.toml
 ```
 
-We can activate an environment using the `--project` option when starting Julia or use the `Pkg.activate` function in existing Julia session.
+We can activate an environment using the `--project` option when starting Julia or use the `Pkg.activate` function in the existing Julia session.
 For example, we can open the Julia REPL with the project's environment active as follows:
 
 ```bash
 julia --project=.
 ```
 
+We can call the `Base.active_project()` function to retrieve a path to the active project, that is, `Project.toml` file.
+
 Activating an environment does not automatically install the packages defined by `Manifest.toml` or `Project.toml`.
-For that, we need to invoke the `Pkg.instantiate` function with the project's environment active as follows:
+For that, we need to instantiate the project as follows:
+
+```julia
+using Pkg
+Pkg.activate(".")
+Pkg.instantiate()
+```
+
+Alternatively, we can use the following one-liner:
 
 ```bash
 julia --project=. -e 'using Pkg; Pkg.instantiate()'
@@ -92,7 +125,7 @@ julia --project=. script.jl
 ```
 
 Julia will activate the default environment if we don't specify an environment.
-We should always use a unique environment for Julia projects instead of the default environment.
+Preferably, we should use a unique environment for Julia projects instead of the default environment.
 That way, we can manage the dependencies of different Julia projects separately.
 
 
@@ -103,8 +136,14 @@ On the Julia REPL, we can use the package manager by importing it.
 using Pkg
 ```
 
+We can activate a Julia environment on the current working directory as follows.
+
+```julia
+Pkg.activate(".")
+```
+
 We can add packages to the active environment using the `Pkg.add` function.
-For example, we can add `ArgParse` package as follows.
+For example, we can add the `ArgParse` package as follows.
 
 ```julia
 Pkg.add("ArgParse")
@@ -124,34 +163,35 @@ Pkg.compat("julia", "1.8")
 ```
 
 
-### Depot and load paths
+### Code loading and the shared environment
 The Julia constants [`Base.DEPOT_PATH`](https://docs.julialang.org/en/v1/base/constants/#Base.DEPOT_PATH) and [`Base.LOAD_PATH`](https://docs.julialang.org/en/v1/base/constants/#Base.LOAD_PATH) constants control the directories where Julia loads code.
 To set them via the shell, we use the `JULIA_DEPOT_PATH` and `JULIA_LOAD_PATH` environment variables.
+We can call the `Base.load_path()` function to retrieve the expanded load path.
 The Julia module automatically appends the default depot and load paths to ensure the standard library and shared depots are available.
-The CSC-specific shared depots are installed in the `JULIA_CSC_DEPOT` directory, and the shared environment is in the `JULIA_CSC_ENVIRONMENT` directory.
-We can look up the shared packages and their versions using the package manager as follows:
+
+The first directory on the depot path controls where Julia stores installed packages, compiled files, log files, and other depots.
+We can change the directory by prepending the `JULIA_DEPOT_PATH` with a different directory.
+For example, we can use the following by replacing the `<project>` with your CSC project.
 
 ```bash
-julia --project="$JULIA_CSC_ENVIRONMENT" -e 'using Pkg; Pkg.status()'
+export JULIA_DEPOT_PATH="/projappl/<project>/$USER/.julia:$JULIA_DEPOT_PATH"
 ```
 
-The first directory on the depot path controls where Julia stores installed packages, compiled files, log files, and other depots.
-
-!!! warning "Changing the default depot directory"
-    The default depot directory is `$HOME/.julia`.
+!!! warning "Changing the default depot directory."
+    By default, the first depot directory in the depot path is `$HOME/.julia`.
     However, the home directory has a fixed quota for Puhti and Mahti.
-    Therefore, we recommend changing the directory to a directory under Projappl or Scratch to avoid running out of quota because some packages install a large amounts of files.
-    Afterwards, you can safely remove the default depot directory using `rm -r $HOME/.julia`.
+    Therefore, we recommend changing the directory to a directory under Projappl or Scratch to avoid running out of quota because some packages install a large number of files.
+    Afterward, you can safely remove the default depot directory using `rm -r $HOME/.julia`.
 
-We can change the directory by prepending the `JULIA_DEPOT_PATH` with a different directory.
-For example, we can use the following by replacing the `<project>` with your CSC project.
+The CSC-specific shared depots are installed in the `CSC_JULIA_DEPOT_DIR` directory, and the shared environment is in the `CSC_JULIA_ENVIRONMENT_DIR` directory.
+We can look up the shared packages and their versions using the package manager as follows:
 
 ```bash
-export JULIA_DEPOT_PATH="/projappl/<project>/$USER/.julia:$JULIA_DEPOT_PATH"
+julia --project="$CSC_JULIA_ENVIRONMENT_DIR" -e 'using Pkg; Pkg.status()'
 ```
 
 
-### Creating a package with command line interface
+### Creating a package with a command line interface
 We should package the code as a code base grows instead of running standalone scripts.
 A Julia package includes a module file, such as `src/Hello.jl`, and the `Project.toml` file.
 Including a command line interface in your program, such as `src/cli.jl`, is also wise.
@@ -195,7 +235,7 @@ export say
 end
 ```
 
-We can use `ArgParse` package to create a command line interface `src/cli.jl` for the package.
+We can use the `ArgParse` package to create a command line interface `src/cli.jl` for the package.
 For example, the command line interface below defines an option `--say` whose value is parsed into a string and supplied to the `say` function imported from the `Hello` module.
 
 ```julia
@@ -221,8 +261,8 @@ julia --project=. src/cli.jl --say "Hello world"
 We should define and use a command line interface because it is more flexible than hard-coding values to the scripts.
 
 
-### Running Julia jobs on Puhti and Mahti
-We explain how to run serial, parallel and GPU jobs with Julia on Puhti and Mahti in the [**Running Julia jobs on Puhti and Mahti clusters**](../support/tutorials/julia.md) section.
+### Running Julia jobs on Puhti, Mahti, and LUMI clusters
+We explain how to run serial, parallel, and GPU jobs with Julia on Puhti, Mahti, and LUMI in the [**Running Julia jobs on Puhti, Mahti, and LUMI clusters**](../support/tutorials/julia.md) tutorial.
 
 
 ### Using Julia on Jupyter and VSCode