Julia core development
1 Julia core overview
The computational core is one of the components of Ribasim as illustrated in the component overview.
The computational process can be divided in three phases:
- Model initialization
- Running the simulation loop
- Writing the output files
A more detailed sequence diagram of the simulation loop is available at the core home page.
2 Set up the developer environment
2.1 Install optional Julia libraries
Start the Julia REPL by executing pixi run julia in your terminal. Within the REPL type ] to enter the Pkg REPL. For more information on how to use Pkg, see the Getting Started page in its documentation. There you can add Revise to your global environment.
pkg> add Revise2.2 Setup Revise.jl
Revise.jl is a library that allows you to modify code and use the changes without restarting Julia. You can let it start automatically by following these instructions.
2.3 Install Visual Studio Code (optional)
There is a section on editors and IDEs for Julia on https://julialang.org/, scroll down to see it. We use and recommend Microsoft’s free editor Visual Studio Code. When combined with the Julia extension it provides a powerful and interactive development experience.
3 Developing on Ribasim
3.1 Running tests
You will want to run the testsuite on a regular basis to check if your changes had unexpected side effects. It is also a good way to find out if your development environment is set up correctly.
Before the tests can run, you need to prepare model input.
With the root of the repository as your working directory you can start the REPL with activated root environment by running the following:
julia --projectWhile not technically required, it is advised to import Ribasim first to catch installation issues early on.
julia> using RibasimThen open the Pkg REPL by typing ] and execute:
pkg> test RibasimIn order to debug tests, you can run individual test items from Visual Studio Code. Click the green play icon in front of a test item, as show in the image below. The first run will be slow.
3.2 Render documentation
Example models are created and simulated as part of the rendering of the documentation.
In order to preview documentation you can run the following command from the docs/ folder. Afterwards, a browser tab will open with the rendered documentation, updating it as you make changes.
pixi run quarto-previewThe documentation also includes Jupyter notebooks. Note that they are stored in the repository without any output, and this should stay this way to keep the repository small. The documentation rendering process adds the output by running the notebooks.
The Jupyter VS Code extension allows you to run Jupyter notebooks directly in VS Code.
3.3 Run Ribasim simulations
Assuming your working directory is the root of the repository, you can activate this project by entering the Pkg mode of the REPL with ] and execute:
pkg> activate .
pkg> instantiatePress backspace to go back to the Julia REPL. There you can run a model with:
julia> Ribasim.run("path/to/model/ribasim.toml")The Julia VS Code extension allows you to execute code cells in REPL. This is a very convenient way of executing only parts of your source file.
3.4 Build Ribasim
The Ribasim core can be built into an executable with a command line interface (CLI) and a shared library, libribasim. These products will run without a Julia installation. To create both these products at once, run:
pixi run buildTo verify that the build was successful, you can run both these commands.
pixi run test-ribasim-api
pixi run test-ribasim-cliDuring development these steps are normally done on TeamCity, though in some cases it can be more convenient to build locally.