Style Guide

Most of the style guidelines are based on the Julia Style Guide and the JuMP Style Guide. Please refer to these guides for more details.

In this document we will cover some specific guidelines for IARA.jl.

Folder Structure

The folder structure of the project is organized to separate concerns and improve maintainability. Below is a brief description of the main directories:

  • compile: Contains scripts and configurations for compiling the project.
  • database: Includes migration scripts and metadata for the attributes of each table in the database.
  • docker: Contains a dockerfile and related files for building a docker image capable of simulating a day-to-day operation of the system.
  • docs: Documentation files for the project, including this style guide.
  • format: Scripts and configurations for code formatting using JuliaFormatter.jl.
  • profiling: Profiling scripts to analyze and optimize performance.
  • revise: Utilities for live code reloading during development.
  • src: The main source code of the project, organized into submodules for different functionalities.
  • test: Test cases and scripts for verifying the correctness of the project.

Each subdirectory in src corresponds to a specific module or functionality, and its structure is designed to keep related code together for better organization.

More specifically, the src directory is organized as follows:

  • collections: Contains the data structures for each collection of the model, with their respective attributes and methods.
  • external_time_series: Contains methods for reading and writing time series files.
  • interface_calls: Contains the methods compatible with the docker image generated by the docker folder.
  • model_constraints: Contains the methods for generating the constraints of the model.
  • model_variables: Contains the methods for generating the variables of the model.
  • plots: Contains the methods for generating the plots of the model.
  • post_processing: Contains the methods for post-processing the results of the model.

In addition to the subdirectories, the src folder also contains other .jl files, including some utility functions and methods related to the optimization problem, such as mathematical_model.jl, that contains functions to build the optimization model, using methods from the model_variables and model_constraints subdirectories.

IARA.jl
├── compile
├── database
├── docker
├── docs
├── format
├── profiling
├── revise
├── src
│   ├── collections
|   |     └── ...
|   ├── external_time_series
|   |     └── ...
|   ├── interface_calls
|   |     └── ...
|   ├── model_constraints
|   |     └── ...
|   ├── model_variables
|   |     └── ...
|   ├── plots
|   |     └── ...
|   ├── post_processing
|   |     └── ...
|   └── ...
├── test
└── ...

Code Formatting

To ensure uniform formatting, this project uses JuliaFormatter.jl. You can format your code just by running the following commands:

julia --project=format 'format/format.jl'

Make sure you format your code before committing it. Otherwise, a CI job will run the JuliaFormatter.jl and raise an error if the code is not formatted correctly.

Testing

We use Test.jl for testing. The tests are located in the test directory of the project.

The tests are organized into subdirectories based on the module they test. Each module is related to a base case and its variants. A base case is created in the base_case subdirectory, using the build_case.jl script, and its variants are created in their respective subdirectories, with a modify_case.jl file that modifies the base case. Finally, each subdirectory contains a test_case.jl file that contains the tests for that specific case.

Example Case 1:

test/case_01
├── base_case
│   ├── ...
│   ├── build_case.jl
│   └── test_case.jl
├── ...
|
└── ac_line_case
    ├── ...
    ├── modify_case.jl
    └── test_case.jl

In order to run all the tests, you can run the following command in the root directory of the project:

julia --project=test -e "import Pkg; Pkg.Registry.update(); Pkg.test()"