Add documentation for Julia uenv and Julia uage in JupyterHub #120
Conversation
|
preview available: https://docs.tds.cscs.ch/120 |
|
preview available: https://docs.tds.cscs.ch/120 |
bcumming
left a comment
bcumming
left a comment
There was a problem hiding this comment.
Thanks for the PR!
I have a few suggested changes.
The main feedback is that the docs should be focussed more on how to use, with additional background material about Julia added to a tutorial or guide, so that users can get straight to the "how do I Julia" part of the docs.
docs/software/prgenv/julia.md
Outdated
|
|
||
| [Julia](https://julialang.org/) is a programming language that was designed to solve the "two-language problem", the problem that prototypes written in an interactive high-level language like MATLAB, R or Python need to be partly or fully rewritten in lower-level languages like C, C++ or Fortran when a high-performance production code is required. Julia, which has its origins at MIT, can however reach the performance of C, C++ or Fortran despite being high-level and interactive. This is possible thanks to Julia's just-ahead-of-time compilation: code can be executed in an interactive shell as usual for prototyping languages, but functions and code blocks are compiled to machine code right before their first execution instead of being interpreted (note that modules are pre-compiled). | ||
|
|
||
| Julia is optimally suited for parallel computing, supporting, e.g., MPI (via [`MPI.jl`](https://github.com/JuliaParallel/MPI.jl)) and threads similar to OpenMP. Moreover, Julia's GPU packages ([`CUDA.jl`](https://github.com/JuliaGPU/CUDA.jl), [`AMDGPU.jl`](https://github.com/JuliaGPU/AMDGPU.jl), etc.) enables writing native Julia code for GPUs [1], which can reach similar efficiency as CUDA C/C++ [2] or the analog for other vendors. Julia was shown to be suitable for scientific GPU supercomputing at large scale, enabling near optimal performance and nearly ideal scaling on thousands of GPUs on Piz Daint [2,3,4,5]. Packages like [ParallelStencil.jl](https://github.com/omlins/ParallelStencil.jl) [[4](https://doi.org/10.21105/jcon.00138)] and [ImplicitGlobalGrid.jl](https://github.com/eth-cscs/ImplicitGlobalGrid.jl) [[3](https://doi.org/10.21105/jcon.00137)] enable to unify prototype and high-performance production code in one single codebase. Furthermore, Julia permits direct calling of C/C++ and Fortran libraries without glue code. It also features similar interfaces to prototyping languages as, e.g., Python, R and MATLAB. Finally, the [Julia PackageCompiler](https://github.com/JuliaLang/PackageCompiler.jl) enables to compile Julia modules in order to create shared libraries that are callable from C or other languages (a comprehensive [Proof of Concept](https://github.com/omlins/libdiffusion) was already available in 2018 and the PackageCompiler has matured very much since). |
There was a problem hiding this comment.
The aim of the documentation is to guide users in how to use the uenv, and I feel that the information is a distraction here.
We can assume that a user is looking at this documentation because they are already aware of the benefits of Julia, and want to get started using it as quickly as possible.
How about removing this, or putting it at the bottom of this page as "further reading"?
There was a problem hiding this comment.
I moved it to the end to ## Background on Julia for HPC
docs/software/prgenv/julia.md
Outdated
| [](){#ref-uenv-julia} | ||
| # julia | ||
|
|
||
| [Julia](https://julialang.org/) is a programming language that was designed to solve the "two-language problem", the problem that prototypes written in an interactive high-level language like MATLAB, R or Python need to be partly or fully rewritten in lower-level languages like C, C++ or Fortran when a high-performance production code is required. Julia, which has its origins at MIT, can however reach the performance of C, C++ or Fortran despite being high-level and interactive. This is possible thanks to Julia's just-ahead-of-time compilation: code can be executed in an interactive shell as usual for prototyping languages, but functions and code blocks are compiled to machine code right before their first execution instead of being interpreted (note that modules are pre-compiled). |
There was a problem hiding this comment.
Please add line breaks between sentences.
Also, I would avoid adding so much background material or advertising up front, so that users can get to the "how do I use the julia uenv" part of the docs.
docs/software/prgenv/julia.md
Outdated
|
|
||
| There is also a view `jupyter` available, which is required for [using Julia in JupyterHub][using-julia-in-jupyterhub]. | ||
|
|
||
| !!! info "The installation of `juliaup` and the latest `julia` version happens automatically the first time when `juliaup` is called." |
There was a problem hiding this comment.
This title is quite long and verbose.
How about "Setting up Julia the first time", with the current title "The installation of juliaup..." as text inside the admonition?
docs/software/prgenv/julia.md
Outdated
| Find and pull a Julia uenv image: | ||
| ```bash | ||
| uenv image find julia # list available julia images | ||
| uenv image pull julia/VERSION:TAG # copy version:tag from the list above |
There was a problem hiding this comment.
What are the available VERSION and TAG values? Maybe use a concrete example, and provide more information in a Versioning section?
docs/services/jupyterlab.md
Outdated
| Each time you start a JupyterHub server, you need to do the following in the JupyterHub Spawner Options form mentioned above: | ||
| !!! important "pass a [`julia`][ref-uenv-julia] uenv and the view `jupyter`." | ||
|
|
||
| At first time use of Julia within Jupyter, IJulia and one or more Julia kernel needs to be installed. Type the following command in a shell within JupyterHub to install IJulia, the default Julia kernel and, on systems whith Nvidia GPUs, a Julia kernel running under Nvidia Nsight Systems: |
There was a problem hiding this comment.
Please add line breaks between sentences, as per the contributing guide:
https://eth-cscs.github.io/cscs-docs/contributing/#text-formatting
|
preview available: https://docs.tds.cscs.ch/120 |
|
preview available: https://docs.tds.cscs.ch/120 |
|
preview available: https://docs.tds.cscs.ch/120 |
2 participants
No description provided.