How to run Pumas tutorials using Quarto and Julia

Author

Jaya Shree Dilli Batcha

Aim

To learn how to run the Pumas tutorial using Quarto (.qmd) and Julia (.jl) files.

Step-by-step guide

There are two ways to follow the tutorials:

  1. Running the code using a Quarto (.qmd) file.
  2. Running the code using a Julia (.jl) file.

Learning through quarto file

  • First, download a tutorial from the PumasAI tutorials.

  • The tutorials can be downloaded using the “Download tutorial” option available at the top right corner of each tutorial page, as shown in the figure below.

Note: The tutorial can be downloaded by clicking on the download tutorial option shown inside the red box.

  • The downloaded file will be a quarto (.qmd) file.

  • Open the downloaded file in the VS Code.

Where to Run the Quarto file?
  • If you are using the Pumas Desktop application on Windows or Mac, you should have a local install of VS Code. You can run the Quarto file in VS Code.
  • If you are using Pumas via JuliaHub, you can run the Quarto file in the PumasIDE environment (Code Server).
  • When you open a quarto file in VS Code or Code Server, you will first see the YAML metadata enclosed within --- at the top of the .qmd file. This section defines various document properties, including the title, formatting, execution settings, and author details.
What is YAML?

YAML (Yet Another Markup Language) is a human-readable data format used primarily for configuration files and data serialization. It uses indentation to structure data, making it easier to read and modify. YAML is widely used in applications like Quarto, to define settings in a structured manner.

More information on metadata customization can be found here: Setting options with YAML

  • The code chunks in a Quarto file for running the code will look as shown below:

Code Chunks
  • Code chunks in Quarto allow you to run Julia code inside a .qmd file. These chunks are enclosed in triple backticks (```) and specified with {julia}, as you can see in the image above. This chunk executes the Julia code inside it and displays the output.
Tip

  • If you are using the Pumas Desktop application, before you run a particular code chunk, ensure that you started Pumas by starting the Julia REPL terminal. You can do this calling the command palette (Ctrl + Shift + P) and typing “Julia: Start REPL” in the command palette. This will start the Pumas environment in the Julia REPL terminal. Once the license information is loaded, you can initiate Pumas by running the command using Pumas in the Julia REPL terminal. This will load the Pumas package and make it available for use in your code chunks.

  • If you are using Pumas via JuliaHub, the Pumas environment is already set up for you in the PumasIDE environment (Code Server). All you have to do is load Pumas using using Pumas in the REPL to get started.

  • Quarto allows customization of how code chunks behave using chunk options. For example:

    • label: example Assigns a label to the code chunk. Labels are useful for referencing chunks elsewhere in the document, especially in numbered outputs.
    • output: true Displays the evaluated output. Set to false to prevent the output from being shown.
    • eval: true Runs the code (set to false to disable execution).
    • echo: false Hides the code in the output but shows results.
    • message: false Suppresses any messages from execution.
    • warning: false Prevents warnings from appearing in the output.

  • You can execute the code chunk using the “Run Cell” option (▶️) or by pressing Shift + Enter.

  • The output of each code chunk execution will appear in the Julia REPL terminal as shown below.

Output
Tip

Only the last line of a code chunk’s output will be rendered in the final output file. If you want to see all outputs for each piece of code, consider writing each section in separate code chunks.

  • You can render the final Quarto document into an HTML file by pressing Shift + Ctrl + K (in Windows) or Shift + Command + K (in Mac). This allows you to view the complete document, including code, output, and all content, in a well-organized and readable format.
Note

The Quarto document can be rendered into different output formats, such as HTML, PDF, or Word (.docx), based on the requirement. This must be specified in the format section of the YAML metadata.

Learning through julia file

  • To follow the Pumas tutorial in Julia, create a new .jl file in VS Code.

  • In the new Julia file, copy the code from the tutorial’s code chunks from the rendered html in tutorials.pumas.ai using the “Copy to Clipboard” 📋 option, as shown below.

Note: Copy the codes by clicking on the copy to clipboard icon

  • After pasting the code from all the chunks, execute it using Shift + Enter to run the current line and move to the next one, or Ctrl + Enter to execute only the current line.

  • The output of the executed code will be displayed in the Julia REPL terminal.