A highly adaptable modelling framework for multi-energy systems
A Julia package containing a state-of-the-art energy system optimization model.
There are four main ways to get help with SpineOpt.
Please cite this article when referring to SpineOpt in scientific writing.
Ihlemann, M., Kouveliotis-Lysikatos, I., Huang, J., Dillon, J., O'Dwyer, C., Rasku, T., Marin, M., Poncelet, K., & Kiviluoma, J. (2022). SpineOpt: A flexible open-source energy system modelling framework. Energy Strategy Reviews, 43, [100902]. https://doi.org/10.1016/j.esr.2022.100902
This package requires Julia 1.6 or higher.
SpineOpt is designed to be used with Spine Toolbox.
Install Spine Toolbox as described here.
Download and install the latest version of Julia for your system as described here.
Install SpineOpt using one of the below options:
a. If you want to use SpineOpt but not develop it, we recommend installing it from the Spine Julia Registry:
using Pkg # Use the package manager. Alternatively, use `]` in REPL
pkg"registry add General https://github.com/spine-tools/SpineJuliaRegistry" # Add SpineJuliaRegistry as an available registry for your Julia
pkg"add SpineOpt" # Install SpineOpt from the SpineJuliaRegistry
b. If you want to both use and develop SpineOpt, we recommend installing it from sources:
using Pkg # Use the package manager. Alternatively, use `]` in REPL
pkg"dev <path-to-your-local-SpineInterface-repository>" # Installs the local version of SpineInterface
pkg"dev <path-to-your-local-SpineOpt-repository>" # Installs the local version of SpineOpt
develop
the SpineInterface dependency manually:
using Pkg # Use the package manager. Alternatively, use `]` in REPL
pkg"activate <path-to-your-local-SpineOpt-repository>" # Activate the local SpineOpt environment
pkg"dev <path-to-your-local-SpineInterface-repository>" # Install the local SpineInterface into the local SpineOpt environment
instantiate
command:using Pkg # Use the package manager. Alternatively, use `]` in REPL
pkg"activate <path-to-your-local-SpineInterface-repository>" # Activate the local SpineInterface environment
pkg"instantiate" # Install SpineInterface dependencies
pkg"activate <path-to-your-local-SpineOpt-repository>" # Activate the local SpineOpt environment
pkg"instantiate" # Install SpineOpt dependencies (SpineInterface already installed locally in step 5)
Configure Spine Toolbox to use your Julia:
a. Run Spine Toolbox.
b. Go to File -> Settings -> Tools.
c. Under Julia, enter the path to your Julia executable. It should look something like this. In case you have multiple Julia's in your system, the path should point to the same Julia version as is in your environment PATH.
d. Press Ok.
It doesn't work? See our Troubleshooting section.
If you want to run SpineOpt outside Spine Toolbox, you need to configure SpineInterface PyCall using the instructions at the end of SpineInterface installation instructions.
SpineOpt is constantly improving. To get the most recent version, upgrade SpineOpt using one of the following methods, depending on how you have installed it.
If you have installed SpineOpt from the registry:
a. Start the Julia REPL.
b. Copy/paste the following text into the julia prompt (it will update the SpineOpt package from the Spine Julia Registry):
using Pkg
pkg"up SpineOpt"
If you have installed SpineOpt from the sources:
a. Git-pull the latest master from this repository.
b. Git-pull the latest master from the SpineInterface repository.
c. Start the Julia REPL.
d. Copy/paste the following text into the julia prompt:
using Pkg
pkg"up SpineOpt"
For how to use SpineOpt in your Spine Toolbox projects, please start from here. (We apologize for the lengthiness of that example. We're currently working on a minimal example that will get you started faster.)
SpineOpt documentation, including getting started guide and reference, can be found here: Documentation. Alternatively, one can build the documentation locally, as it is bundled in with the source code.
First, navigate into the SpineOpt main folder and activate the docs
environment from the julia package manager:
(SpineOpt) pkg> activate docs
(docs) pkg>
Next, in order to make sure that the docs
environment uses the same SpineOpt version it is contained within,
install the package locally into the docs
environment:
(docs) pkg> develop .
Resolving package versions...
<lots of packages being checked>
(docs) pkg>
Now, you should be able to build the documentation by exiting the package manager and typing:
julia> include("docs/make.jl")
This should build the documentation on your computer, and you can access it in the docs/build/
folder.
Sometimes it can be useful to 'compile' SpineOpt into a so-called system image. A system image is a binary library that, roughly speaking, 'stores' all the compilation work from a previous Julia session. If you start Julia with a system image, then Julia doesn't need to redo all that work and your code will be fast the first time you run it.
However if you upgrade your version of SpineOpt, any system images you might have created will not reflect that change - you will need to re-generate them.
To compile SpineOpt into a system image just do the following:
Install PackageCompiler.jl.
Create a file with precompilation statements for SpineOpt:
a. Start julia with --trace-compile=file.jl
.
b. Call run_spineopt(url...)
with a nice DB - one that triggers most of SpineOpt's functionality you need.
c. Quit julia.
Create the sysimage using the precompilation statements file:
a. Start julia normally.
b. Create the sysimage with PackageCompiler:
using PackageCompiler
create_sysimage(; sysimage_path="SpineOpt.dll", precompile_statements_file="file.jl")
Start Julia with --sysimage=SpineOpt.dll
to use the generated image.
Some of the development of SpineOpt depends on the development of SpineInterface and vice versa. At some points in time that can create an incompatibility between the two.
You could get an error like:
ERROR: LoadError: MethodError: no method matching MathOptInterface.EqualTo(::SpineInterface.Map{Symbol, SpineInterface.TimeSeries{Float64}})
Closest candidates are:
MathOptInterface.EqualTo(::T) where T\<:Number at C:\\Users\\prokjt.julia\\packages\\MathOptInterface\\vwZYM\\src\\sets.jl:223
It might just be a matter of time before the projects are updated. In the meanwhile you can check the issues whether someone has already reported the out-of-sync issue or otherwise create the issue yourself.
In the meanwhile you can try another version. One option is to update directly from the github repository instead of the julia registry:
using Pkg
Pkg.add(url="https://github.com/spine-tools/SpineInterface.jl.git")
Another option is to use the developer version as described in the installation section.
Using Julia 1.5.3 on Windows, installation fails with one of the following messages (or similar):
julia> pkg"add SpineOpt"
Updating registry at `C:\Users\manuelma\.julia\registries\General`
Updating git-repo `https://github.com/JuliaRegistries/General.git`
Updating registry at `C:\Users\manuelma\.julia\registries\SpineRegistry`
Updating git-repo `https://github.com/spine-tools/SpineJuliaRegistry`
Resolving package versions...
ERROR: expected package `UUIDs [cf7118a7]` to be registered
...
julia> pkg"add SpineOpt"
Updating registry at `C:\Users\manuelma\.julia\registries\SpineRegistry`
Updating git-repo `https://github.com/spine-tools/SpineJuliaRegistry`
Resolving package versions...
ERROR: cannot find name corresponding to UUID f269a46b-ccf7-5d73-abea-4c690281aa53 in a registry
...
Reset your Julia General registry. Copy/paste the following in the julia prompt:
using Pkg
rm(joinpath(DEPOT_PATH[1], "registries", "General"); force=true, recursive=true)
withenv("JULIA_PKG_SERVER"=>"") do
pkg"registry add"
end
Try to install SpineOpt again.
On Windows 7, installation fails with the following message (or similar):
julia> pkg"add SpineOpt"
...
Downloading artifact: OpenBLAS32
Exception setting "SecurityProtocol": "Cannot convert null to type "System.Net.
SecurityProtocolType" due to invalid enumeration values. Specify one of the fol
lowing enumeration values and try again. The possible enumeration values are "S
sl3, Tls"."
At line:1 char:35
+ [System.Net.ServicePointManager]:: <<<< SecurityProtocol =
+ CategoryInfo : InvalidOperation: (:) [], RuntimeException
+ FullyQualifiedErrorId : PropertyAssignmentException
...
Install .NET 4.5 from here: https://www.microsoft.com/en-US/download/details.aspx?id=30653.
Install Windows management framework 3 or later, from here https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/wmf/overview?view=powershell-7.1.
Try to install SpineOpt again.
See CONTRIBUTING.md
SpineOpt is licensed under GNU Lesser General Public License version 3.0 or later.
This work has been partially supported by EU project Mopo (2023-2026), which has received funding from European Climate, Infrastructure and Environment Executive Agency under the European Union’s HORIZON Research and Innovation Actions under grant agreement N°101095998. | |
This work has been partially supported by EU project Spine (2017-2021), which has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 774629. |