diff --git a/README.md b/README.md index 7d1bb3f01..a62a86b2a 100644 --- a/README.md +++ b/README.md @@ -249,6 +249,72 @@ are not needed and there is a chance of conflicts between the packages. **Note**: Python 3.8.0 is not supported. Use Python 3.8.1 or later. +## Recorded Webinars showing the use of Spine Tools + +### Spine Toolbox: Data, workflow and scenario management for modelling +*Wednesday Sep 8, 17:00-18:30 CEST (11:00-12:30 EDT) - Organized together with G-PST* + +Spine Toolbox is an open source software to manage data, scenarios and workflows for modelling and simulation. You can have your local workflow, but work as a team through version control and SQL databases. This webinar gives a quick overview of the different functionalities and showcases them through two examples. + +Recording Chapters: +- [00:00-00:05](https://www.youtube.com/watch?v=jaDIxonOmfY) Relation to G-PST Pillar 5 (Clayton Barrows, NREL) +- [00:05-00:35](https://youtu.be/jaDIxonOmfY?t=1350) Building a workflow in Spine Toolbox [PDF](http://www.spine-model.org/pdf/webinar/Spine%20Toolbox%20-%20Building%20a%20workflow%20in%20Toolbox%20by%20Juha%20Kiviluoma.pdf), *(Juha Kiviluoma, VTT)* +- [00:35-00:55](https://youtu.be/jaDIxonOmfY?t=2445) Example workflow from Canada to manage lots of input sources [PDF](http://www.spine-model.org/pdf/webinar/Spine%20Toolbox%20-%20Case%20in%20energy%20system%20integration%20with%20Toolbox%20by%20Madeleine%20McPherson%20and%20Jacob%20Monroe.pdf), *(Madeleine McPherson and Jake Monroe, University of Victoria)* +- [01:05-01:15](https://youtu.be/jaDIxonOmfY?t=3722) Example workflow from EU project TradeRES to serve +multiple models *(Milos Cvetkovic and Jim Hommes, TU Delft)* +- [01:15-01:30](https://youtu.be/jaDIxonOmfY?t=4500) Moderated Q&A + +### SpineOpt: A flexible energy system modelling framework in Julia +*Tuesday Sep 7, 14:00-15:30 CEST (8:00-9:30 EDT) - Organized together with EERA ESI* + +The importance of operational details in planning future energy systems has been rapidly increasing. One driver for this is the increasing role of variable power generation, which requires that the energy system models consider higher temporal granularity, longer time series and new aspects in power system stability. Another important driver is a consequence of sector coupling through the electrification of transport, space heating and industries. As the other sectors become more integrated with electricity, they need to be modelled at a granularity that is sufficient for describing the potential flexibility they can bring to the power system dominated by variable and uncertain power generation. + +This webinar will present the open source Julia based energy system modelling framework SpineOpt, which has been built with these challenges in mind. It can represent different energy sectors using representation typically available only in sector specific models and with highly adaptable temporal and stochastic structures available both for planning and operations. More information at https://spine-project.github.io/SpineOpt.jl/latest/index.html. + +Recording Chapters: +- [00:00-00:08](https://www.youtube.com/watch?v=FiiqZNcx7Ds) Introduction [PDF](http://www.spine-model.org/pdf/webinar/SpineOpt_Introduction%20by%20Erik%20Delarue.pdf) +- [00:08-00:31](https://www.youtube.com/watch?v=FiiqZNcx7Ds&t=475s) Basic elements of SpineOpt and the flexible spatial structure [PDF](http://www.spine-model.org/pdf/webinar/SpineOpt_Basic%20elements%20of%20SpineOpt%20by%20Maren%20Ihlemann.pdf) +- [00:31-00:40](https://youtu.be/FiiqZNcx7Ds?t=1876) Adaptable temporal and stochastic structures [PDF](http://www.spine-model.org/pdf/webinar/SpineOpt_Flexible%20temporal%20and%20stochastic%20structure%20by%20Topi%20Rasku.pdf) +- [00:50-01:30](https://youtu.be/FiiqZNcx7Ds?t=3608) Representation of different energy sectors & +Attempts to make the model faster [PDF](http://www.spine-model.org/pdf/webinar/SpineOpt_Different%20energy%20sectors%20and%20accomodating%20complexity%20by%20Jody%20Dillon.pdf) +- [01:25-01:35](https://youtu.be/FiiqZNcx7Ds?t=5065) Q&A + Step-by-step 10 minute demo on how to build a simple model with SpineOpt using Spine Toolbox + +### Demonstration of Spine modelling tools through selected case studies +*Thursday Sep 9, 14:00-16:00 CEST (8:00-10:00 EDT)* + +[Full recording](https://youtu.be/i2fxDwsMuF8), all presentations slides [PDF](http://www.spine-model.org/pdf/webinar/Case_Studies_all_presentations.pdf) + +Over the past 4 years, the EU project Spine has developed a set of open-source tools for modelling complex energy systems. This webinar demonstrates the Spine software through six selected case studies, covering topics such as sector coupling, co-optimization of operation and investments, stochastic modelling, and rolling horizon optimization. Each subsection described below consists of a brief introduction followed by a live demonstration of the particular case, where some of the outstanding features of Spine are highlighted and discussed. + +Recording Chapters: +- [00:05-00:15](https://youtu.be/i2fxDwsMuF8?t=252) Introduction to Spine: This section uses a simple example to demonstrate the SpineOpt modelling principle. First, the user defines the different objects in their system, such as units and nodes, as well as the relationships between them, such as which units are connected to which nodes. Then, they specify values for certain pre-defined parameters such as node demand, unit capacity, cost, and conversion ratio. The resulting dataset is passed to SpineOpt which generates the corresponding optimisation model, optimizes it, and delivers the results. +- [00:15-00:30](https://youtu.be/i2fxDwsMuF8?t=939) Hydro: This section demonstrates hydropower modelling in Spine as performed in Case study A5. The objective is to model part of the Swedish hydropower system, namely the Skellefte river with its 15 power stations, by coupling the river system with the power system. The model maximizes income from electricity supply over one week with an hourly resolution, while respecting basic hydrological constraints. +- [00:29-00:45](https://youtu.be/i2fxDwsMuF8?t=1745) Building heating: This section demonstrates building heating modelling in Spine as performed in Case study A4. The objective is to model the Finnish power and district heating system coupled with an electrically heated residential building stock. The result is a rolling unit commitment and economic dispatch model, that optimizes system performance over one year at hourly resolution. +- [00:45-00:57] Break +- [00:57-01:06](https://youtu.be/i2fxDwsMuF8?t=3411) Gas grid: This section demonstrates gas grid modelling in Spine as performed in Case study A2. The objective is to model a natural gas transmission system with pressure-driven gas and couple it with an electricity system to capture the flexibility provided by the gas network. The result is a dispatch model that co-optimizes operations in both systems over a day at hourly resolution. +- [01:06-01:22](https://youtu.be/i2fxDwsMuF8?t=3992) Stochastic: This section demonstrates stochastic modelling in Spine using a simple example system. Three different stochastic structures are demonstrated: purely deterministic, stochastic fan, and converging fan. +- [01:22-01:35](https://youtu.be/i2fxDwsMuF8?t=4970) Power grid investments: This section demonstrates power grid investment modelling in Spine as performed in case study C2. The objective is twofold: (i) to model the Nordic synchronous power system (Norway, Sweden, Finland, and Denmark) with high operational detail; and (ii) to find optimal transmission line investment decisions over a long-term horizon of 10 years, for three different wind penetration scenarios. +- [01:35-01:40](https://youtu.be/i2fxDwsMuF8?t=5652) Q&A + +### SpineInterface: How to quickly and easily create new optimization models in Julia Friday +*Friday Sep 10, 14:00-15:30 CEST (8:00-9:30 EDT)* + +[Full recording](https://youtu.be/cUopRUTzXpY), all presentations [PDF](http://www.spine-model.org/pdf/webinar/SpineInterface_all_presentations.pdf) + +Creation of new optimisation models requires a lot of work to get the data to the models and the results out of the models. Spine Toolbox is an open source data and workflow management tool to assist with these tasks and can work with models written in any language. Meanwhile, SpineInterface is a Julia package that links the data management capabilities of Spine Toolbox with Julia/JuMP modelling environment in a very direct way. + +The data interfaces of Spine Toolbox together with SpineInterface simplifies the process of developing optimization models by allowing the model developer to focus on the constraint equations. The required data structures and data are defined with a graphical interface in Spine Toolbox and are immediately available to the model developer inside the constraint equation code without any action or code required by the model developer. SpineInterface supports the full range of data parameter types supported by Toolbox and provides a mechanism for representation of time and time-based data, either time series, time patterns or arbitrarily varying temporal data. + +This session will be of interest to model developers and/or students who want a significant head start in developing optimization models. The sessions will also be of interest to model developers who may wish to translate existing models developed in other platforms such as GAMS, into the Spine framework using SpineInterface. The power of SpineInterface will be demonstrated in an interactive session where the full modelling workflow will be illustrated from data structure design and implementation to constraint equation development. + +Agenda: +- Overview of SpineInterface +- Toolbox concepts and data structures including the Spine data API +- SpineInterface: convenience functions and accessing Spine Toolbox data in Julia +- Defining a model data structure in Spine Toolbox +- Building and solving an optimization model using SpineInterface +- Q&A + live demo [00:45-01:21](https://youtu.be/cUopRUTzXpY?t=2737) + ## Contribution Guide All are welcome to contribute! diff --git a/docs/source/contribution_guide.rst b/docs/source/contribution_guide.rst index e29452b03..d051a2fdf 100644 --- a/docs/source/contribution_guide.rst +++ b/docs/source/contribution_guide.rst @@ -1,5 +1,4 @@ .. Contribution guide - Created: 19.6.2018 .. _Qt Style Sheets: http://doc.qt.io/qt-5/stylesheet.html .. _PEP-8: https://www.python.org/dev/peps/pep-0008/ @@ -7,9 +6,9 @@ .. _Contribution Guide: -************************************ -Contribution Guide for Spine Toolbox -************************************ +****************** +Contribution Guide +****************** All are welcome to contribute! This guide is based on a set of best practices for open source projects [JF18]_. Reporting Bugs diff --git a/docs/source/data_import_export.rst b/docs/source/data_import_export.rst index d88ad253e..afc5ddb78 100644 --- a/docs/source/data_import_export.rst +++ b/docs/source/data_import_export.rst @@ -1,5 +1,4 @@ .. Importing and exporting data - Created: 15.5.2019 .. |open-folder| image:: ../../spinetoolbox/ui/resources/menu_icons/folder-open-solid.svg :width: 16 @@ -10,7 +9,7 @@ **************************** -Importing and exporting data +Importing and Exporting Data **************************** This section explains the different ways of importing and exporting data to and from a Spine database. @@ -386,7 +385,7 @@ GAMS gdx export .. note:: You need to have GAMS installed to use this functionality. However, you do not need to own a GAMS license as the demo version works just as well. - See :ref:`Setting up External Tools` for more information. + See :ref:`Setting up Consoles and External Tools` for more information. The gdx backend turns the output tables to GAMS sets, parameters and scalars following the rules below: diff --git a/docs/source/developer_documentation.rst b/docs/source/developer_documentation.rst index 30623ff9d..ffc2cf769 100644 --- a/docs/source/developer_documentation.rst +++ b/docs/source/developer_documentation.rst @@ -1,4 +1,4 @@ -Developer documentation +Developer Documentation ======================= Here you can find developer specific documentation on Spine Toolbox. diff --git a/docs/source/execution_modes.rst b/docs/source/execution_modes.rst deleted file mode 100644 index a2a207c15..000000000 --- a/docs/source/execution_modes.rst +++ /dev/null @@ -1,185 +0,0 @@ -.. How to set up shell or Jupyter Console execution model. - Created 4.6.2021 - -.. |browse| image:: ../../spinetoolbox/ui/resources/menu_icons/folder-open-solid.svg - :width: 16 -.. |play| image:: ../../spinetoolbox/ui/resources/menu_icons/play-circle-solid.svg - :width: 16 -.. |stop| image:: ../../spinetoolbox/ui/resources/menu_icons/stop-circle-regular.svg - :width: 16 - -.. _Execution Modes: - -*************** -Execution Modes -*************** - -Python and Julia Tools can be executed in either an embedded basic console or a Jupyter Console. GAMS Tools -are only executed in the shell. Executable tools are a shell or by running the executable file straight. - -Python -****** - -Under the **Tools** page in **File -> Settings...**, you can set the default console for new Python Tool specifications -as either a Basic Console or a Jupyter Console. In the Tool Specification Editor, Tool specification specific selections -can be made overriding the default settings. - -Basic Console -------------- - -If Basic Console is selected (it is by default) Tools are executed in the **Console** dock widget on a basic console. -You can set the default Python interpreter in the settings and item specific interpreters in the -Tool's specification editor. - -Jupyter Console ---------------- -Jupyter Console will also appear in the **Console** dock widget. -If you want to use a Jupyter Console as the default, check the *Jupyter Console* check box. -There is an extra step involved since -the Jupyter Console requires a couple of extra packages (*ipykernel* and its dependencies) to be -installed on the selected Python. In addition, kernel specifications for the selected Python needs to be -installed beforehand. **Spine Toolbox can install these for you**, from the **Python Kernel Specification Creator** widget that -you can open from the **Tools** page in **File -> Settings...** by clicking the **Make Python Kernel** button. - -.. note:: - You can install Python kernel specifications manually and Spine Toolbox will find them. You can select the kernel - spec used in the Jupyter Console from the drop-down menu *Select Python kernel...*. - -.. 1. Go to ``_ and download the Python you want - 2. Run the Python installer and follow instructions - 3. Either let the installer put Python in your PATH or memorize the path where you installed it - (e.g. `C:\\Python38`) - 4. Start Spine Toolbox - 5. Go to File -> Settings (or press F1) and click the Tools tab open - 6. If the installed Python is now in your PATH, you can leave the Python interpreter line edit blank. - Or you can set the Python interpreter explicitly by setting it to e.g. `C:\\Python38\\python.exe` - by using the |browse| button. - 7. Check the `Use embedded Python Console` check box - 8. Create a project with a Tool and a Python Tool specification (See :ref:`Getting Started`) - 9. Press play to execute the project (See :ref:`Executing Projects`) - 10. You will see a question box - -.. .. image:: img/ipykernel_missing.png - :align: center - -.. When you click on the *Install ipykernel* button, you can see the progress of the - operation in Process Log. The following packages will be installed on your selected Python.:: - -.. backcall, colorama, decorator, ipykernel, ipython, ipython-genutils, jedi, jupyter-client, - jupyter-core, parso, pickleshare, prompt-toolkit, pygments, python-dateutil, pywin32, pyzmq, six, - tornado, traitlets, wcwidth - -.. When this operation finishes successfully, you will see another guestion box. - -.. .. image:: img/kernel_specs_missing.png - :align: center - -.. Clicking on *Install specifications* button starts installing the kernel specs for the selected Python. - On the tested system, this creates a new kernel into directory - `C:\\Users\\ttepsa\\AppData\\Roaming\\jupyter\\kernels\\Python-3.8`, which contains the `kernel.json` file - required by the embedded Python Console (which is actually a jupyter qtconsole) - -.. 11. After the kernel specs have been installed, executing your Tool project item starts in the - Python Console immediately. You can see the executed command and the Tool output in the Python - Console. - -.. .. note:: - If you want to set up your Python environment ready for Python Console manually, the following - commands are executed by Spine Toolbox under the hood - -.. This installs all required packages:: - -.. python -m pip install ipykernel - -.. And this installs the kernel specifications:: - -.. python -m ipykernel install --user --name python-3.8 --display-name Python3.8 - - -Julia -***** - -As with Python, default console type can be selected in the settings and Julia kernels can also be created by pressing -**Make Julia Kernel** -button. In addition a default project can be selected for Julia Tool specifications. - -Basic Console -------------- -On **Tools** page in **File -> Settings...**, check the **Basic Console** radiobutton. -This is the default execution mode for Julia Tools. - -.. 1. Go to ``_ and download the Julia you want - 2. Run the Julia installer and follow instructions - 3. Either let the installer put Julia in your PATH or memorize the path where you installed it - (e.g. `C:\\Julia-1.2.0`) - 4. Start Spine Toolbox - 5. Go to File -> Settings (or press F1) and click the Tools tab open - 6. If the installed Julia is now in your PATH, you can leave the Julia executable line edit blank. - Or you can set the Julia executable explicitly by setting it to e.g. `C:\\Julia.1.2.0\\bin\\julia.exe` - by using the |browse| button. - 7. Uncheck the `Use embedded Julia Console` check box - 8. Create a project with a Tool and a Julia Tool specification (See :ref:`Getting Started`) - 9. Press |play| to execute the project (See :ref:`Executing Projects`) - 10. Executing your Tool project item starts. You can see the output (stdout and stderr) in the - Process Log. - -Jupyter Console ---------------- - -Like the Python Console, the Jupyter Console with Julia requires some extra setting up. A couple of -additional packages (`IJulia`, etc.) are required to be installed and built. **Spine Toolbox can set this up for you -automatically**. Just click the **Make Julia Kernel** button after selecting the **Jupyter Console** -radiobutton. - -.. note:: - You can install Julia kernel specifications manually and Spine Toolbox will find them. You can select the kernel - spec used in the Jupyter Console from the drop-down menu *Select Julia kernel...*. - -.. 1. Go to ``_ and download the Julia you want - 2. Run the Julia installer and follow instructions - 3. Either let the installer put Julia in your PATH or memorize the path where you installed it - (e.g. `C:\\Julia-1.2.0`) - 4. Start Spine Toolbox - 5. Go to File -> Settings (or press F1) and click the Tools tab open - 6. If the installed Julia is now in your PATH, you can leave the Julia executable line edit blank. - Or you can set the Julia executable explicitly by setting it to e.g. `C:\\Julia.1.2.0\\bin\\julia.exe` - by using the |browse| button. - 7. Check the `Use embedded Julia Console` check box - 8. Create a project with a Tool and a Julia Tool specification (See :ref:`Getting Started`) - 9. Press |play| to execute the project (See :ref:`Executing Projects`) - 10. You will see a question box - -.. .. image:: img/ijulia_missing.png - :align: center - -.. When you click on the *Allow* button, installing IJulia starts and you can see the progress of the - operation in Process Log. **This may take a few minutes**. - -.. When you see the these messages in the Event Log, the Julia Console is ready to be used.:: - -.. IJulia installation successful. - *** Starting Julia Console *** - -.. 11. After the installation has finished, executing your Julia Tool project item starts in the - Julia Console immediately. You can see the executed command and the Tool output in the Julia - Console. If nothing seems to be happening in the Julia Console. Just click |Stop| button and - then try executing the project again by clicking the |play| button. - -Executable -********** - -With executable Tool types there are two ways to run the executable file: using a shell or without one. - -Using a shell -------------- - -To run an executable with a shell you need to select a shell out of the three available options that is -appropriate for the operating system you are running Spine Toolbox on. Then you can write a command that -runs the executable with the arguments that it needs into the *Command* textbox just like you would on a -normal shell. - -Without a shell ---------------- - -To run an executable file without a shell you can either select the executable file as the main program -file of the Tool and write the possible arguments into *Command line arguments* or select *no shell* and -write the filepath of the executable file followed by it's arguments into the *Command* textbox. -Either way the file is executed independent of a shell and with the provided arguments. diff --git a/docs/source/execution_tests.rst b/docs/source/execution_tests.rst index 016816d2a..38f2ec0c2 100644 --- a/docs/source/execution_tests.rst +++ b/docs/source/execution_tests.rst @@ -1,6 +1,6 @@ .. _Execution tests: -Execution tests +Execution Tests =============== Toolbox contains *execution tests* that test entire workflows in the headless mode. diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 809919445..eb2e73e2d 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -35,7 +35,7 @@ Welcome to the Spine Toolbox's getting started guide. In this guide you will learn two ways of running a `"Hello, World!" program `_ on Spine Toolbox. If you need help on how to run **SpineOpt.jl** using Spine Toolbox, see chapter -:ref:`How to set up SpineOpt.jl`. For small example projects utilizing **SpineOpt.jl**, see `SpineOpt tutorials +:ref:`How to Set up SpineOpt.jl`. For small example projects utilizing **SpineOpt.jl**, see `SpineOpt tutorials `_. This chapter introduces the following topics: @@ -205,7 +205,7 @@ Once the execution is finished, you can see the details about the item execution | -.. note:: For more information about execution modes in Spine Toolbox, please see :ref:`Setting Up External Tools` +.. note:: For more information about setting up Consoles in Spine Toolbox, please see :ref:`Setting up Consoles and External Tools` for help. Congratulations, you just executed your first Spine Toolbox project. @@ -321,7 +321,7 @@ Press |execute| once again. The project will be executed successfully this time: That's all for now. I hope you've enjoyed following this guide as much as I enjoyed writing it. See you next time. Where to next: If you need help on how to set up and run **SpineOpt.jl** using Spine Toolbox, see chapter -:ref:`How to set up SpineOpt.jl`. After setting up SpineOpt, there are three tutorials over on **SpineOpt.jl**'s +:ref:`How to Set up SpineOpt.jl`. After setting up SpineOpt, there are three tutorials over on **SpineOpt.jl**'s documentation that will help you get started on using SpineOpt in Spine Toolbox: `Simple system `_, diff --git a/docs/source/how_to_run_spineopt.rst b/docs/source/how_to_run_spineopt.rst index 7ab6a42ee..f03ddf5c9 100644 --- a/docs/source/how_to_run_spineopt.rst +++ b/docs/source/how_to_run_spineopt.rst @@ -1,13 +1,12 @@ -.. How to set up SpineOpt.jl documentation - Created 26.5.2021 +.. How to Set up SpineOpt.jl documentation .. |execute| image:: ../../spinetoolbox/ui/resources/menu_icons/play-circle-solid.svg :width: 16 -.. _How to set up SpineOpt.jl: +.. _How to Set up SpineOpt.jl: ************************* -How to set up SpineOpt.jl +How to Set up SpineOpt.jl ************************* #. Install Julia (v1.6 or later) from ``_ if you don't have one. @@ -17,17 +16,17 @@ How to set up SpineOpt.jl #. Create a new project (**File -> New project...**) -#. Select **File -> Settings** from the main menu and open the `Tools` page. +#. Select **File -> Settings** from the main menu and open the *Tools* page. -#. Set a path to a Julia executable to the appropriate line edit (e.g. ``C:/Julia-1.5.4/bin/julia.exe``). +#. Set a path to a Julia executable to the appropriate line edit (e.g. `C:/Julia-1.6.0/bin/julia.exe`). Your selections should look similar to this now. - .. image:: img/settings_tools_filled_for_spineopt_github.png + .. image:: img/settings_tools_default.png :align: center #. *[Optional]* If you want to install and run SpineOpt in a specific Julia project environment (the place for - ``Project.toml`` and ``Manifest.toml``), you can set the path to the environment folder to the line edit just below the - Julia executable (the one that says `Using Julia default project`). + `Project.toml` and `Manifest.toml`), you can set the path to the environment folder to the line edit just below the + Julia executable (the one that says *Using Julia default project*). #. Next, you need to install **SpineOpt.jl** package for the Julia you just selected for Spine Toolbox. You can do this manually by `following the instructions `_ @@ -49,7 +48,7 @@ Spine Toolbox and Julia are now correctly set up for running **SpineOpt.jl**. Ne `Create a project workflow using SpineOpt.jl `_ (takes you to SpineOpt documentation). See also `Tutorials `_ in SpineOpt documentation for more advanced -use cases. For more information on how to select a specific Python or Julia version, see :ref:`Setting up External Tools`). +use cases. For more information on how to select a specific Python or Julia version, see :ref:`Setting up Consoles and External Tools`). .. note:: The **SpineOpt Plugin Toolbar** contains an exporter specification as well as three predefined Tools that make use of SpineOpt.jl. **The SpineOpt Plugin is not a requirement to run SpineOpt.jl**, they are provided just for diff --git a/docs/source/img/executable_tool_spec_dir_runner.png b/docs/source/img/executable_tool_spec_dir_runner.png new file mode 100644 index 000000000..d6d6373c0 Binary files /dev/null and b/docs/source/img/executable_tool_spec_dir_runner.png differ diff --git a/docs/source/img/ijulia_missing.png b/docs/source/img/ijulia_missing.png deleted file mode 100644 index 6e60a6001..000000000 Binary files a/docs/source/img/ijulia_missing.png and /dev/null differ diff --git a/docs/source/img/ipykernel_missing.png b/docs/source/img/ipykernel_missing.png deleted file mode 100644 index 763814ab7..000000000 Binary files a/docs/source/img/ipykernel_missing.png and /dev/null differ diff --git a/docs/source/img/julia_jupyter_console_selected.png b/docs/source/img/julia_jupyter_console_selected.png new file mode 100644 index 000000000..163714b1b Binary files /dev/null and b/docs/source/img/julia_jupyter_console_selected.png differ diff --git a/docs/source/img/julia_kernel_specification_creator.png b/docs/source/img/julia_kernel_specification_creator.png new file mode 100644 index 000000000..46f3c095c Binary files /dev/null and b/docs/source/img/julia_kernel_specification_creator.png differ diff --git a/docs/source/img/kernel_specs_missing.png b/docs/source/img/kernel_specs_missing.png deleted file mode 100644 index ef823a53f..000000000 Binary files a/docs/source/img/kernel_specs_missing.png and /dev/null differ diff --git a/docs/source/img/python_jupyter_console_selected.png b/docs/source/img/python_jupyter_console_selected.png new file mode 100644 index 000000000..af3c3b900 Binary files /dev/null and b/docs/source/img/python_jupyter_console_selected.png differ diff --git a/docs/source/img/python_kernel_specification_creator.png b/docs/source/img/python_kernel_specification_creator.png new file mode 100644 index 000000000..914e4b5f2 Binary files /dev/null and b/docs/source/img/python_kernel_specification_creator.png differ diff --git a/docs/source/img/settings_tools_default.png b/docs/source/img/settings_tools_default.png new file mode 100644 index 000000000..c87bf15fb Binary files /dev/null and b/docs/source/img/settings_tools_default.png differ diff --git a/docs/source/img/settings_tools_default_python_git_version.png b/docs/source/img/settings_tools_default_python_git_version.png deleted file mode 100644 index 890bc56ff..000000000 Binary files a/docs/source/img/settings_tools_default_python_git_version.png and /dev/null differ diff --git a/docs/source/img/settings_tools_filled_for_spineopt.png b/docs/source/img/settings_tools_filled_for_spineopt.png deleted file mode 100644 index b125e5e88..000000000 Binary files a/docs/source/img/settings_tools_filled_for_spineopt.png and /dev/null differ diff --git a/docs/source/img/settings_tools_python_installed_version.png b/docs/source/img/settings_tools_python_installed_version.png deleted file mode 100644 index d32ee36bf..000000000 Binary files a/docs/source/img/settings_tools_python_installed_version.png and /dev/null differ diff --git a/docs/source/img/start_jupyter_console_menu_listing.png b/docs/source/img/start_jupyter_console_menu_listing.png new file mode 100644 index 000000000..f286a04de Binary files /dev/null and b/docs/source/img/start_jupyter_console_menu_listing.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index f70720971..ef3611d96 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,9 +12,9 @@ Welcome to Spine Toolbox's User Guide! computation tasks, such as energy system models. If you are new to Spine Toolbox, :ref:`Getting Started` section is a good place to start. If you want to run -`SpineOpt.jl `_ using Spine Toolbox, :ref:`How to set up SpineOpt.jl` +`SpineOpt.jl `_ using Spine Toolbox, :ref:`How to Set up SpineOpt.jl` provides the step-by-step instructions on how to get started. For information on how to set up Python, Julia, and -Gams for Spine Toolbox, see :ref:`Setting up External Tools`. Please see :ref:`Settings` chapter for information +Gams for Spine Toolbox, see :ref:`Setting up Consoles and External Tools`. Please see :ref:`Settings` chapter for information on user customizable Spine Toolbox settings. If you need help in understanding the terms we use throughout the app and this User Guide, please check the :ref:`Terminology` section. If you want to contribute to this project, please see the :ref:`Contribution Guide`. The last section contains the complete code reference of Spine Toolbox. @@ -23,6 +23,7 @@ please see the :ref:`Contribution Guide`. The last section contains the complete :maxdepth: 1 :caption: Contents: + whats_new getting_started how_to_run_spineopt setting_up @@ -31,9 +32,8 @@ please see the :ref:`Contribution Guide`. The last section contains the complete links tool_specification_editor executing_projects - execution_modes settings - Spine database editor + Spine Database Editor plotting parameter_value_editor metadata_description diff --git a/docs/source/metadata_description.rst b/docs/source/metadata_description.rst index 9358fc89f..9f3ddae73 100644 --- a/docs/source/metadata_description.rst +++ b/docs/source/metadata_description.rst @@ -1,7 +1,7 @@ .. _Metadata description: ************************** -Spine metadata description +Spine Metadata Description ************************** This is the metadata description for Spine, edited from ``_. diff --git a/docs/source/parameter_value_editor.rst b/docs/source/parameter_value_editor.rst index 3cafa74f0..89e1f9eae 100644 --- a/docs/source/parameter_value_editor.rst +++ b/docs/source/parameter_value_editor.rst @@ -1,8 +1,7 @@ .. Parameter value editor - Created: 15.8.2019 ********************** -Parameter value editor +Parameter Value Editor ********************** Parameter value editor is used to edit object and relationship parameter values diff --git a/docs/source/plotting.rst b/docs/source/plotting.rst index 71272f3d0..3dc587dd1 100644 --- a/docs/source/plotting.rst +++ b/docs/source/plotting.rst @@ -1,5 +1,4 @@ .. Plotting - Created: 15.8.2019 Plotting ======== diff --git a/docs/source/project_item_development.rst b/docs/source/project_item_development.rst index dcd1029ed..f4dc77a18 100644 --- a/docs/source/project_item_development.rst +++ b/docs/source/project_item_development.rst @@ -1,6 +1,6 @@ .. _Project item development: -Project item development +Project Item Development ======================== This document discusses the basics of :ref:`project item` development: diff --git a/docs/source/setting_up.rst b/docs/source/setting_up.rst index 4b066b1d3..fc77b0ec6 100644 --- a/docs/source/setting_up.rst +++ b/docs/source/setting_up.rst @@ -1,5 +1,4 @@ -.. Setting up External Tools - Created 2.4.2020 +.. Setting up Consoles and External Tools .. |browse| image:: ../../spinetoolbox/ui/resources/menu_icons/folder-open-solid.svg :width: 16 @@ -8,101 +7,203 @@ .. |stop| image:: ../../spinetoolbox/ui/resources/menu_icons/stop-circle-regular.svg :width: 16 -.. _Setting up External Tools: +.. _Setting up Consoles and External Tools: -************************* -Setting up External Tools -************************* +************************************** +Setting up Consoles and External Tools +************************************** + +This section describes the options for executing different Python, Julia, Gams, and Executable Tools and how to set +them up. To get started with **SpineOpt.jl**, see :ref:`How to Set up SpineOpt.jl`. See also +:ref:`Executing Projects`. -This section describes the default **Python** used by Spine Toolbox and how to change that. Here you can also find the -instructions on how to set up **Julia** and **Gams** for executing Julia and Gams Tools. To get started with -**SpineOpt.jl**, see :ref:`How to set up SpineOpt.jl`. See also :ref:`Executing Projects` and :ref:`Execution Modes`. .. contents:: :local: +Python and Julia Tools can be executed either in an embedded *Basic Console* or in a *Jupyter Console*. GAMS Tools +are executed in a sub-process. Executable Tools (external programs) are executed in a shell or by running the +executable file straight. You can also make a Tool that executes a shell command by creating an *Executable* Tool +Spec in **Tool Specification Editor**, entering the shell command to the *Command* line edit and then selecting the +Shell for this Tool. + +Basic Consoles +-------------- +Basic Console appears to the **Console** dock widget in the main window when you execute (|play|) a project +containing either a Python or a Julia Tool with Basic Console selected. + Python ****** -No set up required! Python Tools are executed using the **default Python**, which **depends on how you installed Spine Toolbox.** The -installation options are: - -1. Using a single-file **installation bundle** (e.g. *spine-toolbox-0.6.0-final.2-x64.exe* or newer). You can - find this file and all releases from - `Spine Toolbox releases `_. - The installation bundles are only available for Windows at the moment. -2. Cloning Spine Toolbox Git repository from ``_. Checkout branch - **release-0.6** or **master** and run `pip install -r requirements.txt` in the repo root. - -.. tip:: You can always see the current Python configured for Spine Toolbox from the `Tools` page in - `File->Settings...`. - -Default Python for Spine Toolbox installed using an installation bundle ------------------------------------------------------------------------ -The default Python is the **Python in your PATH** environment variable. **If Python is not in your PATH**, the -default Python is an 'embedded' Python that is shipped with the installation bundle. The 'embedded' Python is -located in *\\tools\\python.exe*, where ** is *C:\\Program Files\\Spine Toolbox* if you -installed Spine Toolbox to the default directory for all users. - -.. important:: If you want access to `spinedb_api` package from Tools and Consoles in Spine Toolbox, bear in mind - that the version of `spinedb_api` must be compatible with the version of Spine Toolbox you are using! Spine - Toolbox v0.6.0 is shipped with `spinedb_api` v0.12.1. If you want to use the Python in your PATH, **you must install - the correct version of spinedb_api for this Python manually**. The correct version in this case is in the - `release-0.12` branch of `spinedb_api` git repo - (https://github.com/spine-tools/Spine-Database-API/tree/release-0.12). - **To avoid this additional step, it is recommended** that you use the 'embedded' Python interpreter that is shipped - with the application. You can set up this Python for Spine Toolbox by opening the `Tools` page of - `File->Settings...` and replacing the path of the Python Interpreter with *\\tools\\python.exe*. - **The 'embedded' Python interpreter has access to `spinedb_api` that is shipped with the application.** - -Here are the recommended settings - -.. image:: img/settings_tools_python_installed_version.png +Executing a Python Tool in the Basic Console requires no set up. Simply create a *Python* Tool Spec in +**Tool Specification Editor** and select the Basic Console radio button. The default Python interpreter used +in launching the Console is the same Python that was used in launching Spine Toolbox. You can also select another +Python by changing the Python interpreter line edit. Remember to save the new Tool Spec when closing the **Tool +Spec. Editor**. Then drag the Python Tool Spec into the **Design View**, and press |play| to execute it. + +.. note:: The Python settings on the *Tools* page in **File -> Settings** are the *default* settings for new Python + Tool Specs. You can select a different Python executable for each Python Tool Spec separately using the + **Tool Specification Editor**. + +Julia +***** +To execute Julia Tools in the Basic Console, first install Julia (v1.6 or later) +`from here `_ and add `/bin` to your PATH environment variable +(if not done automatically by the installer). Then go to the *Tools* page in **File -> Settings** and make sure that +the Basic Console radio button is selected in the Julia group. If Julia is in your PATH, the Julia executable line +edit should show the path as (grey) placeholder text. If you want to use another Julia on your system, you can change +the path in the line edit. You can also set a Julia Project below the Julia executable line edit. + +.. note:: The Julia settings are *global* application settings. All Julia Tools are executed with the settings + selected on the *Tools* page in **File -> Settings**. In upcoming versions, the Julia settings will be consistent + with the Python settings, in a way that you can select a specific Julia executable and Julia project for each + Julia Tool Spec separately. + +Jupyter Consoles +---------------- +Jupyter Console appears to the **Console** dock widget in the main window when you execute (|play|) a project +containing either a Python or a Julia Tool with the *Jupyter Console* selected. The Jupyter Console +requires a Jupyter kernel to be installed on your system. Kernels are programming language specific processes +that run independently and interact with the Jupyter Applications and their user interfaces. + +Python +****** +Select *Jupyter Console* radio button in **File -> Settings**. You also need to select the Python kernel you +wish to use from the *Select Python kernel...* combo box. If this list is empty, you need to install the kernel specs +on your system. You can either do this manually or click the **Make Python Kernel** button. Clicking the button opens +a **Python Kernel Specification Creator** window, that first installs the **ipykernel** package (if missing) for +the Python that is currently selected in the Python interpreter line edit (the kernel specs will be created +for `C:/Python39/python.exe` in the picture below). You can make kernel specs for other Pythons and virtual +environments (venv) by changing the Python interpreter line edit path to point to another Python. Please see +specific instructions for creating kernel specs for Conda environments below. + +.. image:: img/python_jupyter_console_selected.png :align: center -Default Python for Spine Toolbox installed using Git ----------------------------------------------------- -The default Python is the **Python that was used in launching the application** (i.e. *sys.executable*). -When you start the app for the first time (or if you clear the path), the path to the default Python is -shown as placeholder (gray) text in the line edit like this: +Once the **ipykernel** package is installed, the wizard runs the **ipykernel** install command, which creates the +kernel specs directory on your system. You can quickly open the kernel spec directory from the +**Select Python Kernel...** combo box's context-menu (mouse right-click menu). Once the process finishes, +click Close, and the newly created kernel spec (*python39* in this case) should be selected automatically. +Click *Ok* to close the **Settings** widget and to save your selections. -.. image:: img/settings_tools_default_python_git_version.png +.. image:: img/python_kernel_specification_creator.png :align: center -The default Python has access to the `spinedb_api` version that was installed with the application (the one in -in \\lib\\site-packages\\spinedb_api). +If something went wrong, or if you want to remake the kernel specs, you can remove the kernel spec directory from +your system, try the **Make Python Kernel** button again, or install the kernel specs manually. + +If you want to install the Python kernel specs manually, these are the commands that you need to run. + +To install **ipykernel** and it's dependencies, run:: + + python -m pip install ipykernel -Changing the default Python ---------------------------- -If you want to use another Python than the default, you can use existing Pythons in your system or you can -download additional Pythons from ``_. You can change the default Python -on the `Tools` page of `File->Settings...` by clicking the |browse| button and selecting the Python interpreter -(`python.exe` on Windows) you want. You can use **any Python in your system**. +And to install the kernel specs run:: + + python -m ipykernel install --user --name python39 --display-name python39_spinetoolbox + +Make sure to use the ``--user`` argument to make sure that the kernel specs are discoverable by Spine Toolbox. + +.. note:: + Clicking **Make Python Kernel** button when the kernel specs have already been installed, does NOT open the + **Python Kernel Specification Creator**, but simply selects the Python kernel automatically. .. note:: Executing Python Tools using the Jupyter Console supports Python versions from 2.7 all the way to newest one. - Executing Python Tools **without** using the Jupyter Console supports even earlier Pythons than 2.7. - You can start Spine Toolbox only with Python 3.7 or with 3.8, but you can set up a Jupyter Console in - Spine Toolbox that uses e.g. Python 2.7. This means, that if you still have some old Python 2.7 scripts - lying around, you can incorporate those into a Spine Toolbox project workflow and execute them without - modifications. + This means, that if you still have some old Python 2.7 scripts lying around, you can incorporate those into + a Spine Toolbox project workflow and execute them without modifications. .. important:: If you want to have access to `spinedb_api`, you need to install it manually for the Python you select here. Julia ***** -Executing Julia Tools in Spine Toolbox requires that Julia is installed on your system. Julia downloads are -available from ``_. You can see the current Julia on the `Tools` page in -`File->Settings...`. The **default Julia is the Julia in your PATH** environment variable. Setting some other -Julia to the line edit overrides the Julia in PATH. If you want to use a specific **Julia project environment** -(the place for Project.toml and Manifest.toml), you can set the path to the environment folder to the line -edit just below the Julia executable line edit (the one that says *Using Julia default project* when empty). +To use the Jupyter Console with Julia Tools, go to the *Tools* page in **File -> Settings** and select the +Jupyter Console radio button like in the picture below. + +.. image:: img/julia_jupyter_console_selected.png + :align: center + +Like with Python, you need to select an existing Julia kernel for the Julia Jupyter Console, or create one +either manually, or by clicking the **Make Julia Kernel** button. + +.. image:: img/julia_kernel_specification_creator.png + :align: center + +Clicking the button opens **Julia Kernel Specification Creator** window, that first installs the **IJulia** package +(if missing) for the Julia and Julia project that are currently selected in the Julia executable and Julia Project +line edits (the kernel specs will be created for the default project of `C:/Julia-1.9.0/bin/julia.exe` in the +picture above). + +If something went wrong, or if you want to remake the kernel specs, you can remove the kernel spec directory from +your system, try the **Make Julia Kernel** button again, or install the kernel specs manually. + +If you want to install the Julia kernel specs manually, these are the commands that you need to run. + +To install **IJulia** and it's dependencies, open Julia REPL with the project you want and run:: -If you are trying to execute Julia Tools and you see an error message in Event Log complaining about not finding -Julia, you either don't have a Julia installation in your PATH, or the Julia path in Settings is invalid. + using Pkg + Pkg.add("IJulia") + +Rebuild IJulia:: + + Pkg.build("IJulia") + +And to install the kernel specs run:: + + using IJulia + installkernel("julia", --project="my_project") + +.. note:: + Clicking **Make Julia Kernel** button when the kernel specs have already been installed, does NOT open the + **Julia Kernel Specification Creator**, but simply selects a Julia kernel that matches the selected Julia + executable and Julia Project. If a kernel spec matching the Julia executable is found but the Julia project is + different, a warning window appears, saying that Julia kernel spec may be overwritten if you continue. + +Conda +***** +You also have the option of running Python Tools in a Conda environment. All you need to do is the following. + +1. Open Anaconda Prompt and make a new Conda environment:: + + conda create -n test python=3.10 + +2. Activate the environment:: + + conda activate test + +3. Install **ipykernel**:: + + pip install ipykernel + +4. Back in Spine Toolbox, add path to Conda executable on the *Tools* page in **File -> Settings**. + +That's it! Now, in Spine Toolbox main window, open the **Consoles -> Start Jupyter Console** menu, wait a second, +and the new kernel should appear in the list. In this case, the new kernel name is *conda-env-.conda-test-py*. +This autogenerated name will most likely change to something more readable in the future. You can use Conda Python +kernels just like regular Python kernels, i.e. select one of them as the default kernel in the +**File -> Settings** widget or select them for individual Python Tool Specs in **Tool Specification Editor** directly. + +Detached Consoles +***************** +You can open 'detached' Jupyter Consoles from the main window menu **Consoles -> Start Jupyter Console**. The menu +is populated dynamically with every Jupyter kernel that Spine Toolbox is able to find on your system. 'Detached' +here means that the Consoles are not bound to any Tool. These Consoles are mostly useful e.g. for +checking that the kernel has access to the correct packages, debugging, small coding, testing, etc. These may be +especially useful for checking that everything works before running a full workflow that may take hours to finish. + +Officially, Spine Toolbox only supports Python and Julia Jupyter kernels but it's possible that other kernels can +be accessed in a Detached Console as well. For example, if you install a javascript kernel on your system, you can +open a Detached Console for it, but this does not mean that Spine Toolbox projects should support Javascript. However, +if there's interest and legitimate use cases for other kernels, we may build support for them in future releases. + +.. image:: img/start_jupyter_console_menu_listing.png + :align: center + +If interested, you can `read more on Jupyter kernels `_ . +There you can also find a `list of available kernels `_. GAMS -**** +---- Executing Gams Tools or needing to use the GDX file format requires an installation of Gams on your system. You can download Gams from ``_. @@ -110,9 +211,26 @@ You can download Gams from ``_. .. important:: The bitness (32 or 64bit) of Gams has to match the bitness of the Python interpreter. -The default Gams is the Gams defined under ``gams.location`` in Windows registry or in your PATH environment variable. -You can see the one that is currently in use from the `Tools` page in `File->Settings...`. -The placeholder text shows the default Gams if found. -You can also override the default Gams by setting some other gams.exe path to the line edit -(e.g. `C:\\GAMS\\win64\\28.2\\gams.exe`). +The default Gams is the Gams defined under ``gams.location`` in Windows registry or in your PATH environment +variable. You can see the one that is currently in use from the *Tools* page in **File -> Settings**. The +placeholder text shows the default Gams if found. You can also override the default Gams by setting some other +gams executable path to the line edit. + +Executable +---------- +Executable Tool Spec types can be used to execute virtually any program as part of a Spine Toolbox workflow. They +also provide the possibility to run Shell commands as part the workflow. To run an executable with a shell you +need to select a shell out of the three available options that is appropriate for your operating system. +Then you can write a command that runs the executable with the arguments that it needs into the *Command* +line edit just like you would on a normal shell. +To run an executable file without a shell you can either select the executable file as the main program +file of the Tool and write the possible arguments into *Command line arguments* or select *no shell* and +write the filepath of the executable file followed by it's arguments into the *Command* textbox. +Either way the file is executed independent of a shell and with the provided arguments. + +To run a Shell command, just type the command into the *command* line edit and select the appropriate Shell from the +list. Picture below depicts an Executable Tool Spec that runs *dir* in in cmd.exe. + +.. image:: img/executable_tool_spec_dir_runner.png + :align: center diff --git a/docs/source/settings.rst b/docs/source/settings.rst index c78eeaa78..678ee256f 100644 --- a/docs/source/settings.rst +++ b/docs/source/settings.rst @@ -1,5 +1,7 @@ .. Settings form documentation - Created 14.1.2019 + +.. |open-folder| image:: ../../spinetoolbox/ui/resources/menu_icons/folder-open-solid.svg + :width: 16 .. _Settings: @@ -7,16 +9,17 @@ Settings ******** -You can open Spine Toolbox settings from the main window menu `File->Settings...`, or by +You can open Spine Toolbox settings from the main window menu **File -> Settings...**, or by pressing **Ctrl+,**. Settings are categorized into five tabs; *General*, *Tools*, *Db editor*, *Spec. editors* and *Engine*. -In addition to application settings, each Project item has user adjustable -properties (See :ref:`Project Items`) +In addition to application settings, each project item has user adjustable +properties (See :ref:`Project Items`). See also :ref:`Setting up Consoles and External Tools` +for more information on how to set up Consoles and external Tools. .. contents:: :local: -General settings +General Settings ---------------- .. image:: img/settings_general.png @@ -32,7 +35,7 @@ Settings in the **Main** group: - **Delete data when project item is removed from project** Check this box to delete project item's data when a project item is removed from project. This means that the *project item directory* and its contents will be deleted from your hard drive. You can find the project item directories from the - ``/.spinetoolbox/items/`` directory, where ```` is your current project directory. + `/.spinetoolbox/items/` directory, where `` is your current project directory. - **Open previous project at startup** If checked, application opens the project at startup that was open the last time the application was shut down. If left unchecked, application starts without a @@ -45,7 +48,7 @@ Settings in the **Main** group: when the application exits. - **Work directory** Directory where processing the Tool takes place. Default place (if left empty) is - the ``/work`` subdirectory of Spine Toolbox install directory. You can change this directory. + the `/work` subdirectory of Spine Toolbox install directory. You can change this directory. Make sure to clean up the directory every now and then. Settings in the **UI** group: @@ -55,44 +58,109 @@ Settings in the **UI** group: - **Color properties widgets** Check this box to make the background of Project item properties more colorful. -- **Curved links** Controls the look of the arrows on Design View. +- **Curved links** Controls the look of the arrows on **Design View**. - **Drag to draw links** When checked, the mouse button needs to be pressed while drawing links between project items. If unchecked, single clicks at link source and destination items suffices. - **Prevent items from overlapping** When checked, other project items can be pushed away when - moving an item around the Design view. If left unchecked, items can be piled on top of each other. + moving an item around the **Design view**. If left unchecked, items can be piled on top of each other. - **Rounded items** Check this box to round the corners of otherwise rectangular project items. -- **Show date and time in Event Log messages** If checked, every Event Log message is prepended with +- **Show date and time in Event Log messages** If checked, every **Event Log** message is prepended with a date and time 'tag'. -- **Smooth zoom** Controls the way zooming (by using the mouse wheel) behaves in Design View and in - Spine database editor. Controls if the zoom in/out is continuous or discrete. On older computers, +- **Smooth zoom** Controls the way zooming (by using the mouse wheel) behaves in **Design View** and in + **Spine DB Editor**. Controls if the zoom in/out is continuous or discrete. On older computers, smooth zoom is not recommended because it may be slower. -- **Background** Has some pattern options for the background of the Design view. +- **Background** Has some pattern options for the background of the **Design View**. Clicking on the square next to 'Color' let's you choose the pattern's color. -- **Link flash speed** This slider controls the speed of the link animation on Design - View when execution is ongoing. +- **Link flash speed** This slider controls the speed of the link animation on **Design + View** when execution is ongoing. -Tools settings +Tools Settings -------------- -The Tool settings tab contains settings for external tools. -See :ref:`Setting up External Tools` for more information and examples. +The Tools tab contains settings for external tools. + +.. image:: img/settings_tools_default.png + :align: center + +Settings in the **GAMS** group: + +- **GAMS executable** Set the path to GAMS executable you want to use when executing GAMS tools. If you have GAMS in + your PATH environment variable, it will be automatically used. You can also choose another GAMS by clicking the + |open-folder| button. + +Settings in the **Julia** group: + +Choose the settings on how Julia Tools are executed. + +- **Basic Console** When selected, Julia Tools will be executed in a custom interactive Julia REPL. + +- **Julia executable** Set the path to a Julia Executable used in launching the Basic Console. If Julia is in PATH + this will be autofilled, but you can also choose another Julia executable. + +- **Julia project** Set the Julia project you want to activate in the Basic Console. + +- **Jupyter Console** Choosing this option runs Julia Tools in a custom Jupyter QtConsole embedded into Spine Toolbox. + +- **Select Julia kernel... drop-dowm menu** Select the kernel you want to launch in Jupyter Console. + +- **Make Julia Kernel** clicking this button makes a new kernel based on the selected *Julia executable*, and *Julia + project*. The progress of the operation is shown in another dialog. Installing a Julia kernel requires the **IJulia** + package which will be installed to the selected *Julia project*. After **IJulia** has been installed, the kernel is + installed. This process can take a couple of minutes to finish. + +- **Install Julia** Installs the latest Julia on your system using the **jill** package. + +- **Add/Update SpineOpt** Installs the latest compatible **SpineOpt** to the selected Julia project. If the selected + *Julia project* already has SpineOpt, it is upgraded if there's a new version available. + +.. note:: These Julia settings are *global* application settings. All Julia Tools are executed with the settings + selected here. + +Settings in the **Python** group: + +Choose the settings on how Python Tools are executed. + +- **Basic Console** When selected, Python Tools will be executed in a custom interactive Python REPL. + +- **Python executable** Set the path to a Python Executable used in launching the Basic Console. The default option + (if the line edit is blank) is the Python executable that was used in launching Spine Toolbox. + +- **Jupyter Console** Choosing this option runs Python Tools in a custom Jupyter QtConsole embedded into Spine + Toolbox. + +- **Select Python kernel... drop-dowm menu** Select the kernel you want to launch in Jupyter Console. + +- **Make Python Kernel** clicking this button makes a new kernel based on the selected *Python executable*. The + progress of the operation is shown in another dialog. Installing a Python kernel (actually IPython kernel) + requires the **ipykernel** package which will be installed to the selected *Python executables*. After + **ipykernel** has been installed, the kernel is installed. This process can take a couple of minutes to finish. + +.. note:: These Python settings are just the default settings *for new Python Tool Specs*. You can select a + specific Python kernel for each Python Tool Spec separately using the **Tool Specification Editor**. + +Settings in the **Conda** group: + +- **Miniconda executable** If you want to run Python Tools in a Conda environment, you can set the path + to your Conda executable here. + +See :ref:`Setting up Consoles and External Tools` for more information and examples. -Database editor settings ------------------------- +Db editor Settings +------------------ .. image:: img/settings_db_editor.png :align: center -This tab contains settings for the Database editor. -The same settings can be accessed directly from the Database editor itself. +This tab contains settings for the Spine Database editor. The same settings can be accessed directly +from the Database editor itself. - **Commit session before closing** This checkbox controls what happens when you close a database editor which has uncommitted changes. When this is unchecked, all changes are discarded without @@ -126,8 +194,8 @@ The same settings can be accessed directly from the Database editor itself. that are open on the same table into a single graph if they contains common object nodes. If unchecked, a separate graph will be drawn for each database. -Specification editor settings ------------------------------ +Spec. editor Settings +--------------------- .. image:: img/settings_specification_editors.png :align: center diff --git a/docs/source/spine_db_editor/index.rst b/docs/source/spine_db_editor/index.rst index 6672cd533..fdad1e7f2 100644 --- a/docs/source/spine_db_editor/index.rst +++ b/docs/source/spine_db_editor/index.rst @@ -1,7 +1,7 @@ .. _Spine db editor: -Welcome to Spine database editor's User Guide! +Welcome to Spine Database Editor's User Guide! ============================================== Spine database editor is a dedicated component of Spine Toolbox, diff --git a/docs/source/tool_specification_editor.rst b/docs/source/tool_specification_editor.rst index 0e9a614c1..128c2d370 100644 --- a/docs/source/tool_specification_editor.rst +++ b/docs/source/tool_specification_editor.rst @@ -1,5 +1,4 @@ .. Tool specification editor documentation - Created 15.1.2019 .. |folder_open| image:: ../../spinetoolbox/ui/resources/menu_icons/folder-open-regular.svg :width: 16 @@ -15,7 +14,7 @@ .. _Tool specification editor: ************************* -Tool specification editor +Tool Specification Editor ************************* This section describes how to make a new Tool specification and how to edit existing Tool specifications. @@ -89,8 +88,8 @@ The Tool specification file is a text file in JSON format and has an extension * You can change the location by pressing [change]. Also, you need to save your project for the specification to stick. -.. tip:: Only *name*, *type*, and *main program file* fields are required to make a Tool specification. The other - fields are optional. +.. tip:: Only *name*, *type*, and either *main program file* or *command* fields are required to make a Tool + specification. The other fields are optional. Here is a minimal Tool specification for a Julia script *script.jl* diff --git a/docs/source/ui_guidelines.rst b/docs/source/ui_guidelines.rst index 9b871cd86..7aff3e2a7 100644 --- a/docs/source/ui_guidelines.rst +++ b/docs/source/ui_guidelines.rst @@ -1,6 +1,6 @@ .. _UI guidelines: -UI guidelines +UI Guidelines ============= Keyboard shortcuts diff --git a/docs/source/unit_testing_guidelines.rst b/docs/source/unit_testing_guidelines.rst index 2ac3cb654..56441e966 100644 --- a/docs/source/unit_testing_guidelines.rst +++ b/docs/source/unit_testing_guidelines.rst @@ -1,6 +1,6 @@ .. _Unit testing guidelines: -Unit testing guidelines +Unit Testing Guidelines ======================= Test modules, directories diff --git a/docs/source/whats_new.rst b/docs/source/whats_new.rst new file mode 100644 index 000000000..e80bb58e4 --- /dev/null +++ b/docs/source/whats_new.rst @@ -0,0 +1,10 @@ +.. _Whats new: + +*********** +What's New? +*********** + +Here's the Changelog for Spine Toolbox. + +.. include:: ../../CHANGELOG.md + :literal: diff --git a/spinetoolbox/fetch_parent.py b/spinetoolbox/fetch_parent.py index 19fab9253..e7641f107 100644 --- a/spinetoolbox/fetch_parent.py +++ b/spinetoolbox/fetch_parent.py @@ -22,7 +22,7 @@ class FetchParent(QObject): Attrs: fetch_token (int or None) will_have_children (bool or None): Whether this parent will have children if fetched. - None means we don't know yet. Set to a boolean value whenever we find out. + None means we don't know yet. Set to a boolean value whenever we find out. """ _changes_pending = Signal() @@ -31,9 +31,9 @@ def __init__(self, owner=None, chunk_size=1000): """ Args: owner (object): somebody who owns this FetchParent. If it's a QObject instance, then this FetchParent - becomes obsolete whenever the owner is destroyed + becomes obsolete whenever the owner is destroyed chunk_size (int or None): the number of items this parent should be happy with fetching at a time. - If None, then no limit is imposed and the parent should fetch the entire contents of the DB. + If None, then no limit is imposed and the parent should fetch the entire contents of the DB. """ super().__init__() self._timer = QTimer() diff --git a/spinetoolbox/mvcmodels/map_model.py b/spinetoolbox/mvcmodels/map_model.py index 3983d586e..04437bc78 100644 --- a/spinetoolbox/mvcmodels/map_model.py +++ b/spinetoolbox/mvcmodels/map_model.py @@ -564,7 +564,7 @@ def _apply_index_names(map_value, index_names): def _numpy_string_to_python_strings(rows): - """Converts instances of numpy.str_ to regular Python strings. + """Converts instances of ``numpy.str_`` to regular Python strings. Args: rows (list of list): table rows diff --git a/spinetoolbox/spine_db_editor/mvcmodels/alternative_model.py b/spinetoolbox/spine_db_editor/mvcmodels/alternative_model.py index 7b2da2d57..7e5f2495e 100644 --- a/spinetoolbox/spine_db_editor/mvcmodels/alternative_model.py +++ b/spinetoolbox/spine_db_editor/mvcmodels/alternative_model.py @@ -63,7 +63,7 @@ def paste_alternative_mime_data(self, mime_data, database_item): Args: mime_data (QMimeData): mime data - database_item (DBItem): target database item + database_item (alternative_item.DBItem): target database item """ alternative_data = pickle.loads(mime_data.data(mime_types.ALTERNATIVE_DATA)) names_to_descriptions = {} diff --git a/spinetoolbox/spine_db_editor/widgets/tabular_view_mixin.py b/spinetoolbox/spine_db_editor/widgets/tabular_view_mixin.py index 29558f4ae..fb4248dce 100644 --- a/spinetoolbox/spine_db_editor/widgets/tabular_view_mixin.py +++ b/spinetoolbox/spine_db_editor/widgets/tabular_view_mixin.py @@ -174,6 +174,9 @@ def _connect_pivot_table_header_signals(self): def init_models(self): """Initializes models.""" super().init_models() + self.current_class_id.clear() + self.current_class_type = None + self.current_class_name = None self.clear_pivot_table() @Slot(QModelIndex, object) diff --git a/spinetoolbox/widgets/multi_tab_window.py b/spinetoolbox/widgets/multi_tab_window.py index 51fba6f5a..826adc5ba 100644 --- a/spinetoolbox/widgets/multi_tab_window.py +++ b/spinetoolbox/widgets/multi_tab_window.py @@ -474,7 +474,7 @@ def __init__(self, parent): self._plus_button.setIcon(QIcon(CharIconEngine("\uf067"))) self._plus_button.clicked.connect(lambda _=False: self.plus_clicked.emit()) self._move_plus_button() - self.setShape(QTabBar.RoundedNorth) + self.setShape(QTabBar.Shape.RoundedNorth) self.setTabsClosable(True) self.setMovable(True) self.setElideMode(Qt.ElideLeft)