This post was written by Steven Whitaker.

Ever wish your Python code could run faster on heavy calculations or simulations? With juliacall, you can call Julia straight from Python and instantly access blazing-fast performance and powerful scientific libraries, all without rewriting your existing code. Supercharge your Python workflows today and elevate your data science and engineering projects to new heights!

In this Julia for Devs post, learn step-by-step how to install and utilize juliacall, enabling you to boost critical code performance effortlessly, without rewriting your entire project. Unlock the powerful combination of Python’s vast ecosystem and Julia’s speed, making it easy to experiment, optimize, or gradually migrate key components.

Let's dig in!

Installing juliacall

Installation is a breeze, all you need is

pip install juliacall

You can test your installation by running the following in Python:

from juliacall import Main as jl

The first time this runs, it will install the Julia packages needed for communicating between Julia and Python.

Then you can try it out:

import numpy as np
A = np.array(jl.rand(5, 3))
x = np.array(jl.randn(3))
y = A @ x

Great, Julia-Python interoperability works for this small example! Now let's see how we can extend this to a larger example.

Calling Custom Code

In practice, we might have written some custom code in Julia that we want to integrate into our Python workflow. Let's walk through the process of this integration.

Julia Code

Typically, the Julia code will be organized into a package, including its own package environment and dependencies.

We'll work with an example that runs a simulation using OrdinaryDiffEq.jl and StaticArrays.jl. The example package has the following directory structure:

JuliaExample
├── Project.toml
└── src
    └── JuliaExample.jl

The Project.toml has the following content:

name = "JuliaExample"
uuid = "0b6476de-1cea-499f-93be-749bc74a9c07"
authors = ["Author Name <address@email.com>"]
version = "0.1.0"

[deps]
OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"

And JuliaExample.jl contains:

module JuliaExample

using OrdinaryDiffEq: ODEProblem, Tsit5, solve
using StaticArrays: SVector

struct Params
    α::Float64
    β::Float64
    γ::Float64
end

function f(u, p, t)

    (; α, β, γ) = p

    dx = α * (u[2] - u[1])
    dy = u[1] (β - u[3]) - u[2]
    dz = u[1] * u[2] - γ * u[3]

    return SVector(dx, dy, dz)

end

function simulate(u0, t_start, t_end, α, β, γ)

    u0 = SVector{3, Float64}(u0)
    tspan = (t_start, t_end)
    p = Params(α, β, γ)
    prob = ODEProblem{false}(f, u0, tspan, p)
    sol = solve(prob, Tsit5())

end

end

Python Code

We have our custom Julia code, so now let's see what our Python workflow looks like that calls out to Julia.

We'll have our code organized in the following directory structure:

python_example
├── pyproject.toml
├── scripts
│   └── run.py
└── src
    └── python_example
        ├── __init__.py
        └── analysis.py

The main functionality of our Python code is in analysis.py:

from juliacall import Main as jl
jl.seval("using JuliaExample: simulate")

import numpy as np
import matplotlib.pyplot as plt

def simulate(*args):
    result = jl.simulate(*args)
    t = np.array(result.t)
    sol = np.array([np.array(u) for u in result.u])
    return t, sol

def plot_results(t, sol):
    plt.figure(figsize=(10, 6))
    labels = ["x", "y", "z"]
    colors = ["tab:blue", "tab:orange", "tab:green"]

    for i in range(3):
        plt.plot(t, sol[:, i], label=labels[i], color=colors[i])

    plt.xlabel("Time [s]")
    plt.ylabel("Value")
    plt.title("Solution Components Over Time")
    plt.legend()
    plt.grid(True)
    plt.tight_layout()
    plt.show()

This code provides two functions: one for calling out to Julia to run a simulation, and another for plotting the simulation results.

Let's break down some of this code to see how Julia is incorporated:

• from juliacall import Main as jl
  

  We saw this earlier; this is how to load juliacall.

• jl.seval("using JuliaExample: simulate")
  

  Here, we load our Julia package, specifically bringing the function simulate into scope.
• The Python function simulate calls the Julia simulate, passing along all its inputs:

  result = jl.simulate(*args)
  

  The Python function then does some processing to convert the Julia results into something more easily utilized by further Python processing.

This functionality is exercised in the run.py script:

from python_example import simulate, plot_results
import numpy as np

u0 = np.array([1, 0, 0])
t_start = 0
t_end = 100
alpha = 10
beta = 28
gamma = 8/3
t, sol = simulate(u0, t_start, t_end, alpha, beta, gamma)
plot_results(t, sol)

Finally, for completeness, here's __init__.py:

from .analysis import simulate, plot_results

Finding Julia

We have all our code set up, so now we need Python to be able to find the Julia code so we can call out to it. In other words, we need the Julia package environment used by juliacall to have JuliaExample as a dependency.

We can accomplish this by creating a juliapkg.json file in our Python project directory (i.e., python_example/juliapkg.json). The file should contain the following JSON:

{
    "packages": {
        "JuliaExample": {
            "uuid": "0b6476de-1cea-499f-93be-749bc74a9c07",
            "path": "path/to/JuliaExample",
            "dev": true
        }
    }
}

Note that the uuid here needs to match the uuid in JuliaExample/Project.toml. And the "path" and "dev": true fields are necessary because our Julia package exists locally on our machine; it is not a registered Julia package. See the juliacall docs for more information about juliapkg.json.

Putting It Together

Now we have all the components we need: Python code to run, Julia code to call out to, and juliapkg.json to tell juliacall where to find our Julia code.

So, what happens when we run run.py?

The first time it is run, juliacall will set up the Julia package environment, installing the dependencies of JuliaExample. Then, the script proceeds to run the simulation (calling out to Julia to do so) and plot the results:

Awesome, we now have a working example showing how to call out to Julia from a Python project!

Summary

In this post, we saw how to install and use juliacall to call out to Julia from within Python. We looked at a trivial example as well as a more realistic example of integrating custom Julia code into a Python project.

What custom Julia code do you want to integrate into your Python projects? Contact us, and we can make it happen!

Additional Links

• PythonCall.jl
  • One cool thing about juliacall is it is maintained in the same GitHub repo as PythonCall, which is the recommended way to call Python code from Julia.
• GLCS Modeling & Simulation
  • Connect with us for Julia Modeling & Simulation consulting.

This post was written by Steven Whitaker.

The Julia programming language is a high-level language that is known, at least in part, for its outstanding composability. Much of Julia's composability stems from its multiple dispatch, which allows functions written in one package to work with objects from another package without either package needing to depend on or even know about the other. (See another blog post for more details.)

Sometimes, however, it is useful for a package to be able to extend its functions to provide additional functionality when given an object of a specific type from another package. One way to do so is to add the other package as an explicit dependency so that its type is available for the first package to use to define a specific method for it.

But what if the package can function just fine without the additional functionality? What if the extra functionality isn't integral to what the package does and only applies if the user wants to work with objects of that specific type? In this case, it doesn't make much sense to make the other package a direct dependency, because then every user pays the price of extra package load time for functionality that only some users actually want.

The solution is package extensions. A package extension is code that gets loaded conditionally, depending on what other packages the user has explicitly loaded. In other words, when a user loads both the package and the dependency the extension depends on, the extension gets loaded automatically. This way, users who want to use the package can do so without the added dependency, while users who want the extra functionality can load the dependency themselves.

In this post, we will learn about some package extensions that exist in the Julia package ecosystem. We will also learn how to write a package extension and how to load the extension.

This post assumes you are familiar with the structure of a Julia package. If you need to learn more, check out our post on creating Julia packages.

Package Extensions in the Wild

• ForwardDiff.jl has an extension for StaticArrays.jl, enabling forward-mode automatic differentiation with the performance benefits of StaticArrays.
• Lux.jl has an extension for Flux.jl that adds functionality for converting deep learning models defined in Flux to Lux.
• Some other packages with extensions (just look in the ext folder of these git repos):
  • ModelingToolkit.jl
  • JET.jl
  • Distributions.jl
  • ChainRulesCore.jl
  • LinearSolve.jl
  • PackageExtensionsExample.jl
    • Okay, this one isn't really a package extension in the wild, but it could be a good resource for learning how they work.

Writing a Package Extension

To create a package extension, one needs to create a module that adds method definitions to functions from one of the packages (either the package being extended or the package that triggers loading the extension) that dispatch on types from the other package. This module will live in the ext directory of the package being extended. Additionally, the extended package's Project.toml needs to be updated to inform the package manager of the existence of the extension and when to load it.

Let's look at a concrete example.

Example Package to Extend

This example will build on a custom package called Averages.jl that we discussed in our blog post on testing Julia packages. The package code is as follows:

module Averages

using Statistics: mean

export compute_average

compute_average(x) = (check_real(x); mean(x))

function compute_average(a, b...)

    check_real(a)

    N = length(a)
    for (i, x) in enumerate(b)
        check_real(x)
        check_length(i + 1, x, N)
    end

    T = float(promote_type(eltype(a), eltype.(b)...))
    average = Vector{T}(undef, N)
    average .= a
    for x in b
        average .+= x
    end
    average ./= length(b) + 1

    return a isa Real ? average[1] : average

end

function check_real(x)

    T = eltype(x)
    T <: Real || throw(ArgumentError("only real numbers are supported; unsupported type $T"))

end

function check_length(i, x, expected)

    N = length(x)
    N == expected || throw(DimensionMismatch("the length of input $i does not match the length of the first input: $N != $expected"))

end

end

Creating the Extension

For this example, we will create an extension that implements additional functionality for DataFrames. These are the tasks we need to do to implement the extension:

1. Create the extension at Averages/ext/AveragesDataFramesExt.jl. Note that this follows the naming convention for extensions: <PackageName><NameOfPackageThatTriggersExtension>Ext. Inside this file, we create a module called AveragesDataFramesExt (same name as the file) and put the code we want to be included when Averages.jl and DataFrames.jl are loaded together:

   module AveragesDataFramesExt
   
   import Averages
   using Averages: compute_average
   using DataFrames: All, DataFrame, combine
   
   function Averages.compute_average(df::DataFrame)
   
       @info "Running code in AveragesDataFramesExt!"
   
       df_avg = combine(df, All() .=> compute_average)
   
       return df_avg
   
   end
   
   end
   

2. Add [weakdeps] and [extensions] sections to the Project.toml of Averages.jl. (See our previous blog post for the original Project.toml.) In [weakdeps], specify DataFrames.jl and its UUID, and, in [extensions], specify our extension (AveragesDataFramesExt) and its dependency (DataFrames.jl). The UUID of DataFrames.jl can be found in DataFrames.jl's Project.toml.

   Here's the updated Project.toml for Averages.jl:

   name = "Averages"
   uuid = "1fc6e63b-fe0f-463a-8652-42f2a29b8cc6"
   version = "0.1.0"
   
   [deps]
   Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
   
   [weakdeps]
   DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
   
   [extensions]
   AveragesDataFramesExt = "DataFrames"
   
   [extras]
   Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
   
   [targets]
   test = ["Test"]
   

   (Note that, just as compatible versions of the [deps] packages can be specified in a [compat] section, so too can the compatible versions of the [weakdeps] packages be specified.)

Using the Extension

First, let's see what happens if we try this without the extension:

julia> compute_average(DataFrame(a = [1, 2], b = [3.0, 4.0]))
ERROR: ArgumentError: only real numbers are supported; unsupported type Any
Stacktrace:
 [1] check_real(x::DataFrame)
   @ Averages /path/to/Averages/src/Averages.jl:34
 [2] compute_average(x::DataFrame)
   @ Averages /path/to/Averages/src/Averages.jl:7
 [3] top-level scope
   @ REPL[5]:1

So, now let's see if the extension allows this function call to work.

To use the extension, install and load Averages.jl and DataFrames.jl (for Averages.jl, use the dev command, i.e., pkg> dev /path/to/Averages) and then call compute_average:

julia> using Averages, DataFrames

julia> compute_average(DataFrame(a = [1, 2], b = [3.0, 4.0]))
[ Info: Running code in AveragesDataFramesExt!
1×2 DataFrame
 Row │ a_compute_average  b_compute_average
     │ Float64            Float64
─────┼──────────────────────────────────────
   1 │               1.5                3.5

Nice, it works! And with that, we have an example package extension that illustrates how to implement your own.

And remember, a user of Averages.jl will only incur the cost of loading AveragesDataFramesExt if they load DataFrames.jl. For more details, see the slide annotations in this screenshot from JuliaCon 2023:

(See also the full talk on package extensions for even more details.)

Note: Where Should an Extension Live?

By the way, if you're wondering why we put the extension in Averages.jl instead of DataFrames.jl, the answer is that it doesn't really matter because the user experience will be the same regardless. If you still want some rules to follow, I'm not aware of any Julia best-practices in this regard, but here are some rules that make sense to me:

• If one of the two packages in question defines an interface, the extension should go in the package that implements the interface.
• Otherwise, put the extension in the package that owns the functions that are being extended. In our example, we extended the compute_average function. Since this function is defined in Averages.jl, we put the extension in Averages.jl.
• An exception to the previous rule is if getting the new functionality right requires a good understanding of the internals of the new data type that's being dispatched on, in which case the extension should belong in the package that defines the type. For example, if compute_average was super complicated for some reason when working with DataFrames, it would make sense for those with the needed expertise (i.e., the developers of DataFrames.jl) to own and maintain the extension.

Summary

In this post, we listed some real Julia packages that have their own package extensions. We also demonstrated creating our own extension for an example package and showed how to use the extension's code.

What package extensions have you found useful? Let us know in the comments below!

Additional Links

• Julia Package Extension Docs
  • Official Julia documentation on package extensions.
• JuliaCon 2023 Talk Introducing Package Extensions
  • Talk by Kristoffer Carlsson in which package extensions are introduced.

This post was written by Steven Whitaker.

A new version of the Julia programming language was just released! Version 1.12 is now the latest stable version of Julia.

This release is a minor release, meaning it includes language enhancements and bug fixes but should also be fully compatible with code written in previous Julia versions (from version 1.0 and onward).

In this post, we will check out some of the features and improvements introduced in this newest Julia version. Read the full post, or click on the links below to jump to the features that interest you.

• Improved Quality of Life with Redefinable Types
• New Way to Fix Function Arguments
• Progress Towards More Reasonable Executables

If you are new to Julia (or just need a refresher), feel free to check out our Julia tutorial series, beginning with how to install Julia and VS Code.

Improved Quality of Life with Redefinable Types

Julia 1.12 introduces a major quality of life improvement for package development by allowing types to be redefined. To illustrate, prior to Julia 1.12:

julia> struct A end

julia> struct A
           x::Int
       end
ERROR: invalid redefinition of constant Main.A
Stacktrace:
 [1] top-level scope
   @ REPL[2]:1

But in Julia 1.12, no error is thrown! Note, however, that any objects of the old type will still be of the old type---they don't automatically update to conform to the new type definition. For example:

julia> struct A end

julia> a1 = A()
A()

julia> struct A
           x::Int
       end

julia> a2 = A(1)
A(1)

julia> a1
@world(A, 38513:38515)()

Note that after redefining A, a1 is denoted as being of type A from a previous so-called "world age".

Importantly, when defining a method that dispatches on a type, it will be defined for the version of the type that existed at the time of method definition. Continuing from the previous example:

julia> f(a::A) = println("hello")
f (generic function with 1 method)

julia> f(a2)
hello

julia> f(a1) # Method doesn't exist for the old type
ERROR: MethodError: no method matching f(::@world(A, 38513:38515))
The function `f` exists, but no method is defined for this combination of argument types.

Closest candidates are:
  f(::A)
   @ Main REPL[6]:1

Stacktrace:
 [1] top-level scope
   @ REPL[8]:1

julia> struct A # Update the type
           x::Float64
       end

julia> f(A(2.0)) # Method doesn't exist for the new type
ERROR: MethodError: no method matching f(::A)
The function `f` exists, but no method is defined for this combination of argument types.

Closest candidates are:
  f(::@world(A, 38516:38521))
   @ Main REPL[6]:1

Stacktrace:
 [1] top-level scope
   @ REPL[18]:1

In other words, if updating a type, be sure to update methods as well.

Often, however, when someone is working with a type and many methods that use the type for dispatch, they are developing a package. Package development works differently than just working in the REPL, so let's see how package development is affected by the ability to update types.

First, without proper tooling, Julia package development can be a slog, regardless of whether types (or anything else) can be updated. This is because normally, after a package is loaded, changes made to the package's source code don't take effect until Julia is restarted and the package is loaded again. In other words, the whole Julia runtime has to be started up again and code has to be reloaded even if just a single function in the package was updated.

Fortunately, Revise.jl exists. Revise.jl provides massive quality of life improvements for package developers by allowing changes to the package source code to take effect immediately, without restarting Julia.

The biggest caveat? Revise.jl couldn't handle changes to struct definitions. So, if you decide a struct in your package needs an extra field, you're out of luck, you have to restart Julia. And then if you decide the struct actually didn't need that field, too bad again, restart Julia.

But that all changes with Julia 1.12! This release adds a mechanism for redefining types that Revise.jl hooks into, removing arguably the most significant remaining pain point of Julia package development. The number of times a developer needs to restart Julia will decrease significantly with Julia 1.12, allowing for greater productivity.

New Way to Fix Function Arguments

Julia 1.12 introduces the Fix struct that can be used to fix function arguments. (Here, "to fix" means "to set", not "to correct".) Think of it as another way to define a closure.

One of the main uses of Fix is purely for convenience, particularly when creating closures of functions with many inputs. For example, suppose we have the following (nonsensical) physical model:

function dynamics(velocity, resistance, gravity, position, friction, length, mass)
    return velocity + resistance + gravity + position + friction + length + mass
end

Now, suppose we have another function that computes (or accepts as input) a particular value for mass and then creates a new function that computes dynamics with mass fixed. Previously, an anonymous function typically would be used, so let's compare using an anonymous function to using Fix:

mass = 30 # Some computed or given value

# Using an anonymous function.
# Note that the `let mass = mass` is essential
# to guarantee Julia doesn't box `mass`
# (see <https://docs.julialang.org/en/v1/manual/performance-tips/#man-performance-captured>).
# (Though also note that sometimes boxing does not occur
# even if the `let` block is omitted.)
dynamics_with_mass = let mass = mass
    (velocity, resistance, gravity, position, friction, length) -> dynamics(velocity, resistance, gravity, position, friction, length, mass)
end

# Using `Fix`.
# The `7` indicates that we want to fix the 7th argument.
dynamics_with_mass_fix = Base.Fix{7}(dynamics, mass)

As you can see, using Fix is much more concise. But both dynamics_with_mass and dynamics_with_mass_fix act as a function of six arguments and compute dynamics with mass fixed to a specific value.

Next, suppose we want to compute the derivative of dynamics as a function of velocity for fixed values of the other parameters. In this case, there are six arguments that need to be fixed. Fix allows for fixing just one argument, but Fixes can be nested to fix multiple arguments. Let's compare using an anonymous function to using Fix:

# Fixed values, either computed or given.
resistance = 2
gravity = 9.8
position = 0
friction = 0
length = 0.5
mass = 30

# Using an anonymous function.
f = let resistance = resistance,
        gravity = gravity,
        position = position,
        friction = friction,
        length = length,
        mass = mass
    velocity -> dynamics(velocity, resistance, gravity, position, friction, length, mass)
end

# Using `Fix`.
f_fix = Base.Fix{2}(Base.Fix{2}(Base.Fix{2}(Base.Fix{2}(Base.Fix{2}(Base.Fix{2}(dynamics, resistance), gravity), position), friction), length), mass)

# Using `Fix` with piping for nicer formatting.
pipefix(::Val{N}, x) where {N} = Base.Fix{2}(Base.Fix{N}, x)
f_pipefix = Base.Fix{2}(dynamics, resistance) |>
    pipefix(Val{2}(), gravity) |>
    pipefix(Val{2}(), position) |>
    pipefix(Val{2}(), friction) |>
    pipefix(Val{2}(), length) |>
    pipefix(Val{2}(), mass)

In this case, I would argue using an anonymous function is clearer to read. However, Fix can have some performance advantages over anonymous functions. For example, using Fix can reduce the need to compile anonymous functions that are used repeatedly.

For a lot more context and discussion, see the pull request that introduced Fix.

Progress Towards More Reasonable Executables

Perhaps surprisingly, an experimental feature is probably the most highly anticipated addition in Julia 1.12: a new command-line argument --trim that enables a (currently experimental) feature that removes unnecessary code from compiled executables.

Along with the release of Julia 1.12, JuliaC.jl was also created to streamline the creation of executables. JuliaC.jl can be installed as a Julia app (another new feature with 1.12!):

pkg> app add JuliaC

Installing JuliaC.jl in this way creates the juliac executable at ~/.julia/bin/juliac. (After installation, you may want to add ~/.julia/bin to your PATH.)

Let's see how to use juliac with a simple program:

# main.jl

function @main(args::Vector{String})::Cint
    for arg in args
        # Note the use of `Core.stdout` instead of `stdout`
        # (which is used by default if an `io` argument is omitted).
        println(Core.stdout, arg)
    end
    return 0
end

This program simply prints to the console all its given command-line arguments.

To compile it into an executable, just run the following command:

juliac --output-exe print_args --project . --bundle bundle --trim main.jl

To verify it works:

$ ./bundle/bin/print_args hello world
hello
world

So, what exactly is the impact of --trim? Without the new (experimental) feature, the size of the print_args executable was 205 MB on my computer. With --trim, that number improved by over 100x, dropping to just 1.7 MB!

Summary

In this post, we learned about some of the new features and improvements introduced in Julia 1.12, including redefinable types, Fix, and --trim. Curious readers can check out the release notes for the full list of changes.

What are you most excited about in Julia 1.12? Let us know in the comments below!

Additional Links

• Julia v1.12 Release Notes
  • Full list of changes made in Julia 1.12.
• Julia Basics for Programmers
  • Series of blog posts covering Julia basics.
• Diving into Julia
  • Series of blog posts covering more advanced Julia concepts.

This post is a cleaned-up transcript of the JuliaCon 2025 talk Integrating Julia and MATLAB: Julia and MATLAB Can Coexist by Steven Whitaker. Check out the submission page for the talk abstract and summary. To download a PowerPoint of the talk slides, click here.

Introduction

Thank you for the introduction. I'm going to be talking about Julia-MATLAB integration. I'll start by talking about why we might want to do this. Why not just stick with MATLAB^® or why not transition entirely to Julia? I'll talk about how to actually do the integration and I'll walk through an example model. I'll show you the MATLAB code, show how it needs to be translated to Julia and then reintegrated back into the MATLAB workflow that we're working with. And I'll demonstrate some benchmark results from before and after doing the Julia-MATLAB integration.

MATLAB Is Everywhere, Julia Is Fast

To begin, I do want to say that from our perspective MATLAB is great software. It's used by businesses and people all over the world, and it has withstood the test of time. MATLAB has excellent tooling and documentation. It has been the go-to for scientific computing and engineering, and it is ubiquitous in modeling and simulation. By a quick raise of hands, who here has written a model or a function in MATLAB? I think literally everyone (in the JuliaCon audience). Me too. Engineers have had time to amass decades worth of MATLAB models and workflows, which is to say MATLAB isn't going anywhere.

But is MATLAB the best option in all cases? Now, there's this trade-off between speed and what I'll call reputation. MATLAB has an incredibly good reputation. It has excellent tooling. It's robust and it has a ton of other awesome features. It has gained a reputation for being reliable and it is an established industry standard. Large companies may have hundreds of MATLAB models and thousands upon thousands of lines of MATLAB code. But that makes it impractical to switch all this MATLAB code entirely over to Julia all at once.

However, there may be instances where MATLAB isn't the best choice to use. For example, if you have performance critical or large-scale models where speed is absolutely paramount, a language like Julia may be more suitable for those cases. Let's look at some concrete numbers.

Benchmark Comparisons

I pulled some benchmarks from the SciML benchmarks website. And as an aside for those of you who haven't heard about the SciML ecosystem, the Julia scientific machine learning ecosystem is incredible. So check it out if you haven't yet.

So what these benchmarks do is compare ODE solvers from various languages for various ODEs and just see how fast these ODE solvers compare. So for one example we have a non-stiff problem here. We're plotting how long it takes these ODE solvers to solve this non-stiff problem. The Julia solvers are in green, MATLAB in orange. And looking at this plot, we see that for this particular non-stiff problem, Julia is 10 to 1000 times faster than MATLAB.

Now what about a stiff problem? Similar story for this particular stiff problem. Julia is 10 to 1000 times faster than MATLAB.

Now consider if your long simulations or parameter optimizations take hours or even days to run in MATLAB. You have to start asking yourself: is it worth using MATLAB when time is money? Does the reputation of MATLAB really outweigh the cost in time?

Introducing Julia with Minimal Disruptions

The key question is: How do we get Julia's speed but without rewriting all of our MATLAB code in Julia? How can we get that speed without major disruption, without completely retooling everything?

So another question: does anyone here by the raise of hands work with large MATLAB codebases? All right, a few of you (in the JuliaCon audience). Like I said, companies have had decades to mass tons of MATLAB code. And so if you're working at a company that has a large MATLAB codebase, if you use MATLAB every day, your colleagues use MATLAB every day, and, frankly, the code works, it runs, it gives the results that you need—these are all valid reasons for sticking with MATLAB. But the speed—Julia is fast! And some might say that Julia is the superior language. That's why we're here at JuliaCon—we want to use Julia!

The good news is that there is a way to introduce Julia into your MATLAB workflows, and you can do this with minimal disruption. You want to start small. Pinpoint the particular pain point in your MATLAB workflow and start targeting that area. You want to keep your existing MATLAB workflows intact. That way you help keep people on board with your project. But most importantly, you also want to show meaningful performance wins because that ultimately gets people's attention.

Example Model

For the rest of my talk, I will walk through the process of doing Julia-MATLAB integration using an example model. The example model that I'll use includes 50 equations and state variables along with 37 model parameters.

We'll also have discrete events and continuous events. For the discrete events, we will update one of the parameters at four specific time points along the simulation. An example of this in practice might be injecting a dose of medicine or modifying the thrust provided by a rocket.

We'll also have a continuous event where we modify a state variable when it reaches a certain value. A classic example is when modeling the velocity of objects that collide with boundaries. For example, if you drop a ball, that ball is going to fall until it hits the ground. And when it hits the ground, it doesn't keep falling. There's an event that occurs that causes the ball to bounce. That's the sort of thing that's captured by these continuous events.

For our example, we'll look at two problems of interest. One is just simply solving the ODE one time. How long does it take to do that? But then in practice, we don't normally solve an ODE a single time and then call it quits. Normally, we're solving ODEs many, many times. So, we're also going to look at doing a parameter sweep where we'll solve this example model ODE with about 200,000 different sets of model parameters and then choose the one to use in production.

Model Plots

To illustrate this model a bit more, here are three of the state variables plotted over time. The first plot is a state variable of interest. This might represent the position of a mechanical part, or maybe it's the temperature of concrete or some other substance that we're modeling over time.

The second plot illustrates the discrete events. At these particular time points, we're changing one of the model parameters, and we see how that influences the time course for the state variable.

And then the third plot illustrates the continuous events where, when this state variable reaches a value of -10 or -2, we negate its derivative and we see how the time course is influenced as a result.

Looking back at the first state variable here, I'm plotting it for two different sets of model parameters. The first set of model parameters results in these large oscillations while the second set of model parameters has virtually no oscillations.

MATLAB ODE Solve Timing

The first question is how long did it take to solve this ODE one time so we could get this plot. Solving this ODE in MATLAB took about 20 milliseconds. Okay, so maybe that's not so bad.

Now, going back to this plot, like I mentioned, this state variable might represent the position of a mechanical part. And so if we have these oscillations, we can imagine that those oscillations cause wear on this mechanical part. And as a result, we would love to use the second set of model parameters so that there's less wear on that part, which means we don't have to replace it as often, which saves our company money. The problem is we don't know what those parameters are beforehand. Okay. So, what we'll do is pick 200,000 different sets of parameter values. We'll solve the ODE with each of those sets of parameter values and choose the parameter set that minimizes the oscillations so that we don't have to replace this part so often.

Now, if we do this parameter sweep in MATLAB, it takes about five hours to run on my laptop.

Now, if you run this exactly one time, maybe that's not such a huge deal. But if this is part of continuous integration or testing or if you do a parameter sweep for many different models and many different workflows, you can see how the time starts to add up quickly.

So, we want to see how Julia can fare in this situation. What we're going to do is we're going to take our MATLAB parameter sweep and translate that into Julia but then reconnect it into our MATLAB workflow.

Julia vs MATLAB for Simulations

The first thing to mention when converting from MATLAB to Julia is the syntax. MATLAB and Julia have a very similar syntax. MATLAB was the language that I used primarily before I started using Julia, and when I started learning Julia it almost didn't feel like I was learning a new language. That's how similar the syntax was to me.

In terms of the dynamics, Julia is designed for performance. In MATLAB, every time the ODE solver calls out to your dynamics function it has to allocate new memory to store the results of the computed state derivatives. Whereas in Julia, you can allocate that memory up front and then every time the ODE solver calls out to your dynamics function, it can reuse that memory, which boosts performance.

Events and Callbacks

I found that in Julia working with events and callbacks was more intuitive and easier to do. For this particular example, I could define them in fewer lines of code in Julia. Julia provides for better code organization and it also provides many pre-built callbacks that you can use out of the box.

So, looking more into events and callbacks: here's some example code in MATLAB and in Julia for defining events and callbacks.

%% MATLAB

% In events_func.m
v(n+1) = u(u49) + 2;
v(n+2) = u(u49) + 10;

% In callback_func.m
if any(ismember([n + 1, n + 2], ie))
    u(u50) = -u(u50);
end

# Julia

# In callbacks.jl
event1(u, t, integrator) = u[u49] + 2
event2(u, t, integrator) = u[u49] + 10
callback!(integrator) = integrator.u[u50] = -integrator.u[u50]
ContinuousCallback(event1, callback!)
ContinuousCallback(event2, callback!)

In MATLAB we have one file for the events and then a separate file for all the callbacks. Whereas in Julia we can define the events and the corresponding callbacks together in the same file which allows for better code organization.

Additionally, in MATLAB we have a single function that defines all of the events and then we have a single function that defines all of the callbacks. In Julia we can be more modular. We can define a single function per event, a single function per callback.

And then finally, in MATLAB there's more bookkeeping that we have to do on our own. We have to keep track of indexes of the events. We have to manually check if events occur and manually call the correct callbacks if those events occur. Whereas Julia takes care of all of that for us. In Julia, all we have to do is explicitly pair an event with its callback and then Julia takes care of the rest. Julia will check if the event occurs. It will then call the correct callback that you assigned it and we don't have to worry about that ourselves.

So again, I found that working with events and callbacks in Julia was more intuitive and easier to do.

Julia Is Easy to Learn

Now, another consideration when adopting a new software is how much learning you have to do to get up and running with it. I already mentioned the syntax. Julia syntax is similar to MATLAB, and so that isn't much of a barrier to entry.

Then there's also what packages are available and how quickly can I learn those packages. For this particular example I only needed to use two Julia packages to get it up and running. I used DiffEqCallbacks.jl for the events and callbacks and OrdinaryDiffEq.jl for setting up and solving the ODE.

And then perhaps more importantly: part of learning the package is going through its documentation and learning how to use the package from the documentation. So how good is the documentation?

Particularly for the SciML ecosystem, but also other ecosystems in Julia, the documentation is excellent. So if you look at the OrdinaryDiffEq.jl documentation it will clearly go through how to set up an ODE problem, how to solve it, and what options are available for solving. It also has a list of different solvers and shows you how to swap out different solvers with essentially just a single line of code change in Julia.

Then the DiffEqCallbacks.jl documentation is similarly good. It describes quite a few ready-to-use callbacks that you can use. There's the PresetTimeCallback for the discrete events at specific times. There are also more advanced callbacks such as those for step size control.

And then kind of the cherry on top for converting from MATLAB to Julia is there's one of the pages of the documentation that is a solver comparison. And so basically what it does is it lists the MATLAB solvers and then it says what are the corresponding Julia solvers you can use. So if in MATLAB you're using the ode45 solver, this web page will say, "okay, the corresponding Julia solver is DP5, but then there are also these other solvers you might want to try that might perform better."

So, the excellent documentation, the excellent package ecosystem and the similar syntax between Julia and MATLAB really makes transitioning from MATLAB to Julia a breeze.

Julia-MATLAB Integration Demo

Doing the actual integration we use the MATFrost.jl package. MATFrost.jl is a package that was developed by ASML. So, thank you to ASML for developing the package and open sourcing it for the Julia community to use. And I will illustrate the process of integrating Julia back into MATLAB via a live demo. So, I'm going to switch over to MATLAB.

% demo.m

[u0, tspan, p] = get_inputs();
[p_opt_indexes, grid_vals, lb_cons, ub_cons] = get_gridsearch_inputs();

tic
p_opt = gridsearch(u0, tspan, p, p_opt_indexes, grid_vals, lb_cons=lb_cons, ub_cons=ub_cons);
toc

sol0 = solve(u0, tspan, p);
p.p(p_opt_indexes) = p_opt;
sol = solve(u0, tspan, p);

plot(sol0.Time, sol0.Solution(1,:), Color="r", LineWidth=2);
hold on
plot(sol.Time, sol.Solution(1,:), Color="b", LineWidth=2);
hold off
legend("Before", "After");
title("u1 Before and After Parameter Sweep");
xlabel("Time");
ylabel("Value");

Alright. So, here's the MATLAB workflow we're going to work with. In this case, it's fairly minimal. That's for demonstration purposes, but the main point is we have some workflow, but there's a particular part of the workflow that's causing us grief, and we want that to be faster, but we want to make it faster without entirely destroying or disrupting our workflow.

So, I'm going to start this running.

The Workflow

In this workflow, we have some pre-processing. We're just getting inputs ready for our computation. The core computation in this workflow is this gridsearch function. This gridsearch function is our implementation of that parameter sweep that I mentioned. And then once we have the output, we do some post-processing. In this case, we're just plotting values.

But again, the main point is that we have a workflow, but there's a pain point in that workflow that we want to be better. We want to make it better with Julia.

MATLAB Results

So there are our results. Alright, so here I'm plotting the first state variable before the parameter sweep and after the parameter sweep. And as expected, we see that the oscillations are smaller than before. And then if we look at the elapsed time, it took about 40 seconds for this to run in MATLAB.

Translating to Julia

Okay. So now we want Julia. So, the first step is to take the part of the workflow that we want to improve, and we're going to translate that into Julia.

# JuliaModel/src/gridsearch.jl

function gridsearch(
    u0::Vector{Float64},
    tspan::Vector{Float64},
    p::Vector{Float64},
    cb_times::Vector{Float64},
    cb_values::Vector{Float64},
    p_opt_indexes::Vector{Int64},
    grid_vals::NTuple{5, Vector{Float64}},
    lb_cons::Float64,
    ub_cons::Float64,
    abstol::Float64,
    reltol::Float64,
)

    # `p` is updated in place during the callbacks,
    # so take a copy that will be used to re-initialize `p`
    # at the start of each loop iteration below.
    p_original = copy(p)

    callback = get_callbacks(cb_times, cb_values)

    prob = ODEProblem{true}(dynamics!, u0, (tspan[1], tspan[2]), p)
    solver = DP5()

    sol0 = OrdinaryDiffEq.solve(prob, solver; callback, abstol, reltol)
    loss0 = max_variation(sol0)

    losses = Array{Float64, length(grid_vals)}(undef, length.(grid_vals)...)
    loss_opt = loss0
    p_opt = p_original[p_opt_indexes]
    for (i, p_vals) in enumerate(Iterators.product(grid_vals...))
        p .= p_original
        p[p_opt_indexes] .= p_vals
        new_prob = remake(prob; p)
        sol = OrdinaryDiffEq.solve(new_prob, solver; callback, abstol, reltol)
        if constraints_met(sol, lb_cons, ub_cons)
            l = max_variation(sol)
            if l < loss_opt
                loss_opt = l
                p_opt .= p_vals
            end
            losses[i] = l
        else
            losses[i] = Inf
        end
    end

    return (p_opt, loss_opt, loss0, losses)

end

So, we take the gridsearch function, we look at its implementation, we translate it into Julia, and we end up with a Julia function. I'm calling it gridsearch just like the MATLAB function. It takes the same inputs. It does the parameter sweep. It returns the same outputs as the MATLAB version. So the same computation, just now written in Julia instead of MATLAB.

And then we're going to house this function inside of a Julia package. In this case I called the Julia package JuliaModel. So now we have a Julia package. It has our Julia implementation of gridsearch, our parameter sweep.

Using MATFrost.jl

Now we need to build a bridge using MATFrost.jl. So, MATFrost.jl needs to be a dependency of our Julia package, even if the package doesn't use it at all, because what we're going to do is instantiate our Julia package's package environment. Then import MATFrost.jl and then call MATFrost.install. And what this does is it takes our Julia package and creates a MATLAB class out of that package, and in this case and it uses the same name.

So now we have a JuliaModel Julia package, but now we have a JuliaModel MATLAB class, which we'll use to interface with Julia. So this is what MATFrost.jl created for us.

Minimizing Disruptions

So now that we have that MATLAB class, now we need to start using this code to start interfacing with Julia. Now, we could add this directly to the workflow itself, but again, we want to minimize disruptions to the workflow, especially if we have colleagues that are also working on this workflow simultaneously with us.

So, the key idea here is we want calling out to Julia to be an implementation detail from the perspective of the workflow. So we don't want the workflow to care that we're calling out to Julia. We want the workflow to work as is.

So, what we're going to do is we're going to create a new MATLAB function, but within that function we call out to Julia. This MATLAB function I'm going to call gridsearch_julia, and importantly it needs the same API as whatever function we're replacing. So, I'm going to have it take the same inputs. It's going to return the same output, but then internally there's not much to it, again, because all the functionality is in Julia.

% gridsearch_julia.m

function [p_opt, loss_opt, loss0, losses] = gridsearch_julia(u0, tspan, p, p_opt_indexes, grid_vals, options)

    arguments

        u0
        tspan
        p
        p_opt_indexes
        grid_vals
        options.lb_cons = 1.65
        options.ub_cons = 2.25
        options.abstol = 1e-7
        options.reltol = 1e-7

    end

    jl = get_julia();

    out = jl.gridsearch(u0, tspan, p.p, p.cb_times, p.cb_values, p_opt_indexes, grid_vals, ...
        options.lb_cons, options.ub_cons, options.abstol, options.reltol);

    [p_opt, loss_opt, loss0, losses] = out{:};

end

What this function is going to do is I have this function get_julia which is a function I wrote that instantiates a JuliaModel object. Then with that object I can interface with Julia. So if I do jl.gridsearch right here, this gridsearch is not the MATLAB function. This is the gridsearch that I wrote in Julia in my Julia package. So what we're doing here is taking our MATLAB values and passing them over to Julia. Julia is going to run the gridsearch function I defined in Julia. It'll do the parameter sweep and then it will return a Tuple of values which is a cell array in MATLAB. So I just unpack that cell array to get the appropriate output for this function.

But again the main point to minimize disruption for the workflow is that this new function needs to have the same API so that from the workflow's perspective nothing changes.

Julia-MATLAB Results

Let's see how this works. So, I'm just going to change the one function. (Change gridsearch to gridsearch_julia in demo.m.) Importantly I'm not changing any of the pre-processing or post-processing. I'm not changing any of the inputs or outputs. And then if I run it I get my result. The plot looks pretty much the same as last time, maybe exactly the same. And if we look at the timing, it was 100 times faster.

So, from the workflow's perspective, essentially nothing changed. I called out to a new function, but didn't have to change any the pre- or post-processing, but now the workflow runs 100 times faster than before.

So this was a 40-second version of the parameter sweep, not the five hour version. So, does it scale? Let's look at some other benchmarks.

ODE Solve Timing: MATLAB vs Julia-MATLAB

Alright, first looking at a single ODE solve. If we just did a single ODE solve in Julia and then did the Julia-MATLAB integration, that ODE solve takes 10 milliseconds. So, it's twice as fast as the pure MATLAB version. I will note that there is a significant overhead to using MATFrost.jl for the first call, but subsequent calls are faster. So a 2x speed up, that's something, but it's not the 10 to 1000 times speed up that we were seeing with the SciML benchmarks. But again, we don't typically solve an ODE a single time.

So what about the parameter sweep? You'll recall that in MATLAB the parameter sweep with 200,000 ODE solves took about five hours to run. In Julia, that time dropped to less than two minutes. So that's 163 times faster than the pure MATLAB version.

So I think that's fast enough for this meme. I am speed. Julia is speed. So that's amazing. We took our workflow, we created a new MATLAB function that called out to Julia internally (but from the workflow's perspective nothing really changed) but now it's 163 times faster.

Uncompromised Simulation Accuracy

Okay, so it's faster, but now the other question is are the results still good or are they garbage now.

The results are still good. Here, I'm plotting the first state variable before and after the parameter sweep; the MATLAB results are in red, the blue dots are the Julia results. And we see that the Julia results align with the MATLAB results.

I also checked all the other state variables, and in all cases all of the Julia-MATLAB integrated results are within 1/100th of a percent compared to the MATLAB results. So, we achieve the accuracy that we want for our simulations at a fraction of the computational cost.

Julia-MATLAB Integration with GLCS

So now if you want these speed ups in your code, but you're not quite sure how to start, feel free to reach out to us at GLCS. We have an approach for helping clients pinpoint these areas of concern in their MATLAB workflows. We help translate the code to Julia and reintegrate it back into MATLAB and we ensure that we meet the accuracy and performance metrics that we need to.

Conclusion

So, unlock up to 100 times faster performance by integrating Julia. In today's example, we saw even faster than 100 times faster. Adopt Julia seamlessly. Integrate it step by step without disrupting your MATLAB workflows. So, enhance the MATLAB code that you have. Elevate its capabilities by integrating Julia and taking advantage of its speed and flexibility.

Thank you.

Q&A

1. Audience: Can you show us that get_julia function you mentioned?

   Yeah. So we want to see the get_julia function that I wrote in MATLAB. So yes, here it is. So basically I made use of a persistent variable to make sure I'm not reinitializing the Julia instance every time. So I'm reusing the same Julia instance every time I call this function. But the first time there's that overhead that I mentioned.

   Audience: Your MATLAB code isn't showing.

   function jl = get_julia()
   
       persistent jl_
       if isempty(jl_)
           mjl = JuliaModel();
           jl_ = mjl.JuliaModel;
       end
   
       jl = jl_;
   
   end
   

   Oh, thank you. I need to actually get me out of the slideshow. There we go. Okay. Persistent variable. So that way on subsequent calls to the function, I'm using the same initialization of the Julia runtime. So we're not wasting resources every time. But yeah, here is where we're actually initializing the JuliaModel MATLAB object. Yeah, there's nothing to it. There's no parameters to—I mean you can change the Julia version if you want but if you have everything set up in your PATH you don't need to pass anything to it.

2. Audience: Just a quick question, about how long did it take to, when you call MATFrost.jl to install JuliaModel, how long does that take?

   That's a good question. I don't remember off the top of my head.

   Audience: Well, it was quick, I'm assuming, or it just builds a little bit of MATLAB code, right?

   Right, if I remember correctly, it was on order of seconds, maybe minutes, but nothing terrible.

3. Audience: Does MATFrost.jl work with Linux or is it still like only for Windows?

   As far as I know, it's only supported for Windows.

4. Audience: Some of these numbers scare me a little with the performance comparisons between Julia and MATLAB. I know there's a huge difference in LAPACK and BLAS versioning, right, MATLAB typically goes for a more numerical stable version of LAPACK versus if Julia will use OpenBLAS by default, I think (I might be wrong on that). Could you tell me what version of each you're using for both?

   I do not know what versions I'm using.

   Audience: You just, in the MATLAB terminal, just do version -lapack. There's an "i" in "version".

   Oh, thank you. Is it capital LAPACK or lower?

   Audience: That's correct. Yeah. Okay, that is a faster one. Okay.

5. Audience: Can you actually like create structs or more complicated types than arrays with this?

   So can you create structs and arrays in Julia, are you saying?

   Audience: No no, like in MATLAB can you like create structs from Julia? Like if you define a data type in Julia can you like create it here in MATLAB?

   Yeah. So one of the key things to working with MATFrost.jl is everything needs to be concretely typed. So, like, if you create a struct, you can have nested structs and they basically get translated to MATLAB structs, but you need to concretely type it as a Float64 or an Int depending on whatever data type you have. So, no abstract types, and the function calls also need to be typed.

6. Audience: I remember a long time ago when I was calling C code from MATLAB it had to use these MEX files. Is that what it's using under the hood here or is there some new fancier way of calling external code and MEX files that this is using?

   Yeah, so MATFrost.jl does use a MEX file to work.

Additional Links

• JuliaCon Talk Submission Page
  • Submission page for the talk, including an abstract and summary.
• Julia and MATLAB^® Integration at GLCS
  • Our web page detailing our Julia and MATLAB^® integration service.

MATLAB is a registered trademark of The MathWorks, Inc.

Cover image: The JuliaCon 2025 logo was obtained from https://juliacon.org/2025/.

This post was written by Steven Whitaker.

At GLCS, we're proud to have delivered innovative projects across top industries, including renewable energy, aerospace, and biomedical engineering. Our comprehensive Modeling and Simulation Services empower clients to elevate their designs, whether rewriting models in Julia for greater efficiency or unlocking cutting-edge features to solve complex problems. With deep expertise spanning several engineering and scientific domains, including computational fluid dynamics, thermodynamics, controls, biomedical engineering, and chemistry, we are your trusted partner in pushing modeling boundaries and achieving breakthrough results.

In this post, we'll focus on systems modeling for renewable energy.

Renewable energy systems, from wind farms to wave power, require precise modeling and simulation. Selecting the optimal computational tools is crucial; it can significantly accelerate development, reduce costs, and drive the transition to a sustainable future.

Both MATLAB^® and Julia are widely used in engineering, particularly for solving differential equations. This post compares how each handles a renewable energy modeling scenario, the steady axisymmetric turbulent wake behind a wind turbine, ultimately showing why Julia has the edge. Maximize efficiency and energy output with cutting-edge technologies designed for tomorrow’s energy.

Steady Axisymmetric Turbulent Wake

When air flows past a wind turbine, a wake forms downstream. The wake velocity deficit impacts turbine spacing, efficiency, and power output.

A simplified steady axisymmetric turbulent wake equation is:

\[ \frac{\partial U}{\partial x} = \nu_t \cdot \left( \frac{\partial^2 U}{\partial r^2} + \frac{1}{r} \frac{\partial U}{\partial r} \right) \]

where:

• \( U \) is the axial velocity.
• \( x \) is the downstream distance.
• \( r \) is the radial coordinate.
• \( \nu_t \) is the turbulent viscosity.

This is a reduced form of the momentum equation, capturing diffusion of momentum due to turbulence.

MATLAB vs Julia: ODE/PDE System Set-up

Let's see how to convert the math into code and solve this PDE.

• MATLAB:

  function dUdx = wake_eq(x, U, p)
      % Radial step size
      dr = p.r(2) - p.r(1);
  
      % First derivative (central difference)
      dUdr = (U(3:end) - U(1:end-2)) / (2 * dr);
  
      % Second derivative (central difference)
      d2Udr2 = (U(3:end) - 2 * U(2:end-1) + U(1:end-2)) / dr^2;
  
      dUdx = zeros(size(U));
      dUdx(2:end-1) = p.nu_t * (d2Udr2 + dUdr ./ p.r(2:end-1));
  end
  
  U0 = initial_profile();
  xspan = [0 100];
  p.nu_t = 0.05;
  p.r = linspace(0, 1, numel(U0));
  
  prob = ode;
  prob.ODEFcn = @dUdx;
  prob.InitialTime = xspan(1);
  prob.InitialValue = U0;
  prob.Parameters = p;
  prob.Solver = "ode45";
  
  sol = solve(prob, xspan(1), xspan(2));
  

• Julia:

  using DifferentialEquations
  
  @kwdef mutable struct WakeParams{T}
      ν_t::Float64
      const r::T
  end
  
  function wake_eq!(dU, U, p, x)
      # Radial step size
      dr = p.r[2] - p.r[1]
  
      # First derivative (central difference)
      dUdr = (U[3:end] .- U[1:end-2]) ./ (2 * dr)
  
      # Second derivative (central difference)
      d2Udr2 = (U[3:end] .- 2 .* U[2:end-1] .+ U[1:end-2]) ./ dr^2
  
      dU[1] = dU[end] = 0
      dU[2:end-1] .= p.ν_t .* (d2Udr2 .+ dUdr ./ p.r[2:end-1])
  end
  
  U0 = initial_profile()
  xspan = (0.0, 100.0)
  p = WakeParams(; ν_t = 0.05, r = range(0.0, 1.0, length(U0)))
  
  prob = ODEProblem(wake_eq!, U0, xspan, p)
  solver = Tsit5()
  
  sol = solve(prob, solver)
  

(Note that, in practice, the boundary conditions for \( r = 0 \) and \( r = 1 \) would need to be handled with more care.)

As you can see, the syntax for Julia and MATLAB is quite similar. However, there are some key differences between the two approaches:

• Julia's broadcasting (.=, .*, etc.) is explicit and fast.
• Julia can use in-place functions to minimize memory allocations, boosting performance.
• The Julia code for the dynamics above was written to look more like the MATLAB code. However, additional easy performance optimizations are possible to reduce memory allocations.
• Julia's DifferentialEquations.jl supports many solvers with a unified interface. MATLAB supports only a limited set of solvers.

Event Handling and Callbacks: Wind Gusts

Now let's add a gust at \( x = 50 \) that will change \( \nu_t \) for \( x \ge 50 \).

• MATLAB:

  function v = events_func(x, U, p, gust_position)
      % Event occurs when `x == gust_position`.
      v = x - gust_position;
  end
  
  function [stop, U, p] = callbacks_func(x, U, ie, p)
      stop = false;
      % Check if the event occurred.
      if ismember(1, ie)
          p.nu_t = 0.08;
      end
  end
  
  gust_position = 50;
  
  event = odeEvent;
  event.EventFcn = @(x, U, p) events_func(x, U, p, gust_position);
  event.Response = "callback";
  event.CallbackFcn = @callbacks_func;
  
  prob.EventDefinition = event;
  
  sol = solve(prob);
  

• Julia:

  function gust_affect!(integrator)
      integrator.p.ν_t = 0.08
  end
  
  gust_position = 50.0;
  callback = PresetTimeCallback([gust_position], gust_affect!)
  
  sol = solve(prob, solver; callback)
  

When it comes to events and callbacks, Julia's approach is better:

• Julia's callbacks are better organized; events and corresponding callbacks can be defined next to each other in the code, instead of separated across files as is typical in MATLAB.
• Multiple events can be combined cleanly with CallbackSet, no need to try to cram multiple events into a single function like you have to do in MATLAB.
• Julia keeps track of what events are triggered. In MATLAB, you have to check what events were triggered manually.
• Julia provides many pre-defined callbacks (in DiffEqCallbacks.jl) that often have to be manually implemented in MATLAB.

Other Considerations

In addition to the differences in solving differential equations, here are some other key differences between Julia and MATLAB:

• Performance: Julia's JIT-compilation and method specialization yield C-like speeds. Large-scale renewable energy simulations run faster and scale better, especially for parameter sweeps. You can expect to see 50--150 times faster code with Julia.
• Workflow: MATLAB offers a polished GUI and plotting out of the box. However, Julia offers open-source freedom, easy integration with Python/C, and a thriving ecosystem.
• Licensing: MATLAB requires a paid license; Julia is entirely free and open-source.

Summary

In this post, we saw how Julia and MATLAB compare for defining and solving steady axisymmetric turbulent wake. Both languages can model renewable energy systems effectively. However, Julia offers:

• Performance: JIT speed for large systems.
• Flexibility: Powerful callbacks and open integrations.
• Cost: No license fees.
• Modern syntax: Designed for productivity and clarity.

Ready to revolutionize your renewable energy simulations? Transition your MATLAB models to Julia and experience unparalleled speed, flexibility, and long-term maintainability. Reach out today and let's accelerate your green energy innovations together!

Worried about the technical hurdles and costs of switching from MATLAB to Julia? Discover our cutting-edge Julia-MATLAB Integration. We develop high-performance Julia models that seamlessly connect with your existing MATLAB codebase, minimizing risks while maximizing your return on investment. Transition smarter, faster, and more cost-effectively with our expert solutions!

Additional Links

• Julia SciML Docs
  • Documentation for the scientific machine learning ecosystem (including DifferentialEquations.jl).
• SciML Benchmarks
  • ODE solver performance comparisons, including Julia and MATLAB solvers (and others).
• GLCS Modeling & Simulation
  • Connect with us for Julia development help.
• GLCS Julia-MATLAB Integration
  • A smart way to begin your Julia journey, fully modeled and seamlessly integrated with MATLAB.

MATLAB is a registered trademark of The MathWorks, Inc.

This post was written by Steven Whitaker.

In this Julia for Devs post, we will discuss using Julia's Profile standard library for performance and allocation profiling. We will illustrate these tools with example code and then show how to improve the code.

This post will showcase the powerful techniques we used to significantly accelerate our clients simulations, resulting in a remarkable 25% reduction in run time of code that was already highly optimized for performance. The impact of these techniques on our client's work is a testament to their effectiveness and should inspire you in your own projects.

Many new Julia developers face poor code performance, but these techniques can net 10x or even 100x faster run times!

While we won't be sharing client-specific code, we will provide similar examples that are practical and applicable to a wide range of simulations. This approach should give you the confidence to apply these techniques in your work.

Here are some of the key ideas we will focus on:

• Pinpoint areas of improvement with Profile.@profile.
• Track down allocations with Profile.Allocs.@profile.
• Improve run time and reduce allocations with @generated functions.

Let's dive in!

Profiling in Julia

Profiling is a crucial tool for locating performance bottlenecks. This knowledge is invaluable as it guides development efforts to the parts of the code that will have the most significant impact on run time. Understanding this process will keep you informed and in control of your code's performance.

Here is some example code we will use to illustrate profiling in Julia:

using StaticArrays: SVector

function kernel_original(x::SVector{N}) where N

    y = zeros(N + 1)
    y[1] = x[1]
    for i = 2:N
        y[i] = 0.5 * y[i-1] + x[i]
    end
    y[end] = sum(@view(y[1:end-1]))

    return SVector{N+1}(y)

end

function workflow_original()

    total = 0.0
    for i = 1:100
        x = SVector{10, Float64}(rand(10))
        y = kernel_original(x)
        total += y[end]
    end
    return total

end

The main idea with this example is that there is a workflow, workflow_original, that calls out to a core computation for many different input values.

To profile this code, we will use the Profile standard library. Since Profile implements a statistical profiler, we need to ensure the code we profile runs long enough to reduce the impact of noise in the measurements (see the documentation for more info). So, let's see how long workflow_original takes (using BenchmarkTools.jl):

julia> using BenchmarkTools

julia> @btime workflow_original();
  6.410 μs (300 allocations: 25.00 KiB)

6 microseconds is very fast compared to the default profiling sample delay of 1 millisecond. Therefore, we must run the workflow many times to get enough samples. We have found that 1000--5000 samples are usually plenty for identifying performance bottlenecks, though slower code will likely need more samples and/or a larger sample delay.

So, to get approximately 1000 samples, we will need to run the workflow \( 1000 \cdot \frac{1 \mathrm{ms}}{0.006 \mathrm{ms}} = 166,667 \) times. We'll round up to 200,000 for good measure.

Let's see how to profile the code:

julia> using Profile

julia> Profile.clear()

julia> workflow_original();

julia> Profile.@profile for _ in 1:200_000 workflow_original() end

A couple of notes:

• The Profile.clear() step is not strictly necessary. However, a habit of always clearing the profile data ensures one doesn't inadvertently spoil their profiles with old data from previous profiling results.
• We called workflow_original once before profiling to avoid profiling JIT compilation.

Now we want to display the profile data. One way is via Profile.print, which prints a textual representation of the profile to the console, but this isn't the most efficient method for inspecting the data. Typically, profile data is visualized using a flamegraph.

The Profiling docs list several packages for visualizing profiles. We will use ProfileCanvas.jl, which creates an HTML file we can view in a web browser and interactively inspect the profiling results:

julia> using ProfileCanvas

julia> ProfileCanvas.view()

This code creates and displays a flamegraph:

One thing that stands out in this flamegraph is the three yellow rectangles. These indicate occurrences of garbage collection (GC), which implies the code allocated memory. Since these yellow blocks represent a decent portion of the run time (as indicated by the width of the rectangles), let's investigate.

Allocation Profiling

We will use Julia's allocation profiling tools to further inspect the allocations we know the workflow has. The process is similar to performance profiling, with the following differences:

• We will use Profile.Allocs.@profile and pass the option sample_rate = 1.0 to record all allocations. In a larger workflow with many more allocations, a smaller sample_rate is advised (the default value is 0.1).
• We will run the workflow just one time.
• We will visualize the results with ProfileCanvas.view_allocs.

Here's how to profile allocations:

julia> using Profile, ProfileCanvas

julia> Profile.Allocs.clear()

julia> workflow_original();

julia> Profile.Allocs.@profile sample_rate = 1.0 workflow_original();

julia> ProfileCanvas.view_allocs()

In this flamegraph, the widths of each rectangle correspond to how many allocations were made. In this example, each yellow block is the same width, meaning they all contributed the same number of allocations.

Now we need to determine whether we can do anything about these allocations.

Moving up from the bottom of the flamegraph lets us trace the call stack to see where these allocations came from. For example, we can see that GenericMemory was called from Array, which itself was called from Array, and so on. Eventually, we get to workflow_original.

If we hover our mouse cursor over that block, it will display the file and line number:

(In this case, I defined workflow_original in the first REPL prompt of a fresh Julia session, so that's why REPL[1] shows up for the file name.)

Looking at these profile results shows us that the offending lines are:

• x = SVector{10, Float64}(rand(10)) (in workflow_original)
• y = zeros(N + 1) (in kernel_original)

This makes sense; in each of these lines, we explicitly create an array (via rand and zeros), which allocates memory.

But it turns out we can eliminate these allocations!

Eliminating the first allocation requires knowledge of the StaticArrays.jl package. In particular, the @SVector macro can create an SVector directly from standard array expressions (like rand) without allocating memory. So, instead of using the SVector constructor, we can write:

x = @SVector rand(10)

The second allocation, however, is a bit trickier to remove.

Reducing Allocations with @generated Functions

What makes it difficult to remove the allocation in kernel_original is the elements of the vector y depend on previous elements of the vector. That means we have to compute one element to compute the next, which means we have to store that element somehow. If we knew exactly how long y would be, we could store the computations in local (scalar) variables. However, the function needs to work with any input size; we don't want to create a separate method for each possible input size.

At least, not by hand.

It turns out Julia can automate the creation of these specialized methods. The trick is to use the @generated macro.

A method annotated with @generated uses type information to produce specialized implementations of the method depending on the input types. And since type information is available at compile time, this specialization occurs at compile time, leading to run time improvements.

Using a @generated function to replace kernel_original will allow us to, essentially, move the run time allocation to compile time.

Here's what the new function looks like:

@generated function kernel_generated(x::SVector{N}) where N

    assignments = [:(y1 = x[1])]

    for i = 2:N
        yprev = Symbol(:y, i - 1)
        yi = Symbol(:y, i)
        push!(assignments, :($yi = 0.5 * $yprev + x[$i]))
    end

    yend = Symbol(:y, N + 1)
    sum_expr = reduce((a, b) -> :($a + $b), (Symbol(:y, i) for i = 1:N))
    push!(assignments, :($yend = $sum_expr))

    vars = ntuple(i -> Symbol(:y, i), N + 1)

    return quote
        $(assignments...)
        return SVector{$(N + 1), Float64}($(vars...))
    end

end

The first thing you might notice, especially if you are unfamiliar with metaprogramming, is that this function looks quite different from kernel_original. So, let's unpack this a bit:

• A @generated function needs to return an expression. The compiler will then compile the code resulting from the expression. Finally, at run time, the compiled code will be used, not the code used to generate the compiled expression. In other words, this function must return the specialized code itself, not the result of a run time computation.
• The returned expression is created with a quote block. This quote block interpolates (using $) expressions built up earlier in the function. The computations to build up these expressions occur only at compile time.

If we want to inspect what the generated function looks like, we need to refactor the code just a bit. Essentially, we'll create a regular Julia function that returns an expression, and the @generated function will just call that function:

function _gen_kernel_generated(::Type{<:SVector{N}}) where N
    # Same code as `kernel_generated` above.
end

@generated kernel_generated(x::SVector) = _gen_kernel_generated(x)

Then we can call _gen_kernel_generated directly to see what code actually runs:

julia> _gen_kernel_generated(typeof(@SVector rand(1)))
quote
    #= REPL[2]:18 =#
    y1 = x[1]
    y2 = y1
    #= REPL[2]:19 =#
    return SVector{2, Float64}(y1, y2)
end

julia> _gen_kernel_generated(typeof(@SVector rand(2)))
quote
    #= REPL[2]:18 =#
    y1 = x[1]
    y2 = 0.5y1 + x[2]
    y3 = y1 + y2
    #= REPL[2]:19 =#
    return SVector{3, Float64}(y1, y2, y3)
end

julia> _gen_kernel_generated(typeof(@SVector rand(3)))
quote
    #= REPL[2]:18 =#
    y1 = x[1]
    y2 = 0.5y1 + x[2]
    y3 = 0.5y2 + x[3]
    y4 = (y1 + y2) + y3
    #= REPL[2]:19 =#
    return SVector{4, Float64}(y1, y2, y3, y4)
end

Yep, the implementation looks right!

We can also see that the generated code avoids creating an array to store intermediate results, instead storing computations in local variables. But we didn't have to write any of those methods ourselves! Using @generated allows us to maintain just one function to generate all these specialized implementations.

Let's benchmark the new implementation:

julia> @btime workflow_generated();
  1.093 μs (0 allocations: 0 bytes)

Nice, six times faster and no allocations!

And here's the profile:

There aren't obvious places for improvement, so I'd say we did a pretty good job optimizing the code.

Summary

In this post, we saw how to use the Profile standard library to profile the run time and the allocations of a piece of code. We also illustrated how a @generated function can eliminate run time allocations and speed up the code. These were key ideas we used to help one of our clients speed up their simulations.

Do you need help pinpointing performance bottlenecks or tracking down allocations in your code? Contact us, and we can help you out!

Additional Links

• Profiling in Julia
  • Julia manual section on profiling.
• Metaprogramming in Julia
  • Julia manual section on metaprogramming, including @generated functions.
• GLCS Modeling & Simulation
  • Connect with us for Julia Modeling & Simulation.

This post was written by Steven Whitaker.

In this Julia for Devs post, we will explore the fascinating world of using universal differential equations (UDEs) for model discovery. A UDE is a differential equation where part (or all) of it is defined by a universal approximator (typically a neural network). These UDEs play a pivotal role in uncovering missing aspects of established models.

UDEs enable seamless integration of known mechanistic models with data-driven modeling approaches. Rather than omit or guess at unknown aspects of a model, a neural network can be embedded into the model, which can then be trained using observed data.

Once trained, the embedded neural network can be approximated by a mathematical expression. This allows us to replace the neural network with an interpretable formula, improving transparency while filling in the missing aspects of the original model with new structure learned from observed data.

This post will illustrate key ideas and design decisions made while helping one of our clients uncover missing dynamics in their model, a complex system representing the human body under treatment of a rare disease.

By replacing just one aspect of our client's model with a neural network, we achieved a significant milestone: a 30% reduction in the error of the model predictions. This success story is a testament to the power of UDEs in enhancing model performance.

We will not share client-specific code, but will provide similar examples to illustrate our approach.

Here are some of the key ideas we will focus on:

• Ensure nonnegativity of state variables (as needed).
• Appropriately initialize neural network weights.
• Normalize neural network inputs.
• Make dynamics modular.
• Fit symbolic expression.

Note that we will discuss fully connected neural networks, so some comments below may not apply if other architectures are used.

And with that, let's dive in!

Ensure Nonnegativity of States

When working with a model representing a real phenomenon, chances are that at least some of the model's state variables are naturally nonnegative. For example, the energy of a system or the concentration of a chemical cannot be negative quantities.

However, a differential equation solver sees only math, not the physical phenomenon the math represents. So, we have to tell the solver to respect the natural constraints that exist.

One way to enforce nonnegativity is to pass the isoutofdomain option to solve, where isoutofdomain is a function that returns true when at least one of the provided state variables violates the nonnegativity constraint. For example, if all state variables should be nonnegative, the function can be defined as:

isoutofdomain(u, p, t) = any(<(0), u)

As another example, if only the first and third states should be nonnegative:

isoutofdomain(u, p, t) = u[1] < 0 || u[3] < 0

For more information and other tools for tackling nonnegativity, check out the SciML docs.

The idea of telling the solver about the nonnegativity constraints may seem obvious. Still, it has important implications for the initialization of neural networks embedded into the model. Care should be taken to ensure the initial network weights (before training) do not cause states to become negative. See the next section below for more details.

Appropriately Initialize Neural Network Weights

To learn missing dynamics, the neural network in a UDE needs to be trained.

Training the neural network can occur only if the UDE can be solved using the initial network weights. Otherwise, the gradient of the loss, which is used by optimization algorithms to train the neural network, cannot be computed.

As a result, it is necessary to choose a good initialization for the neural network weights. Here are some approaches for initialization and how well they work:

• Random initialization: Typically, neural network weights are initialized randomly. However, this results in random UDE dynamics, so whether a state variable stays positive (or satisfies any other constraints) is left to chance. And if constraints are violated, but we try to enforce them via, e.g., isoutofdomain, the solver will be unable to solve the UDE, preventing computation of the loss gradient. So, random initialization might work, but it might not.
• Zero initialization: Don't do this. Network weights won't ever update during training because the gradients with respect to those weights will always be zero.
• Constant initialization: Don't do this, either. Initializing all the weights to the same, non-zero value will result in some amount of learning, but it severely limits the expressivity of the network.
• Pre-training: If the neural network in the UDE is used to replace an expression that is believed to be incorrect (but otherwise gives a usable model), one way to initialize the network weights for UDE training is to initialize the weights randomly but then train the network directly (i.e., not the UDE as a whole) to fit the expression the network is to replace. This works because no constraints are involved during pre-training (so randomly initializing the weights is okay), but when training the UDE, the network weights have been set to avoid running into issues with constraints.
• Smoothed Collocation: Smoothed collocation is another approach for pre-training the neural network without involving constraints. See the SciML docs for more info.

For our client, randomly initialized weights failed to give a usable gradient for training, so we decided on pre-training because they had a reasonable guess that we could fit the initial network weights to.

Normalize Neural Network Inputs

One key to ensuring UDE training proceeds nicely is to normalize the inputs to the neural network to ensure all inputs are roughly of the same magnitude.

Normalizing is essential because the gradient of the training loss function is proportional to the network inputs. If one input tends to be 1000 times larger than another, the gradient will also tend to be that much larger, dominating the learning algorithm.

To illustrate how to normalize, suppose we have the following neural network (created using Lux.jl):

nn = Chain(
    Dense(2, 5, tanh),
    Dense(5, 5, tanh),
    Dense(5, 1),
)

Then we can add a function to the Chain that performs the normalization:

nn_normalized = Chain(
    x -> x ./ normalization,
    # Other layers as before
)

In this example, normalization is a Vector containing the values to scale each input variable. And of course, we're not limited to scaling the inputs; we can implement whatever function we want to process the inputs (such as z-score standardization).

The neural network in our client's UDE did not learn without normalization. After normalizing the inputs, we got the neural network to learn meaningful dynamics.

Make Dynamics Modular

While not strictly necessary for UDEs, making the dynamics modular vastly simplifies comparing between different approaches.

For our client, we wanted to compare three versions of the dynamics: the original dynamics, the UDE (where part of the original dynamics was replaced with a neural network), and the updated dynamics (where the trained neural network was replaced with a symbolic expression fit to the neural network).

Rather than duplicate the dynamics function three times with each slight variation, we allowed the variable part of the dynamics to be passed in as an option to the dynamics function. To illustrate:

function f!(du, u, p, t; g = original_g)
    # ... some code ...

    # `a` and `b` are values computed above
    # or pulled from `u`, etc.
    val = g(a, b, p)
    # `val` is used to update `du` in some way.

    # ... some code ...
end

However, ODEProblems don't allow passing options to the dynamics function. But that's not a problem; we can create a closure to set the option before handing the function to an ODEProblem. For example, if we want g to use a Lux.jl neural network:

nn = Chain(...)
(p_nn, st) = Lux.setup(...)
# Be sure to include `p_nn` in the `ODEProblem` parameters `p`.
g_nn = (a, b, p) -> nn([a, b], p.p_nn, st)[1][1]
f_nn! = (du, u, p, t) -> f!(du, u, p, t; g = g_nn)

Setting up our client's code like this reduced code duplication while allowing easy comparisons across different versions of the dynamics.

Fit Symbolic Expression

One of the key steps to learning interpretable dynamics from a UDE is to fit a symbolic expression to the trained neural network. Doing so allows us to replace the black box neural network with a mathematical expression we can understand.

The first step is to collect the data to use for the fitting. If the neural network takes two inputs, we will need a Matrix of values:

X = [
    a1 a2 ... aN;
    b1 b2 ... bN;
]

The (ai, bi) pairs should cover the expected range of input values. One way to determine this range is to solve the UDE and save off the values that end up going into the neural network.

To get the target values, evaluate the neural network with the X we just created:

y = nn(X, p_nn, st)[1] |> vec

(Here we assume the neural network outputs a single number per input pair.)

Now we can figure out a mathematical expression relating X to y. One way to do this is to use SymbolicRegression.jl.

After obtaining an Expression object eq (called tree in the README for SymbolicRegression.jl), we can use it in our dynamics function as described in the previous section:

# `p` needs to be an input even though it's not used.
g_eq = (a, b, p) -> eq([a; b;;])[1]
f_eq! = (du, u, p, t) -> f!(du, u, p, t; g = g_eq)

Using SymbolicRegression.jl to fit the trained UDE neural network, we could provide our client with a precise mathematical expression representing the dynamics that were missing from their original differential equation.

Summary

In this post, we discussed vital aspects of implementing UDEs to learn missing dynamics. We learned some tips for helping UDE training, including appropriately initializing network weights and normalizing network inputs. We also saw the benefits of code modularity and how that can easily allow us to insert a learned mathematical expression into the dynamics. For our client, we were able to use these ideas to train a UDE to achieve 30% less error in the model predictions.

Do you want to leverage UDEs to improve your models' predictive capabilities? Contact us, and we can help you out!

Additional Links

• SciML UDE Tutorial
  • UDE tutorial from official Julia SciML docs.
• SciML Docs about Nonnegativity
  • More information about debugging problems with negativity, including a discussion about isoutofdomain.
• Lux.jl
  • Package for creating and training neural networks.
• SymbolicRegression.jl
  • Package for fitting expressions to data.
• GLCS Modeling & Simulation
  • Connect with us for Julia Modeling & Simulation consulting.

This post was written by Steven Whitaker.

In this Julia for Devs post, we will discuss improving the performance of simulation code written in Julia by eliminating sources of type-instabilities.

We wrote another post detailing what type-stability is and how type-instabilities can degrade performance. We also showed how SnoopCompile.jl and Cthulhu.jl can be used to pinpoint causes of type-instability.

This post will cover some of the type-instabilities we helped one of our clients overcome.

Our client is a technology innovator. They are building a first-of-its-kind logistics system focused on autonomous electric delivery to reduce traffic and air pollution. Their aim is to provide efficient delivery services for life-saving products to people in both urban and rural areas. Julia is helping them power critical Guidance, Navigation, and Control (GNC) systems.

With this client, we:

• Eliminated slowdown-related failures on the most important simulation scenario.
• Decreased the compilation time of the scenario by 30%.
• Improved the slowest time steps from 300 ms to 10 ms (30x speedup), enabling 2x real-time performance.

We will not share client-specific code, but will provide similar examples to illustrate root-cause issues and suggested resolutions.

Here are the root-cause issues and resolutions we will focus on:

• Help type-inference by unrolling recursion.
• Standardize the output of different branches.
• Avoid loops over Tuples.
  • Use SnoopCompile.jl to reveal dynamic dispatches.
  • Investigate functions with Cthulhu.jl.
• Avoid dictionaries that map to functions.

Let's dive in!

Help Type-Inference by Unrolling Recursion

One of the interesting problems we saw was that there was a part of the client's code that SnoopCompile.jl reported was resulting in calls to inference, but when we inspected the code with Cthulhu.jl the code looked perfectly type-stable.

This code consisted of a set of functions that recursively called each other, traversing the model tree to grab data from all the submodels.

As it turns out, recursion can pose difficulties for Julia's type-inference. Basically, if type-inference detects recursion but cannot prove it terminates (based only on the types of inputs---remember that type-inference occurs before runtime), inference gives up, resulting in code that runs like it is type-unstable. (See this Discourse post and comments and links therein for more information.)

The solution we implemented was to use a @generated function to unroll the recursion at compile time, resulting in a flat implementation that could be correctly inferred.

Here's an example that illustrates the essence of the recursive code:

# Grab all the data in the entire model tree beginning at `model`.
get_data(model::NamedTuple) = (; data = model.data, submodels = get_submodel_data(model.submodels))

# This generated function is necessary for type-stability.
# It calls `get_data` on each of the fields of `submodels`
# and returns a `NamedTuple` of the results.
# (This is not the generated function implemented in the solution.)
@generated function get_submodel_data(submodels::NamedTuple)
    assignments = map(fieldnames(submodels)) do field
        Expr(:kw, field, :(get_data(submodels.$field)))
    end
    return Expr(:tuple, Expr(:parameters, assignments...))
end

get_submodel_data(::@NamedTuple{}) = (;)

Note that in this example get_data calls get_submodel_data, which in turn calls get_data on the submodels.

Here's the code for unrolling the recursion:

function _gen_get_data(T, path)
    subT = _typeof_field(T, :submodels)
    subpath = :($path.submodels)
    return quote
        (;
            data = $path.data,
            submodels = $(_gen_get_submodel_data(subT, subpath)),
        )
    end
end

# This function determines the type of `model.field`
# given just the type of `model` (so we can't just call `typeof(model.field)`).
# This function is necessary because we need to unroll the recursion
# using a generated function, which means we have to work in the type domain
# (because the generated function is generated before runtime).
function _typeof_field(::Type{NamedTuple{names, T}}, field::Symbol) where {names, T}
    i = findfirst(n -> n === field, names)
    return T.parameters[i]
end

function _gen_get_submodel_data(::Type{@NamedTuple{}}, subpath)
    return quote
        (;)
    end
end

function _gen_get_submodel_data(subT, subpath)
    assignments = map(fieldnames(subT)) do field
        T = _typeof_field(subT, field)
        path = :($subpath.$field)
        Expr(:kw, field, _gen_get_data(T, path))
    end
    return Expr(:tuple, Expr(:parameters, assignments...))
end

@generated get_data_generated(model::NamedTuple) = _gen_get_data(model, :model)

Unfortunately, this example doesn't reproduce the issue our client had, but it does show how to use a @generated function to unroll recursion. Note that there is still recursion: _gen_get_data and _gen_get_submodel_data call each other. The key, though, is that this recursion happens before inference, which means that when get_data_generated is inferred, the recursion has already taken place, resulting in unrolled code without any recursion that might cause inference issues.

When we implemented this solution for our client, we saw the total memory utilization of their simulation decrease by ~35%. This was enough to allow them to disable garbage collection during the simulation, speeding it up to faster than real-time! And this was the first time this simulation had run faster than real-time!

Standardize Output of Different Branches

The client had different parts of their model update at different frequencies. As a result, at any particular time step only a subset of all the submodels actually needed to update. Here's an example of what this might look like:

function get_output(model, t)
    if should_update(model, t)
        out = update_model(model, t)
    else
        out = get_previous_output(model)
    end
    return out
end

Unfortunately, update_model and get_previous_output returned values of different types, resulting in type-instability: the output type of get_output depended on the runtime result of should_update.

Furthermore, this function was called at every time point on every submodel (and every sub-submodel, etc.), so the type-instability in this function affected the whole simulation.

The issue was that update_model typically returned the minimal subset of information actually needed for the specific model, whereas get_previous_output was generic and returned a wider set of information. For example, maybe update_model would return a NamedTuple like (x = [1, 2], xdot = [0, 0]), while get_previous_output would return something like (x = [1, 2], xdot = [0, 0], p = nothing, stop_sim = false).

To fix this issue, rather than manually updating the return values of all the methods of update_model for all the submodels in the system, we created a function standardize_output that took whatever NamedTuple returned by update_model and added the missing fields that get_previous_output included. Then, the only change needed in get_output was to call standardize_output:

out = update_model(model, t) |> standardize_output

The result of making this change was a 30% decrease in compilation time for their simulation!

Avoid Loops over Tuples

The client stored submodels of a parent model as a Tuple or NamedTuple. This makes sense for type-stability because each submodel was of a unique type, so storing them in this way preserved the type information when accessing the submodels. In contrast, storing the submodels as a Vector{Any} would lose the type information of the submodels.

However, type-stability problems arise when looping over Tuples of different types of objects. The problem is that the compiler needs to compile code for the body of the loop, but the body of the loop needs to be able to handle all types included in the Tuple. As a result, the compiler must resort to dynamic dispatch in the loop body (but see the note on union-splitting further below).

Here's an example of the issue:

module TupleLoop

function tupleloop(t::Tuple)

    for val in t
        do_something(val)
    end

end

do_something(val::Number) = val + 1
do_something(val::String) = val * "!"
do_something(val::Vector{T}) where {T} = isempty(val) ? zero(T) : val[1]
do_something(val::Dict{String,Int}) = get(val, "hello", 0)

end

Using SnoopCompile.jl reveals dynamic dispatches to do_something:

julia> using SnoopCompileCore

julia> tinf = @snoop_inference TupleLoop.tupleloop((1, 2.0, "hi", [10.0], Dict{String,Int}()));

julia> using SnoopCompile

julia> tinf
InferenceTimingNode: 0.019444/0.020361 on Core.Compiler.Timings.ROOT() with 4 direct children

julia> itrigs = inference_triggers(tinf); mtrigs = accumulate_by_source(Method, itrigs)
2-element Vector{SnoopCompile.TaggedTriggers{Method}}:
 eval_user_input(ast, backend::REPL.REPLBackend, mod::Module) @ REPL ~/.julia/juliaup/julia-1.11.5+0.x64.linux.gnu/share/julia/stdlib/v1.11/REPL/src/REPL.jl:247 (1 callees from 1 callers)
 tupleloop(t::Tuple) @ Main.TupleLoop /path/to/TupleLoop.jl:3 (3 callees from 1 callers)

Looking at tupleloop with Cthulhu.jl:

julia> using Cthulhu

julia> ascend(mtrigs[2].itrigs[1])
Choose a call for analysis (q to quit):
     do_something(::String)
 >     tupleloop(::Tuple{Int64, Float64, String, Vector{Float64}, Dict{String, Int64}}) at /path/to/TupleLoop.jl
tupleloop(t::Tuple) @ Main.TupleLoop /path/to/TupleLoop.jl:3
 3 function tupleloop(t::Tuple{Int64, Float64, String, Vector{Float64}, Dict{String, Int64}}::Tuple)::Core.Const(nothing)
 5
 5     for val::Any in t::Tuple{Int64, Float64, String, Vector{Float64}, Dict{String, Int64}}
 6         do_something(val::Any)
 7     end
 9
 9 end

And we see the problem! Even though the Tuple is inferred, the loop variable val is inferred as Any, which means that calling do_something(val) must be a dynamic dispatch.

Note that in some cases Julia can perform union-splitting automatically to remove the dynamic dispatch caused by this type-instability. In this example, union-splitting occurs when the Tuple contains 4 (by default) or fewer unique types. However, it's not a general solution.

One way to remove the dynamic dispatch without relying on union-splitting is to eliminate the loop:

do_something(t[1])
do_something(t[2])
⋮

But we can quickly see that writing this code is not at all generic; we have to hard-code the number of calls to do_something, which means the code will only work with Tuples of a particular length. Fortunately, there's a way around this issue. We can write a @generated function to have the compiler unroll the loop for us in a generic way:

@generated function tupleloop_generated(t::Tuple)

    body = [:(do_something(t[$i])) for i in fieldnames(t)]
    return quote
        $(body...)
        return nothing
    end

end

(Note that this code would also work if we specified t::NamedTuple in the method signature.)

Due to the way @generated functions work, SnoopCompile.jl still detects dynamic dispatches, but note that tupleloop_generated does not have any dynamic dispatches reported:

julia> using SnoopCompileCore

julia> tinf = @snoop_inference TupleLoop.tupleloop_generated((1, 2.0, "hi", [10.0], Dict{String,Int}()));

julia> using SnoopCompile

julia> tinf
InferenceTimingNode: 0.022208/0.050369 on Core.Compiler.Timings.ROOT() with 5 direct children

julia> itrigs = inference_triggers(tinf); mtrigs = accumulate_by_source(Method, itrigs)
3-element Vector{SnoopCompile.TaggedTriggers{Method}}:
 (g::Core.GeneratedFunctionStub)(world::UInt64, source::LineNumberNode, args...) @ Core boot.jl:705 (1 callees from 1 callers)
 eval_user_input(ast, backend::REPL.REPLBackend, mod::Module) @ REPL ~/.julia/juliaup/julia-1.11.5+0.x64.linux.gnu/share/julia/stdlib/v1.11/REPL/src/REPL.jl:247 (1 callees from 1 callers)
 var"#s1#1"(::Any, t) @ Main.TupleLoop none:0 (3 callees from 1 callers)

And we can verify with Cthulhu.jl that there are no more dynamic dispatches in tupleloop_generated:

julia> using Cthulhu

julia> ascend(mtrigs[2].itrigs[1])
Choose a call for analysis (q to quit):
 >   tupleloop_generated(::Tuple{Int64, Float64, String, Vector{Float64}, Dict{String, Int64}})
       eval at ./boot.jl:430 => eval_user_input(::Any, ::REPL.REPLBackend, ::Module) at /cache/build/tester-amdci5-12/julialang/julia-release-1-dot-1
tupleloop_generated(t::Tuple) @ Main.TupleLoop /path/to/TupleLoop.jl:11
Variables
  #self#::Core.Const(Main.TupleLoop.tupleloop_generated)
  t::Tuple{Int64, Float64, String, Vector{Float64}, Dict{String, Int64}}

Body::Core.Const(nothing)
    @ /path/to/TupleLoop.jl:11 within `tupleloop_generated`
   ┌ @ /path/to/TupleLoop.jl:15 within `macro expansion`
1 ─│ %1  = Main.TupleLoop.do_something::Core.Const(Main.TupleLoop.do_something)
│  │ %2  = Base.getindex(t, 1)::Int64
│  │       (%1)(%2)
│  │ %4  = Main.TupleLoop.do_something::Core.Const(Main.TupleLoop.do_something)
│  │ %5  = Base.getindex(t, 2)::Float64
│  │       (%4)(%5)
│  │ %7  = Main.TupleLoop.do_something::Core.Const(Main.TupleLoop.do_something)
│  │ %8  = Base.getindex(t, 3)::String
│  │       (%7)(%8)
│  │ %10 = Main.TupleLoop.do_something::Core.Const(Main.TupleLoop.do_something)
│  │ %11 = Base.getindex(t, 4)::Vector{Float64}
│  │       (%10)(%11)
│  │ %13 = Main.TupleLoop.do_something::Core.Const(Main.TupleLoop.do_something)
│  │ %14 = Base.getindex(t, 5)::Dict{String, Int64}
│  │       (%13)(%14)
│  │ @ /path/to/TupleLoop.jl:16 within `macro expansion`
└──│       return Main.TupleLoop.nothing
   └

Here we have to examine the so-called "Typed" code (since the source code was generated via metaprogramming), but we see that there is no loop in this code. As a result, each call to do_something is a static dispatch with a concretely inferred input. Hooray!

Avoid Dictionaries that Map to Functions

The client registered functions for updating their simulation visualization via a dictionary that mapped from a String key to the appropriate update function.

Sometimes it can be convenient to have a dictionary of functions, for example:

d = Dict{String, Function}(
    "sum" => sum,
    "norm" => norm,
    # etc.
)
x = [1.0, 2.0, 3.0]
d["sum"](x) # Compute the sum of the elements of `x`
d["norm"](x) # Compute the norm of `x`

This allows you to write generic code that can call the appropriate intermediate function based on a key supplied by the caller.

You could use multiple dispatch to achieve similar results, but it requires a bit more thought to organize the code in such a way that ensures the caller has access to the types to dispatch on.

As another alternative, you could also have the caller just pass in the function to call. But again, it takes a bit more effort to organize the code to make it work.

Unfortunately, using a dictionary in this way is type-unstable: Julia can't figure out what function will be called until runtime, when the precise dictionary key is known. And since the function is unknown, the type of the result of the function is also unknown.

One partial solution is to use type annotations:

d[func_key](x)::Float64

Then at least the output of the function can be used in a type-stable way. However, this only works if all the functions in the dictionary return values of the same type given the same input.

A slightly less stringent alternative is to explicitly convert the result to a common type, but this requires conversion to be possible.

Our client updated a dictionary using the output of the registered function, so the full solution we implemented for our client was to remove the dictionary and instead have explicit branches in the code. That is, instead of

updates[key] = d[key](updates[key])

we had

if key == "k1"
    updates[key] = f1(updates[key]::OUTPUT_TYPE_F1)
elseif key == "k2"
    updates[key] = f2(updates[key]::OUTPUT_TYPE_F2)
# Additional branches as needed
end

Note that we needed the type annotations OUTPUT_TYPE_F1 and OUTPUT_TYPE_F2 because updates had an abstractly typed value type. The key that makes this solution work is recognizing that in the first branch updates[key] is the output of f1 from the previous time step in the simulation (and similarly for the other branches). Therefore, in each branch we know what the type of updates[key] is, so we can give the compiler that type information.

Also note that the previously mentioned ideas of using multiple dispatch or just passing in the functions to use don't work in this situation without removing the updates dictionary (and refactoring the affected code).

Making the above change completely removed type-instabilities in that part of the client's code.

Summary

In this post, we explored a few problems related to type-stability that we helped our client resolve. We were able to diagnose issues using SnoopCompile.jl and Cthulhu.jl and make code improvements that enabled our client's most important simulation scenario to pass tests for the first time. This was possible because our solutions enabled the scenario to run faster than real-time and reduced compilation time by 30%.

Do you have type-instabilities that plague your Julia code? Contact us, and we can help you out!

Additional Links

• SnoopCompile.jl Docs
  • Documentation for SnoopCompile.jl.
• Cthulhu.jl Docs
  • Documentation (the package's README) for Cthulhu.jl.
• Julia Performance Tips
  • Very good tips for improving the performance of Julia code.
• GLCS Software Development
  • Connect with us for Julia development help.
• Upcoming JuliaCon Talk Announcement
  • Check out our JuliaCon 2025 talk announcement!

The cover image background of a person at the start of a race was found at freepik.com.

The cartoon about looping over Tuples was generated with AI.

This post was written by Steven Whitaker.

The Julia programming language is a high-level language that boasts the ability to achieve C-like speeds. Julia can run fast, despite being a dynamic language, because it is compiled and has smart type-inference.

Type-inference is the process of the Julia compiler reasoning about the types of objects, enabling compilation to create efficient machine code for the types at hand.

However, Julia code can be written in a way that prevents type-inference from succeeding---specifically, by writing type-unstable functions. (I'll explain type-instability later on.) When type-inference fails, Julia has to compile generic machine code that can handle any type of input, sacrificing the C-like performance and instead running more like an interpreted language such as Python.

Fortunately, there are tools that Julia developers can use to track down what code causes type-inference to fail. Among the most powerful of these tools are SnoopCompile.jl and Cthulhu.jl. Using these tools, developers can fix type-inference failures and restore the C-like performance they were hoping to achieve.

In this post, we will learn about type-stability and how it impacts performance. Then we will see how to use SnoopCompile.jl and Cthulhu.jl to locate and resolve type-instabilities.

Type-Stability

A function is type-stable if the type of the function's output can be concretely determined given the types of the inputs to the function, without any runtime information.

To illustrate, consider the following function methods:

f(x::Int) = "stable"
f(x::Float64) = rand(Bool) ? 1 : 2.0

In this example, if we call f(x) where x is an Int, the compiler can figure out that the output will be a String without knowing the value of x, so f(x::Int) is type-stable. In other words, it doesn't matter whether x is 1, -1, or 176859431; the return value will always be a String if x is an Int.

On the other hand, if we call f(x) where x is a Float64, the compiler doesn't know whether the output will be an Int or a Float64 because that depends on the result of rand(Bool), which is computed at runtime. Therefore, f(x::Float64) is type-unstable.

Here's a more subtle example of type-instability:

function g(x)
    if x < 0
        return 0
    else
        return x
    end
end

In this example, g(x) is type-unstable because the output will either be an Int or whatever the type of x is, and it all depends on the value of x, which isn't known at compile time. (Note, however, that g(x) is type-stable if x is an Int because then both branches of the if statement return the same type of value.)

And sometimes a function that might look type-stable can be type-unstable depending on the input. For example:

h(x::Array) = x[1] + 1

In this case, h([1]) is type-stable, but h(Any[1]) is not. Why? Because with h([1]), x is a Vector{Int}, so the compiler knows that the type of x[1] will be Int. On the other hand, with h(Any[1]), x is a Vector{Any}, so the compiler thinks x[1] could be of any type.

To reiterate: a function is type-stable if the compiler can figure out the concrete type of the return value given only the types of the inputs, without any runtime information.

When Compilation Occurs

Another aspect of type-inference that is useful to understand is when compilation (including type-inference) occurs.

In a static language like C, an entire program is compiled before any code runs. This is possible because the types of all variables are known in advance, so machine code specific to those types can be generated in advance.

In an interpreted language like Python, no code is ever compiled because variables are dynamic, meaning their types aren't really ever known until variables are actually used (i.e., during runtime).

Julia programs can lie pretty much anywhere between the extremes of C and Python, and where on that spectrum a program lies depends on type-stability.

In a just-in-time (JIT) compiled language like Julia, compilation occurs once types are known.

• If a Julia program is completely type-stable, type-inference can figure out the types of all variables in the program before running any code. As a result, the entire program can be compiled as if it were written in a static language. This is what allows Julia to achieve C-like speeds.
• If a Julia program is entirely type-unstable, every function has to be compiled individually. In this case, compilation occurs at the moment the function is called because that's when the runtime information of all the input types is finally known. Furthermore, the machine code for a type-unstable function cannot be efficient because it must be able to handle a wide range of potential types. As a result, despite being compiled, the code runs essentially like an interpreted language.

Running a Julia program with type-instabilities is like driving down the street and hitting all the red lights. Julia will compile all the code for which type-inference succeeds and then start running. But when the program reaches a function call that could not be inferred, that's like a car stopping at a red light; Julia stops running the code to compile the function call now that it knows the runtime types of the inputs. After the function is compiled, the program can continue execution, like how the car can continue driving once the light turns green.

Type-Stability and Performance

As this analogy implies, and as I've stated before, type-stability has performance implications. Type-instabilities can cause various performance degradations, including:

• Dynamic (aka runtime) dispatch. If the compiler knows the input types to a function, the generated machine code can include a call to the specific method determined by those types. But if the compiler doesn't know those types, the machine code has to include instructions to perform dynamic dispatch. As a result, rather than jumping directly to the correct method, Julia has to spend runtime CPU cycles to look up the correct method to call.
• Increased memory allocations. If the compiler doesn't know what type a variable will have, it's impossible to put it in a register or even allocate stack space for it. As a result, it has to be heap-allocated and managed by the garbage collector.
• Suboptimal compiled code. Imagine summing the contents of an array in a loop. If the compiler knows the array contains just Float64s, it can perform optimizations to compute the sum as efficiently as possible, e.g., by using specialized CPU instructions. Such optimizations cannot occur if the compiler doesn't know what type of data it's working with.

Here's an example (inspired by this Stack Overflow answer) that illustrates the impact type-stability can have on performance:

# Type-unstable because `x` is a non-constant global variable.
x = 0
f() = [i + x for i = 1:10^6]

# Type-stable because `y` is constant and therefore always an `Int`.
const y = 0
g() = [i + y for i = 1:10^6]

using BenchmarkTools
@btime f() #  16.868 ms (1998983 allocations: 38.13 MiB)
@btime g() # 190.755 μs (3 allocations: 7.63 MiB)

Note that the type-unstable version is two orders of magnitude slower! Also note, however, that this is an extreme example where essentially the entire computation is type-unstable. In practice, some type-instabilities will not impact performance very much. Type-stability mainly matters in "hot loops", i.e., in parts of the code that run very frequently and contribute to a significant portion of the program's overall run time.

Detecting Type-Instabilities with SnoopCompile.jl

Now the question is, how do we know if or where our code is type-unstable? One excellent tool for discovering where type-instabilities occur in code is SnoopCompile.jl. This package provides functionality for reporting how many times a Julia program needs to stop to compile code. (Remember that a perfectly type-stable program can compile everything in one go, so every time execution stops for compilation indicates a type-instability was encountered.)

Let's use an example to illustrate how to use SnoopCompile.jl. First, the code we want to analyze:

module Original

struct Alg1 end
struct Alg2 end

function process(alg::String)

    if alg == "alg1"
        a = Alg1()
    elseif alg == "alg2"
        a = Alg2()
    end

    data = get_data(a)

    result = _process(a, data)

    return result

end

get_data(::Alg1) = (1, 1.0, 0x00, 1.0f0, "hi", [0.0], (1, 2.0))

function _process(::Alg1, data)

    val = data[1]
    if val < 0
        val = -val
    end

    result = map(data) do d
        process_item(d, val)
    end

    return result

end

process_item(d::Int, val) = d + val
process_item(d::AbstractFloat, val) = d * val
process_item(d::Unsigned, val) = d - val
process_item(d::String, val) = d * string(val)
process_item(d::Array, val) = d .+ val
process_item(d::Tuple, val) = d .- val

get_data(::Alg2) = rand(5)
_process(::Alg2, data) = error("not implemented")

end

We'll use the @snoop_inference macro to analyze this code. Note that this macro should be used in a fresh Julia session (after loading the code to be analyzed, but before running anything) to get the most accurate analysis results.

julia> using SnoopCompileCore

julia> tinf = @snoop_inference Original.process("alg1");

julia> using SnoopCompile

julia> tinf
InferenceTimingNode: 0.144601/0.247183 on Core.Compiler.Timings.ROOT() with 8 direct children

You can consult the SnoopCompile.jl docs for more information about what we just did, but for now, notice that displaying tinf revealed 8 direct children. That means compilation occurred 8 times while running Original.process("alg1"). If this function were completely type-stable, @snoop_inference would have reported just 1 direct child, so we know there are type-instabilities somewhere.

Each of the 8 direct children is an inference trigger, i.e., calling the specific method indicated in the inference trigger caused compilation to occur. We can collect the inference triggers:

julia> itrigs = inference_triggers(tinf)
 Inference triggered to call process(::String) from eval (./boot.jl:430) inlined into REPL.eval_user_input(::Any, ::REPL.REPLBackend, ::Module) (/cache/build/tester-amdci5-12/julialang/julia-release-1-dot-11/usr/share/julia/stdlib/v1.11/REPL/src/REPL.jl:261)
 Inference triggered to call process_item(::Int64, ::Int64) from #1 (./REPL[1]:30) with specialization (::var"#1#2")(::Int64)
 Inference triggered to call process_item(::Float64, ::Int64) from #1 (./REPL[1]:30) with specialization (::var"#1#2")(::Float64)
 Inference triggered to call process_item(::UInt8, ::Int64) from #1 (./REPL[1]:30) with specialization (::var"#1#2")(::UInt8)
 Inference triggered to call process_item(::Float32, ::Int64) from #1 (./REPL[1]:30) with specialization (::var"#1#2")(::Float32)
 Inference triggered to call process_item(::String, ::Int64) from #1 (./REPL[1]:30) with specialization (::var"#1#2")(::String)
 Inference triggered to call process_item(::Vector{Float64}, ::Int64) from #1 (./REPL[1]:30) with specialization (::var"#1#2")(::Vector{Float64})
 Inference triggered to call process_item(::Tuple{Int64, Float64}, ::Int64) from #1 (./REPL[1]:30) with specialization (::var"#1#2")(::Tuple{Int64, Float64})

The first inference trigger corresponds to compiling the top-level process function we called (this is the inference trigger we always expect to see). But then it looks like Julia had to stop running to compile several different methods of process_item.

Inference triggers tell us that type-instabilities existed when calling the given functions, but what we really want to know is where these type-instabilities originated. You'll note that each displayed inference trigger above also indicates the calling function by specifying from <calling function>. (Note that the from #1 in the above example indicates process_item was called from an anonymous function.)

We can use accumulate_by_source to get an aggregated view of what functions made calls via dynamic dispatch:

julia> mtrigs = accumulate_by_source(Method, itrigs)
2-element Vector{SnoopCompile.TaggedTriggers{Method}}:
 eval_user_input(ast, backend::REPL.REPLBackend, mod::Module) @ REPL ~/.julia/juliaup/julia-1.11.5+0.x64.linux.gnu/share/julia/stdlib/v1.11/REPL/src/REPL.jl:247 (1 callees from 1 callers)
 (::var"#1#2")(d) @ Main REPL[1]:30 (7 callees from 7 callers)

From this, we can see that the example code really has only one problematic function: the anonymous function var"#1#2".

Diving in with Cthulhu.jl

Now that we have a rough idea of where the type-instabilities come from, we can drill down into the code and pinpoint the precise causes with Cthulhu.jl. We can use the ascend function on an inference trigger to start investigating:

julia> using Cthulhu

julia> ascend(itrigs[2]) # Skip `itrigs[1]` because that's the top-level compilation that should always occur.

ascend provides a menu that shows process_item and the anonymous function. Select the anonymous function and press Enter. Here's a screenshot of the Cthulhu output:

Reading the output of Cthulhu.jl takes some time to get used to (especially when it can't display source code, as in this example), but the main thing to remember is that red is bad. See the Cthulhu.jl README for more information.

In this example, the source of the type-instability was fairly easy to pinpoint. I annotated the screenshot to indicate from where the type-instability arose, which is this Core.Box thing. These are always bad; they are essentially containers that can hold values of any type, hence the type-instability that arises when accessing the contents. In this particular case, Core.getfield(#self#, :val) indicates val is a variable that was captured by the anonymous function.

Once we determine what caused the type-instability, the solution varies on a case-by-case basis. Some potential solutions may include:

• Ensure different branches of an if statement return data of the same type.
• Add a type annotation to help out inference. For example,

  x = Any[1]
  y = do_something(x[1]::Int)
  

• Make sure a container type has a concrete element type. For example, x = Int[], not x = [].
• Avoid loops over heterogeneous Tuples.
• Use let blocks to define closures. (See this section of the Julia manual for more details.)

We'll use this last solution in our example. The anonymous function in question is defined by the do block in _process. So, let's fix the issue of the captured variable val:

module Corrected

# All other code is the same as in module `Original`.

function _process(::Alg1, data)

    val = data[1]
    if val < 0
        val = -val
    end

    f = let val = val
        d -> process_item(d, val)
    end

    result = map(f, data)

    return result

end

# All other code is the same as in module `Original`.

end

Now let's see what @snoop_inference says:

julia> using SnoopCompileCore

julia> tinf = @snoop_inference Corrected.process("alg1");

julia> using SnoopCompile

julia> tinf
InferenceTimingNode: 0.113669/0.183888 on Core.Compiler.Timings.ROOT() with 1 direct children

There's just one direct child. Hooray, type-stability!

Let's see how performance compares:

julia> using BenchmarkTools

julia> @btime Original.process("alg1");
  220.506 ns (16 allocations: 496 bytes)

julia> @btime Corrected.process("alg1");
  51.104 ns (8 allocations: 288 bytes)

Awesome, the improved code is ~4 times faster!

Summary

In this post, we learned about type-stability and how type-instabilities affect compilation and runtime performance. We also walked through an example that demonstrated how to use SnoopCompile.jl and Cthulhu.jl to pinpoint the sources of type-instability in a program. Even though the example in this post was a relatively easy fix, the principles discussed apply to more complicated programs as well. And, of course, check out the documentation for SnoopCompile.jl and Cthulhu.jl for further examples to bolster your understanding.

Do you have type-instabilities that plague your Julia code? Contact us, and we can help you out!

Additional Links

• SnoopCompile.jl Docs
  • Documentation for SnoopCompile.jl.
• Cthulhu.jl Docs
  • Documentation (the package's README) for Cthulhu.jl.
• Julia Performance Tips
  • Very good tips for improving the performance of Julia code.
• GLCS Software Development
  • Connect with us for Julia development help.
• Upcoming JuliaCon Talk Announcement
  • Check out our JuliaCon 2025 talk announcement!

This post was written by Steven Whitaker.

This post is a teaser for my JuliaCon 2025 talk. If you want to see the talk itself, check out this other blog post!

Have you ever wished you could start using the Julia programming language to develop custom models? Does the idea of replacing outdated MATLAB^® code and models seem overwhelming?

Or maybe you don't plan to replace all MATLAB code, but wouldn't it be exciting to integrate Julia code into existing workflows?

Also, technicalities aside, how do you convince your colleagues to make the leap into the Julia ecosystem?

I'm excited to share an announcement! At this year's JuliaCon, I will be speaking about a small but significant step you can take to start adding Julia to your MATLAB codebase.

Great news! You can transition to Julia smoothly without completely abandoning MATLAB. There's a straightforward method to embrace the best of both worlds, so you won't need to rewrite your legacy models from scratch.

I'll give my full talk in July, but if you don't want to wait, keep reading for a sneak peek!

Background

The GLCS.io team has been developing Julia-based solutions since 2015. Over the past 4 years, we've had the pleasure of redesigning and enhancing Julia models for our clients in the finance, science, and engineering sectors. Its incredible speed and versatility have transformed how we tackle complex computations together. However, we also fully acknowledge the reality: MATLAB continues to hold a significant place in countless companies and research labs worldwide.

For decades, MATLAB has been the benchmark for data analysis, modeling, and simulation across scientific and engineering fields. There are likely hundreds of thousands of MATLAB licenses in use, with millions of users supporting an unimaginable number of models and codebases.

Even for a single company, fully transitioning to Julia often feels insurmountable. The vast amount of existing MATLAB code presents a significant challenge for any team considering adopting Julia.

Yet, unlocking Julia's power is vital for companies aiming to excel in today's competitive landscape. The question isn't if companies should adopt Julia---it's how to do it.

Companies should blend Julia with their MATLAB environments, ensuring minimal disruption and optimal resource use. This strategic integration delivers meaningful gains in accuracy, performance, and scalability to transform operations and drive success.

JuliaCon Preview

At JuliaCon, I'm excited to share how you can seamlessly integrate Julia into existing MATLAB workflows---a process that has delivered up to 100x performance improvements while enhancing code quality and functionality. Through a real-world model, I'll highlight design patterns, benchmark comparisons, and valuable business case insights to demonstrate the transformative potential of integrating Julia.

(Spoiler alert: the performance improvement is more than 100x for the example I will show at JuliaCon.)

What We Offer

Unlock high-performance modeling! Our dedicated team is here to integrate Julia into your MATLAB workflows. Experience a strategic, step-by-step process tailored for seamless Julia-MATLAB integration, focused on efficiency and delivering measurable results:

1. Tailored Assessment: Pinpoint challenges and opportunities for Julia to address.
2. MATLAB Benchmarking: Establish a performance baseline to measure progress and impact.
3. Julia Model Development: Convert MATLAB models to Julia or assist your team in doing so.
4. Julia Integration: Combine Julia's capabilities with your existing MATLAB workflows for optimal results.
5. Roadmap Alignment: Validate performance improvements, create a strong business case for leadership, and agree on future support and innovation.

Check out our website for more details.

Summary

By attending my JuliaCon talk, you will learn how to seamlessly integrate Julia into your existing MATLAB codebase. And by leveraging our support at GLCS, you can adopt Julia without disruption---unlocking faster computations, improved models, and better scalability while retaining the strengths of your MATLAB codebase.

Are you or someone you know excited about harnessing the power of Julia and MATLAB together? Let's connect! Schedule a consultation today to discover incredible performance gains of 100x or more.

Additional Links

• JuliaCon 2025 Talk
  • Check out the actual JuliaCon talk! Find links to the recording, talk submission, and presentation slides.
• Julia and MATLAB^® Integration at GLCS
  • Our web page detailing our Julia and MATLAB^® integration service.

MATLAB is a registered trademark of The MathWorks, Inc.

Cover image: The JuliaCon 2025 logo was obtained from https://juliacon.org/2025/.

This post was written by Steven Whitaker.

The Julia programming language is a high-level language that is known, at least in part, for its excellent package manager and outstanding composability. (See another blog post that illustrates this composability.)

Julia makes it super easy for anybody to create their own package. Julia's package manager enables easy development and testing of packages. The ease of package development encourages developers to split reusable chunks of code into individual packages, further enhancing Julia's composability.

In our previous post, we discussed how to create and register your own package. However, to encourage people to actually use your package, it helps to have an assurance that the package works. This is why testing is important. (Plus, you also want to know your package works, right?)

In this post, we will learn about some of the tools Julia provides for testing packages. We will also learn how to use GitHub Actions to run package tests against commits and/or pull requests to check whether code changes break package functionality.

This post assumes you are comfortable navigating the Julia REPL. If you need a refresher, check out our post on the Julia REPL.

Example Package

We will use a custom package called Averages.jl to illustrate how to implement testing in Julia.

The Project.toml looks like:

name = "Averages"
uuid = "1fc6e63b-fe0f-463a-8652-42f2a29b8cc6"
version = "0.1.0"

[deps]
Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"

[extras]
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

[targets]
test = ["Test"]

Note that this Project.toml has two more sections besides [deps]:

• [extras] is used to indicate additional packages that are not direct dependencies of the package. In this example, Test is not used in Averages.jl itself; Test is used only when running tests.
• [targets] is used to specify what packages are used where. In this example, test = ["Test"] indicates that the Test package should be used when testing Averages.jl.

The actual package code in src/Averages.jl looks like:

module Averages

using Statistics

export compute_average

compute_average(x) = (check_real(x); mean(x))

function compute_average(a, b...)

    check_real(a)

    N = length(a)
    for (i, x) in enumerate(b)
        check_real(x)
        check_length(i + 1, x, N)
    end

    T = float(promote_type(eltype(a), eltype.(b)...))
    average = Vector{T}(undef, N)
    average .= a
    for x in b
        average .+= x
    end
    average ./= length(b) + 1

    return a isa Real ? average[1] : average

end

function check_real(x)

    T = eltype(x)
    T <: Real || throw(ArgumentError("only real numbers are supported; unsupported type $T"))

end

function check_length(i, x, expected)

    N = length(x)
    N == expected || throw(DimensionMismatch("the length of input $i does not match the length of the first input: $N != $expected"))

end

end

Adding Tests

Tests for a package live in test/runtests.jl. (The file name is important!) Inside this file there are two main testing utilities that are used: @testset and @test. Additionally, @test_throws can also be useful for testing. The Test standard library package provides all of these macros.

• @testset is used to organize tests into cohesive blocks.
• @test is used to actually test package functionality.
• @test_throws is used to ensure the package throws the errors it should.

Here is how test/runtests.jl might look for Averages.jl:

using Averages
using Test

@testset "Averages.jl" begin

    a = [1, 2, 3]
    b = [4.0, 5.0, 6.0]
    c = (BigInt(7), 8f0, Int32(9))
    d = 10
    e = 11.0
    bad = ["hi", "hello", "hey"]

    @testset "`compute_average(x)`" begin

        @test compute_average(a) == 2
        @test compute_average(a) isa Float64
        @test compute_average(c) == 8
        @test compute_average(c) isa BigFloat
        @test compute_average(d) == 10

    end

    @testset "`compute_average(a, b...)`" begin

        @test compute_average(a, a) == a
        @test compute_average(a, b) == [2.5, 3.5, 4.5]
        @test compute_average(a, b, c) == b
        @test compute_average(a, b, c) isa Vector{Float64}
        @test compute_average(b, b, b) == b
        @test compute_average(d, e) == 10.5

    end

    @testset "Error Handling" begin

        @test_throws ArgumentError compute_average(im)
        @test_throws ArgumentError compute_average(a, bad)
        @test_throws ArgumentError compute_average(bad, c)
        @test_throws DimensionMismatch compute_average(a, b[1:2])
        @test_throws DimensionMismatch compute_average(a[1:2], b)

    end

end

Now let's look more closely at the macros used:

• @testset can be given a label to help organize the reporting Julia does at the end of testing. Besides that, @testset wraps around a set of tests (including other @testsets).
• @test is given an expression that evaluates to a boolean. If the boolean is true, the test passes; otherwise it fails.
• @test_throws takes two inputs: an error type and then an expression. The test passes if the expression throws an error of the given type.

Testing Against Other Packages

In some cases, you might want to ensure your package is compatible with a type defined in another package. For our example, let's test against StaticArrays.jl. Our package does not depend on StaticArrays.jl, so we need to add it as a test-only dependency by editing the [extras] and [targets] sections in the Project.toml:

[extras]
StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

[targets]
test = ["StaticArrays", "Test"]

(Note that I grabbed the UUID for StaticArrays.jl from its Project.toml on GitHub.)

Then we can add some tests to make sure compute_average is generic enough to work with StaticArrays:

using Averages
using Test
using StaticArrays

@testset "Averages.jl" begin

    ⋮

    @testset "StaticArrays.jl" begin

        s = SA[12, 13, 14]

        @test compute_average(s) == 13
        @test compute_average(s, s) == [12, 13, 14]
        @test compute_average(a, b, s) == [17/3, 20/3, 23/3]
        @test compute_average(s, a, c) == [20/3, 23/3, 26/3]

    end

end

Running Tests Locally

Now Averages.jl is ready for testing. To run package tests on your own computer, start Julia, activate the package environment, and then run test from the package prompt:

(@v1.X) pkg> activate /path/to/Averages

(Averages) pkg> test

The first thing test does is set up a temporary package environment for testing that includes the packages defined in the test target in the Project.toml. Then it runs the tests and displays the result:

     Testing Running tests...
Test Summary: | Pass  Total  Time
Averages.jl   |   20     20  0.7s
     Testing Averages tests passed

If a test fails, the result looks like this:

     Testing Running tests...
`compute_average(a, b...)`: Test Failed at /path/to/Averages/test/runtests.jl:27
  Expression: compute_average(a, b) == [2.0, 3.5, 4.5]
   Evaluated: [2.5, 3.5, 4.5] == [2.0, 3.5, 4.5]

Stacktrace:
 [1] macro expansion
   @ /path/to/julia-1.X.Y/share/julia/stdlib/v1.X/Test/src/Test.jl:672 [inlined]
 [2] macro expansion
   @ /path/to/Averages/test/runtests.jl:27 [inlined]
 [3] macro expansion
   @ /path/to/julia-1.X.Y/share/julia/stdlib/v1.X/Test/src/Test.jl:1577 [inlined]
 [4] macro expansion
   @ /path/to/Averages/test/runtests.jl:26 [inlined]
 [5] macro expansion
   @ /path/to/julia-1.X.Y/share/julia/stdlib/v1.X/Test/src/Test.jl:1577 [inlined]
 [6] top-level scope
   @ /path/to/Averages/test/runtests.jl:7
Test Summary:                | Pass  Fail  Total  Time
Averages.jl                  |   19     1     20  0.9s
  `compute_average(x)`       |    5            5  0.1s
  `compute_average(a, b...)` |    5     1      6  0.6s
  Error Handling             |    5            5  0.0s
  StaticArrays.jl            |    4            4  0.2s
ERROR: LoadError: Some tests did not pass: 19 passed, 1 failed, 0 errored, 0 broken.
in expression starting at /path/to/Averages/test/runtests.jl:5
ERROR: Package Averages errored during testing

Some things to note:

• When all tests in a test set pass, the test summary does not report the individual results of nested test sets. When a test fails, results of nested test sets are reported individually to report more precisely where the failure occurred.
• When a test fails, the file and line number of the failing test are reported, along with the expression that failed. This information is displayed for all failures that occur.
• The test summary reports how many tests passed and how many failed in each test set, in addition to how long each test set took.
• Tests in a test set continue to run after a test fails. To have a test set stop on failure, use the failfast option:

  @testset failfast = true "Averages.jl" begin
  

  (This option is available only in Julia 1.9 and later.)

Now, when developing Averages.jl, we can run the tests locally to ensure we don't break any functionality!

Running Tests with GitHub Actions

Besides running tests locally, one can use GitHub Actions to run tests on one of GitHub's servers. One advantage is that it enables automated testing on various machines/operating systems and across various Julia versions. Automating tests in this way is an essential part of continuous integration (CI) (so much so that the phrase "running CI" is equivalent to "running tests via GitHub Actions", even though CI technically involves more than just testing).

To enable testing via GitHub Actions, we just need to add an appropriate .yml file in the .github/workflows directory of our package. As mentioned in our previous post, PkgTemplates.jl can automatically generate the necessary .yml file. This is the default CI workflow generated by PkgTemplates.jl:

name: CI
on:
  push:
    branches:
      - main
    tags: ['*']
  pull_request:
  workflow_dispatch:
concurrency:
  # Skip intermediate builds: always.
  # Cancel intermediate builds: only if it is a pull request build.
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
jobs:
  test:
    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
    runs-on: ${{ matrix.os }}
    timeout-minutes: 60
    permissions: # needed to allow julia-actions/cache to proactively delete old caches that it has created
      actions: write
      contents: read
    strategy:
      fail-fast: false
      matrix:
        version:
          - '1.10'
          - '1.6'
          - 'pre'
        os:
          - ubuntu-latest
        arch:
          - x64
    steps:
      - uses: actions/checkout@v4
      - uses: julia-actions/setup-julia@v2
        with:
          version: ${{ matrix.version }}
          arch: ${{ matrix.arch }}
      - uses: julia-actions/cache@v2
      - uses: julia-actions/julia-buildpkg@v1
      - uses: julia-actions/julia-runtest@v1

For most users, the most relevant fields to customize are version and os (under jobs: test: strategy: matrix). Under os, specify the operating systems to run tests on (e.g., ubuntu-latest, windows-latest, macOS-latest). Under version, specify the versions of Julia to use when testing:

• '1.X' means run on Julia 1.X.Y, where Y is the largest patch of Julia 1.X that has been released. For example, '1.9' means run on Julia 1.9.4.
• '1' means run on the latest stable version of Julia.
• 'pre' means run on the latest pre-release version of Julia.
• 'lts' means run on Julia's long-term support (LTS) version.

Usually, it makes sense just to test '1' and 'pre' to ensure compatibility with the current and upcoming Julia versions.

One can also fine-tune the version and os fields, as well as other fields, when generating a package with PkgTemplates.jl. For example, to generate the .yml file to run tests only on Windows with Julia 1.8 and the latest pre-release version of Julia:

using PkgTemplates
gha = GitHubActions(; linux = false, windows = true, extra_versions = ["1.8", "pre"])
t = Template(; dir = ".", plugins = [gha])
t("MyPackage")

Note that the .yml file generated will also include testing on Julia 1.6. The Template constructor has a keyword argument julia that sets the minimum version of Julia you want your package to support, and this version is included in testing. As of this writing, by default the minimum version is Julia 1.6.

See the PkgTemplates.jl docs about Template and GitHubActions for more details on customizing the .yml file. See also the GitHub Actions docs, and in particular the workflow syntax docs, for more details on what makes up the .yml file. (Be warned, these docs are quite lengthy and probably aren't practically useful for most people to get a CI workflow up and running. For a more approachable overview of the .yml file, consider looking at this tutorial for building and testing Python.)

Once we push .github/workflows/CI.yml to GitHub, whenever branch main is pushed to, or a pull request (PR) is opened or pushed to, our package's tests will run. This is the essence of CI: continuously making sure changes we make to our code integrate well with the code base (i.e., don't break anything). By running tests against PRs, we can be sure changes made don't break existing functionality.

One neat thing about GitHub Actions is that GitHub provides a status badge/icon that you can display in your package's README. This badge lets people know

1. that your package is regularly tested, and
2. whether the current state of your package passes those tests.

In other words, this badge is a good way to boost confidence that your package is suitable for use. You can add this badge to your package's README by adding something like the following markdown:

[![CI](https://github.com/username/Averages.jl/actions/workflows/CI.yml/badge.svg)](https://github.com/username/Averages.jl/actions/workflows/CI.yml)

And it will display as follows:

Summary

In this post, we learned how to add tests to our own Julia package. We also learned how to enable CI with GitHub Actions to run our tests against code changes to ensure our package remains in working order.

How difficult was it for you to set up CI for the first time? Do you have any tips for beginners? Let us know in the comments below!

Now that you have testing down, learn how to conditionally extend package functionality in another post about package extensions!

Additional Links

• Julia Testing Docs
  • Official Julia documentation on testing.
• PkgTemplates.jl Docs
  • Documentation for PkgTemplates.jl, including potential customizations to the generated CI workflow.

This post was written by Steven Whitaker.

The Julia programming language is a high-level language that is known, at least in part, for its excellent package manager and outstanding composability. (See another blog post that illustrates this composability.)

Julia makes it super easy for anybody to create their own package. Julia's package manager enables easy development and testing of packages. The ease of package development encourages developers to split reusable chunks of code into individual packages, further enhancing Julia's composability.

In this post, we will learn what comprises a Julia package. We will also discuss tools that automate the creation of packages. Finally, we will talk about the basics of package development and walk through how to publish (register) a package for others to use.

This post assumes you are comfortable navigating the Julia REPL. If you need a refresher, check out our post on the Julia REPL.

Components of a Package

Packages are easy enough to use: just install them with add PkgName in the package prompt and then run using PkgName in the julia prompt. But what actually goes into a package?

Packages must follow a specific directory structure and include certain information to be recognized as a package by Julia.

Suppose we are creating a package called PracticePackage.jl. First, we create a directory called PracticePackage. This directory is the package root. Within the root directory we need a file called Project.toml and another directory called src.

The Project.toml requires the following information:

name = "PracticePackage"
uuid = "11111111-2222-3333-aaaa-bbbbbbbbbbbb"
authors = ["Your Name <youremail@email.com>"]
version = "0.1.0"

• uuid stands for universally unique identifier, and can be generated in Julia with using UUIDs; uuid4(). The purpose of a UUID is to allow different packages of the same name to coexist.
• version should be set to whatever version is appropriate for your package, typically "0.1.0" or "1.0.0" for an initial release. The versioning of Julia packages follows SemVer.
• The Project.toml will also include information about package dependencies, but more on that later.

The src directory requires one Julia file named PracticePackage.jl that defines a module named PracticePackage:

module PracticePackage

# Package code goes here.

end

So, the directory structure of the package looks like the following:

PracticePackage
├── Project.toml
└── src
    └── PracticePackage.jl

And that's all there is to a package! (Well, at least minimally.)

Some Technicalities

Feel free to skip this section, but if you are curious about some technicalities for what comprises a valid package, read on.

• The Project.toml only needs the name and uuid fields for Julia to recognize the package. Without the version field, Julia treats the version as v0.0.0.
  • However, the version and authors fields are needed to register the package.
• The name of the package root directory doesn't matter, meaning it doesn't have to match the package name. However, the name field in Project.toml does have to match the name of the module defined in src/PracticePackage.jl, and the file name of src/PracticePackage.jl also has to match.
  • For example, we could change the name of the package by setting name = "Oops" in Project.toml, renaming src/PracticePackage.jl to src/Oops.jl, and defining module Oops in that file. We would not have to rename the package root directory from PracticePackage to Oops (though that would be a good idea to avoid confusion).

Automatically Generating Packages

The basic structure of a package is pretty simple, so there ought to be a way to automate it, right? (I mean, who wants to manually generate a UUID?) Good news: package creation can be automated!

Package generate Command

Julia comes with a generate package command built-in. First, change directories to where the package root directory should live, then run generate in the Julia package prompt:

pkg> generate PracticePackage

This command creates the package root directory PracticePackage and the Project.toml and src/PracticePackage.jl files. Some notes:

• The Project.toml is pre-filled with the correct fields and values, including an automatically generated UUID. When I ran generate on my computer, it also pre-filled the authors field with my name and email from my ~/.gitconfig file.
• src/PracticePackage.jl is pre-filled with a definition for the module PracticePackage. It also defines a function greet in the module, but typically you will replace that with your own code.

PkgTemplates.jl

The generate command works fine, but it's barebones. For example, if you are planning on hosting your package on GitHub, you might want to include a GitHub Action for continuous integration (CI), so it would be nice to automate the creation of the appropriate .yml file. This is where PkgTemplates.jl comes in.

PkgTemplates.jl is a normal Julia package, so install it as usual and run using PkgTemplates. Then we can create our PracticePackage.jl:

t = Template(; dir = ".")
t("PracticePackage")

Running this code creates the package with the following directory structure:

PracticePackage
├── .git
│   ⋮
├── .github
│   ├── dependabot.yml
│   └── workflows
│       ├── CI.yml
│       ├── CompatHelper.yml
│       └── TagBot.yml
├── .gitignore
├── LICENSE
├── Manifest.toml
├── Project.toml
├── README.md
├── src
│   └── PracticePackage.jl
└── test
    └── runtests.jl

As you can see, PkgTemplates.jl automatically generates a lot of files that aid in following package development best practices, like adding CI and tests.

Note that many options can be supplied to Template to customize what files are generated. See the PkgTemplates.jl docs for all the options.

Basic Package Development

Once your package is set up, the next step is to actually add code. Add the functions, types, constants, etc. that your package needs directly in the PracticePackage module in src/PracticePackage.jl, or add additional files in the src directory and include them in the module. (See a previous blog post for more information about modules, though note that using modules directly works slightly differently than using packages.)

To add dependencies for your package to use, you will need to activate your project's package environment and then add packages. For example, if you want your package to use the DataFrames.jl package, start Julia and navigate to your package root directory. Then, activate the package environment and add the package:

(@v1.X) pkg> activate .

(PracticePackage) pkg> add DataFrames

After this, you will be able to include using DataFrames in your package code to enable the functionality provided by DataFrames.jl.

Adding packages after activating the package environment edits the package's Project.toml file. It adds a [deps] section that lists the added packages and their UUIDs. In the example above, adding DataFrames.jl adds the following lines to the Project.toml file:

[deps]
DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"

(And (PracticePackage) pkg> rm DataFrames would remove the DataFrames = ... line, so it is best not to edit the [deps] section manually.)

Finally, to try out your package, activate your package environment (as above) and then load your package as usual:

julia> using PracticePackage # No need to `add PracticePackage` first.

Note that by default Julia will have to be restarted to reload any changes you make to your package code. If you want to avoid restarting Julia whenever you make changes, check out Revise.jl.

Publishing/Registering a Package

Once your package is in working order, it is natural to want to publish the package for others to use.

A package can be published by registering it in a package registry, which basically is a map that tells the Julia package manager where to find a package so it can be downloaded.

The General registry is the largest registry as well as the default registry used by Julia; most, if not all, of the most popular open-source packages (DataFrames.jl, Plots.jl, StaticArrays.jl, ModelingToolkit.jl, etc.) exist in General. Once a package is registered in General, it can be installed with pkg> add PracticePackage.

(Note that if registering a package is not desired for some reason, a package can be added via URL, e.g., pkg> add https://github.com/username/PracticePackage.jl, assuming the package is in a public git repository. However, the package manager has limited ability to manage packages added in this way; in particular, managing package versions must be done manually.)

The most common way to register a package in General is to use Registrator.jl as a GitHub App. See the README for detailed instructions, but the process basically boils down to:

1. Write/test package code.
2. Update the version field in the Project.toml (e.g., to "0.1.0" or "1.0.0" for the first registered version).
3. Add a comment with @JuliaRegistrator register to the latest commit that should be included in the registered version of the package.

Note that there are additional steps for preparing a package for publishing that we did not discuss in this post (such as specifying compatible versions of Julia and package dependencies). Refer to the General registry's documentation and links therein for details.

Summary

In this post, we discussed creating Julia packages. We learned what comprises a package, how to automate package creation, and how to register a package in Julia's General registry.

What package development tips do you have? Let us know in the comments below!

Now that you know how to create a Julia package, check out our next post to learn about package testing! Or, if you're curious about how to conditionally extend package functionality, check out another post about package extensions!

Additional Links

• Official Package Creation Docs
  • Official Julia documentation on creating packages.
• PkgTemplates.jl Docs
  • Documentation for PkgTemplates.jl.
• Project.toml Docs
  • Documentation for the Project.toml file.
• Julia General Registry
  • GitHub repo (including README) for Julia's General registry.

Cover image background provided by www.proflowers.com at https://www.flickr.com/photos/127365614@N08/16011252136.

Treasure map image source: https://openclipart.org/detail/299283/x-marks-the-spot

This post was written by Steven Whitaker.

Note that Julia 1.11 is no longer the most recent Julia version. To learn more about the most recent version, check out our series of posts about Julia releases.

A new version of the Julia programming language was just released! Version 1.11 is now the latest stable version of Julia.

This release is a minor release, meaning it includes language enhancements and bug fixes but should also be fully compatible with code written in previous Julia versions (from version 1.0 and onward).

In this post, we will check out some of the features and improvements introduced in this newest Julia version. Read the full post, or click on the links below to jump to the features that interest you.

• Improved Clarity of Public API with public Keyword
• Standardized Entry Point for Scripts
• Improved String Styling
• New Functions for Testing Existence of Documentation
• More Complete @timed Macro
• New Convenience Function logrange

If you are new to Julia (or just need a refresher), feel free to check out our Julia tutorial series, beginning with how to install Julia and VS Code.

Improved Clarity of Public API with public Keyword

An important aspect of semantic versioning (aka SemVer, which Julia and Julia packages follow) is the public API users have access to. In essence, SemVer states that minor package updates should not break compatibility with existing code that uses the public API. However, other parts of the code are free to change in a minor update. To illustrate:

• If I have sum([1, 2, 3]) in my code that I wrote in Julia 1.10, it will continue to return 6 in Julia 1.11 because sum is part of Julia's public API. But it could break in Julia 2.0. (Hopefully not, though!)
• If I have SomePackage._internal_function(0) in my code that I wrote with SomePackage v1.2.0, it might error when SomePackage upgrades to v1.2.1 (because, for example, _internal_function got deleted). Such a change would be allowed because _internal_function is not part of the public API.

So, the question is, how does a user know what the public API of a package is? Historically, there have been some conventions followed:

• Names that are exported (e.g., export DataFrame) are part of the public API.
• Unexported names that are prefixed with an underscore (e.g., SomePackage._internal_function) are not part of the public API.

But what about a function like ForwardDiff.gradient? That function is the reason why 99% of users load the ForwardDiff package, but it's not exported! The good news is that it's still part of the public API because, well, ForwardDiff's maintainers say so. Or maybe it's because the documentation says so. Or maybe it's because enough people use it? Sometimes it's not entirely clear.

But now in Julia 1.11, the code can indicate the public API! This is thanks to a new public keyword. Now, all symbols that are documented with public are part of the public API. (Note that this is in addition to exported symbols, i.e., func would be considered public API with either export func or public func.)

Usage of public is the same as export. For example:

module MyPackage

public add1

"""
Docstring for a public function.
"""
add1(x) = x + 1

"""
Docstring for a private function.
"""
private_add1(x) = x + 1

end

With using MyPackage, no symbols are made available (except MyPackage), e.g., add1 can only be called via MyPackage.add1, because nothing is exported with export. And both MyPackage.add1(1) and MyPackage.private_add1(1) work, even though add1 is public and private_add1 is private. So, the public keyword doesn't change how MyPackage works or is used.

However, the public keyword does change some behaviors. The most notable difference is when displaying documentation in the REPL's help mode:

help?> MyPackage.add1
  Docstring for a public function.

help?> MyPackage.private_add1
  │ Warning
  │
  │  The following bindings may be internal; they may change or be removed in future versions:
  │
  │    •  MyPackage.private_add1

  Docstring for a private function.

See the warning with private_add1? Such warnings, in addition to the more straightforward documentation of the public API, may help reduce usage of package internals (particularly accidental usage), which in turn may help improve the stability of Julia packages.

To summarize, even though the public keyword doesn't change how a package works or is used, it does provide a mechanism for clearly stating the public API and providing warnings when viewing the documentation for internal functions. This, in turn, may improve the stability of Julia packages as they adhere more closely to public APIs.

Read more about public in the Julia manual.

Standardized Entry Point for Scripts

There is now a standardized entry point when running scripts from the command line.

Julia 1.11 introduces the @main macro. This macro, when placed in a script, and when the script is run via the command line, tells Julia to run a function called main after running the code in the script. main will be passed a Vector of Strings containing the command line arguments passed to the script.

To use @main, just include it in your script on its own line after defining your main function. (If @main occurs before defining main, for example at the top of the script, an error will be thrown, so the ordering matters.)

Of course, for this to work there has to be a function main with a method that takes a Vector{String} as the only input.

Let's look at an example to illustrate how this works. Say we have the following in test.jl:

print_val(x) = print(x)

function main(args)
    print_val(args)
end
@main

If we run this file in the REPL with include("test.jl"), the functions print_val and main will be defined, but main will not get called. This is the same behavior as when @main is not present.

On the other hand, if we run this file via the command line with julia test.jl, the functions print_val and main will be defined and then main will be called with the command line arguments as the input. To illustrate:

• julia test.jl will call main(String[]) (because no command line arguments were passed).
• julia test.jl 1 hello will call main(["1", "hello"]).

As a result of @main, a Julia file can have different behavior depending on whether it is run as a script or not.

If you're familiar with Python, @main might remind you of if __name__ == "__main__". However, there is one significant difference:

• In Python, if script1.py imports script2.py and script2.py has the "if main" check, running script1.py as a script will not run script2.py's "if main" code.
• In Julia, if script1.jl includes script2.jl and script2.jl uses @main, running script1.jl as a script will run script2.jl's main function. (Technicality: Unless script1.jl defines an appropriate main method, in which case script1.jl's main would be called, even if script1.jl did not include @main.)

This isn't to say Julia's @main is bad or wrong; it's just important to know that it works differently than Python. And it's still cool to have a standardized entry point for Julia scripts now!

Read more about @main in the Julia manual.

Improved String Styling

Julia 1.11 introduces a new StyledStrings.jl standard library package. This package provides a convenient way to add styling to strings. StyledStrings makes printing styled strings much easier than calling printstyled, particularly when different parts of the string have different styles.

The easiest way to create a styled string is with styled"...". For example:

using StyledStrings
styled_string = styled"{italic:This} is a {bold,bright_cyan:styled string}!"

Then, when printing the styled string, it will display according to the provided annotations.

Also, because the style information is stored with the string, it can easily be preserved across string manipulations such as string concatenation or grabbing a substring.

Check out the documentation for more information about the variety of different annotations StyledStrings supports.

And here's some more information from the State of Julia talk at JuliaCon 2024:

New Functions for Testing Existence of Documentation

Julia 1.11 makes it easy to determine programmatically whether a function has a docstring. This can be useful for, e.g., CI checks to ensure a package is well documented.

There are two functions for this purpose. The first is Docs.hasdoc, which is used to query a particular function. hasdoc takes two inputs: the module to look in and the name (as a Symbol) of the function. For example:

julia> Docs.hasdoc(Base, :sum)
true

The other function provided is Docs.undocumented_names, which returns a list of a module's public names that have no docstrings. (Note that public names include symbols exported via export as well as symbols declared as public via public.) For example:

julia> module Example

       export f1, f4
       public f2, f5

       "Exported, documented"
       f1() = 1

       "Public, documented"
       f2() = 2

       "Internal, documented"
       f3() = 3

       # Exported, undocumented
       f4() = 4

       # Public, undocumented
       f5() = 5

       # Internal, undocumented
       f6() = 6

       end
Main.Example

# Note that `f6` is not returned because it is neither exported nor public.
julia> Docs.undocumented_names(Example)
3-element Vector{Symbol}:
 :Example
 :f4
 :f5

It will be interesting to see what tooling arises to take advantage of these functions.

More Complete timed Macro

The @timed macro provides more complete timing information in Julia 1.11.

Previously, @timed gave run time and allocation/garbage collection information, but nothing about compilation time. Now, compilation time is included.

But why care about @timed when @time already gave all that info? Because @time is hard-coded to print to stdout, meaning there's no way to capture the information, e.g., for logging purposes.

I actually had a project where I wanted to redirect the output of @time to a log file. I couldn't just use redirect_stdio because that would also redirect the output of the code being timed. I ended up using @timed along with Base.time_print to create the log statements, but I was disappointed @timed didn't give me compilation time information. Well, now it does!

New Convenience Function logrange

Pop quiz: Which of the following is the correct way to create a logarithmically spaced range of numbers?

1. log.(range(exp(a), exp(b), N))
2. exp.(range(log(a), log(b), N))

I have occasionally needed to use logarithmically spaced ranges of numbers, not so frequently that I memorized which expression to use, but frequently enough that I developed a real distaste for the mental gymnastics I had to go through every time just to remember where to put the exps and logs. Maybe I should have just taken some time to memorize the answer...

But now it doesn't matter! The correct answer is neither 1 nor 2, but logrange(a, b, N)! Here's an example usage:

julia> logrange(1, 10, 5)
5-element Base.LogRange{Float64, Base.TwicePrecision{Float64}}:
 1.0, 1.77828, 3.16228, 5.62341, 10.0

I know it's a fairly minor change, but the addition of logrange in Julia 1.11 is probably the change I'm most excited about. There was much rejoicing when I saw the news!

Summary

In this post, we learned about some of the new features and improvements introduced in Julia 1.11. Curious readers can check out the release notes for the full list of changes.

Note also that with the new release, Julia 1.10 will now become the LTS (long-term support) version, replacing Julia 1.6. As a result, Julia 1.10 will receive maintenance updates instead of Julia 1.6 (which has now reached end of support) until the next LTS version is announced. If you want to learn more about what changes Julia 1.10 brought, check out our post!

What are you most excited about in Julia 1.11? Let us know in the comments below!

Additional Links

• Julia v1.11 Release Notes
  • Full list of changes made in Julia 1.11.
• Julia Basics for Programmers
  • Series of blog posts covering Julia basics.

Running a Julia File

Now that we have the extension installed and configured, we can start using the extension. One of the first things we will examine is the most basic feature - running code! To run code, we do the following:

1. Click the drop down in the top right of the code window
2. Click "Julia: Execute Code in REPL"
3. Enjoy the results!

When you hit Ctrl+Enter, the line your cursor is currently on will run, and the cursor will advance to the next line. This is one way to step through the code line by line.

You are also able to use Ctrl+F5 (Option+F5 for Macs) to run the entire file. You can learn more about running Julia code from the official documentation.

Code Navigation

The information in this section applies to any language and is not exclusive to the Julia extension. The features below are helpful to know and can increase your productivity as you code.

Within VS Code, if you use Ctrl+P, a prompt will open at the top of your editor. In that prompt, you can start typing the name of a file you want to jump to in your project. Once you click the option (or press enter), VS Code will jump directly to that file. You can also use Ctrl+G to jump to a specific line number in the file if you know which line you are looking for. Being able to jump back and forth between files without having to search the file tree will greatly enhance your workflow. Imagine all the time you will save by not searching through file trees!

Using Ctrl+Shift+O (be sure to use the letter O, not the number 0) will allow you to navigate through individual symbols within your program. After using the shortcut above, type : and all your symbols will be grouped by type. You are then able to navigate between them all.

Editing Code

Code navigation is a great skill to develop, especially when given some wonderful legacy code to unravel...we've all been there. Being proficient in navigating your code does you no good unless you are also proficient at editing the code.

One way to get going quickly is to use the "rename symbol" shortcut. You can either right click on a symbol and press "rename" or hit F2. When you rename the symbol, it will be renamed everywhere else in the file that it exists. Pretty neat, huh?

The Plot Viewer

Up until this point in the article we have laid the ground work for working with your code in VS Code. Next, we will look into some of the Julia specific features that the Julia extension offers, starting with the plot viewer.

The plot viewer is a really handy tool that lets you...well...view plots. We can look at an example to see how it works.

First, we will install the plots package if it hasn't been installed already.

julia> using Pkg
julia> Pkg.add("Plots")
# OR
# We can type the "]" key and use the package interface
(@v1.10) pkg>
(@v1.10) pkg> add Plots

After we do that, we can create a plot to visualize.

using Plots

function make_plot()
    # Create a plot
    p = plot()

    θ = range(0, 2π, length=100)
    x = cos.(θ) * 5
    y = sin.(θ) * 5
    plot!(p, x, y, linecolor=:black, linewidth=2, legend=:topright)

    x_left = 1 .+ 0.5 * cos.(θ)
    y_left = 2 .+ 0.5 * sin.(θ)
    plot!(p, x_left, y_left, linecolor=:black, linewidth=2, fillalpha=0.2)

    x_right = 3 .+ 0.5 * cos.(θ)
    y_right = 2 .+ 0.5 * sin.(θ)
    plot!(p, x_right, y_right, linecolor=:black, linewidth=2, fillalpha=0.2)

    θ_arc = range(0, π, length=10)
    x_arc = 2 .+ cos.(θ_arc) * 2
    y_arc = -1 .+ sin.(θ_arc) * 1
    plot!(p, x_arc, y_arc, linecolor=:black, linewidth=2)

    # Adjust plot limits and display the final plot
    xlims!(-6, 6)
    ylims!(-6, 6)
    display(p)
end

# Execute the function to plot
make_plot()

Next we run this by using the keyboard shortcut we learned earlier (Ctrl+Enter), and we can see the result below!

Pretty cool! Now we can see our charts generated in real time right inside our editor!

The Table Viewer

I don't know about you, but I never liked having to try and dump the contents of an array, matrix, or other data structures to the console and try and parse through the data. Lucky for us we don't have to do that. The Julia extension allows us to view any Tables.jl compatible table in the special table viewer. There are two ways to do this.

The first way is by clicking the "View in VS Code" button next to your table in the "Workspace" section.

The second way to do this is by running the vscodedisplay(name_of_table) directly in the REPL.

It's pretty cool if you ask me. Having the ability to view the data is a nice feature, but to make it even better, you can sort the data in the UI by clicking the column headers. You can also copy data by using Ctrl + C just like you would in Excel!

A word of caution: All the table data you see is cached so any changes you make will not be reflected in the table viewer. To fix that just re-display the table in the editor and you will see your changes.

Debugging

The last topic we will cover is the debugging tools.

There are many things you can do in the VS Code debugger that are not language-specific. We aren't going to cover all of those features here, so if you want a more in-depth look, check out the official documentation.

Since the only truly bug free code is no code, we will start by writing some code that we can test and try to catch bugs in.

function do_math(a, b)
    c = a + b
    d = a * b
    c + d
end

function print_things()
    println("First print")
    println("Second print")

    var = do_math(5,8)

    println("Third print and math: ", var)

    var2 = do_math("Bug",3)

    println("Fourth print and bug: ", var2)
end

print_things()

We have code to run, so we can run the debugger and see what we get. First, we must switch to the "Run and Debug" tab. We do this by either clicking on the tab (the one with the bug and play button) or by hitting Ctrl+Shift+D.

Once we are there, we will be greeted with a screen like this:

From here we can observe the compiled Julia code, our breakpoints, and several other things as the program runs. We will want to run our code through the debugger, and to do that, we can either click the big "Run and Debug" button or hit F5.

We step through the code a bit, and see some of what the debugger will show us.

1: The variables passed into the function

2: The variables local to the function

3: The indicator of which line we are currently on

4: A breakpoint indicator

We can set our breakpoints by double clicking next to the line numbers. After setting our breakpoints, we will be able to step through the code. As we step through the code line by line, the variables that get created are populated in the top section and their values are shown. Another neat feature the debugger gives that is not highlighted above but should be noted is the "CALL STACK" section. As the name suggests, this will show us the entire call stack as you step through the code. All of these are most likely things we have seen before in other debuggers, but they are useful nonetheless.

Keyboard Shortcuts

To wrap up, let's look at a list of keyboard shortcuts for effective Julia extension usage. Note that a command like Alt+J Alt+C means press Alt+J followed by Alt+C.

Summary

We reviewed some of the basics of the Julia VS Code extension. We looked at running a Julia file, the basics of code navigation and editing, the usefulness of the plot and table viewers, and some basic debugging features. This was only an overview, and there is much more that the extension has to offer! If you would like to do a deeper dive into the Julia VS Code extension, visit the official documentation or their GitHub.

If you would like to learn more about Julia so you can fully take advantage of the extension's features, check out our Julia Basics series!

The Great Lakes Consulting team collaborated with a major healthcare client to develop a Revenue Forecasting application using the Julia framework. This application allows in-memory processing of large healthcare claims datasets, enabling real-time scenario modeling and quick analysis.

Recently, our team upgraded the application, replacing JuliaDB.jl with DataFrames.jl. During this project, JuliaDB.jl NDSparse objects were replaced with a custom DCTable object. This new custom object wraps a DataFrame and manages disk caching with MemPool.jl. High-level design decisions and lessons learned are detailed in this blog post.

As a bonus, our Healthcare client is looking to hire new developers to continue development and support of the Net Revenue Forecasting application and its Julia framework. There are two (2) positions posted on their Jobs Portal. Please consider applying if you are interested.

Julia Developer Specialist (REMOTE)

Senior Applications Programmer / Analyst (REMOTE)

Background

In 2018, the GLCS team developed a Net Revenue and Mid-Month Forecasting application (NRF) for one of the largest not-for-profit healthcare systems in the U.S. This application is part of a suite of revenue tools that provide A/R Valuation, Revenue Forecasting, Analytics, and Reporting. It helps the health system create accurate revenue forecasts for over 200 hospitals, continuing care facilities, and urgent care locations nationwide.

The most recent generation of the NRF application leverages a services-based architecture powered by Julia. The platform facilitates in-memory processing for very large multi-dimensional datasets (8 GB – 12 GB) to enable real-time scenario modeling for users. Core data manipulation was originally performed with JuliaDB.jl.

When the NRF application was developed in 2018, JuliaDB.jl was the best solution for:

• Loading multi-dimensional datasets quickly.

• Indexing data and performing FILTER, AGGREGATE, SORT and JOIN operations.

• Saving results and loading them back efficiently.

• Leveraging Julia's built-in parallelism to fully utilize available resources.

Now for some bad news. The last official release for this package was August 3, 2020 (v0.13.1). JuliaDB.jl is effectively abandoned and not receiving support or maintenance updates. The development recommended DTables.jl and DataFrames.jl as the preferred alternatives for JuliaDB.jl.

Earlier this year, the GLCS team set out to upgrade the NRF application and replace JuliaDB.jl components within the framework. The first design leveraged DTables.jl, an abstraction layer on top of Dagger.jl that allows for manipulation of table-like structures in a distributed environment.

Issues Encountered

The initial builds showed some promise. In general, query and processing performance improved. However, when deployed to the test environment (which mimicked the production server configuration) with real-time user interactions and very large datasets, individual processes occasionally failed or hung without explanation. Due to the constraints of the test environment, a C-library function call within Dagger.jl, a dependency of DTables.jl, failed when scheduling parallel tasks. Additionally, the new framework had excessive memory (RAM) demands, which exhausted available resources and resulted in poor performance.

The initial versions were less stable for single-threaded, multi-process applications like NRF. The GLCS team reported several issues to the maintainers of DTables.jl and Dagger.jl to enhance their stability for applications like NRF. The resulting bug fixes and improvements increased effectiveness and efficiency. Local testing ran smoothly, but the application would still occasionally hang or crash when deployed to the official test environment.

Root Cause Analysis

DTables.jl does not allow for modifying data in-place. As a result, data often had to be copied to another structure, modified, and then stored again using DTables.jl. This frequent copying of very large datasets led to high memory usage and slow performance.

Despite working closely with the maintainers of DTables.jl and Dagger.jl, NRF still faced occasional issues in the official test environment that did not occur in personal test setups. This suggests an incompatibility between Dagger.jl and the operating system used in the official test environment (RHEL 7.9).

Solution

Because the only feature NRF needed from DTables.jl was disk caching (i.e., being able to swap data seamlessly from memory to disk, and vice versa), the team dropped DTables.jl and instead used MemPool.jl. The team replaced JuliaDB.jl NDSparse objects with custom DCTable objects (DC meaning disk-cacheable). The new custom object wraps a DataFrames.jl DataFrame object and manages disk caching with MemPool.jl. In code, a DCTable is used in the same way one would use a DataFrame. The difference is that whenever a DCTable is used, first the underlying DataFrame must be grabbed from MemPool.jl, fetching the DataFrame from disk if it has been cached. Then the DataFrame is used as normal. The result of the operation (if it is a DataFrame) is then wrapped in a new DCTable to be managed by MemPool.jl.

"""
DCTable --> Disk-cacheable table (`DataFrame`).
Disk caching is managed via MemPool.jl, and a `DCTable` stores a `DRef` 
returned by calling `poolset` on the `DataFrame` to store.
The `DataFrame` can be retrieved by calling `fetch` on a `DCTable` 
(which calls `poolget` on the stored `DRef`).
"""
struct DCTable
    ref::DRef
    DCTable(df::DataFrame) = new(poolset(df; size = nbytes(df)))
end

The DCTable objects resolved the issues experienced with DTables.jl. First, because operating on a DCTable works on the underlying DataFrame, all the benefits of using DataFrames apply, including being able to modify data in-place. As a result, using DCTables requires much less memory. And second, relying on MemPool.jl drops the complex task-scheduling logic of Dagger.jl that seemed to be incompatible with the official NRF test environment.

With DCTable objects on hand, the team was able to replace all JuliaDB.jl function calls with equivalent operations on DCTable/DataFrame objects. The team ensured feature parity between new and old back-ends. Tests were developed to ensure the results obtained via the new back-end were consistent with the old back-end, and benchmarks were created to compare the performance of the old and new back-ends. Next, the team deployed the new codebase to the official test environment. Finally, after extensive internal testing and user-acceptance testing, the new codebase was officially deployed to the production environment.

Follow-up Opportunities

Are you a Julia programmer looking for a new opportunity? Our client is seeking additional help to continue developing and supporting the Net Revenue Forecasting application and its Julia framework. They have posted two positions on their Jobs Portal. Links to those positions are below. Please consider applying if you are interested.

Julia Developer Specialist (REMOTE)

Senior Applications Programmer / Analyst (REMOTE)

Introduction

The great thing about a package like Dataframes.jl is that it bridges the gap between traditional programming and SQL (Structured Query Language). Databases are great tools for easily gaining insights into your data by joining, filtering, aggregating, sorting, etc... Dataframes.jl brings those goodies right into your hands by simply adding the package into your julia session. So, lets get started!

Getting Started

Adding the package is a few simple steps.

julia> using Pkg
julia> Pkg.add("DataFrames")
julia> using DataFrames

The constructor for a DataFrame provides flexibility to create from arrays, tuples, constants, or files. The documentation covers all these, but for this post we'll just explore one of the more common ways.

julia> df = DataFrame(a = 1:4, b = rand(4), c = "My first DataFrame")
4×3 DataFrame
 Row │ a      b         c                  
     │ Int64  Float64   String             
─────┼─────────────────────────────────────
   1 │     1  0.141874  My first DataFrame
   2 │     2  0.432084  My first DataFrame
   3 │     3  0.47098   My first DataFrame
   4 │     4  0.414639  My first DataFrame

You'll notice in the code above we use a mix of datatypes including range, array, and scalar. The underlying vectors must be of the same size and the scalar gets broadcasted, or repeated, for each row. Also, pay attention that the types of each column are inferred based on the arrays passed into the constructor.

Now, to access a column of a DataFrame there are also a few different possibilities. Here are a few examples of accessing the first column "a".

julia> df.a
4-element Vector{Int64}:
 1
 2
 3
 4

julia> df."a"
4-element Vector{Int64}:
 1
 2
 3
 4

julia> df[!, "a"]
4-element Vector{Int64}:
 1
 2
 3
 4

julia> df[!, :a]
4-element Vector{Int64}:
 1
 2
 3
 4

julia> df[:, :a]
4-element Vector{Int64}:
 1
 2
 3
 4

In these examples columns can be access directly with literals such as df.a, or more dynamically using brackets (since variables could be substituted.) You may also find yourself wondering the difference between ! and :, which is an important distinction!

The ! returns the underlying vector and : returns a copy. This can be showcased in an example where we will attempt to change the description of the second value in column c to "I love Julia!"

julia> df[:, :c][2] = "I love Julia!"
3

julia> df
4×3 DataFrame
 Row │ a      b         c                  
     │ Int64  Float64   String             
─────┼─────────────────────────────────────
   1 │     1  0.394165  My first DataFrame
   2 │     2  0.809883  My first DataFrame
   3 │     3  0.124035  My first DataFrame
   4 │     4  0.886781  My first DataFrame

julia> df[!, :c][2] = "I love Julia!"
3

julia> df
4×3 DataFrame
 Row │ a      b         c                  
     │ Int64  Float64   String             
─────┼─────────────────────────────────────
   1 │     1  0.394165  My first DataFrame
   2 │     3  0.809883  I love Julia!
   3 │     3  0.124035  My first DataFrame
   4 │     4  0.886781  My first DataFrame

Notice how the change will only persist to df when we access the column with !.

There is often a tradeoff between returning copies versus the actual underlying vectors. Returning a copy is generally considered safer since if the copy is later mutated the underlying DataFrame remains unchanged. However, with very large DataFrames copying every column access will result in an increase in memory. It is best to weigh those considerations and figure out what approach will work best for a given program.

Data Wrangling

Import / Export

Another great feature of the Julia programming language is that many different packages will interact well when used together. For instance, DataFrames.jl and CSV.jl can be used to very easily import and export data.

First, we can save the DataFrame from above to CSV.

julia> using CSV

julia> path = joinpath(homedir(), "my_df.csv")

julia> CSV.write(path, df)

And, reading in the DataFrame from file is just as easy!

julia> CSV.read(path, DataFrame)
4×3 DataFrame
 Row │ a      b         c                  
     │ Int64  Float64   String31           
─────┼─────────────────────────────────────
   1 │     1  0.601361  My first DataFrame
   2 │     2  0.178065  My first DataFrame
   3 │     3  0.729591  My first DataFrame
   4 │     4  0.280314  My first DataFrame

There are many keyword arguments to explore when handling csv files and the documentation is best for covering all of these CSV.jl.

DataFrames.jl also supports writing and reading to multiple files types such as Arrow, JSON, Parquet, and others.

Joins

A join is a way to merge data from two DataFrames into a single DataFrame. There are several types and they generally mimic the same types that a database would support.

• innerjoin
• leftjoin
• rightjoin
• outerjoin
• semijoin
• antijoin
• crossjoin

Definitions of each can be found in either the documentation, or docstrings, but lets take a look at a few examples. Say we have the following DataFrame sets containing information from a school.

julia> student_df = DataFrame(student_id = 1:10, student_name = ["Joe", "Sally", "Jim", "Sandy", "Beth", "Alex", "Tom", "Liz", "Bill", "Carl"], teacher_id = repeat([1,2],5))
10×3 DataFrame
 Row │ student_id  student_name  teacher_id 
     │ Int64       String        Int64      
─────┼──────────────────────────────────────
   1 │          1  Joe                    1
   2 │          2  Sally                  2
   3 │          3  Jim                    1
   4 │          4  Sandy                  2
   5 │          5  Beth                   1
   6 │          6  Alex                   2
   7 │          7  Tom                    1
   8 │          8  Liz                    2
   9 │          9  Bill                   1
  10 │         10  Carl                   2

julia> teacher_df = DataFrame(teacher_id = 1:2, teacher_name = ["Mr. Jackson", "Ms. Smith"])
2×2 DataFrame
 Row │ teacher_id  teacher_name 
     │ Int64       String       
─────┼──────────────────────────
   1 │          1  Mr. Jackson
   2 │          2  Ms. Smith

julia> grade_df = DataFrame(exam_id = 1, student_id = vcat(1:3, 5:10), grade = [0.95, 0.93, 0.81, 0.85, 0.73, 0.88, 0.77, 0.75, 0.93])
9×3 DataFrame
 Row │ exam_id  student_id  grade   
     │ Int64    Int64       Float64 
─────┼──────────────────────────────
   1 │       1           1     0.95
   2 │       1           2     0.93
   3 │       1           3     0.81
   4 │       1           5     0.85
   5 │       1           6     0.73
   6 │       1           7     0.88
   7 │       1           8     0.77
   8 │       1           9     0.75
   9 │       1          10     0.93

If we look at the grade_df we can see there are 9 results, but in the student_df we have 10 students. So, someone must have missed the exam! Let's find out who that way we can alert the teacher to schedule a makeup.

Let's do a leftjoin, which means every row will persist from the first DataFrame regardless if there is a match to the second DataFrame. The leftjoin function also takes an on keyword argument to signify what column needs to be used to find matches.

julia> student_grade_df = leftjoin(student_df, grade_df, on=:student_id)
10×5 DataFrame
 Row │ student_id  student_name  teacher_id  exam_id  grade      
     │ Int64       String        Int64       Int64?   Float64?   
─────┼───────────────────────────────────────────────────────────
   1 │          1  Joe                    1        1        0.95
   2 │          2  Sally                  2        1        0.93
   3 │          3  Jim                    1        1        0.81
   4 │          5  Beth                   1        1        0.85
   5 │          6  Alex                   2        1        0.73
   6 │          7  Tom                    1        1        0.88
   7 │          8  Liz                    2        1        0.77
   8 │          9  Bill                   1        1        0.75
   9 │         10  Carl                   2        1        0.93
  10 │          4  Sandy                  2  missing  missing

We notice Sandy has a missing value for both the exam_id and grade fields. missing is a special datatype in Julia that is similar to a null value in databases. This would signify to us that there was no match in the grade_df meaning Sandy missed the exam. We can add one more join to get the respective teacher's name.

julia> result_df = innerjoin(student_grade_df, teacher_df, on=:teacher_id)
10×6 DataFrame
 Row │ student_id  student_name  teacher_id  exam_id  grade       teacher_name 
     │ Int64       String        Int64       Int64?   Float64?    String       
─────┼─────────────────────────────────────────────────────────────────────────
   1 │          1  Joe                    1        1        0.95  Mr. Jackson
   2 │          2  Sally                  2        1        0.93  Ms. Smith
   3 │          3  Jim                    1        1        0.81  Mr. Jackson
   4 │          5  Beth                   1        1        0.85  Mr. Jackson
   5 │          6  Alex                   2        1        0.73  Ms. Smith
   6 │          7  Tom                    1        1        0.88  Mr. Jackson
   7 │          8  Liz                    2        1        0.77  Ms. Smith
   8 │          9  Bill                   1        1        0.75  Mr. Jackson
   9 │         10  Carl                   2        1        0.93  Ms. Smith
  10 │          4  Sandy                  2  missing  missing     Ms. Smith

We used an innerjoin this time since we know that every student would have a teacher assigned. Now, we can let Ms. Smith know that she needs to reach out to Sandy to re-schedule her exam.

Sorting

Another helpful function for analysis is sort. Let's sort our result_df by the grade column.

julia> sort(result_df, [:grade])
10×6 DataFrame
 Row │ student_id  student_name  teacher_id  exam_id  grade       teacher_name 
     │ Int64       String        Int64       Int64?   Float64?    String       
─────┼─────────────────────────────────────────────────────────────────────────
   1 │          6  Alex                   2        1        0.73  Ms. Smith
   2 │          9  Bill                   1        1        0.75  Mr. Jackson
   3 │          8  Liz                    2        1        0.77  Ms. Smith
   4 │          3  Jim                    1        1        0.81  Mr. Jackson
   5 │          5  Beth                   1        1        0.85  Mr. Jackson
   6 │          7  Tom                    1        1        0.88  Mr. Jackson
   7 │          2  Sally                  2        1        0.93  Ms. Smith
   8 │         10  Carl                   2        1        0.93  Ms. Smith
   9 │          1  Joe                    1        1        0.95  Mr. Jackson
  10 │          4  Sandy                  2  missing  missing     Ms. Smith

The function takes the DataFrame and an array of columns to sort on. Our result of sort is putting the lowest grade first, but if we wanted it descending we can pass a rev keyword argument.

julia> sort(result_df, [:grade], rev=true)
10×6 DataFrame
 Row │ student_id  student_name  teacher_id  exam_id  grade       teacher_name 
     │ Int64       String        Int64       Int64?   Float64?    String       
─────┼─────────────────────────────────────────────────────────────────────────
   1 │          4  Sandy                  2  missing  missing     Ms. Smith
   2 │          1  Joe                    1        1        0.95  Mr. Jackson
   3 │          2  Sally                  2        1        0.93  Ms. Smith
   4 │         10  Carl                   2        1        0.93  Ms. Smith
   5 │          7  Tom                    1        1        0.88  Mr. Jackson
   6 │          5  Beth                   1        1        0.85  Mr. Jackson
   7 │          3  Jim                    1        1        0.81  Mr. Jackson
   8 │          8  Liz                    2        1        0.77  Ms. Smith
   9 │          9  Bill                   1        1        0.75  Mr. Jackson
  10 │          6  Alex                   2        1        0.73  Ms. Smith

In both these cases a copy of the DataFrame is returned and the result_df is left unchanged. But, if we wanted to sort in-place we can also use the sort! function that will update the passed DataFrame.

julia> sort!(result_df, [:grade], rev=true)
10×6 DataFrame
 Row │ student_id  student_name  teacher_id  exam_id  grade       teacher_name 
     │ Int64       String        Int64       Int64?   Float64?    String       
─────┼─────────────────────────────────────────────────────────────────────────
   1 │          4  Sandy                  2  missing  missing     Ms. Smith
   2 │          1  Joe                    1        1        0.95  Mr. Jackson
   3 │          2  Sally                  2        1        0.93  Ms. Smith
   4 │         10  Carl                   2        1        0.93  Ms. Smith
   5 │          7  Tom                    1        1        0.88  Mr. Jackson
   6 │          5  Beth                   1        1        0.85  Mr. Jackson
   7 │          3  Jim                    1        1        0.81  Mr. Jackson
   8 │          8  Liz                    2        1        0.77  Ms. Smith
   9 │          9  Bill                   1        1        0.75  Mr. Jackson
  10 │          6  Alex                   2        1        0.73  Ms. Smith

Split-apply-combine

Now that we have some basics down, it's time to dive into aggregating results. In DataFrames.jl this is referred to as a split-apply-combine strategy. It is a bit of a mouthful, but let's walk through what exactly this is referring to.

Split is simply breaking the DataFrame into groups using the groupby function. In our example lets split our DataFrame by the teacher_name column.

julia> grouped_df = groupby(result_df, :teacher_name)
GroupedDataFrame with 2 groups based on key: teacher_name
First Group (5 rows): teacher_name = "Mr. Jackson"
 Row │ student_id  student_name  teacher_id  exam_id  grade     teacher_name 
     │ Int64       String        Int64       Int64?   Float64?  String       
─────┼───────────────────────────────────────────────────────────────────────
   1 │          1  Joe                    1        1      0.95  Mr. Jackson
   2 │          3  Jim                    1        1      0.81  Mr. Jackson
   3 │          5  Beth                   1        1      0.85  Mr. Jackson
   4 │          7  Tom                    1        1      0.88  Mr. Jackson
   5 │          9  Bill                   1        1      0.75  Mr. Jackson
⋮
Last Group (5 rows): teacher_name = "Ms. Smith"
 Row │ student_id  student_name  teacher_id  exam_id  grade       teacher_name 
     │ Int64       String        Int64       Int64?   Float64?    String       
─────┼─────────────────────────────────────────────────────────────────────────
   1 │          2  Sally                  2        1        0.93  Ms. Smith
   2 │          6  Alex                   2        1        0.73  Ms. Smith
   3 │          8  Liz                    2        1        0.77  Ms. Smith
   4 │         10  Carl                   2        1        0.93  Ms. Smith
   5 │          4  Sandy                  2  missing  missing     Ms. Smith

The result of calling groupby is of type GroupedDataFrame, which is basically a wrapper around one, or many, groups of a DataFrame. In our example we have two teachers and so the result GroupedDataFrame has two groups.

Now, lets try to get an average exam grade for our two teachers. This will introduce the combine function that takes a GroupedDataFrame and any number of aggregation functions. Let's also add the Statistics.jl package, so we can take advantage of the mean function.

julia> using Statistics

julia> combine(grouped_df, :grade => mean)
2×2 DataFrame
 Row │ teacher_name  grade_mean  
     │ String        Float64?    
─────┼───────────────────────────
   1 │ Mr. Jackson         0.848
   2 │ Ms. Smith     missing

The result is a DataFrame where the first column(s) will match our GroupedDataFrame key(s) and the subsequent column(s) will match the function(s) we pass for aggregation. However, Ms. Smith has a grade_mean of missing!?

In our earlier discussion we found that Sandy missed the exam, so her grade was set to missing. A missing value behaves differently than normal numbers, which is problematic in our aggregation function. Take a look at a very simple example.

julia> 1 + missing
missing

We notice that adding a value of 1 to missing equals missing. This is a necessary evil and you may be wondering why don't we just treat it as 0? Let's see what happens to our results if we replace missing with 0.

julia> combine(grouped_df, :grade => (x -> mean(coalesce.(x, 0))))
2×2 DataFrame
 Row │ teacher_name  grade_function 
     │ String        Float64        
─────┼──────────────────────────────
   1 │ Mr. Jackson            0.848
   2 │ Ms. Smith              0.672

In the above example, instead of just passing mean as the function we create an anonymous function. This allows us to get a little more clever with adding a coalesce to replace the missing values with 0. We see from the results that Ms. Smith has a much lower scoring average than Mr. Jackson. But, if we think about it the results are getting incorrectly skewed. We know Sandy didn't actually score a 0, but rather didn't take the test at all. Treating her result as a 0 is skewing the average much lower than it should be.

In some cases replacing with a 0 would make sense, but not in this scenario. Here are a few better options:

We could just drop the rows that contain missing values prior to aggregation. DataFrames.jl provides a dropmissing function specifically for this.

julia> result_no_missing_df = dropmissing(result_df)
9×6 DataFrame
 Row │ student_id  student_name  teacher_id  exam_id  grade    teacher_name 
     │ Int64       String        Int64       Int64    Float64  String       
─────┼──────────────────────────────────────────────────────────────────────
   1 │          1  Joe                    1        1     0.95  Mr. Jackson
   2 │          2  Sally                  2        1     0.93  Ms. Smith
   3 │          3  Jim                    1        1     0.81  Mr. Jackson
   4 │          5  Beth                   1        1     0.85  Mr. Jackson
   5 │          6  Alex                   2        1     0.73  Ms. Smith
   6 │          7  Tom                    1        1     0.88  Mr. Jackson
   7 │          8  Liz                    2        1     0.77  Ms. Smith
   8 │          9  Bill                   1        1     0.75  Mr. Jackson
   9 │         10  Carl                   2        1     0.93  Ms. Smith

julia> grouped_no_missing_df = groupby(result_no_missing_df, :teacher_name)
GroupedDataFrame with 2 groups based on key: teacher_name
First Group (5 rows): teacher_name = "Mr. Jackson"
 Row │ student_id  student_name  teacher_id  exam_id  grade    teacher_name 
     │ Int64       String        Int64       Int64    Float64  String       
─────┼──────────────────────────────────────────────────────────────────────
   1 │          1  Joe                    1        1     0.95  Mr. Jackson
   2 │          3  Jim                    1        1     0.81  Mr. Jackson
   3 │          5  Beth                   1        1     0.85  Mr. Jackson
   4 │          7  Tom                    1        1     0.88  Mr. Jackson
   5 │          9  Bill                   1        1     0.75  Mr. Jackson
⋮
Last Group (4 rows): teacher_name = "Ms. Smith"
 Row │ student_id  student_name  teacher_id  exam_id  grade    teacher_name 
     │ Int64       String        Int64       Int64    Float64  String       
─────┼──────────────────────────────────────────────────────────────────────
   1 │          2  Sally                  2        1     0.93  Ms. Smith
   2 │          6  Alex                   2        1     0.73  Ms. Smith
   3 │          8  Liz                    2        1     0.77  Ms. Smith
   4 │         10  Carl                   2        1     0.93  Ms. Smith

julia> combine(grouped_no_missing_df, :grade => mean)
2×2 DataFrame
 Row │ teacher_name  grade_mean 
     │ String        Float64    
─────┼──────────────────────────
   1 │ Mr. Jackson        0.848
   2 │ Ms. Smith          0.84

We now see that the two teachers average test scores are very similar. This approach would work well if we never again needed the rows containing missing values.

But, if we wanted to keep those rows around and rather just exclude them from certain calculations. We can make use of another function, skipmissing, which will simply skip over the missing values.

julia> combine(grouped_df, :grade => (x -> mean(skipmissing(x))))
2×2 DataFrame
 Row │ teacher_name  grade_function 
     │ String        Float64        
─────┼──────────────────────────────
   1 │ Mr. Jackson            0.848
   2 │ Ms. Smith              0.84

One last thing to note on missing values is that it is easy to identify if one, or more, of your DataFrame columns contains missing values. We talked earlier that DataFrames.jl infers the types for each column and displays them in the output. You'll notice in result_df that the column teacher_id is of datatype Int64 and exam_id is of Int64?. Here the ? denotes that missing values were found, so be careful!

Conclusion

We've touched on some of the topics that makes DataFrames.jl such a great general purpose package. It is a helpful tool to quickly interact for data exploration, or to be used in production code to manipulate tabular data. I hope you've enjoyed today's reading and be sure to check out the rest of our blog posts on blog.glcs.io!

StaticArrays.jl provides drop-in replacements for Array, the standard Julia array type. These StaticArrays work just like Arrays, but they provide one additional piece of information in the type: the size of the array. Consequently, you can't insert or remove elements of a StaticArray; they are statically sized arrays (hence the name). However, this restriction allows more information to be given to Julia's compiler, which in turn results in more efficient machine code (for example, via loop unrolling and SIMD operations). The resulting speed-up can often be 10x or more!

In this post, we will learn how to use StaticArrays.jl and compare the performance of StaticArrays to that of regular Arrays for several different operations.

Note that the code examples in this post assume StaticArrays.jl has been installed and loaded:

# Press ] to enter the package prompt.
pkg> add StaticArrays

# Press Backspace to return to the Julia prompt.
julia> using StaticArrays

(Check out our post on the Julia REPL for more details about the package prompt and navigating the REPL.)

How to Use StaticArrays.jl

When working with StaticArrays.jl, typically one will use the SVector type or the SMatrix type. (There is also the SArray type for N-dimensional arrays, but we will focus on 1D and 2D arrays in this post.) SVectors and SMatrixes have both static size and static data, meaning the data contained in such objects cannot be modified. For statically sized arrays whose contents can be modified, StaticArrays.jl provides MVector and MMatrix (and MArray). We will stick with SVectors and SMatrixes in this post unless we specifically need mutability.

Constructors

There are three ways to construct StaticArrays.

1. Convenience constructor SA:

   julia> SA[1, 2, 3]
   3-element SVector{3, Int64} with indices SOneTo(3):
    1
    2
    3
   
   julia> SA[1 2; 3 4]
   2×2 SMatrix{2, 2, Int64, 4} with indices SOneTo(2)×SOneTo(2):
    1  2
    3  4
   

2. Normal constructor functions:

   julia> SVector(1, 2)
   2-element SVector{2, Int64} with indices SOneTo(2):
    1
    2
   
   julia> SMatrix{2,3}(1, 2, 3, 4, 5, 6)
   2×3 SMatrix{2, 3, Int64, 6} with indices SOneTo(2)×SOneTo(3):
    1  3  5
    2  4  6
   

3. Macros:

   julia> @SVector [1, 2, 3]
   3-element SVector{3, Int64} with indices SOneTo(3):
    1
    2
    3
   
   julia> @SMatrix [1 2; 3 4]
   2×2 SMatrix{2, 2, Int64, 4} with indices SOneTo(2)×SOneTo(2):
    1  2
    3  4
   

   Note that using macros also enables a convenient way to create StaticArrays from common array-creation functions (eliminating the need to create an Array first just to convert it immediately to a StaticArray):

   @SVector [10 * i for i = 1:10]
   @SVector zeros(5)
   @SVector rand(7)
   @SMatrix [(i, j) for i = 1:2, j = 1:3]
   @SMatrix zeros(2, 2)
   @SMatrix randn(6, 6)
   

Conversion to/from Array

It may occasionally be necessary to convert to or from Arrays. To convert from an Array to a StaticArray, use the appropriate constructor function. However, because Arrays do not have size information in the type, we ourselves must provide the size to the constructor:

SVector{3}([1, 2, 3])
SMatrix{4,4}(zeros(4, 4))

To convert back to an Array, use the collect function:

julia> collect(SVector(1, 2))
2-element Vector{Int64}:
 1
 2

Comparing StaticArrays to Arrays

Once a StaticArray is created, it can be operated on in the same way as an Array. To illustrate, we will run a simple benchmark, both to compare the run-time speeds of the two types of arrays and to show that the same code can work with either type of array.

Here's the benchmark code, inspired by StaticArrays.jl's benchmark:

using BenchmarkTools, StaticArrays, LinearAlgebra, Printf

add!(C, A, B) = C .= A .+ B

function run_benchmarks(N)

    A = rand(N, N); A = A' * A
    B = rand(N, N)
    C = Matrix{eltype(A)}(undef, N, N)
    D = rand(N)
    SA = SMatrix{N,N}(A)
    SB = SMatrix{N,N}(B)
    MA = MMatrix{N,N}(A)
    MB = MMatrix{N,N}(B)
    MC = MMatrix{N,N}(C)
    SD = SVector{N}(D)

    speedup = [
        @belapsed($A + $B) / @belapsed($SA + $SB),
        @belapsed(add!($C, $A, $B)) / @belapsed(add!($MC, $MA, $MB)),
        @belapsed($A * $B) / @belapsed($SA * $SB),
        @belapsed(mul!($C, $A, $B)) / @belapsed(mul!($MC, $MA, $MB)),
        @belapsed(norm($D)) / @belapsed(norm($SD)),
        @belapsed(det($A)) / @belapsed(det($SA)),
        @belapsed(inv($A)) / @belapsed(inv($SA)),
        @belapsed($A \ $D) / @belapsed($SA \ $SD),
        @belapsed(eigen($A)) / @belapsed(eigen($SA)),
        @belapsed(map(abs, $A)) / @belapsed(map(abs, $SA)),
        @belapsed(sum($D)) / @belapsed(sum($SD)),
        @belapsed(sort($D)) / @belapsed(sort($SD)),
    ]

    return speedup

end

function main()

    benchmarks = [
        "Addition",
        "Addition (in-place)",
        "Multiplication",
        "Multiplication (in-place)",
        "L2 Norm",
        "Determinant",
        "Inverse",
        "Linear Solve (A \\ b)",
        "Symmetric Eigendecomposition",
        "`map`",
        "Sum of Elements",
        "Sorting",
    ]
    N = [3, 5, 10, 30]
    speedups = map(run_benchmarks, N)
    fmt_header = Printf.Format("%-$(maximum(length.(benchmarks)))s" * " | %7s"^length(N))
    header = Printf.format(fmt_header, "Benchmark", string.("N = ", N)...)
    println(header)
    println("="^length(header))
    fmt = Printf.Format("%-$(maximum(length.(benchmarks)))s" * " | %7.1f"^length(N))
    for i = 1:length(benchmarks)
        println(Printf.format(fmt, benchmarks[i], getindex.(speedups, i)...))
    end

end

main()

Notice that all the functions called when creating the array speedup in run_benchmarks are the same whether using Arrays or StaticArrays, illustrating that StaticArrays are drop-in replacements for standard Arrays.

Running the above code prints the following results on my laptop (the numbers indicate the speedup of StaticArrays over normal Arrays; e.g., a value of 17.7 means using StaticArrays was 17.7 times faster than using Arrays):

Benchmark                    |   N = 3 |   N = 5 |  N = 10 |  N = 30
====================================================================
Addition                     |    17.7 |    14.5 |     7.9 |     2.0
Addition (in-place)          |     1.6 |     1.3 |     1.4 |     0.7
Multiplication               |     8.2 |     7.0 |     4.2 |     2.6
Multiplication (in-place)    |     1.9 |     5.9 |     3.0 |     1.0
L2 Norm                      |     4.2 |     4.0 |     5.4 |     9.7
Determinant                  |    66.6 |     2.5 |     1.3 |     0.9
Inverse                      |    54.8 |     5.9 |     1.8 |     0.9
Linear Solve (A \ b)         |    65.5 |     3.7 |     1.8 |     0.9
Symmetric Eigendecomposition |     3.7 |     1.0 |     1.0 |     1.0
`map`                        |    10.6 |     8.2 |     4.9 |     2.1
Sum of Elements              |     1.5 |     1.1 |     1.7 |     2.1
Sorting                      |     7.1 |     2.9 |     1.5 |     1.1

There are two main conclusions from this table. First, using StaticArrays instead of Arrays can result in some nice speed-ups! Second, the gains from using StaticArrays tend to diminish as the sizes of the arrays increase. So, you can't expect StaticArrays.jl to always magically make your code faster, but if your arrays are small enough (the recommendation being fewer than about 100 elements) then you can expect to see some good speed-ups.

Of course, the above code timed just individual operations; how much faster a particular application would be is a different matter.

For example, consider a physical simulation where many 3D vectors are manipulated over several time steps. Since 3D vectors are static in size (i.e., are 1D arrays with exactly three elements), such a situation is a prime example of where StaticArrays.jl is useful. To illustrate, here is an example (taken from the field of magnetic resonance imaging) of a physical simulation using Arrays vs using StaticArrays:

using BenchmarkTools, StaticArrays, LinearAlgebra

function sim_arrays(N)

    M = Matrix{Float64}(undef, 3, N)
    M[1,:] .= 0.0
    M[2,:] .= 0.0
    M[3,:] .= 1.0
    M2 = similar(M)

    (sinα, cosα) = sincosd(30)
    R = [1 0 0; 0 cosα sinα; 0 -sinα cosα]
    E1 = exp(-0.01)
    E2 = exp(-0.1)
    (sinθ, cosθ) = sincosd(1)
    F = [E2 * cosθ E2 * sinθ 0; -E2 * sinθ E2 * cosθ 0; 0 0 E1]
    FR = F * R
    C = [0, 0, 1 - E1]
    # Run for 100 time steps (each loop iteration does 2 time steps).
    for t = 1:50
        mul!(M2, FR, M)
        M2 .+= C
        mul!(M, FR, M2)
        M .+= C
    end
    total = sum(M; dims = 2)

    return complex(total[1], total[2])

end

function sim_staticarrays(N)

    M = fill(SVector(0.0, 0.0, 1.0), N)

    (sinα, cosα) = sincosd(30)
    R = @SMatrix [1 0 0; 0 cosα sinα; 0 -sinα cosα]
    E1 = exp(-0.01)
    E2 = exp(-0.1)
    (sinθ, cosθ) = sincosd(1)
    F = @SMatrix [E2 * cosθ E2 * sinθ 0; -E2 * sinθ E2 * cosθ 0; 0 0 E1]
    FR = F * R
    C = @SVector [0, 0, 1 - E1]
    # Run for 100 time steps (each loop iteration does 1 time step).
    for t = 1:100
        # Apply simulation dynamics to each 3D vector.
        for i = 1:length(M)
            M[i] = FR * M[i] + C
        end
    end
    total = sum(M)

    return complex(total[1], total[2])

end

function main(N)

    r1 = @btime sim_arrays($N)
    r2 = @btime sim_staticarrays($N)
    @assert r1 ≈ r2 # Make sure the results are the same.

end

The speed-ups on my laptop for different values of N were as follows:

• N = 10: 14.6x faster
• N = 100: 7.1x faster
• N = 1000: 5.2x faster

(Here, N is the number of 3D vectors in the simulation, not the size of the StaticArrays.)

Note also that I wrote sim_arrays to be as performant as possible by doing in-place operations (like mul!), which has the unfortunate side effect of making the code a bit harder to read. Therefore, sim_staticarrays is both faster and easier to read!

As another example of how StaticArrays.jl can speed up a more involved application, see the DifferentialEquations.jl docs.

Summary

In this post, we discussed StaticArrays.jl. We saw that StaticArrays are drop-in replacements for regular Julia Arrays. We also saw that using StaticArrays can result in some nice speed-ups over using Arrays, at least when the sizes of the arrays are not too big.

Are array operations a bottleneck in your code? Try out StaticArrays.jl and then comment below how it helps!

Additional Links

• StaticArrays.jl Docs
  • Documentation for StaticArrays.jl.

Cover image background from https://openverse.org/image/875bf026-11ef-47a8-a63c-ee1f1877c156?q=circuit%20board%20array.

Welcome to our first Julia for Devs blog post! This will be a continuously running series of posts where our team will discuss how we have used Julia to solve real-life problems. So, let's get started!

In this Julia for Devs post, we will discuss using Julia to optimize scan parameters in magnetic resonance imaging (MRI).

If you are interested just in seeing example code showing how to use Julia to optimize your own cost function, feel free to skip ahead.

While we will discuss MRI specifically, the concepts (and even some of the code) we will see will be applicable in many situations where optimization is useful, particularly when there is a model for an observable signal. The model could be, e.g., a mathematical equation or a trained neural network, and the observable signal (aka the output of the model) could be, e.g., the image intensity of a medical imaging scan or the energy needed to heat a building.

Problem Setup

In this post, the signal model we will use is a mathematical equation that gives the image intensity of a balanced steady-state free precession (bSSFP) MRI scan. This model has two sets of inputs: those that are user-defined and those that are not. In MRI, user-defined inputs are scan parameters, such as how long to run the scan for or how much power to use to generate MRI signal. The other input parameters are called tissue parameters because they are properties that are intrinsic to the imaged tissue (e.g., muscle, brain, etc.).

Tissue parameters often are assumed to take on a pre-defined value for each specific tissue type. However, because they are tissue-specific and can vary with health and age, sometimes tissue parameters are considered to be unknown values that need to be estimated from data.

The problem we will discuss in this post is how to estimate tissue parameters from a set of bSSFP scans. Then we will discuss how to optimize the scan parameters of the set of bSSFP scans to improve the tissue parameter estimates.

To estimate tissue parameters, we need the following:

1. a signal model, and
2. an estimation algorithm.

Signal Model

Here's the signal model:

# Reference: https://www.mriquestions.com/true-fispfiesta.html
function bssfp(TR, flip, T1, T2)

    E1 = exp(-TR / T1)
    E2 = exp(-TR / T2)
    (sinα, cosα) = sincosd(flip)
    num = sinα * (1 - E1)
    den = 1 - cosα * (E1 - E2) - E1 * E2
    signal = num / den

    return signal

end

This function returns the bSSFP signal as a function of two scan parameters (TR, a value in units of seconds, and flip, a value in units of degrees) and two tissue parameters (T1 and T2, each a value in units of seconds).

Estimation Algorithm

There are various estimation algorithms out there, but, for simplicity in this post, we will stick with a grid search. We will compute the bSSFP signal over many pairs of T1 and T2 values. We will compare these computed signals to the actual observed signal, and the pair of T1 and T2 values that results in the closest match will be chosen as the estimates of the tissue parameters. Here's the algorithm in code:

# `signal` is the observed signal.
# `TR` and `flip` are the scan parameters that were used,
# and we want to estimate `T1` and `T2`.
# `signal`, `TR` and `flip` should be vectors of the same length,
# representing running multiple scans
# and recording the observed signal for each pair of `TR` and `flip` values.
function gridsearch(signal, TR, flip)

    # Specify the grid of values to search over.
    # `T1_grid` and `T2_grid` could optionally be inputs to this function.
    T1_grid = exp10.(range(log10(0.5), log10(3), 40))
    T2_grid = exp10.(range(log10(0.005), log10(0.7), 40))

    T1_est = T1_grid[1]
    T2_est = T2_grid[1]
    best = Inf
    # Pre-allocate memory for some computations to speed up the following loop.
    residual = similar(signal)
    # Iterate over the Cartesian product of `T1_grid` and `T2_grid`.
    for (T1, T2) in Iterators.product(T1_grid, T2_grid)
        # Physical constraint: T1 is greater than T2, and both are positive.
        T1 > T2 > 0 || continue
        # For the given T1 and T2 pairs, compute the (noiseless) bSSFP signal
        # for each bSSFP scan and subtract them from the given signals.
        # Tip: In Julia, one can apply a scalar function elementwise on vector
        #      inputs using the "dot" notation (see the `.` after `bssfp` below).
        residual .= signal .- bssfp.(TR, flip, T1, T2)
        # Compute the norm squared of the above difference.
        err = residual' * residual
        # If the candidate T1 and T2 pair fit the given signals better,
        # keep them as the current estimate of T1 and T2.
        if err < best
            best = err
            T1_est = T1
            T2_est = T2
        end
    end

    isinf(best) && error("no valid grid points; consider changing `T1_grid` and/or `T2_grid`")

    return (T1_est, T2_est)

end

Cost Function

Now, to optimize scan parameters we need a function to optimize, also called a cost function. In this case, we want to minimize the error between what our estimator tells us and the true tissue parameter values. But because we need to optimize scan parameters before running any scans, we will simulate bSSFP MRI scans using the given sets of scan parameters and average the estimator error over several sets of tissue parameters. Here's the code for the cost function:

# Load the Statistics standard library package to get access to the `mean` function.
using Statistics

# `TR` and `flip` are vectors of the same length
# specifying the pairs of scan parameters to use.
function estimator_error(TR, flip)

    # Specify the grid of values to average over and the noise level to simulate.
    # For a given pair of `T1_true` and `T2_true` values,
    # bSSFP signals will be simulated, and then the estimator
    # will attempt to estimate what `T1_true` and `T2_true` values were used
    # based on the simulated bSSFP signals and the given scan parameters.
    T1_true = [0.8, 1.0, 1.5]
    T2_true = [0.05, 0.08, 0.1]
    noise_level = 0.01

    T1_avg = mean(T1_true)
    T2_avg = mean(T2_true)
    # Pre-allocate memory for some computations to speed up the following loop.
    signal = float.(TR)
    # The following computes the mean estimator error over all pairs
    # of true T1 and T2 values.
    return mean(Iterators.product(T1_true, T2_true)) do (T1, T2)
        # Ignore pairs for which `T2 > T1`.
        T2 > T1 && return 0
        # Simulate noisy signal using the true T1 and T2 values.
        signal .= bssfp.(TR, flip, T1, T2) .+ noise_level .* randn.()
        # Estimate T1 and T2 from the noisy signal.
        (T1_est, T2_est) = gridsearch(signal, TR, flip)
        # Compare estimates to truth.
        T1_err = (T1_est - T1)^2
        T2_err = (T2_est - T2)^2
        # Combine the T1 and T2 errors into one single error metric
        # by averaging the respective errors
        # after normalizing by the mean true value of each parameter.
        err = (T1_err / T1_avg + T2_err / T2_avg) / 2
    end

end

Optimization

Now we are finally ready to optimize! We will use Optimization.jl. Many optimizers are available, but because we have a non-convex optimization problem, we will use the adaptive particle swarm global optimization algorithm. Here's a function that does the optimization:

# Load needed packages.
# Optimization.jl provides the optimization infrastructure,
# while OptimizationOptimJL.jl wraps the Optim.jl package
# that provides the optimization algorithm we will use.
using Optimization, OptimizationOptimJL

# Load the Random standard library package to enable setting the random seed.
using Random

# `TR_init` and `flip_init` are vectors of the same length
# that provide a starting point for the optimization algorithm.
# The length of these vectors also determines the number of bSSFP scans to simulate.
function scan_optimization(TR_init, flip_init)

    # Ensure randomly generated noise is the same for each evaluation.
    Random.seed!(0)

    N_scans = length(TR_init)
    length(flip_init) == N_scans || error("`TR_init` and `flip_init` have different lengths")

    # The following converts the cost function we created (`estimator_error`)
    # into a form that Optimization.jl can use.
    # Specifically, Optimization.jl needs a cost function that takes two inputs
    # (the first of which contains the parameters to optimize)
    # and returns a real number.
    # The input `x` is a concatenation of `TR` and `flip`,
    # i.e., `TR == x[1:N_scans]` and `flip == x[N_scans+1:end]`.
    # The input `p` is unused, but is needed by Optimization.jl.
    cost_fun = (x, p) -> estimator_error(x[1:N_scans], x[N_scans+1:end])

    # Specify constraints.
    # The lower and upper bounds are chosen to ensure reasonable bSSFP scans.
    (min_TR, max_TR) = (0.001, 0.02)
    (min_flip, max_flip) = (1, 90)
    constraints = (;
        lb = [fill(min_TR, N_scans); fill(min_flip, N_scans)],
        ub = [fill(max_TR, N_scans); fill(max_flip, N_scans)],
    )

    # Set up and solve the problem.
    f = OptimizationFunction(cost_fun)
    prob = OptimizationProblem(f, [TR_init; flip_init]; constraints...)
    sol = solve(prob, ParticleSwarm(lower = prob.lb, upper = prob.ub, n_particles = 3))

    # Extract the optimized TRs and flip angles, remembering that `sol.u == [TR; flip]`.
    TR_opt = sol.u[1:N_scans]
    flip_opt = sol.u[N_scans+1:end]

    return (TR_opt, flip_opt)

end

Results

Let's see how scan parameter optimization can improve tissue parameter estimates. We will use the following function to take scan parameters, simulate bSSFP scans, and then estimate the tissue parameters from those scans. We will compare the results of this function with manually chosen scan parameters to those with optimized scan parameters.

# Load the LinearAlgebra standard library package for access to `norm`.
using LinearAlgebra

# Load Plots.jl for displaying the results.
using Plots

# Helper function for plotting.
function plot_true_vs_est(T_true, T_est, title, rmse, clim)

    return heatmap([T_true T_est];
        title,
        clim,
        xlabel = "RMSE = $(round(rmse; digits = 4)) s",
        xticks = [],
        yticks = [],
        showaxis = false,
        aspect_ratio = 1,
    )

end

function run(TR, flip)

    # Create a synthetic object to scan.
    # The background of the object will be indicated with values of `0.0`
    # for the tissue parameters.
    nx = ny = 128
    object = map(Iterators.product(range(-1, 1, nx), range(-1, 1, ny))) do (x, y)
        r = hypot(x, y)
        if r < 0.5
            return (0.8, 0.08)
        elseif r < 0.8
            return (1.3, 0.09)
        else
            return (0.0, 0.0)
        end
    end

    # Simulate the bSSFP scans.
    T1_true = first.(object)
    T2_true = last.(object)
    noise_level = 0.001
    signal = map(T1_true, T2_true) do T1, T2
        # Ignore the background of the object.
        (T1, T2) == (0.0, 0.0) && return 0.0
        bssfp.(TR, flip, T1, T2) .+ noise_level .* randn.()
    end

    # Estimate the tissue parameters.
    T1_est = zeros(nx, ny)
    T2_est = zeros(nx, ny)
    for i in eachindex(signal, T1_est, T2_est)
        # Don't try to estimate tissue parameters for the background.
        signal[i] == 0.0 && continue
        (T1_est[i], T2_est[i]) = gridsearch(signal[i], TR, flip)
    end

    # Compute the root mean squared error.
    m = T1_true .!= 0.0
    T1_rmse = sqrt(norm(T1_true[m] - T1_est[m]) / count(m))
    T2_rmse = sqrt(norm(T2_true[m] - T2_est[m]) / count(m))

    # Plot the results.
    p_T1 = plot_true_vs_est(T1_true, T1_est, "True vs Estimated T1", T1_rmse, (0, 2.5))
    p_T2 = plot_true_vs_est(T2_true, T2_est, "True vs Estimated T2", T2_rmse, (0, 0.25))

    return (p_T1, p_T2)

end

First, let's see the results with no optimization:

TR_init = [0.005, 0.005, 0.005]
flip_init = [30, 60, 80]
(p_T1_init, p_T2_init) = run(TR_init, flip_init)

display(p_T1_init)

display(p_T2_init)

Now let's optimize the scan parameters and then see how the tissue parameter estimates look:

(TR_opt, flip_opt) = scan_optimization(TR_init, flip_init)
(p_T1_opt, p_T2_opt) = run(TR_opt, flip_opt)

display(p_T1_opt)

display(p_T2_opt)

We can see that the optimized scans result in much better tissue parameter estimates!

Summary

In this post, we saw how Julia can be used to optimize MRI scan parameters to improve tissue parameter estimates. Even though we discussed MRI specifically, the concepts presented here easily extend to other applications where signal models are known and optimization is required.

Note that most of the code for this post was taken from a Dash app I helped create for JuliaHub. Feel free to check it out if you want to see this code in action!

Are you facing slow optimization or simulation runs in MATLAB^®? Want to leverage Julia for enhanced performance but don't know where to start? Check out our webpage and watch our JuliaCon talk for solutions tailored just for you!

Additional Links

• Optimizing MRI Scans Dash App
  • Web app showcasing the capabilities discussed in this post.
• Optimizing MRI Scans Pluto Notebook
  • Pluto notebook accompanying the Dash app mentioned above. (Unfortunately, the data used in the notebook didn't get set up properly, so most of the code can't run correctly.)
• Links to other blog posts discussing how to do MRI in Julia:
  • Simulating MRI Physics with the Bloch Equations
  • Mastering MRI Bloch Simulations with BlochSim.jl in Julia
  • MRI Scan Simulation Made Easy with BlochSim.jl
• Optimization.jl Docs
  • Official documentation for Optimization.jl.
• Julia-MATLAB integration:
  • Service webpage
  • JuliaCon 2025 talk recording
  • JuliaCon 2025 talk transcript
  • JuliaCon 2025 preview blog post

MATLAB is a registered trademark of The MathWorks, Inc.

What if I were to tell you that Julia's type system has even more to offer? Well, welcome back to class, my friends! Today, we will see what else the Julia type system offers us. Let's dive right in and look at our first topic: Type Unions.

Type Unions

Type unions are exactly what you think they are. They are a union of two or more types that create a new abstract type. With this new abstract type that you create with the Union keyword, you can assign values to a variable with that type that matches any of the types specified in the Union. Let's look at an example:

    julia> IntOrString = Union{Int,AbstractString}
    Union{Int64, AbstractString}


    julia> function testUnionTypes(aType::IntOrString)
            print(`The type of aType is $(typeof(aType))`)
        end
    testUnionTypes (generic function with 1 method)


    julia> testUnionTypes(1)
    `The type of aType is Int64`


    julia> testUnionTypes("Testing Union Types")
    `The type of aType is String`


    julia> testUnionTypes(3.14)
    ERROR: MethodError: no method matching testUnionTypes(::Float64)


    Closest candidates are:
    testUnionTypes(::Union{Int64, AbstractString})
    @ Main REPL[8]:1


    Stacktrace:
    [1] top-level scope
    @ REPL[11]:1

You'll notice that when we test our new Union type, it rejects the float value we gave it, but it accepts both the integer and the string! Just like the Any type we discussed in a previous article on types, this allows us to develop generic code that works with several types. Julia itself actually uses this concept to allow for nullable types. Julia uses Union{T, Nothing} where T has any type you want. For example, Union{AbstractString, Nothing} would allow you to assign a string or a null (written with the symbol nothing in Julia).

Parametric Types

Parametric types are a very interesting part of Julia, and yes, they are exactly what they sound like. They are types that can take parameters. Let's look at an example of the syntax and then discuss its use.

julia> struct Triangle{T}
           a::T
           b::T
       end


julia> myFloatTriangle = Triangle{AbstractFloat}(1.0,2.0)
Triangle{AbstractFloat}(1.0, 2.0)


julia> myFloatTriangle.a
1.0


julia> myFloatTriangle.b
2.0

Now that we have created a parametric type, let's see how we can use it.

julia> function calculate_hypotenuse(myShape::Triangle)
           println("The hypotenuse is: $(sqrt(myShape.a^2 + myShape.b^2))")
       end


julia> calculate_hypotenuse(myFloatTriangle)
The hypotenuse is: 3.605551275463989


julia> myIntTriangle = Triangle(1,2)
Triangle{Int64}(1, 2)


julia> calculate_hypotenuse(myIntTriangle)
The hypotenuse is: 3.605551275463989

In our example above, we defined our "Triangle" variable in two ways. In one, we specified the type; in the other, we simply gave the values for the parameters. Julia was able to figure out the rest. This is all possible because T can be any type we give it. We don't have to specify the type upfront, so we can make our code much more flexible and reusable. In fact, not specifying the type (as we did with myIntTriangle) is the preferred way to do it in Julia.

Tuple Types

You can think of Tuples more like boxes that hold items. After you put the items into the box, the box is "sealed," and those items are set in that order with those values...FOREVER... Okay, maybe that is a bit dramatic, but I think you get the point. Tuple types are immutable containers with any number or combination of types. Let's look at the syntax of Tuples:

julia> typeof((42,"Don't panic",10.9))
Tuple{Int64, String, Float64}

One primary use for this is returning multiple types from a single function. Because Tuples are immutable, they ensure that the data stays structured in the order you tell it and remains constant. You can see several more examples of how Tuples are used in the Julia documentation or if you want a great explanation of how Tuples work, check out this video by DoggoDotJl. DoggoDotJl does a fantastic job explaining several different parts of the Julia language, and I highly recommend you check him out at DoggoDotJl on Youtube. #notsponsored

Named Tuples

Named Tuples are just Tuples...but with names. I bet you didn't see that coming. Well, okay... Named Tuples are a little more than just Tuples with names. Let's look at the syntax and then talk a little more about it:

julia> tupleWithNames = (
           language = "Julia",
           isTheBest = true,
           type = "NamedTuple",
       )
(language = "Julia", isTheBest = true, type = "NamedTuple")


julia> typeof(tupleWithNames)
@NamedTuple{language::String, isTheBest::Bool, type::String}

A NamedTuple functions like a JSON object in that you have key-value pairs. They are a fantastic data structure to use when you want to organize your code but don't need the flexibility of an array. When you want to access the elements of a NamedTuple you can do it in two different ways.

julia> function testingTuples(ourTuple)
            println("We can use $(ourTuple.type) to check if $(ourTuple.language) is better than Python")
            println("Is $(ourTuple.language) the best? $(ourTuple[2] ? "Yes it is! .jl > .py" : "No, use Python noob")")end
testingTuples (generic function with 1 method)


julia> testingTuples(tupleWithNames)
We can use NamedTuple to check if Julia is better than Python
Is Julia the best? Yes it is! .jl > .py

You can see in the above example that Julia is indeed better than Python! Okay, maybe this example proves nothing about Julia's superiority and may need to be the topic of another post. But this example does show how you can access elements inside NamedTuples. You can access elements in tuples using the tuple name, the . operator, and then the name of the element you want to access. You can also access it by indexing. Indexing is also how to access data in Tuples that weren't special enough for you to give names to. Now, with access to Tuples and NamedTuples, you can organize data in the same way you would with JSON objects.

NOTE: Just like Tuples, NamedTuples are immutable. Once the values are set, they cannot be changed later.

UnionAll Types

Now I know what you are probably thinking: What is up with the lizard? That can be explained with two simple points:

• Lizards are cool.
• I like to compare UnionAll types to chameleons.

Now, let me elaborate on that a bit. Just like chameleons change color, UnionAll types can change form and adapt to any data type. Chameleons don't change their color to yellow and suddenly become bananas. They are still chameleons. Similarly, you may have a UnionAll type that is a float in one instance and an integer the next, but it still has the same structure. Enough with the lizard talk; let's look at a more practical example to make sense of this reptilian elucidation.

julia> abstract type Shape{T} end


julia> struct Circle{T} <: Shape{T}
           radius::T
       end


julia> struct Square{T} <: Shape{T}
           side::T
       end


julia> circle_float = Circle(2.5)
Circle{Float64}(2.5)



julia> square_int = Square(4)
Square{Int64}(4)



julia> square_int isa Shape
true


julia> square_int isa Square
true


julia> square_int isa Circle
false

You can see that we created an abstract type called Shape, and then we created two other types called Square and Circle. By doing this, we have created a universal way to handle shapes without tying ourselves to any specific numeric type. We aren't limited to just integers or just floats. UnionAll types, similar to other topics we covered, allow you to build very flexible code that is type-stable, generic, and optimal for machine code generation.

Type Aliases

The last thing we will cover is type aliases. Julia allows type aliases to give a new name to an existing type. The idea here is the same as many other concepts we discussed: generic and reusable code. Take Int, for example. When you specify a number as an Int, Julia will check if it needs to be an Int32 or Int64, depending on your system. The Int alias is a convenience operator, removing the abstraction of 32-bit or 64-bit values. You specify a variable as Int, and Julia takes care of the rest. We should probably note that Julia does not have Float as an alias for specific size floating point numbers (such as Float64). Int reflects the exact size of the pointer native to the machine you are running your code on, while floating points, on the other hand, are specified by the IEEE-754 standard. So, just like in real school, you have some homework to do later...or not. I won't judge.

Summary

To recap, we have covered Type Unions, Parametric Types, Tuple Types, UnionAll Types, and Type Aliases. Hopefully, you have a better understanding of the Julia type system and the power it wields. If you want to learn more about Julia or some other interesting topics, be sure to check out our other blog posts on blog.glcs.io!

Additional Links

• Types Documentation
  • Official Julia documentation on all types
• Understanding the Julia Type System
  • Our previous post on the Julia type system

While serial Julia code can be fast, sometimes even more speed is desired. In many cases, writing parallel code can further reduce run time. Parallel code takes advantage of the multiple CPU cores included in modern computers, allowing multiple computations to run at the same time, or in parallel.

Julia provides two methods for writing parallel CPU code: multi-threading and distributed computing. This post will cover the basics of how to use these two methods of parallel processing.

This post assumes you already have Julia installed. If you haven't yet, check out our earlier post on how to install Julia.

Multi-Threading

First, let's learn about multi-threading.

To enable multi-threading, you must start Julia in one of two ways:

1. Set the environment variable JULIA_NUM_THREADS to the number of threads Julia should use, and then start Julia. For example, JULIA_NUM_THREADS=4.
2. Run Julia with the --threads (or -t) command line argument. For example, julia --threads 4 or julia -t 4.

After starting Julia (either with or without specifying the number of threads), the Threads module will be loaded. We can check the number of threads Julia has available:

julia> Threads.nthreads()
4

The simplest way to start writing parallel code is just to use the Threads.@threads macro. Inserting this macro before a for loop will cause the iterations of the loop to be split across the available threads, which will then operate in parallel. For example:

Threads.@threads for i = 1:10
    func(i)
end

Without Threads.@threads, first func(1) will run, then func(2), and so on. With the macro, and assuming we started Julia with four threads, first func(1), func(4), func(7), and func(9) will run in parallel. Then, when a thread's iteration finishes, it will start another iteration (assuming the loop is not done yet), regardless of whether the other threads have finished their iterations yet. Therefore, this loop will theoretically finish 10 iterations in the time it takes a single thread to do 3.

Note that Threads.@threads is blocking, meaning code after the threaded for loop will not run until the loop has finished.

Julia also provides another macro for multi-threading: Threads.@spawn. This macro is more flexible than Threads.@threads because it can be used to run any code on a thread, not just for loops. But let's illustrate how to use Threads.@spawn by implementing the behavior of Threads.@threads:

# Function for splitting up `x` as evenly as possible
# across `np` partitions.
function partition(x, np)
    (len, rem) = divrem(length(x), np)
    Base.Generator(1:np) do p
        i1 = firstindex(x) + (p - 1) * len
        i2 = i1 + len - 1
        if p <= rem
            i1 += p - 1
            i2 += p
        else
            i1 += rem
            i2 += rem
        end
        chunk = x[i1:i2]
    end
end
N = 10
chunks = partition(1:10, Threads.nthreads())
tasks = map(chunks) do chunk
    Threads.@spawn for i in chunk
        func(i)
    end
end
wait.(tasks)

Let's walk through this code, assuming Threads.nthreads() == 4:

• First, we split the 10 iterations evenly across the 4 threads using partition. So, chunks ends up being [1:3, 4:6, 7:8, 9:10]. (We could have hard-coded the partitioning, but now you have a nice partition function that can work with more complicated partitionings!)
• Then, for each chunk, we create a Task via Threads.@spawn that will call func on each element of the chunk. This Task will be scheduled to run on an available thread. tasks contains a reference to each of these spawned Tasks.
• Finally, we wait for the Tasks to finish with the wait function.

To reemphasize, note that Threads.@spawn creates a Task; it does not wait for the task to run. As such, it is non-blocking, and program execution continues as soon as the Task is returned. The code wrapped in the task will also run, but in parallel, on a separate thread. This behavior is illustrated below:

julia> Threads.@spawn (sleep(2); println("Spawned task finished"))
Task (runnable) @0x00007fdd4b10dc30

julia> 1 + 1 # This code executes without waiting for the above task to finish
2

julia> Spawned task finished # Prints 2 seconds after spawning the above task
julia>

Spawned tasks can also return data. While wait just waits for a task to finish, fetch waits for a task and then obtains the result:

julia> task = Threads.@spawn (sleep(2); 1 + 1)
Task (runnable) @0x00007fdd4a5e28b0

julia> fetch(task)
2

Thread Safety

When using multi-threading, memory is shared across threads. If a thread writes to a memory location that is written to or read from another thread, that will lead to a race condition with unpredictable results. To illustrate:

julia> s = 0;

julia> Threads.@threads for i = 1:1000000
           global s += i
       end

julia> s
19566554653 # Should be 500000500000

There are two methods we can use to avoid the race condition. The first involves using a lock:

julia> s = 0; l = ReentrantLock();

julia> Threads.@threads for i = 1:1000000
           lock(l) do
               global s += i
           end
       end

julia> s
500000500000

In this case, the addition can only occur on a given thread once that thread holds the lock. If a thread does not hold the lock, it must wait for whatever thread controls it to release the lock before it can run the code within the lock block.

Using a lock in this example is suboptimal, however, as it eliminates all parallelism because only one thread can hold the lock at any given moment. (In other examples, however, using a lock works great, particularly when only a small portion of the code depends on the lock.)

The other way to eliminate the race condition is to use task-local buffers:

julia> s = 0; chunks = partition(1:1000000, Threads.nthreads());

julia> tasks = map(chunks) do chunk
           Threads.@spawn begin
               x = 0
               for i in chunk
                   x += i
               end
               x
           end
       end;

julia> thread_sums = fetch.(tasks);

julia> for i in thread_sums
           s += i
       end

julia> s
500000500000

In this example, each spawned task has its own x that stores the sum of the values just in the task's chunk of data. In particular, none of the tasks modify s. Then, once each task has computed its sum, the intermediate values are summed and stored in s in a single-threaded manner.

Using task-local buffers works better for this example than using a lock because most of the parallelism is preserved.

(Note that it used to be advised to manage task-local buffers using the threadid function. However, doing so does not guarantee each task uses its own buffer. Therefore, the method demonstrated in the above example is now advised.)

Packages for Quickly Utilizing Multi-Threading

In addition to writing your own multi-threaded code, there exist packages that utilize multi-threading. Two such examples are ThreadsX.jl and ThreadTools.jl.

ThreadsX.jl provides multi-threaded implementations of several common functions such as sum and sort, while ThreadTools.jl provides tmap, a multi-threaded version of map.

These packages can be great for quickly boosting performance without having to figure out multi-threading on your own.

Distributed Computing

Besides multi-threading, Julia also provides for distributed computing, or splitting work across multiple Julia processes.

There are two ways to start multiple Julia processes:

1. Load the Distributed standard library package with using Distributed and then use addprocs. For example, addprocs(2) to add two additional Julia processes (for a total of three).
2. Run Julia with the -p command line argument. For example, julia -p 2 to start Julia with three total Julia processes. (Note that running Julia with -p will implicitly load Distributed.)

Added processes are known as worker processes, while the original process is the main process. Each process has an id: the main process has id 1, and worker processes have id 2, 3, etc.

By default, code runs on the main process. To run code on a worker, we need to explicitly give code to that worker. We can do so with remotecall_fetch, which takes as inputs a function to run, the process id to run the function on, and the input arguments and keyword arguments the function needs. Here are some examples:

# Create a zero-argument anonymous function to run on worker 2.
julia> remotecall_fetch(2) do
           println("Done")
       end
      From worker 2:    Done

# Create a two-argument anonymous function to run on worker 2.
julia> remotecall_fetch((a, b) -> a + b, 2, 1, 2)
3

# Run `sum([1 3; 2 4]; dims = 1)` on worker 3.
julia> remotecall_fetch(sum, 3, [1 3; 2 4]; dims = 1)
1x2 Matrix{Int64}:
 3  7

If you don't need to wait for the result immediately, use remotecall instead of remotecall_fetch. This will create a Future that you can later wait on or fetch (similarly to a Task spawned with Threads.@spawn).

Separate Memory Spaces

One significant difference between multi-threading and distributed processing is that memory is shared in multi-threading, while each distributed process has its own separate memory space. This has several important implications:

• To use a package on a given worker, it must be loaded on that worker, not just on the main process. To illustrate:

  julia> using LinearAlgebra
  
  julia> I
  UniformScaling{Bool}
  true*I
  
  julia> remotecall_fetch(() -> I, 2)
  ERROR: On worker 2:
  UndefVarError: `I` not defined
  

  To avoid the error, we could use @everywhere using LinearAlgebra to load LinearAlgebra on all processes.

• Similarly to the previous point, functions defined on one process are not available on other processes. Prepend a function definition with @everywhere to allow using the function on all processes:

  julia> @everywhere function myadd(a, b)
             a + b
         end;
  
  julia> myadd(1, 2)
  3
  
  # This would error without `@everywhere` above.
  julia> remotecall_fetch(myadd, 2, 3, 4)
  7
  

• Global variables are not shared, even if defined everywhere with @everywhere:

  julia> @everywhere x = [0];
  
  julia> remotecall_fetch(2) do
             x[1] = 2
         end;
  
  # `x` was modified on worker 2.
  julia> remotecall_fetch(() -> x, 2)
  1-element Vector{Int64}:
   2
  
  # `x` was not modified on worker 3.
  julia> remotecall_fetch(() -> x, 3)
  1-element Vector{Int64}:
   0
  

  If needed, an array of data can be shared across processes by using a SharedArray, provided by the SharedArrays standard library package:

  julia> @everywhere using SharedArrays
  
  # We don't need `@everywhere` when defining a `SharedArray`.
  julia> x = SharedArray{Int,1}(1)
  1-element SharedVector{Int64}:
   0
  
  julia> remotecall_fetch(2) do
             x[1] = 2
         end;
  
  julia> remotecall_fetch(() -> x, 2)
  1-element SharedVector{Int64}:
   2
  
  julia> remotecall_fetch(() -> x, 3)
  1-element SharedVector{Int64}:
   2
  

Now, a note about command line arguments. When adding worker processes with -p, those processes are spawned with the same command line arguments as the main Julia process. With addprocs, however, each of those added processes are started with no command line arguments. Below is an example of where this behavior might cause some confusion:

$ JULIA_NUM_THREADS=4 julia --banner=no -t 1
julia> Threads.nthreads()
1

julia> using Distributed

julia> addprocs(1);

julia> remotecall_fetch(Threads.nthreads, 2)
4

In this situation, we have the environment variable JULIA_NUM_THREADS (for example, because normally we run Julia with four threads). But in this particular case we want to run Julia with just one thread, so we set -t 1. Then we add a process, but it turns out that process has four threads, not one! This is because the environment variable was set, but no command line arguments were given to the added process. To use just one thread for the added process, we would need to use the exeflags keyword argument to addprocs:

addprocs(1; exeflags = ["-t 1"])

As a final note, if needed, processes can be removed with rmprocs, which removes the processes associated with the provided worker ids.

Summary

In this post, we have provided an introduction to parallel processing in Julia. We discussed the basics of both multi-threading and distributed computing, how to use them in Julia, and some things to watch out for.

As a parting piece of advice, when choosing whether to use multi-threading or distributed processing, choose multi-threading unless you have a specific need for multiple processes with distinct memory spaces. Multi-threading has lower overhead and generally is easier to use.

How do you use parallel processing in your code? Let us know in the comments below!

Additional Links

• Multi-Threading
  • Official Julia documentation on multi-threading.
• Multi-processing and Distributed Computing
  • Official Julia documentation on distributed computing.

MATLAB is a registered trademark of The MathWorks, Inc.