diff --git a/db/__init__.py b/db/__init__.py
index 38bf4cc8b..e69de29bb 100644
--- a/db/__init__.py
+++ b/db/__init__.py
@@ -1,115 +0,0 @@
-# Copyright 2016-2023 Blue Marble Analytics LLC.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-"""
-All tables names in the GridPath database start with one of seven prefixes:
-:code:`mod_`, :code:`subscenario_`, :code:`inputs_`, :code:`scenarios`,
-:code:`options_`, :code:`status_`, or :code:`ui_`. This structure is meant to
-organize the tables by their function. Below are descriptions of each table
-type and its role, and of the kind of data tables of this type contain.
-
-***********************
-The :code:`mod_` Tables
-***********************
-The :code:`mod_` should not be modified except by developers. These contain
-various data used by the GridPath platform to describe available
-functionality, help enforce input data consistency and integrity, and aid in
-validation.
-
-***************************************************
-The :code:`subscenario_` and :code:`inputs_` Tables
-***************************************************
-Most tables in the GridPath database have the :code:`subscenario_` and
-:code:`inputs_` prefix. With a few exceptions, for each :code:`subscenario_`
-table, there is a respective :code:`inputs_` table (i.e. the tables have the
-same name except for the prefix). This is because the :code:`subscenario_`
-tables contain the descriptions of the input data contained in the
-:code:`inputs_` tables. For example the :code:`inputs_system_load` may
-contain three different load profiles -- low, mid, and high; the
-:code:`subscenarios_system_load` will then contain three rows, one for each
-load profile, with its description and ID. The pairs of :code:`subscenario_`
-and :code:`inputs_` are linked via an ID column: in the case of the system
-load tables, that is the :code:`load_scenario_id` column. We call these
-shared table keys *subscenario IDs*, as we use them to create a full
-GridPath scenario in the :code:`scenarios` table.
-
-***************************
-The :code:`scenarios` Table
-***************************
-In GridPath, we use the term 'scenario' to describe a model run with a
-particular set of inputs. Some of those inputs stay the same from scenario to
-scenario and others we vary to understand their effect on the results. For
-example, we could keep some input types like the zonal and transmission
-topography, temporal resolution, resource availability, and policy
-requirements the same across scenarios, but vary other input types, e.g. the
-load profile, the cost of solar, and the operational characteristics of coal,
-to create different scenarios. We call each of those inputs types a
-'subscenario' since they are the building blocks of a full scenario. In
-GridPath, you can create a scenario by populating a row of the
-:code:`scenarios` table. The columns of the :code:`scenarios` table are
-linked one of the 'building blocks' -- the data in :code:`inputs_` tables --
-via the respective *subscenario ID*.
-
-For example, the :code:`load_scenario_id` column of the :code:`scenarios` table
-references the :code:`load_scenario_id` column of the
-:code:`subscenarios_system_load` table, which in turn determines which load
-profile contained in the :code:`inputs_system_load` table the scenario
-should use. In our example with three different load profiles, the data for
-which are contained in the :code:`inputs_system_load` table,
-:code:`subscenarios_system_load` will contain three rows with values of 1,
-2, and 3 respectively in the :code:`load_scenario_id` column; in the
-:code:`scenarios` table, the user would then be able to select a value of 1,
-2, or 3 in the :code:`load_scenario_id` column to determine which load
-profile the scenario should use. Similarly, we would select the solar costs
-to use in the scenario via the :code:`projects_new_cost_scenario_id` column
-of the :code:`scenarios` table (which is linked to the
-:code:`subscenarios_project_new_cost` and :code:`inputs_project_new_cost`
-tables) and the operational characteristics of coal to use via the
-:code:`project_operational_chars_scenario_id` column (which is linked to the
-:code:`subscenarios_project_operational_chars` and
-:code:`inputs_project_operational_chars` tables).
-
-***************************
-The :code:`options_` Tables
-***************************
-Some GridPath run options can be specified via the database in the
-:code:`options_` tables. Currently, this includes the solver options that
-can be specified for a scenario run
-
-**************************
-The :code:`status_` Tables
-**************************
-GridPath keeps track of scenario validation and run status. The scenario
-status is recorded in the :code:`scenarios` table (in the
-:code:`validation_status_id` and :code:`run_status_id` columns) and an
-additional detail can be found in the :code:`status_` tables. Currently,
-this includes a single table: the :code:`status_validation` table, which
-contains information about errors encountered during validation for each
-scenario that has been validated.
-
-**********************
-The :code:`ui_` Tables
-**********************
-The :code:`ui_` tables are used to include and exclude components of the
-GridPath user interface.
-
-***********************
-The :code:`viz_` Tables
-***********************
-The :code:`viz_` tables are used in the GridPath visualization suite, for
-instance when determining in which color and order to plot the technologies in
-the dispatch plot.
-
-
-"""
diff --git a/db/doc.py b/db/doc.py
new file mode 100644
index 000000000..4693f35fd
--- /dev/null
+++ b/db/doc.py
@@ -0,0 +1,116 @@
+# Copyright 2016-2025 Blue Marble Analytics LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""
+All tables names in the GridPath database start with one of seven prefixes:
+:code:`mod_`, :code:`subscenario_`, :code:`inputs_`, :code:`scenarios`,
+:code:`options_`, :code:`status_`, or :code:`ui_`. This structure is meant to
+organize the tables by their function. Below are descriptions of each table
+type and its role, and of the kind of data tables of this type contain.
+
+***********************
+The :code:`mod_` Tables
+***********************
+The :code:`mod_` should not be modified except by developers. These contain
+various data used by the GridPath platform to describe available
+functionality, help enforce input data consistency and integrity, and aid in
+validation.
+
+***************************************************
+The :code:`subscenario_` and :code:`inputs_` Tables
+***************************************************
+Most tables in the GridPath database have the :code:`subscenario_` and
+:code:`inputs_` prefix. With a few exceptions, for each :code:`subscenario_`
+table, there is a respective :code:`inputs_` table (i.e. the tables have the
+same name except for the prefix). This is because the :code:`subscenario_`
+tables contain the descriptions of the input data contained in the
+:code:`inputs_` tables. For example the :code:`inputs_system_load` may
+contain three different load profiles -- low, mid, and high; the
+:code:`subscenarios_system_load` will then contain three rows, one for each
+load profile, with its description and ID. The pairs of :code:`subscenario_`
+and :code:`inputs_` are linked via an ID column: in the case of the system
+load tables, that is the :code:`load_scenario_id` column. We call these
+shared table keys *subscenario IDs*, as we use them to create a full
+GridPath scenario in the :code:`scenarios` table.
+
+***************************
+The :code:`scenarios` Table
+***************************
+In GridPath, we use the term 'scenario' to describe a model run with a
+particular set of inputs. Some of those inputs stay the same from scenario to
+scenario and others we vary to understand their effect on the results. For
+example, we could keep some input types like the zonal and transmission
+topography, temporal resolution, resource availability, and policy
+requirements the same across scenarios, but vary other input types, e.g. the
+load profile, the cost of solar, and the operational characteristics of coal,
+to create different scenarios. We call each of those inputs types a
+'subscenario' since they are the building blocks of a full scenario. In
+GridPath, you can create a scenario by populating a row of the
+:code:`scenarios` table. The columns of the :code:`scenarios` table are
+linked one of the 'building blocks' -- the data in :code:`inputs_` tables --
+via the respective *subscenario ID*.
+
+For example, the :code:`load_scenario_id` column of the :code:`scenarios` table
+references the :code:`load_scenario_id` column of the
+:code:`subscenarios_system_load` table, which in turn determines which load
+profile contained in the :code:`inputs_system_load` table the scenario
+should use. In our example with three different load profiles, the data for
+which are contained in the :code:`inputs_system_load` table,
+:code:`subscenarios_system_load` will contain three rows with values of 1,
+2, and 3 respectively in the :code:`load_scenario_id` column; in the
+:code:`scenarios` table, the user would then be able to select a value of 1,
+2, or 3 in the :code:`load_scenario_id` column to determine which load
+profile the scenario should use. Similarly, we would select the solar costs
+to use in the scenario via the :code:`projects_new_cost_scenario_id` column
+of the :code:`scenarios` table (which is linked to the
+:code:`subscenarios_project_new_cost` and :code:`inputs_project_new_cost`
+tables) and the operational characteristics of coal to use via the
+:code:`project_operational_chars_scenario_id` column (which is linked to the
+:code:`subscenarios_project_operational_chars` and
+:code:`inputs_project_operational_chars` tables).
+
+***************************
+The :code:`options_` Tables
+***************************
+Some GridPath run options can be specified via the database in the
+:code:`options_` tables. Currently, this includes the solver options that
+can be specified for a scenario run
+
+**************************
+The :code:`status_` Tables
+**************************
+GridPath keeps track of scenario validation and run status. The scenario
+status is recorded in the :code:`scenarios` table (in the
+:code:`validation_status_id` and :code:`run_status_id` columns) and an
+additional detail can be found in the :code:`status_` tables. Currently,
+this includes a single table: the :code:`status_validation` table, which
+contains information about errors encountered during validation for each
+scenario that has been validated.
+
+**********************
+The :code:`ui_` Tables
+**********************
+The :code:`ui_` tables are used to include and exclude components of the
+GridPath user interface.
+
+***********************
+The :code:`viz_` Tables
+***********************
+The :code:`viz_` tables are used in the GridPath visualization suite, for
+instance when determining in which color and order to plot the technologies in
+the dispatch plot.
+
+
+"""
diff --git a/db/utilities/scenario.py b/db/utilities/scenario.py
index e0413d95c..c6669e149 100644
--- a/db/utilities/scenario.py
+++ b/db/utilities/scenario.py
@@ -18,6 +18,9 @@
>>> gridpath_load_scenarios --database PATH/DO/DB --csv_path PATH/TO/SCENARIO/CSV
+If you are using the csvs_test_examples directory included with GridPath, /PATH/TO/SCENARIO/CSV
+can be set to ../csvs_test_examples/scenarios.csv.
+
To load a single scenario by name, use the *--scenario* flag. To delete a scenario from
the database, specify the scenario name with the *--scenario* flag and use the
*--delete* flag.
diff --git a/doc/graphics/gridpath_workflow.png b/doc/graphics/gridpath_workflow.png
index 34da62380..f2aa23a67 100644
Binary files a/doc/graphics/gridpath_workflow.png and b/doc/graphics/gridpath_workflow.png differ
diff --git a/doc/graphics/optype_opchar_matrix.png b/doc/graphics/optype_opchar_matrix.png
index 8e7e3393b..3561309c5 100644
Binary files a/doc/graphics/optype_opchar_matrix.png and b/doc/graphics/optype_opchar_matrix.png differ
diff --git a/doc/graphics/optype_opchar_matrix.svg b/doc/graphics/optype_opchar_matrix.svg
new file mode 100644
index 000000000..b037662cb
--- /dev/null
+++ b/doc/graphics/optype_opchar_matrix.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/doc/opchar_img_gen.py b/doc/opchar_img_gen.py
index 46a721b88..448a80eea 100644
--- a/doc/opchar_img_gen.py
+++ b/doc/opchar_img_gen.py
@@ -1,4 +1,4 @@
-# Copyright 2016-2024 Blue Marble Analytics LLC.
+# Copyright 2016-2025 Blue Marble Analytics LLC.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@@ -28,7 +28,7 @@
)
d2i_tbl_hdr_dict = dict(
- align="right", fill_color="blue", font_color="white", line_color="darkslategray"
+ align="right", fill_color="#5176BF", font_color="white", line_color="darkslategray"
)
d2i_tbl_cel_dict = dict(align="right", line_color="darkslategray")
@@ -45,24 +45,61 @@
tbl_header=d2i_tbl_hdr_dict,
tbl_cells=d2i_tbl_cel_dict,
show_fig=False,
- row_fill_color=("#ffffff", "#d7d8d6"),
+ row_fill_color=("#ffffff", "#5176BF"),
print_index=False,
- fig_size=(1800, 500),
+ fig_size=(3500, 1000),
col_width=tuple(col_width_both),
)
fig_table = fig.data[0]
rr1, cc1 = np.where(df == "required")
-for validx in range(len(rr1)):
- ra = rr1[validx]
- ca = cc1[validx]
- fig_table.cells.fill.color[ca][ra] = "#FF0000"
-
rr2, cc2 = np.where(df == "optional")
-for validx in range(len(rr2)):
- rb = rr2[validx]
- cb = cc2[validx]
- fig_table.cells.fill.color[cb][rb] = "#FFFF00"
+
+# python
+# prepare a mutable, normalized column-first list-of-lists for cell fill colors
+colors = list(fig_table.cells.fill.color)
+
+# determine actual number of rows in the table (includes header row)
+num_rows_in_table = 0
+for col in colors:
+ if isinstance(col, (tuple, list)):
+ num_rows_in_table = max(num_rows_in_table, len(col))
+ else:
+ num_rows_in_table = max(num_rows_in_table, 1)
+if num_rows_in_table == 0:
+ num_rows_in_table = len(df) + 1
+
+# normalize each column to be a list of length num_rows_in_table
+normalized = []
+for col in colors:
+ if not isinstance(col, list):
+ col_list = list(col) if isinstance(col, (tuple, list)) else [col]
+ else:
+ col_list = col
+ if len(col_list) < num_rows_in_table:
+ col_list = col_list + ["#ffffff"] * (num_rows_in_table - len(col_list))
+ elif len(col_list) > num_rows_in_table:
+ col_list = col_list[:num_rows_in_table]
+ normalized.append(list(col_list))
+colors = normalized
+
+# compute offset between dataframe row indices and table row indices (header row)
+header_offset = num_rows_in_table - len(df)
+if header_offset < 0:
+ header_offset = 0
+
+# set required cells to red (apply header_offset)
+for r, c in zip(rr1, cc1):
+ if 0 <= c < len(colors) and 0 <= (r + header_offset) < len(colors[c]):
+ colors[c][r + header_offset] = "#BF5176"
+
+# set optional cells to yellow (apply header_offset)
+for r, c in zip(rr2, cc2):
+ if 0 <= c < len(colors) and 0 <= (r + header_offset) < len(colors[c]):
+ colors[c][r + header_offset] = "#51BF9B"
+
+# assign back the modified colors
+fig_table.cells.fill.color = colors
df2img.save_dataframe(fig=fig, filename="graphics/optype_opchar_matrix.png")
df2img.save_dataframe(fig=fig, filename="graphics/optype_opchar_matrix.svg")
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 971867acb..89a070631 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -18,6 +18,7 @@
import os
import sys
+import sphinx_rtd_theme
sys.path.insert(0, os.path.abspath("../../"))
@@ -36,6 +37,7 @@
"sphinx.ext.todo",
"sphinx.ext.viewcode",
"sphinxarg.ext",
+ "sphinx_rtd_theme",
]
# Add any paths that contain templates here, relative to this directory.
@@ -52,7 +54,7 @@
# General information about the project.
project = "GridPath"
-copyright = "2016-2022, Blue Marble Analytics LLC"
+copyright = "2016-2025, Blue Marble Analytics LLC"
author = "Blue Marble Analytics LLC"
# The version info for the project you're documenting, acts as replacement for
@@ -95,7 +97,7 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
# http://www.sphinx-doc.org/en/stable/theming.html
-html_theme = "nature"
+html_theme = "sphinx_rtd_theme"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
diff --git a/doc/source/database.rst b/doc/source/database.rst
index 33467fe96..a5bf0ad0f 100644
--- a/doc/source/database.rst
+++ b/doc/source/database.rst
@@ -4,18 +4,12 @@ Database
This chapter describes the following:
-* :ref:`database-structure-section-ref` : the structure of the database and its
- associated tables
-* :ref:`building-the-database-section-ref` : instructions on how to build the
+* :ref:`building-the-database-section-ref`: instructions on how to build the
database
-* :ref:`database-testing-section-ref` : instructions on how to validate the
-database inputs
-
-.. _database-structure-section-ref:
-Database Structure
-##################
-
-.. automodule:: db
+* :ref:`db-structure-section-ref`: the structure of the database and its
+ associated tables
+* :ref:`gridpath-input-data-section-ref`: details on the various types of input data that can be loaded into the database
+* :ref:`database-testing-section-ref`: instructions on how to validate the database inputs
.. _building-the-database-section-ref:
@@ -32,6 +26,20 @@ Creating the Database
Populating the Database
***********************
+Example Input Data
+******************
+For the purposes of this section, you may use the example CSV files provided
+in the :code:`gridpath/db/csvs_test_examples` folder. Please ensure that you
+download the CSV files from the same version of GridPath that you are using,
+as the database structure may change between versions. Find your version of
+GridPath `here `_, download the
+source code for your version, and copy the contents of the
+:code:`gridpath/db/csvs_test_examples` folder to your local machine. You can
+then point the GridPath database-building tools to this directory
+(PATH/DO/DB). See the :ref:`db-structure-section-ref` and
+:ref:`gridpath-input-data-section-ref` for an explanation of the database
+structure and its tables.
+
Loading Input Data
******************
@@ -42,9 +50,28 @@ Creating Scenarios
.. automodule:: db.utilities.scenario
+.. _db-structure-section-ref:
+Database Structure
+##################
+
+The database consists of a set of tables that store input data for GridPath
+scenarios. Each table has a specific structure and set of required and
+optional fields. The database also contains tables that store metadata about the
+scenarios, such as the list of subscenarios that make up a scenario and the
+features that are enabled for a scenario.
+
+.. automodule:: db.doc
+
+.. _gridpath-input-data-section-ref:
GridPath Input Data
###################
+A minimal set of inputs for a GridPath scenario would generally includes
+temporal inputs, load zone inputs, system load inputs, a project portfolio
+and load zones, and project operating characteristics. You can look for the
+inputs labeled as
+*core* in the csv_structure.csv file in *db/csvs_test_examples*.
+
***************
Temporal Inputs
***************
@@ -151,28 +178,27 @@ Project Operational Characteristics
.. automodule:: db.csvs_test_examples.project.opchar.doc
-=====================
-Heat Rates (OPTIONAL)
-=====================
+==========
+Heat Rates
+===========
.. automodule:: db.csvs_test_examples.project.opchar.heat_rate_curves.doc
-======================================
-Variable Generator Profiles (OPTIONAL)
-======================================
+===========================
+Variable Generator Profiles
+===========================
-.. automodule:: db.csvs_test_examples.project.opchar.variable_generator_profiles
-.doc
+.. automodule:: db.csvs_test_examples.project.opchar.variable_generator_profiles.doc
-============================================
-Hydro Operational Characteristics (OPTIONAL)
-============================================
+=================================
+Hydro Operational Characteristics
+=================================
.. automodule:: db.csvs_test_examples.project.opchar.hydro_operational_chars.doc
-******************************
-Transmission Inputs (OPTIONAL)
-******************************
+*******************
+Transmission Inputs
+*******************
Optional inputs needed if transmission feature is enabled for a scenario.
@@ -210,9 +236,9 @@ Transmission Operational Characteristics
.. automodule:: db.csvs_test_examples.transmission.opchar.doc
-**********************
-Fuel Inputs (OPTIONAL)
-**********************
+***********
+Fuel Inputs
+***********
Fuel Characteristics
********************
@@ -225,9 +251,9 @@ Fuel Prices
.. automodule:: db.csvs_test_examples.fuels.fuel_prices.doc
-*******************
-Reserves (OPTIONAL)
-*******************
+********
+Reserves
+********
Regulation Up
*************
@@ -388,8 +414,8 @@ Requirement
-Policy (OPTIONAL)
-*****************
+Policy
+******
========================================================
Energy Targets, e.g. Renewables Portfolio Standard (RPS)
@@ -431,9 +457,8 @@ Target
.. _database-testing-section-ref:
-*************************
Database Input Validation
-*************************
+#########################
Once you have built the database with a set of scenarios and associated inputs,
you can test the inputs for a given scenario by running the inputs validation
@@ -470,12 +495,14 @@ columns:
- :code:`timestamp`: lists the exact time when the validation error
encountered.
-Note that the input validation suite is not exhaustive and does not catch
-every possible input error. As we continue to develop and use GridPath, we
-expect that the set of validation tests will expand and cover more and more
-of the common input errors.
-
To run the validation suite from the command line, navigate to the
:code:`gridpath/gridpath` folder and type::
validate_inputs.py --scenario SCENARIO_NAME --database PATH/TO/DATABASE
+
+
+
+Note that the input validation suite is not exhaustive and does not catch
+every possible input error. As we continue to develop and use GridPath, we
+expect that the set of validation tests will expand and cover more and more
+of the common input errors.
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 5945c2411..4d3ad5efb 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -28,8 +28,8 @@ GridPath Documentation
introduction
installation
usage
- functionality
database
+ functionality
data_toolkit
visualization
ui
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index 11d72e245..0f12c4343 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -63,21 +63,6 @@ On Linux-based systems including MacOS, use::
source PATH/TO/PYTHON/ENV/bin/activate
-Solver
-------
-You will need a solver to get optimization results. GridPath assumes you
-will be using `Cbc (Coin-or branch and cut) `_ by default, but you can specify a different solver as long as it
-is `supported by Pyomo `_,
-e.g. GLPK, CPLEX, Gurobi, etc.
-
-You can find the latest instructions for installing Cbc `here
-`__. GridPath allows you to specify
-the location of the solver executable; to get it to be recognized,
-automatically, you can also add it to your PATH system variables (see
-instructions for Windows `here `__).
Installing GridPath
===================
@@ -98,8 +83,8 @@ To get a specific version, e.g., v0.16.0, use::
Note that GridPath versions before 0.16.0 are not available on PyPi.
-Installation from Source
-------------------------
+Installation from Source (Developers and Advanced Users)
+--------------------------------------------------------
GridPath's source code is stored in a GitHub repository. You can find the latest
GridPath release `here `__.
@@ -132,33 +117,27 @@ If you would like to edit the user-interface code, you will also need Node.js in
addition to Python and will be required to install various node packages.
See the User Interface section for more info.
-^^^^^^^^^^^^^^^^^^^^^^^^^
-Testing Your Installation
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To test the GridPath codebase, use the unittest module as follows from the
-:code:`PATH/TO/GRIDPATH` directory::
-
- python -m unittest discover tests
-
-This command will use the python `unittest `_ module to test all functions in the :code:`./tests` folder.
-Testing includes both simple unittests as well as integration tests that run
-small example problems (for which you will need a solver).
+Solver
+======
+You will need a solver to get optimization results. GridPath assumes you
+will be using `Cbc (Coin-or branch and cut) `_ by default, but you can specify a different solver as long as it
+is `supported by Pyomo `_,
+e.g. GLPK, CPLEX, Gurobi, etc.
+You can find the latest instructions for installing Cbc `here
+`__. GridPath allows you to specify
+the location of the solver executable; to get it to be recognized,
+automatically, you can also add it to your PATH system variables (see
+instructions for Windows `here `__).
Database
========
-While not strictly required -- you can generate TAB-delimited scenario input
-files any way you like -- GridPath includes support for input and output
-data management via an SQLite database. We recommend that you store data in
-the database and use GridPath's built-in tools for loading input data into the
-database, creating scenarios and generating scenario input files, and
-importing scenario results into the database. Using the GridPath user
-interface requires that data be stored in a database.
-
-We recommend `SQLite Studio `_ as an SQLite
-database GUI.
+GridPath includes support for input and output data management via an SQLite
+database. We also recommend `SQLite Studio `_ as an SQLite database GUI.
We have implemented various tools to help you build your database. See the
:ref:`building-the-database-section-ref` section of the documentation
diff --git a/doc/source/introduction.rst b/doc/source/introduction.rst
index 971c181ee..5a365873e 100644
--- a/doc/source/introduction.rst
+++ b/doc/source/introduction.rst
@@ -12,43 +12,23 @@ requirements and can speed up insight-generation in the planning process.
.. image:: ../graphics/approaches.png
-Motivation
-==========
-
-Traditional power-system models are often not designed to address the many
-new questions arising from the shift to low-carbon resources, storage
-deployment, widespread electric vehicle and building electrification, load
-participation in system operations, etc. This was the main motivation for
-GridPath's development. Transitioning to a low-carbon electricity system
-poses numerous new challenges to system planners and operators. Variable
-renewable energy technologies such as wind and solar introduce variability
-and uncertainty to system operations, requiring thoughtful integration
-through resource diversity and interconnection as well as the deployment of
-balancing technologies such as energy storage and demand response. Technology
-characteristics and costs as well as the policy landscape are also evolving
-rapidly. Improperly accounting for the uncertainty and risk can result in
-financial losses, jeopardize grid reliability, and/or create environmental
-damage. In that context, robust planning becomes increasingly important and
-advanced software tools specifically designed understand deeply-decarbonized
-grids can help to rapidly and continuously evaluate and plan the evolving
-electricity system.
Architecture
============
-Unlike other power system tools that can be cumbersome to adapt and extend,
-GridPath is built for today’s and tomorrow’s world: it has a highly
+GridPath is built for today’s and tomorrow’s world, and can be easily adapted
+and extended:
+it has a highly
flexible, modular architecture that facilitates its application to different
systems and regions as well as the incorporation of emergent technologies
and resources with non-standard characteristics (renewables, storage, demand
response, and so on). This makes the GridPath platform well-equipped to
quickly and seamlessly add critical functionality around new technologies,
-policies, or practices, and tackle emergent questions about the pathways to
-and dynamics of deeply decarbonized electricity systems.
+policies, or practices, in addition to full-featured traditional power system
+modeling.
Our goal is to create a transparent and user-friendly platform that
-facilitates quick model development and rapid adaptation. GridPath includes a
-user interface, database-building tools, a results-visualization suite, and
+facilitates quick model development and rapid adaptation. GridPath includes database-building tools, a results-visualization suite, and
extensive validation and testing suites.
Functionality
diff --git a/doc/source/ui.rst b/doc/source/ui.rst
index 7609b934a..8e5db2de7 100644
--- a/doc/source/ui.rst
+++ b/doc/source/ui.rst
@@ -3,11 +3,8 @@ GridPath User Interface
#######################
The GridPath user interface (UI) makes it possible to interact with the
-platform without relying on the command line. We will be distributing compiled
-versions of the UI for Windows and Mac. You can also build the UI from
-source (instructions are in the :code:`README.md` file in GridPath's
-:code:`ui` package). Here we provide instructions for how to *use* the UI.
-
+platform without relying on the command line. A new version of th the UI is
+under development and will be released in 2026.
**********
Navigation
diff --git a/doc/source/usage.rst b/doc/source/usage.rst
index bba38e521..8244b8051 100644
--- a/doc/source/usage.rst
+++ b/doc/source/usage.rst
@@ -2,79 +2,68 @@
Using GridPath
**************
+Workflow
+========
-Running GridPath from the Command Line
-======================================
-
-The gridpath_run and gridpath_run_e2e commands
-----------------------------------------------
-
-If you install GridPath via the setup script following the instructions above,
-you can use the command :code:`gridpath_run` to run a scenario from any
-directory -- as long as your GridPath Python environment is enabled and the
-scenario folder contains the appropriate .tab files -- as
-follows::
+.. image:: ../graphics/gridpath_workflow.png
- gridpath_run --scenario SCENARIO_NAME --scenario_location /PATH/TO/SCENARIO
+GridPath input and scenario data are managed via an SQLite database. GridPath
+includes utilities to assist the user with importing raw data into the correct
+database tables and data format. With the inputs loaded, the user can then
+create scenarios by selecting subsets of the data (e.g. selecting a
+particular load profile or a different portoflio of generators). In
+GridPath's database, these subsets of data are called subscenarios. A
+scenario generally consists of a list of subscenarios and GridPath includes
+utilities to select the correct data for each scenario. The user also selects
+desired features, which tells GridPath which database tables to look at.
+
+See the :ref:`building-the-database-section-ref` section for more details on
+how to set up and load inputs into the database, and create scenarios.
+
+Scenario input files are written to disk in TAB files. The next step is for
+the Python model (consisting of various modules that create the model
+formulation) to read in the TAB-delimited input files and
+create the optimization problem. The compiled model file is then sent to the
+solver. GridPath is solver-agnostic and supports a wide range of solvers.
-If you are using the database, you can use the command :code:`gridpath_run_e2e`
-to run GridPath end-to-end, i.e. get inputs for the scenario from the database,
-solve the scenario problem, import the results into the database, and
-process them::
+See the :ref:`running-gridpath-scenarios-section-ref` section below for how
+to run a GridPath scenario.
- gridpath_run_e2e --scenario SCENARIO_NAME --scenario_location /PATH/TO/SCENARIO
+Once the solver finds a solution, it returns the results to GridPath.
+GridPath's modules then write CSV results files to disk. The user can select
+to manually or automatically import these results into the database.
-To see usage and other optional arguments, e.g. how to specify a
-solver, check the help menu, e.g.::
+Finally, GridPath includes functionality to process the results and creates
+various visualizations. See the :ref:`visualization-section-ref` section for
+more details.
- gridpath_run --help
+.. _running-gridpath-scenarios-section-ref:
+Running GridPath Scenarios
+==========================
-Examples
-========
-To run any of the problems in the *examples* directory, you also need
-to specify a scenario location (as these are not in the default
-*scenarios* subdirectory). For example, to run the *test* scenario in
-the *examples* directory, run the following::
+The gridpath_run_e2e and gridpath_run commands
+----------------------------------------------
- gridpath_run --scenario test --scenario_location ../examples
+Once you have loaded inputs into the database and created a scenario,
+you can use the command :code:`gridpath_run_e2e` to run a scenario from any
+directory -- as long as your GridPath Python environment is enabled -- as
+follows::
+ gridpath_run_e2e --database /PATH/TO/DATABASE --scenario SCENARIO_NAME
+ --scenario_location /PATH/TO/SCENARIO
-Workflow
-========
+The above command runs GridPath end-to-end, i.e. gets inputs for the scenario
+from the database, solves the scenario problem, imports the results into the
+database, and processes them.
-.. image:: ../graphics/gridpath_workflow.png
+If you are not using the database (not recommended), you can use
+the command :code:`gridpath_run` to point to a scenario for which input .tab files have
+already been written::
-GridPath requires a large amount of data on a range of electricity system
-aspects such as zonal and transmission topology, load profiles, generator
-capacities and operating characteristics, renewable profiles, hydropower
-operations, reserve requirements, reliability policies, environmental
-policies, etc. Data is managed via an SQLite database. GridPath includes
-utilities to assist the user with importing raw data into the correct
-database tables and data format.
-
-With the database built, the user can then create scenarios by selecting
-subsets of the data (e.g. selecting a particular load profile or a different
-portoflio of generators). In GridPath's database, these subsets of data are
-called subscenarios. A scenario generally consists of a list of
-subscenarios and GridPath includes utilities to select the correct data for
-each scenario. The user also selects desired features, which tells GridPath
-which database tables to look at.
-
-Currently, scenario input files are written to disk in TAB files. These are
-similar to CSVs, but use tabs instead of commas to delimit values. In the
-future, we may support other file formats, including CSVs. We may also skip
-the writing of files altogether, although keeping an additional record of what
-goes into a scenario is often useful.
-
-The next step is for the Python model (consisting of various modules that
-create the model formulation) to read in the TAB-delimited input files and
-create the optimization problem. The compiled model file is then sent to the
-solver. GridPath is solver-agnostic and supports a wide range of solvers.
+ gridpath_run --scenario SCENARIO_NAME --scenario_location /PATH/TO/SCENARIO
-Once the solver finishes solving, it returns the results to GridPath.
-GridPath's modules then write CSV results files to disk. The user can select
-to manually or automatically import these results into the database.
+To see usage and other optional arguments, e.g. how to specify a
+solver, check the help menu, e.g.::
-Finally, GridPath includes functionality to process the results and creates
-various visualizations.
+ gridpath_run_e2e --help
diff --git a/doc/source/visualization.rst b/doc/source/visualization.rst
index db183313b..648bf8b77 100644
--- a/doc/source/visualization.rst
+++ b/doc/source/visualization.rst
@@ -1,3 +1,5 @@
+.. _visualization-section-ref:
+
#############
Visualization
#############
@@ -15,13 +17,30 @@ database, so users need a functioning database to use this package.
The plotting package consists of a set of plotting scripts that can be called
either from the command line or through the GridPath User Interface. For
instance, to obtain a plot that shows the total installed capacity across
-modeling periods for a certain scenario you would navigate to the :code:`./viz`
-folder and run the following::
-
- python capacity_total_plot.py --scenario test --load_zone CAISO --show
-
-The next section provides a brief description of each plotting script and
-its arguments. As GridPath evolves we expect the list of visualizations to grow.
+modeling periods for a certain scenario, you can run the following command::
+
+ gridpath_viz_capacity_total_plot --scenario test --load_zone CAISO --show
+
+
+The available plotting scripts currently include:
+ * gridpath_viz_capacity_factor_plot
+ * gridpath_viz_capacity_new_plot
+ * gridpath_viz_capacity_retired_plot
+ * gridpath_viz_capacity_total_loadzone_comparison_plot
+ * gridpath_viz_capacity_total_plot
+ * gridpath_viz_capacity_total_scenario_comparison_plot
+ * gridpath_viz_carbon_plot
+ * gridpath_viz_cost_plot
+ * gridpath_viz_curtailment_hydro_heatmap_plot
+ * gridpath_viz_curtailment_variable_heatmap_plot
+ * gridpath_viz_dispatch_plot
+ * gridpath_viz_energy_plot
+ * gridpath_viz_energy_target_plot
+ * gridpath_viz_project_operations_plot
+
+See the --help menu for usage details. The next section provides a brief
+description of each plotting script and its arguments. As GridPath evolves we
+expect the list of built-in visualizations to grow.
****************
Plotting scripts
diff --git a/gridpath/project/operations/operational_types/opchar_param_requirements.csv b/gridpath/project/operations/operational_types/opchar_param_requirements.csv
index dfb99c7dc..36d7d134f 100644
--- a/gridpath/project/operations/operational_types/opchar_param_requirements.csv
+++ b/gridpath/project/operations/operational_types/opchar_param_requirements.csv
@@ -1,4 +1,4 @@
-char,type,dr,gen_always_on,gen_commit_bin,gen_commit_cap,gen_commit_lin,gen_hydro,gen_hydro_must_take,gen_must_run,gen_simple,gen_var,gen_var_must_take,stor,gen_var_stor_hyb,fuel_prod,dispatchable_load,flex_load,gen_hydro_water,energy_profile,energy_hrz_shaping,energy_load_following,energy_slice_hrz_shaping,load_component_modifier,load_component_shift,gen_simple_no_load_balance_power
+char,type,dr,gen_always_on,gen_commit_bin,gen_commit_cap,gen_commit_lin,gen_hydro,gen_hydro_must_take,gen_must_run,gen_simple,gen_var,gen_var_must_take,stor,gen_var_stor_hyb,fuel_prod,dispatchable_load,flex_load,gen_hydro_water,load_component_modifier,load_component_shift,gen_simple_no_load_balance_power,energy_profile,energy_hrz_shaping,energy_load_following,energy_slice_hrz_shaping
min_stable_level_fraction,float,,required,required,required,required,,,,,,,,,,,,,,,,,,,
unit_size_mw,float,,required,,required,,,,,,,,,,,,,,,,,,,,
startup_plus_ramp_up_rate,float,,,,optional,,,,,,,,,,,,,,,,,,,,
@@ -20,6 +20,6 @@ powerunithour_per_fuelunit,float,,,,,,,,,,,,,,required,,,,,,,,,,
partial_availability_threshold,float,,,optional,,optional,,,,,,,,,,,,,,,,,,,
powerhouse,str,,,,,,,,,,,,,,,,,required,,,,,,,
generator_efficiency,float,,,,,,,,,,,,,,,,,required,,,,,,,
-linked_load_component,str,,,,,,,,,,,,,,,,,,,,,,required,required,
-efficiency_factor,float,,,,,,,,,,,,,,,,,,,,,,,optional,
-energy_requirement_factor,float,,,,,,,,,,,,,,,optional,,,,,,,,,
+linked_load_component,str,,,,,,,,,,,,,,,,,,required,required,,,,,
+efficiency_factor,float,,,,,,,,,,,,,,,,,,,optional,,,,,
+energy_requirement_factor,float,,,,,,,,,,,,,,,optional,,,,,,,,,
\ No newline at end of file
diff --git a/requirements.txt b/requirements.txt
index 76c1ffae1..a78fd8045 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -2,13 +2,13 @@ alabaster==0.7.16
asttokens==3.0.1
attrs==25.4.0
babel==2.17.0
-black==25.11.0
+black==25.12.0
bokeh==3.8.0
certifi==2025.11.12
charset-normalizer==3.4.4
click==8.3.1
contourpy==1.3.3
-coverage==7.12.0
+coverage==7.13.0
coveralls==4.0.2
decorator==5.2.1
df2img==0.2.21
@@ -18,12 +18,12 @@ docutils==0.20.1
duckdb==1.4.0
executing==2.2.1
fastjsonschema==2.21.2
-GridPath==2025.10.2
+GridPath==2025.10.3
gurobipy==13.0.0
highspy==1.12.0
idna==3.11
imagesize==1.4.1
-ipython==9.7.0
+ipython==9.8.0
ipython_pygments_lexers==1.1.1
jedi==0.19.2
Jinja2==3.1.6
@@ -34,7 +34,7 @@ kaleido==0.2.1
MarkupSafe==3.0.3
matplotlib-inline==0.2.1
mypy_extensions==1.1.0
-narwhals==2.12.0
+narwhals==2.13.0
nbformat==5.10.4
networkx==3.5
nose==1.3.7
@@ -45,7 +45,7 @@ parso==0.8.5
pathspec==0.12.1
pexpect==4.9.0
pillow==12.0.0
-platformdirs==4.5.0
+platformdirs==4.5.1
plotly==6.5.0
ply==3.11
prompt_toolkit==3.0.52
@@ -61,14 +61,16 @@ PyUtilib==6.0.0
PyYAML==6.0.3
referencing==0.37.0
requests==2.32.5
-rpds-py==0.29.0
+rpds-py==0.30.0
six==1.17.0
snowballstemmer==3.0.1
Sphinx==7.2.6
sphinx-argparse==0.4.0
+sphinx-rtd-theme==3.0.2
sphinxcontrib-applehelp==2.0.0
sphinxcontrib-devhelp==2.0.0
sphinxcontrib-htmlhelp==2.1.0
+sphinxcontrib-jquery==4.1
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==2.0.0
sphinxcontrib-serializinghtml==2.0.0
@@ -76,6 +78,6 @@ stack-data==0.6.3
tornado==6.5.2
traitlets==5.14.3
tzdata==2025.2
-urllib3==2.5.0
+urllib3==2.6.1
wcwidth==0.2.14
xyzservices==2025.11.0
diff --git a/setup.py b/setup.py
index 358bf249b..1b0949008 100644
--- a/setup.py
+++ b/setup.py
@@ -54,6 +54,7 @@
"PyUtilib==6.0.0", # used for solver temp file management
"dill==0.3.8", # pickling
"duckdb==1.4.0", # data-handling
+ "sphinx-rtd-theme", # documentation theme
],
extras_require={
"doc": extras_doc,
diff --git a/version.py b/version.py
index c004df83f..0ca05a791 100644
--- a/version.py
+++ b/version.py
@@ -1 +1 @@
-__version__ = "v2025.10.2"
+__version__ = "v2025.10.3"