Part I: Julia Setup for PowerDynamics

This is the first part of a three-part introduction aimed at new colleagues and collaborators who want to use PowerDynamics.jl. It assumes no prior Julia experience.

• Part I (this document): install Julia, set up VSCode, run your first model.
• Part II: Environments and Package Management: how packages, versions and environments actually work.
• Part III: Structuring Research Projects: how to grow from a single script into a maintainable research codebase.

If you've worked with Julia before, you can probably skim Part I and jump to the getting started tutorial.

We also recommend further resources, like the excellent

• community-provided Modern Julia Workflows blog and the
• official Julia documentation.

Install Julia

First you need to install Julia. Check out the install instructions on the official Julia homepage. It is recommended to install Julia using juliaup.

In general, Julia can be installed and run without any administrator privileges.

Windows

You can install Julia on Windows using the Microsoft Store. Instead of searching manually, you can invoke this installation in the terminal. Search for powershell in the start menu and execute

winget install --name Julia --id 9NJNWW8PVKMN -e -s msstore

Linux/Mac

Execute the following code in your terminal:

curl -fsSL https://install.julialang.org | sh

The installer will ask you some questions, you won't need to change any defaults.

Verify installation

After the installation, run the julia command in your terminal. You should get an output like this:

The Julia REPL

Julia's main interface is the REPL (read-eval-print-loop). It is similar to ipython or the Matlab command window. You can execute code in the REPL by typing it. Try julia> println("hello world")<RETURN> to run your first Julia command. Exit the REPL by pressing CTRL + d or typing exit()<RETURN>.

Install VSCode with the Julia extension

The REPL is great, but we also need an editor for writing code. The best editor for most people will be Visual Studio Code. Please download and install it.

Within VSCode, you need to install the julia-extension. You should be able to click the "install" link in any browser, it'll open VSCode and install the extension. Alternatively, you can search for "Julia" in the VSCode extension store.

Environment Basics

Julia has a built-in package manager that lets you install and manage dependencies per project. Different projects often need different packages — and different versions of the same package.

This section gives you the bare minimum to get you up and running. For a deeper understanding of why environments matter, what Project.toml and Manifest.toml actually do, and how to use the package manager properly, see Part II.

To create your first environment, create a new folder somewhere (for example ~/Documents/powerdynamics_playground). Open this empty folder in VSCode and create a new file for your first script:

Open the newly created file, hit CTRL + SHIFT + P to bring up the VSCode "command palette", search for "Start REPL" and launch your Julia REPL.

In the REPL, you can execute pwd() (print working directory) to see the directory where your REPL was launched. Hit ] to launch the package manager. Your REPL prompt changes:

(@v1.11) pkg>

This output means your active environment is the global environment for Julia v1.11. If you were to add packages here, you would add them globally — generally not what you want. So instead we activate the current folder (.) as our working environment:

(@v1.11) pkg> activate .

After activation, we can add PowerDynamics to our newly created environment using

(powerdynamics_playground) pkg> add PowerDynamics

This will install PowerDynamics and all its dependencies, and precompile all of them. This may take a while...

Once you've added a package, you'll see two new files: Project.toml and Manifest.toml. The Project.toml lists your top-level dependencies — this is the file you change when adding new packages. The Manifest.toml is a complete snapshot of every package in the environment with exact versions, including transitive dependencies. Never edit it by hand.

ProjectRoot
├╴example_script.jl
├╴Project.toml
╰╴Manifest.toml

The existence of a Project.toml file marks a folder as a project you can activate. When executing code in a file using the Julia VSCode extension, it will automatically activate the environment for you, provided you tell VSCode which environment to use.

Executing Code in VSCode

Working with Julia is much like working in a notebook (Jupyter, Colab or similar), thanks to the persistent REPL. Because of how Julia works internally, everything will take much more time the first time you do it. Therefore, it is always preferred to have a persistent REPL over relaunching Julia. That is:

1. open a REPL,
2. execute a script in the REPL,
3. change the script,
4. run the script again in the same REPL

is much preferred to

1. executing the script via julia myscript.jl,
2. changing the script,
3. executing it again via julia myscript.jl,

in which case you'd pay the startup costs on every new run.

Besides executing an entire script (play button up top), you can execute single lines and code blocks in VSCode:

• Put the VSCode cursor on a line and hit SHIFT + RETURN to "send" that line of code to the REPL. If the line is part of a multiline expression (like a function), it'll send the entire block.
• Select multiple lines and hit SHIFT + RETURN to send all selected lines.
• Hit ALT + RETURN (or CMD + RETURN) to execute an entire code cell, where a code cell is everything between lines starting with ##.

using PowerDynamics
using ModelingToolkit
using PowerDynamics: Library

@named swing = Library.Swing(V=1)
busmodel = MTKBus(swing)
swingbus = compile_bus(busmodel)

Running PowerDynamics Examples

Now you know everything you need to know to run our examples locally.

At the beginning of each example, there is a link:

This tutorial can be downloaded as a normal Julia script here.

Go to the getting started tutorial, download the script, put it in your directory and go through it, executing it block by block.

julia> ] add OrdinaryDiffEqRosenbrock, CairoMakie

Next Steps

You now have a working Julia setup and can run our examples. From here:

• Part II: Environments and Package Management explains what's actually happening when you run add, update or instantiate, why versions matter, and how to avoid a few common pitfalls. It also introduces Revise.jl — a tool you'll want from day one.
• Part III: Structuring Research Projects is for when your single script grows into something bigger and you want to organize your code, share it with collaborators, and keep your work reproducible.

You don't have to read them in order, but reading them in order is probably the gentlest path.