developing.md



Developing Persefone

Setting up
If you haven't worked with Julia before, here are detailed instructions for how to set up
your development environment. The main development is currently done on Linux (and as
the primary execution platform will be an HPC, Linux compatibility is important), but
developing on Windows works too.

Visual Studio Code on Windows


Download and install Julia,
git and Visual Studio Code.


Install the Julia extension for VS Code: In VS Code,
open the extensions pane (Ctrl+Shift+X). Search for and install Julia Language Support.


Clone the Gitlab repository: In
VS Code, open the source control pane (Ctrl+Shift+G). Click on Clone and enter
the repo URL. Then select a folder on your computer to download the files into, and
let VS Code open the project once it has been cloned.


Start a Julia REPL: In VS Code, bring up the command palette (Ctrl+Shift+P). Execute
the command Julia: Start REPL. Then install all dependencies of Persefone by running
using Pkg; Pkg.activate("."); Pkg.instantiate(). (This will take some time.)


Open the file run.jl and click Execute (triangular button in the top right).
The source code will compile (this can take a lot of time the first time you do it)
and run a default simulation.


Further steps: You may want to familiarise yourself with how to use
git with VS Code.
You may also want to clone the Persefone Desktop
repository (repeat steps 3 to 5).


Emacs on Linux
You can of course also use VS Code on Linux. In that case, follow the instructions above.
Make sure you have git and Julia installed. Git should be in your distro's repos (e.g.
sudo apt install git). To install Julia, download
the binary and unpack it. For greater ease of use, copy the unpacked files to
/usr/local/lib/julia (or similar) and create a symlink to the executable:
sudo ln -s /usr/local/lib/julia/bin/julia /usr/local/bin/julia.
Then go the to folder that you want to use for development and run
git clone https://git.idiv.de/persefone/persefone-model.git . in your terminal.
There are a couple of addons that make working with Julia much nicer in Emacs:


julia-mode gives syntax highlighting. Install with M-x package-install julia-mode.


julia-snail provides IDE-like features,
especially a fully-functional REPL and the ability to evaluate code straight from inside a buffer.
Note that the installation can be somewhat tricky. You first need to manually install
all the dependencies of its dependency vterm,
then install vterm itself with M-x package-install vterm, before you can do
M-x package-install julia-snail. Then add it to your init.el with
(require 'julia-snail) and (add-hook 'julia-mode-hook #'julia-snail-mode).


company-mode integrates with Snail to give code
completion. Install with M-x package-install company, then add
(add-hook 'julia-mode-hook #'company-mode) and
(global-set-key (kbd "C-<tab>") 'company-complete) to your init.el.


magit is a great git interface for Emacs. Install with
M-x package-install magit and add (global-set-key (kbd "C-x g") 'magit-status)
to your init.el.


Development workflow


Pull the current version from the master branch on Gitlab:
https://git.idiv.de/persefone/persefone-model.


If you are working on a new feature, create a new branch to avoid breaking the master branch.
(The master branch on Github should always be in a runnable and error-free state.)


Implement your changes.


Run an example simulation and the test suite to make sure everything works without crashing
(make run and make test on Linux, or execute run.jl and test/runtests.jl manually.)


Commit your work frequently, and try to keep each commit small. Don't forget to add
relevant tests to the test suite.


Once your satisfied with your work, do another pull/merge from the master branch in case
somebody else changed the branch in the meantime. Then merge your work into master and
push to the Gitlab server.


Repeat :-)


The Gitlab issue tracker
can be used to create, discuss, and assign tasks, as well as to monitor progress towards
milestones/releases. Once we have a first release, we will start using
semantic versioning and a changelog.

Important libraries

Agents.jl
Our model uses Agents.jl as a framework.
Their repository can be used to inspect the source
code or submit bug reports (the authors are quick to respond). Questions can be asked at the
Julia Discourse forum.
Tutorial on collaborating on Julia packages:
https://www.matecdev.com/posts/julia-package-collaboration.html.

Revise.jl
Revise.jl allows one to reload code
without restarting the Julia interpreter. Get it with Pkg.add("Revise"), then
add using Revise to .julia/config/startup.jl to have it automatically available.

Test
Persefone uses the inbuilt Julia testing framework.
All new functions should have appropriate tests written for them in the appropriate
file in the test directory. (See test/runtests.jl
for details.) There are three ways to run the test suite: in the terminal, executing
make test or cd test; julia runtests.jl; or in the Julia REPL,
Pkg.activate("."); Pkg.test().

Documenter.jl
The HTML documentation is generated using Documenter.jl.
Therefore, all new functions should have docstrings attached. New files need to be integrated
into the relevant documentation source files in docs/src, and if necessary into
docs/builddocs.jl.
To build the documentation, run make docs, or cd docs; julia builddocs.jl
(if using the latter, don't forget to update the date and commit in docs/src/index.md).

Graphics and user interface
Persefone uses Makie as a plotting library to generate its
output graphics. Additionally, Persefone Desktop uses
QML.jl to create its graphical user interface.