# Introduction

*SpineOpt.jl* is an integrated energy systems optimization model created as part of the Spine project, striving towards adaptability for a multitude of modelling purposes. The data-driven model structure allows for highly customizable energy system descriptions, as well as flexible temporal and stochastic structures, without the need to alter the model source code directly. The methodology is based on mixed-integer linear programming (MILP), and *SpineOpt* relies on *JuMP.jl* for interfacing with the different solvers.

While, in principle, it is possible to run *SpineOpt* by itself, it has been designed to be used through the Spine toolbox, and take maximum advantage of the data and modelling workflow management tools therein. Thus, we highly recommend installing *Spine toolbox* as well, as outlined in the Installation guide.

## Contents

In order to make it easier for you to familiarize yourself with the documentation, here's a list of all the different chapters, as well as descriptions of what they're about.

### Getting Started

As the name implies, this chapter contains guides for starting to use *SpineOpt.jl* for the first time. The Installation section contains a step-by-step guide for how to install *SpineOpt.jl* and *Spine Toolbox* on your computer. The Setting up a workflow for SpineOpt in Spine Toolbox section explains how to set up and run *SpineOpt.jl* from *Spine Toolbox*. The Creating Your Own Model section explains how to create a new model from scratch. This includes a list of the necessary Object Classes and Relationship Classes, but for more information, you will probably need to consult the **Concept Reference** chapter.

### Concept Reference

This chapter lists and explains all the important *data and model structure related concepts* to understand in *SpineOpt.jl*. For a mathematical modelling point of view, see the **Mathematical Formulation** chapter instead. The Basics of the model structure section briefly explains the general purpose of the most important concepts, like Object Classes and Relationship Classes. Meanwhile, the Object Classes, Relationship Classes, Parameters, and Parameter Value Lists sections contain detailed explanations of each and every aspect of *SpineOpt.jl*, organized into the respective sections for clarity.

### Mathematical Formulation

This chapter provides the mathematical view of *SpineOpt.jl*, as some of the methodology-related aspects of the model are more easily understood as math than Julia code. The Variables section explains the purpose of each variable in the model, as well as how the variables are related to the different Object Classes and Relationship Classes. The Constraints section contains the mathematical formulation of each constraint, as well as explanations to their purpose and how they are controlled via different Parameters. Finally, the Objective section explains the default objective function used in *SpineOpt.jl*.

### Advanced Concepts

This chapter explains some of the more complicated aspects of *SpineOpt.jl* in more detail, hopefully making it easier for you to better understand and apply them in your own modelling. The first few sections focus on aspects of *SpineOpt.jl* that most users are likely to use, or which are more or less required to understand for advanced use. The Temporal Framework section explains how defining *time* works in *SpineOpt.jl*, and how it can be used for different purposes. The Stochastic Framework section details how different stochastic structures can be defined, how they interact with each other, and how this impacts writing Constraints in *SpineOpt.jl*. The Unit commitment section explains how clustered unit-commitment is defined, while the Ramping and Reserves section explains how to enable these operational details in your model. The Investment Optimization section explains how to include investment variables in your models, while the Unit Constraints section details how to include generic data-driven custom constraints.

The last few sections focus on highly specialized use-cases for *SpineOpt.jl*, which are unlikely to be relevant for simple modelling tasks. The Decomposition section explains the Benders decomposition implementation included in *SpineOpt.jl*, as well as how to use it. The remaining sections, namely PTDF-Based Powerflow, Pressure driven gas transfer, Lossless nodal DC power flows, and Representative days with seasonal storages, explain various use-case specific modelling approaches supported by *SpineOpt.jl*.