GitHub

Advanced usage

For advanced users it is suggested to install git, bash and vscode or vscodium in addition to Julia. vscode and vscodium both have a very good plugin for Julia support, see https://www.julia-vscode.org. Installation instructions: Julia and VSCode .

Whe using vscode, I do NOT use the Julia terminal provided by vscode, but the normal bash terminal which is also available in vscode by selecting Terminal->New Terminal From this terminal I start Julia with julia --project or a different command as explained below. This makes it easier to understand what happens and is also faster when you need to restart.

Using the JETLS.jl language server

For code navigation, but also for getting warnings about problematic code it is useful to use the new JETLS.jl language server. There is JETLS plugin for VSCode, but JETLS can also be used with many other editors. It is very new and still a bit sensitive. I suggest to use the following two configuration files:

First, launch it single threaded to avoid problems with KiteViewers or ControlPlots. To do that, add the following settings.json file to the .vscode folder of your project:

{
  "jetls-client.executable": {
      "path": "jetls",
      "threads": "1,0"
  }
}

Second, use the following .JETLSConfig.toml file

formatter = "JuliaFormatter"

[full_analysis]
auto_instantiate = false            # boolean, default: true

[diagnostic]
all_files = false                   # boolean, default: true

[[diagnostic.patterns]]
pattern = "not concretized"
match_by = "message"
match_type = "regex"
severity = "off"

This suppresses invalid "not concretized" warnings and runs JETLS.jl only on the files you opened, not on all files of your project.

Sometimes JETLS.jl keeps running even after closing VSCode. This can eat up all your memory. In that case, on Linux you can use the command killall julia to terminate the language server and free the memory after closing VSCode.

Forking the repository and creating a custom system image

To reduce the startup time it is suggested to use a custom system image that contains all the packages you use on a daily base in compiled form.

  1. Go to the website https://github.com/ufechner7/KiteModels.jl and click on the Fork button at the top right.
  2. clone the new repository which is owned by you with a command similar to this one: git clone https://github.com/ufechner7/KiteModels.jl Your own git user name must appear in the URL, otherwise you will not be able to push your changes.

After cloning the repo you can create a new system image:

cd KiteModels.jl
cd bin
./create_sys_image

This will take about 12 min on a Ryzen 7950X CPU. You should now see a new file in the bin folder:

~/repos/test/bin$ ls -lah kps*
-rwxrwxr-x 1 ufechner ufechner 723M apr 18 18:23 kps-image-1.10-main.so

You can launch julia such that it makes use of this system image with the commands:

cd ..
./bin/run_julia

If you now run any of the examples the time-to-first-plot (TTFP) should be less than 10s:

julia> @time include("examples/simulate_simple.jl")
lift, drag  [N]: 597.47, 129.31
Average number of callbacks per time step: 114.92
  10.009223 seconds (29.83 M allocations: 1.727 GiB, 4.31% gc time, 50.81% compilation time)

julia>

A second run of this command needs about 3.7 s which means the startup time (load and compilation time of the package and the libraries) has been reduced to about 6.3s.

Without a system image the first time execution of the script "simulate_simple.jl" on the same computer is about 22.5 seconds while the time for the second execution is the same (3.9s). So now about 15s of time are saved after each restart.

Hints for Developers

Coding style

  • add the packages TestEnv and Revise to your global environment, not to any project

  • avoid hard-coded numeric values like 9.81 in the code, instead define a global constant G_EARTH or read this value from a configuration file

  • stick to a line length limit of 120 characters

  • try to avoid dot operators unless you have to.

Bad: norm1 .~ norm(segment) Good: norm1 ~ norm(segment)

  • if you need to refer to the settings you can use se() which will load the settings of the active project. To define the active project use a line like set = se("system_3l.yaml") at the beginning of your program.
  • use the \cdot operator for the dot product for improved readability
  • use a space after a comma, e.g. force_eqs[j, i]
  • enclose operators like + and * in single spaces, like 0.5 * (s.pos[s.i_C] + s.pos[s.i_D]); exception: mass_tether_particle[i-1]
  • try to align the equation signs for improved readability like this:
    tether_rhs        = [force_eqs[j, i].rhs for j in 1:3]
    kite_rhs          = [force_eqs[j, i+3].rhs for j in 1:3]
    f_xy              = dot(tether_rhs, e_z) * e_z

Outlook

The next steps:

  • add examples that use SymbolicAWEModels
  • add a Matlab/ Simulink wrapper similar to the Python wrapper pykitemodels