Spine-project / SpineOpt.jl

SpineOpt.jl

A package to run an energy system integration model called SpineOpt.

❗ ❗ GitHub organisation has been renamed!

New name spine-tools, used to be spine-project (19.1.2023). Update your weblinks and git origin to all repositories (in each repository folder git remote set-url origin https://github.com/spine-tools/repository-name): Spine Toolbox, SpineOpt.jl, SpineInterface.jl, Spine-Database-API, spine-engine, spine-items.

📢UPDATE: Community 🚀

To connect with other users, to identify problems and exchange experiences, we will organize monthly early-user meetings for Spine Toolbox and SpineOpt. The meetings will be held first Tuesday of every month at 3pm CEST 📆 ics zip and can be joined here..

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
      pkg"registry add General https://github.com/spine-tools/SpineJuliaRegistry"
      pkg"add SpineOpt"

   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
      pkg"dev <path-to-your-local-SpineInterface-repository>"
      pkg"dev <path-to-your-local-SpineOpt-repository>"

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.

Upgrading

SpineOpt is constantly improving. To get the most recent version, just:

1. Start the Julia REPL.

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

Usage

For an example of how to use SpineOpt in your Spine Toolbox projects, please see 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.