SpineOpt.jl

A Julia package containing a state-of-the-art energy system optimization model.

📢 Community and how to ask help 🚀

There are four main ways to get help with SpineOpt.

1. Monthly user meetings for Spine Toolbox and SpineOpt. There you can connect with other users, present problems and exchange experiences. New and old users equally welcome. The meetings are held first Tuesday of every month at 3pm CEST 📆 ics zip and can be joined here.
2. Gitter (i.e. Matrix) chat service. You need to register but allows to ask quick questions and hopefullly get quick answers.
3. Discussion forum (support section) can be used when you don't know how to get something done or you don't quite know why something isn't working. It's highly appreciated if other users can contribute by helping each other (developers are short on time).
4. Issue tracker should be used only when there is a missing feature or something should work but it's not working. Update your tools and test with latest software before submitting an issue. In case of new feature, make sure there is no existing issue. Issues reporting bugs should provide sufficient information to enable locating and fixing the bug.

Compatibility

This package requires Julia 1.6 or higher.

Installation

SpineOpt is designed to be used with Spine Toolbox.

1. Install Spine Toolbox as described here.

2. Download and install the latest version of Julia for your system as described here.

3. 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:

   1. Start the Julia REPL.
   2. Copy and paste the following text into the julia prompt:

      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:

   1. Git-clone this repository into your local machine.
   2. Git-clone the SpineInterface repository into your local machine.
   3. Start the Julia REPL.
   4. Run the following commands from the julia prompt, replacing your local SpineOpt and SpineInterface paths

      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

   5. If you want your local SpineOpt to use your local SpineInterface, you also need to 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

   6. Lastly, you should probably make sure all the required dependencies are installed using the 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)

4. 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.

Upgrading

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.

1. 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"

2. 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"

Usage

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.)

Documentation

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.

Compilation into a Julia system image

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:

1. Install PackageCompiler.jl.

2. 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.

3. 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")

4. Start Julia with --sysimage=SpineOpt.dll to use the generated image.

Troubleshooting

Problem

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
...

Solution

1. 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

2. Try to install SpineOpt again.

Problem

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
...

Solution

1. Install .NET 4.5 from here: https://www.microsoft.com/en-US/download/details.aspx?id=30653.

2. 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.

3. Try to install SpineOpt again.

Reporting Issues and Contributing

See CONTRIBUTING.md

License

SpineOpt is licensed under GNU Lesser General Public License version 3.0 or later.

Citing 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

Acknowledgements

	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.