Research compendium including code written in Julia

This is a template repository, i.e. a repository that can be used to populate a repository when starting a new project from scratch.

This repository includes:

1. a minimal example in script.jl
2. A working workflow to test the code on GitHub actions.

⚠️ Please, avoid long run when your project is private as we have a limited number of seconds per month for private repository.

Style guide

This section describes the coding style rules preferred in the lab (NB this was started by @gabrielgellner). They are heavily based on the JuMP style guides, though there are exceptions.

Formatting

Julia unfortunately does not have an autoformatting tool like gofmt. Until a reliable autoformatting tool is available, we adopt the following conventions.

Whitespace

For conciseness, never use more than one blank line within a function, and never begin a function with a blank line.

Bad:

function foo(x)
    y = 2 * x


    return y
end

function foo(x)

    y = 2 * x
    return y
end

Julia is mostly insensitive to whitespace characters within lines. For consistency:

• Use spaces between binary operators (with some exceptions, see below)
• Use a single space after commas and semicolons
• Do not use extra spaces for unary operators, parentheses, or braces
• Indent within new blocks (except module) using 4 spaces

Good:

f(x, y) = [3 * dot(x, y); x']

Bad:

f(x,y) = [ 3*dot(x,y) ; x' ]

Good:

module Foo

function f(x)
    return x + 1
end

end # module Foo

Exceptions

We make an exception for the : operator when it is used to form a range.

Good:

x = 1:5

Bad:

x = 1 : 5

One reason is that it can be confused with Julia's conditional statement: cond ? x : y which requires whitespace around the :.

Good:

2 * x  # This is preferred if space is not an issue.
2 * (x + 1)

Bad:

2(x + 1)

Return statements

To avoid situations in which it is unclear whether the author intended to return a certain value or not, always use an explicit return statement to exit from a function. If the return from a function is nothing, use return instead of return nothing.

We make an exception for assignment-form one-line functions (f(x) = 2 * x).

Good:

foo(x) = 2 * x  # Acceptable if one line
function foo(x)
    return 2 * x
end
function foo!(x)
    x[1] += 1
    return
end

Bad:

function foo(x)
    2x
end
function foo!(x)
    x[1] += 1
    return nothing
end

Figure plotting

PyPlot is a nice option for plotting. Go here for example coding with PyPlot.

To automatically open plots outside of Atom, disable the Plot Pane in the UI Options of the Juno Settings.

Whenever plotting a figure ensure that the code follows below:

    plot_name = figure()
    plot()
    plotoptions
    return plot_name

To ease figure creation, place plotting code in a let block.