diff --git a/docs/Makefile b/docs/Makefile
index 9c9aa31e..0f056625 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -29,7 +29,7 @@ help:
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
- @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " latexpdf to make LaTeX files and run them through xelatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@@ -100,29 +100,29 @@ latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
- @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ @echo "Run \`make' in that directory to run these through xelatex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
- @echo "Running LaTeX files through pdflatex..."
+ @echo "Running LaTeX files through xelatex..."
@if command -v latexmk > /dev/null 2>&1; then \
$(MAKE) -C $(BUILDDIR)/latex \
LATEXOPTS='-interaction=nonstopmode -file-line-error -halt-on-error' \
all-pdf; \
else \
- echo "latexmk not found, falling back to manual pdflatex..."; \
+ echo "latexmk not found, falling back to manual xelatex..."; \
$(MAKE) -C $(BUILDDIR)/latex \
- PDFLATEX="pdflatex -interaction=nonstopmode -file-line-error -halt-on-error" \
+ PDFLATEX="xelatex -interaction=nonstopmode -file-line-error -halt-on-error" \
LATEXMKOPTS="" \
all-pdf || true; \
- echo "Running pdflatex again for references..."; \
+ echo "Running xelatex again for references..."; \
$(MAKE) -C $(BUILDDIR)/latex \
- PDFLATEX="pdflatex -interaction=nonstopmode -file-line-error -halt-on-error" \
+ PDFLATEX="xelatex -interaction=nonstopmode -file-line-error -halt-on-error" \
LATEXMKOPTS="" \
all-pdf; \
fi
- @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+ @echo "xelatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
diff --git a/docs/source/assets/logo.pdf b/docs/source/assets/logo.pdf
index dacbdd10..35933f72 100644
Binary files a/docs/source/assets/logo.pdf and b/docs/source/assets/logo.pdf differ
diff --git a/docs/source/assets/logo.svg b/docs/source/assets/logo.svg
index e1159b09..45bfb806 100644
--- a/docs/source/assets/logo.svg
+++ b/docs/source/assets/logo.svg
@@ -6,8 +6,30 @@
version="1.1"
width="174.93001"
height="142.12"
+ sodipodi:docname="logo.svg"
+ inkscape:version="1.4.3 (0d15f75042, 2025-12-25)"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns="http://www.w3.org/2000/svg"
xmlns:svg="http://www.w3.org/2000/svg">
+
+ id="path6"
+ style="fill:#1f5a7a;fill-opacity:1" />
+
+ id="path1"
+ style="fill:#1f5a7a;fill-opacity:1" />
+ id="path2"
+ style="fill:#1f5a7a;fill-opacity:1" />
+ id="path3"
+ style="fill:#1f5a7a;fill-opacity:1" />
+ id="path4"
+ style="fill:#1f5a7a;fill-opacity:1" />
+ id="path5"
+ style="fill:#1f5a7a;fill-opacity:1" />
+ id="path6"
+ style="fill:#1f5a7a;fill-opacity:1" />
=`) with a Pyomo object (like supply_annual) generate a Pyomo
-*expression object*, not a boolean True or False as one might expect [#return_expression]_.
+*expression object*, not a boolean True or False as one might expect [return_expression]_.
It is this expression object that must be returned to Pyomo, as on Line 13.
In the above implementation, the constraint is called for every tuple in the
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 43934d0d..0c7b2969 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -1,7 +1,6 @@
#
import os
import sys
-import time
from pathlib import Path
from typing import Any, cast
@@ -32,7 +31,6 @@
author = ', '.join(
author['name'] for author in cast('list[dict[str, Any]]', project_metadata.get('authors', []))
)
-copyright = f'2011-{time.strftime("%Y")}, NC State University'
# The short version
@@ -139,3 +137,6 @@
mermaid_fullscreen = True
mermaid_include_elk = True
mermaid_include_mindmap = True
+
+# -- Options for LaTeX output ------------------------------------------------
+latex_engine = 'xelatex'
diff --git a/docs/source/database.rst b/docs/source/database.rst
new file mode 100644
index 00000000..59dd676f
--- /dev/null
+++ b/docs/source/database.rst
@@ -0,0 +1,217 @@
+
+=====================
+Database Construction
+=====================
+
+Input datasets in Temoa are stored in a relational database management system.
+For those unfamiliar with databases, you can think of them as collections of
+tables. Within each table, a 'primary key' uniquely identifies each row. A
+'foreign key' is a column in one table that references the primary key of
+another table, thereby establishing relationships between tables and ensuring
+data consistency across the database.
+
+The following Entity-Relationship (ER) diagram provides a visual overview of the
+Temoa v4 database schema and the relationships between its various tables:
+
+.. mermaid:: database_schema.mmd
+ :alt: Temoa Database Schema ER Diagram
+ :align: center
+
+Temoa uses `sqlite`_, a widely used, self-contained database
+system. Building a database first requires constructing a sql file, which is
+simply a text file that defines the structure of different database tables and
+includes the input data. The snippet below is from the ``time_period`` table
+used to define the ``test_system`` dataset:
+
+.. parsed-literal::
+ 1 CREATE TABLE time_period
+ 2 (
+ 3 sequence INTEGER UNIQUE,
+ 4 period INTEGER
+ 5 PRIMARY KEY,
+ 6 flag TEXT
+ 7 REFERENCES time_period_type (label)
+ 8 );
+ 9 INSERT INTO "time_period" VALUES(1,2015,'e');
+ 10 INSERT INTO "time_period" VALUES(2,2020,'f');
+ 11 INSERT INTO "time_period" VALUES(3,2025,'f');
+ 12 INSERT INTO "time_period" VALUES(4,2030,'f');
+ 13 INSERT INTO "time_period" VALUES(5,2035,'f');
+
+The first line creates the table. **Lines 3-7** define the columns within this
+table. Note that ``period`` is the primary key. Therefore, the same time period
+cannot be entered twice; each name must be unique. **Line 7**, which helps
+define the ``flag`` column, declares a foreign key reference to the ``label``
+column of the ``time_period_type`` table. As a result, if the user tries to
+enter a label in this table that does not exist in the ``time_period_type``
+table, it will fail with an error. This foreign key reference ensures that the
+modeler doesn't accidentally type the wrong label in this table. For context,
+there are two basic types of time periods in Temoa, ``e``, which defines
+pre-existing periods, and ``f``, which defines future time periods that are to
+be optimized.
+
+This enforcement of names across tables using foreign keys helps immediately
+catch typos. As you can imagine, typos happen in plain text files and Excel when
+defining thousands of rows of data. Another big advantage of using databases is
+that the model run outputs are stored in separate database output tables. The
+outputs by model run are indexed by a scenario name, which makes it possible to
+perform thousands of runs, programmatically store all the results, and execute
+arbitrary queries that instantaneously return the requested
+data.
+
+Because some database table elements serve as foreign keys in other tables, we
+recommend that you populate input tables in the following order:
+
+**Group 1: labels used for internal database processing**
+ * commodity_type: Need to identify which type of commodity. Do NOT change these abbreviations.
+ * technology_type: Need to identify which type of technology. Do NOT change these abbreviations. Categorizing
+ and sub-categorizing can be done in the Technology table itself.
+ * time_period_type: Used to distinguish which time periods are simply used to specify pre-existing
+ vintages and which represent future optimization periods.
+
+
+**Group 2: sets used within Temoa**
+ * commodity: list of commodities used within the database
+ * technology: list of technologies used within the database
+ * time_period: list of both past and future time periods considered in the database
+ * time_season: seasons modeled in the database (also contains segment fractions)
+ * time_of_day: time of day segments modeled in the database
+
+
+**Group 3: parameters used to define processes within Temoa**
+ * metadata_real (global_discount_rate)
+ * demand
+ * demand_specific_distribution
+ * efficiency
+ * existing_capacity
+ * capacity_factor_tech
+ * capacity_factor_process (only if CF varies by vintage; overwrites capacity_factor_tech)
+ * capacity_to_activity
+ * cost_fixed
+ * cost_invest
+ * cost_variable
+ * emission_activity
+ * lifetime_tech
+ * lifetime_process (only if LT varies by vintage; overwrites lifetime_tech)
+
+
+**Group 4: parameters used to define constraints within Temoa** (non-exhaustive)
+ * limit_activity
+ * limit_capacity
+ * limit_emission
+ * limit_growth_capacity
+ * limit_new_capacity
+ * limit_resource
+ * limit_tech_input_split
+ * limit_tech_output_split
+
+
+For help getting started, consider using the ``temoa tutorial ``
+command to generate a template project or inspect the example SQL file at
+``temoa/tutorial_assets/utopia.sql``. To begin building your own database file, use
+``temoa/db_schema/temoa_schema_v4.sql``, which is a database file with the requisite
+structure but no data added. We recommend leaving the database structure intact,
+and simply adding data to the schema file, or constructing an empty database
+from the schema file and then using a script or database editor to import data.
+Once the sql file is complete, you can convert it into a binary sqlite file by
+installing sqlite3 and executing the following command:
+
+.. parsed-literal::
+ $ sqlite3 my_database.sqlite < my_database.sql
+
+.. note::
+ The command above using the ``<`` operator for input redirection is supported
+ in Linux, macOS, and the Windows Command Prompt. Note that PowerShell does not
+ support the Unix-style ``<`` redirection operator. In PowerShell, you can
+ achieve the same result by piping the file content into ``sqlite3``:
+
+ .. code-block:: powershell
+
+ Get-Content my_database.sql | sqlite3 my_database.sqlite
+
+ Alternatively, you can load a SQL file from within the ``sqlite3`` interactive
+ interface using the ``.read`` command:
+
+ .. code-block:: none
+
+ sqlite3 my_database.sqlite
+ sqlite> .read my_database.sql
+
+ When running on Windows, be sure to use the correct path separators (``\``) if you
+ provide absolute paths to your files.
+
+Now you can specify this database as the source for both input and output data
+in the config file.
+
+============
+Data Quality
+============
+
+In addition to numerous internal checks, Temoa (optionally) employs two quality checks on
+data read in from the database. The outputs (actions and warnings) generated by these processes
+are reported in the log file for the run.
+
+Both of the checks below can be run to QA data by running the model in `CHECK` mode and inspecting
+the log file. During `CHECK` mode runs, no solve is attempted on the model.
+
+Price Checking
+--------------
+The "price checker" reviews cost data in the 3 cost tables and considers technology lifetime. It
+screens for possible inconsistencies that would corrupt output quality. Larger models may have
+well over 100K cost entries and an overlooked investment cost for a particular vintage tech in
+a particular region could easily be overlooked. Price checks performed/reported:
+
+1. **Missing Costs (Check 0)**: This check looks for technologies that have no fixed/invest/variable
+ costs at all. Other checks are more discriminating, so this check is only reported when Temoa is run
+ in `debug` mode by using the `-d` flag on the run command.
+2. **Missing Fixed/Investment Costs (Check 1a)**: This check identifies technologies that are *not*
+ flagged as `uncapacitated` with neither a fixed or investment cost associated. These *might* be
+ problematic for solve because the model minimizes cost, so capacity in these technologies would be
+ free. `uncapacitated` technologies have no capacity measure, so fixed/investment costs are prohibited
+ for them and that is checked elsewhere.
+3. **Inconsistent Fixed/Investment Cost (Check 1b)**: This check looks for inconsistent application
+ of fixed or base costs in the "base" or vintage year across all vintages and regions. So, if a tech has
+ a fixed cost in some particular region and vintage year, but not in all, it will be flagged as a likely
+ omission.
+4. **Inconsistent Fixed & Variable Costs (Check 2)**: This check identifies techs that have
+ inconsistencies in the application of fixed - variable costs. Techs that have *any* fixed cost for
+ a particular [region, tech, vintage] process, but do not have entries that match the variable cost
+ entries for the same process are flagged, and vice-versa. This would hopefully identify an
+ accidental omission of some of the fixed/var costs for processes that have at least 1 entry for either.
+5. **Lifetime Costing (Check 3)**: This check identifies costs that fall short or are missing
+ during the process's lifetime. If a process has a variable cost in *any* year during the lifetime, but
+ not all years, it is flagged. Same for fixed cost.
+6. **Uncapacitated Tech Costs**: Any technology flagged as `uncapacitated` will trigger warnings here
+ if it has any fixed/invest costs.
+
+Source Tracing
+--------------
+
+Temoa works backwards from demands to identify chains of technologies required to meet the demand.
+Source Tracing is designed to ensure that this backward tracing from demands describes a proper
+commodity network without gaps that might allow intermediate commodities to be treated as a free
+"source" commodity. Further description of possible network problems is included in the
+:doc:`commodity_network` section.
+
+Source Tracing pre-builds the entire commodity network in each region-period contained in the
+data and analyzes it for "orphans" which likely represent gaps in the network that would lead
+to erroneous output data. The operation is enabled by tagging foundational commodities for which
+there are no predecessors as "source" commodities in the `Commodity` database table with an `s` tag.
+Orphans (or chains of orphans) on either the demand or supply side are reported and *suppressed* in
+the data to prevent network corruption. Additionally, Temoa performs cycle detection on the commodity
+network to identify circular dependencies that could lead to non-convergence or erroneous results.
+Users can configure the cycle detection behavior using the following settings:
+
+* **cycle_count_limit**: Limits the number of cycles reported in the log. A value of `-1` allows
+ unbounded detection, `0` causes the system to log an error on the first detected cycle and then
+ suppresses further cycle reports for the remainder of the run (without terminating execution),
+ and a positive integer sets a specific limit. Default is 100.
+* **cycle_length_limit**: Minimum length of cycles to report. This can be used to filter out small,
+ expected circularities if necessary. Default is 1. The length limit is inclusive, so a cycle of
+ length 1 is a self-loop, and a cycle of length `n` has `n` unique nodes.
+
+Note that the myopic mode *requires* the use of Source Tracing to ensure accuracy as some orphans
+may be produced by endogenous decisions in myopic runs.
+
+
+.. _sqlite: https://www.sqlite.org/
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 63c3f8f7..f9043f39 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,11 +1,35 @@
Temoa Project Documentation
-=======================================================
+===========================
.. toctree::
+ :maxdepth: 2
+ :caption: Getting Started
- Documentation
+ preface
+ quick_start
+ database
+ commodity_network
+ visualization
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Core Concepts
+
+ mathematical_formulation
+ computational_implementation
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Advanced Topics
+
+ mga
monte_carlo
myopic
- unit_checking
stochastics
- mga
+ unit_checking
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Appendix
+
+ references
diff --git a/docs/source/mathematical_formulation.rst b/docs/source/mathematical_formulation.rst
index 1190104f..cc4d3da1 100644
--- a/docs/source/mathematical_formulation.rst
+++ b/docs/source/mathematical_formulation.rst
@@ -1,4 +1,8 @@
+========================
+Mathematical Formulation
+========================
+
To understand this section, the reader will need at least a cursory
understanding of mathematical optimization. We omit here that introduction,
and instead refer the reader to `various`_ `available`_ `online`_ `sources`_.
@@ -318,7 +322,7 @@ process, Temoa also utilizes the indices to understand the valid input
instance, if a modeler does not specify an efficiency for a 2020 vintage coal
power plant, then Temoa will recognize any mention of a 2020 vintage coal power
plant elsewhere as an error. Generally, if a process is not specified in the
-efficiency table,\ [#efficiency_table]_ Temoa assumes it is not a valid process
+efficiency table,\ [efficiency_table]_ Temoa assumes it is not a valid process
and will provide the user a warning with pointed debugging information.
diff --git a/docs/source/monte_carlo.rst b/docs/source/monte_carlo.rst
index 1a4bc9d2..5bb4296a 100644
--- a/docs/source/monte_carlo.rst
+++ b/docs/source/monte_carlo.rst
@@ -1,5 +1,5 @@
-Monte Carlo Uncertainty Quantification
-========================================
+Monte Carlo Simulation
+======================
Temoa provides a Monte Carlo simulation framework that allows users to perform
probabilistic analysis by executing multiple model runs with varying input parameters.
diff --git a/docs/source/preface.rst b/docs/source/preface.rst
index 3ae14438..16b8261d 100644
--- a/docs/source/preface.rst
+++ b/docs/source/preface.rst
@@ -1,5 +1,9 @@
+=======
+Preface
+=======
+
This manual, in both `PDF`_ and `HTML`_ form, is the official documentation of
Tools for Energy Model Optimization and Analysis (Temoa). It describes all
functionality of the Temoa model, and provides a mathematical description of
@@ -30,7 +34,7 @@ The energy system on which Temoa and other ESOMs operate can be visualized as
a directed graph. Primary energy sources represent the points of origin, which
are transformed by a network of energy conversion and delivery technologies, and
ultimately produce consumable energy commodities that satisfy end-use demands.
-[#esom_definition]_. Temoa provides tools to explicitly represent this network,
+[esom_definition]_. Temoa provides tools to explicitly represent this network,
visualize system structure, and trace energy flows through time.
A defining strength of Temoa is its flexible treatment of time. Users may
@@ -46,7 +50,7 @@ driven by specific analytic needs over a decade of model development and
policy-focused application.
Temoa is implemented within an open-source software stack and is released under
-the MIT license, with source code available on GitHub [#open_source_realities]_.
+the MIT license, with source code available on GitHub [open_source_realities]_.
The model is written in Python and seamlessly integrates with the broader Python
ecosystem. Input data are stored in a relational SQLite database, enabling
transparency, reproducibility, and easy modification. The model maintains a
@@ -64,6 +68,8 @@ extensibility, and trust in energy system modeling results.
+
+
Why Temoa?
----------
In 2009, when the idea for Temoa was born, most options for energy systems
@@ -112,12 +118,9 @@ project there are plenty of levels and avenues for error. If you spot a bug,
inconsistency, or general "that could be improved", we want to hear about it.
If you are a software developer-type, feel free to open an issue on our `GitHub
-Issue tracker`_\ . If you would rather not create a GitHub account, feel free
-to let us know the issue on our `mailing list`_\ .
+Issue tracker`_\ .
-.. _PDF: https://temoacloud.com/wp-content/uploads/2020/02/toolsforenergymodeloptimizationandanalysistemoa.pdf
-.. _HTML: http://temoaproject.org/docs/
+.. _PDF: https://assets.temoaproject.org/pdf_docs/temoa_docs.pdf
+.. _HTML: https://docs.temoaproject.org/en/latest/
.. _GitHub Issues: https://github.com/TemoaProject/temoa/issues
.. _GitHub Issue tracker: https://github.com/TemoaProject/temoa/issues
-.. _mailing list: https://groups.google.com/forum/#!forum/temoa-project
-
diff --git a/docs/source/quick_start.rst b/docs/source/quick_start.rst
index 7664bb4c..fb929a8b 100644
--- a/docs/source/quick_start.rst
+++ b/docs/source/quick_start.rst
@@ -1,5 +1,9 @@
+===========
+Quick Start
+===========
+
Installing Software Elements
----------------------------
@@ -15,9 +19,18 @@ The standard way to install Temoa:
First, it is highly recommended to use a Python virtual environment to manage dependencies:
.. parsed-literal::
+ # Linux / macOS
$ python -m venv temoa_env
$ source temoa_env/bin/activate
+ # Windows (Command Prompt)
+ > python -m venv temoa_env
+ > temoa_env\\Scripts\\activate
+
+ # Windows (PowerShell)
+ PS> python -m venv temoa_env
+ PS> .\\temoa_env\\Scripts\\Activate.ps1
+
Then, install Temoa:
.. parsed-literal::
@@ -33,9 +46,12 @@ Then, install Temoa:
For faster dependency resolution:
.. parsed-literal::
- # Install uv
+ # Install uv (Linux / macOS)
$ curl -LsSf https://astral.sh/uv/install.sh | sh
+ # Install uv (Windows)
+ PS> powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
# Create a uv initialized virtual environment
$ uv init
$ cd
@@ -121,198 +137,3 @@ the solver, and (5) to execute several of the modeling extensions.
how to run Temoa from the command line. There is also an option to run
`Temoa on the cloud `, which
is explained in `this video tutorial `.
-
-=====================
-Database Construction
-=====================
-
-Input datasets in Temoa are stored in a relational database management system.
-For those unfamiliar with databases, you can think of them as collections of
-tables. Within each table, a 'primary key' uniquely identifies each row. A
-'foreign key' is a column in one table that references the primary key of
-another table, thereby establishing relationships between tables and ensuring
-data consistency across the database.
-
-The following Entity-Relationship (ER) diagram provides a visual overview of the
-Temoa v4 database schema and the relationships between its various tables:
-
-.. mermaid:: database_schema.mmd
- :alt: Temoa Database Schema ER Diagram
- :align: center
-
-Temoa uses `sqlite`_, a widely used, self-contained database
-system. Building a database first requires constructing a sql file, which is
-simply a text file that defines the structure of different database tables and
-includes the input data. The snippet below is from the ``time_period`` table
-used to define the ``test_system`` dataset:
-
-.. parsed-literal::
- 1 CREATE TABLE time_period
- 2 (
- 3 sequence INTEGER UNIQUE,
- 4 period INTEGER
- 5 PRIMARY KEY,
- 6 flag TEXT
- 7 REFERENCES time_period_type (label)
- 8 );
- 9 INSERT INTO "time_period" VALUES(1,2015,'e');
- 10 INSERT INTO "time_period" VALUES(2,2020,'f');
- 11 INSERT INTO "time_period" VALUES(3,2025,'f');
- 12 INSERT INTO "time_period" VALUES(4,2030,'f');
- 13 INSERT INTO "time_period" VALUES(5,2035,'f');
-
-The first line creates the table. **Lines 3-7** define the columns within this
-table. Note that ``period`` is the primary key. Therefore, the same time period
-cannot be entered twice; each name must be unique. **Line 7**, which helps
-define the ``flag`` column, declares a foreign key reference to the ``label``
-column of the ``time_period_type`` table. As a result, if the user tries to
-enter a label in this table that does not exist in the ``time_period_type``
-table, it will fail with an error. This foreign key reference ensures that the
-modeler doesn't accidently type the wrong label in this table. For context,
-there are two basic types of time periods in Temoa, ``e``, which defines
-pre-existing periods, and ``f``, which defines future time periods that are to
-be optimized.
-
-This enforcement of names across tables using foreign keys helps immediately
-catch typos. As you can imagine, typos happen in plain text files and Excel when
-defining thousands of rows of data. Another big advantage of using databases is
-that the model run outputs are stored in separate database output tables. The
-outputs by model run are indexed by a scenario name, which makes it possible to
-perform thousands of runs, programatically store all the results, and execute
-arbitrary queries that instantaneously return the requested
-data.
-
-Because some database table elements serve as foreign keys in other tables, we
-recommend that you populate input tables in the following order:
-
-**Group 1: labels used for internal database processing**
- * commodity_type: Need to identify which type of commodity. Do NOT change these abbreviations.
- * technology_type: Need to identify which type of technology. Do NOT change these abbreviations. Categorizing
- and sub-categorizing can be done in the Technology table itself.
- * time_period_type: Used to distinguish which time periods are simply used to specify pre-existing
- vintages and which represent future optimization periods.
-
-
-**Group 2: sets used within Temoa**
- * commodity: list of commodities used within the database
- * technology: list of technologies used within the database
- * time_period: list of both past and future time periods considered in the database
- * time_season: seasons modeled in the database (also contains segment fractions)
- * time_of_day: time of day segments modeled in the database
-
-
-**Group 3: parameters used to define processes within Temoa**
- * metadata_real (global_discount_rate)
- * demand
- * demand_specific_distribution
- * efficiency
- * existing_capacity
- * capacity_factor_tech
- * capacity_factor_process (only if CF varies by vintage; overwrites capacity_factor_tech)
- * capacity_to_activity
- * cost_fixed
- * cost_invest
- * cost_variable
- * emission_activity
- * lifetime_tech
- * lifetime_process (only if LT varies by vintage; overwrites lifetime_tech)
-
-
-**Group 4: parameters used to define constraints within Temoa** (non-exhaustive)
- * limit_activity
- * limit_capacity
- * limit_emission
- * limit_growth_capacity
- * limit_new_capacity
- * limit_resource
- * limit_tech_input_split
- * limit_tech_output_split
-
-
-For help getting started, take a look at how ``data_files/example_dbs/utopia.sql``
-is constructed. To begin building your own database file, use
-``data_files/temoa_schema_v4.sql``, which is a database file with the requisite
-structure but no data added. We recommend leaving the database structure intact,
-and simply adding data to the schema file, or constructing an empty database
-from the schema file and then using a script or database editor to import data.
-Once the sql file is complete, you can convert it into a binary sqlite file by
-installing sqlite3 and executing the following command:
-
-.. parsed-literal::
- $ sqlite3 my_database.sqlite < my_database.sql
-
-Now you can specify this database as the source for both input and output data
-in the config file.
-
-============
-Data Quality
-============
-
-In addition to numerous internal checks, Temoa (optionally) employs two quality checks on
-data read in from the database. The outputs (actions and warnings) generated by these processes
-are reported in the log file for the run.
-
-Both of the checks below can be run to QA data by running the model in `CHECK` mode and inspecting
-the log file. During `CHECK` mode runs, no solve is attempted on the model.
-
-Price Checking
---------------
-The "price checker" reviews cost data in the 3 cost tables and considers technology lifetime. It
-screens for possible inconsistencies that would corrupt output quality. Larger models may have
-well over 100K cost entries and an overlooked investment cost for a particular vintage tech in
-a particular region could easily be overlooked. Price checks performed/reported:
-
-1. **Missing Costs (Check 0)**: This check looks for technologies that have no fixed/invest/variable
- costs at all. Other checks are more discriminating, so this check is only reported when Temoa is run
- in `debug` mode by using the `-d` flag on the run command.
-2. **Missing Fixed/Investment Costs (Check 1a)**: This check identifies technologies that are *not*
- flagged as `uncapacitated` with neither a fixed or investment cost associated. These *might* be
- problematic for solve because the model minimizes cost, so capacity in these technologies would be
- free. `uncapacitated` technologies have no capacity measure, so fixed/investment costs are prohibited
- for them and that is checked elsewhere.
-3. **Inconsistent Fixed/Investment Cost (Check 1b)**: This check looks for inconsistent application
- of fixed or base costs in the "base" or vintage year across all vintages and regions. So, if a tech has
- a fixed cost in some particular region and vintage year, but not in all, it will be flagged as a likely
- omission.
-4. **Inconsistent Fixed & Variable Costs (Check 2)**: This check identifies techs that have
- inconsistencies in the application of fixed - variable costs. Techs that have *any* fixed cost for
- a particular [region, tech, vintage] process, but do not have entries that match the variable cost
- entries for the same process are flagged, and vice-versa. This would hopefully identify an
- accidental omission of some of the fixed/var costs for processes that have at least 1 entry for either.
-5. **Lifetime Costing (Check 3)**: This check identifies costs that fall short or are missing
- during the process's lifetime. If a process has a variable cost in *any* year during the lifetime, but
- not all years, it is flagged. Same for fixed cost.
-6. **Uncapacitated Tech Costs**: Any technology flagged as `uncapacitated` will trigger warnings here
- if it has any fixed/invest costs.
-
-Source Tracing
---------------
-
-Temoa works backwards from demands to identify chains of technologies required to meet the demand.
-Source Tracing is designed to ensure that this backward tracing from demands describes a proper
-commodity network without gaps that might allow intermediate commodities to be treated as a free
-"source" commodity. Further description of possible network problems is included in the
-`commodity network notes.md` file in the `docs` folder.
-
-Source Tracing pre-builds the entire commodity network in each region-period contained in the
-data and analyzes it for "orphans" which likely represent gaps in the network that would lead
-to erroneous output data. The operation is enabled by tagging foundational commodities for which
-there are no predecessors as "source" commodities in the `Commodity` database table with an `s` tag.
-Orphans (or chains of orphans) on either the demand or supply side are reported and *suppressed* in
-the data to prevent network corruption. Additionally, Temoa performs cycle detection on the commodity
-network to identify circular dependencies that could lead to non-convergence or erroneous results.
-Users can configure the cycle detection behavior using the following settings:
-
-* **cycle_count_limit**: Limits the number of cycles reported in the log. A value of `-1` allows
- unbounded detection, `0` causes the system to log an error on the first detected cycle and then
- suppresses further cycle reports for the remainder of the run (without terminating execution),
- and a positive integer sets a specific limit. Default is 100.
-* **cycle_length_limit**: Minimum length of cycles to report. This can be used to filter out small,
- expected circularities if necessary. Default is 1. The length limit is inclusive, so a cycle of
- length 1 is a self-loop, and a cycle of length `n` has `n` unique nodes.
-
-Note that the myopic mode *requires* the use of Source Tracing to ensure accuracy as some orphans
-may be produced by endogenous decisions in myopic runs.
-
-
-.. _sqlite: https://www.sqlite.org/
diff --git a/docs/source/Documentation.rst b/docs/source/references.rst
similarity index 58%
rename from docs/source/Documentation.rst
rename to docs/source/references.rst
index b9ccb3b4..1fe8c27f 100644
--- a/docs/source/Documentation.rst
+++ b/docs/source/references.rst
@@ -1,89 +1,61 @@
-=======
-Preface
-=======
-
-.. include:: preface.rst
-
-===========
-Quick Start
-===========
-
-.. include:: quick_start.rst
-
-=============
-Visualization
-=============
-
-.. include:: visualization.rst
-
-
-=====================
-The Math Behind Temoa
-=====================
-
-.. include:: mathematical_formulation.rst
-
-======================================
-The Temoa Computational Implementation
-======================================
-
-.. include:: computational_implementation.rst
+==========
+References
+==========
.. rubric:: Footnotes
-.. [#open_source_realities] The two main goals behind Temoa are transparency and
+.. [open_source_realities] The two main goals behind Temoa are transparency and
repeatability, hence the MIT license. Unfortunately, there are some harsh
realities in the current climate of energy modeling, so this license is not a
guarantee of openness. This documentation touches on the issues involved in
the final section.
-.. [#efficiency_table] The efficiency parameter is often referred to as the
+.. [efficiency_table] The efficiency parameter is often referred to as the
efficiency table, due to how it looks after even only a few entries in the
Pyomo input "dot dat" file.
-.. [#glpk_presolve] Circa 2013, GLPK uses more memory than commercial
+.. [glpk_presolve] Circa 2013, GLPK uses more memory than commercial
alternatives and has vastly weaker presolve capabilities.
-.. [#esom_definition] For a more in-depth description of energy system
+.. [esom_definition] For a more in-depth description of energy system
optimization models (ESOMs) and guidance on how to use them, please see:
DeCarolis et al. (2017) "Formalizing best practice for energy system
optimization modelling", Applied Energy, 194: 184-198.
-.. [#web_browser_svg] SVG support in web browsers is currently hit or miss. The
+.. [web_browser_svg] SVG support in web browsers is currently hit or miss. The
most recent versions of Chromium, Google Chrome, and Mozilla Firefox support
SVG well enough for Temoa's current use of SVG.
-.. [#return_expression] A word on `return` expressions in Pyomo: in most
+.. [return_expression] A word on `return` expressions in Pyomo: in most
contexts a relational expression is evaluated instantly. However, in Pyomo,
a relational expression returns an `expression` object. That is, `'M.aVar >=
5'` does not evaluate to a boolean *true* or *false*, and Pyomo will
manipulate it into the final LP formulation.
-.. [#abstract_model] In contrast to a 'concrete' model, an abstract algebraic
+.. [abstract_model] In contrast to a 'concrete' model, an abstract algebraic
formulation describes the general equations of the model, but requires
modeler-specified input data before it can compute any results.
.. |'''| replace:: ``'``\ ``'``\ ``'``
.. _GNU Linear Programming Kit: https://www.gnu.org/software/glpk/
-.. _WinGLPK: http://winglpk.sf.net/
+.. _WinGLPK: https://winglpk.sourceforge.net/
.. _Github repo: https://github.com/TemoaProject/temoa/
-.. _Temoa model: http://temoaproject.org/download/temoa.py
-.. _temoaproject.org: http://temoaproject.org/
-.. _example data sets: http://temoaproject.org/download/example_data_sets.zip
-.. _mailing list: https://groups.google.com/forum/\#\!forum/temoa-project
-.. _Temoa Forum: https://groups.google.com/forum/\#\!forum/temoa-project
+.. _Temoa model: https://github.com/TemoaProject/temoa/
+.. _temoaproject.org: https://temoaproject.org/
+.. _example data sets: https://datadocs.openenergyoutlook.org/en/latest/datasets.html
+
.. _various: http://xlinux.nist.gov/dads/HTML/optimization.html
-.. _available: http://www.stanford.edu/\~boyd/cvxbook/
+.. _available: https://web.stanford.edu/\~boyd/cvxbook/
.. _online: https://en.wikipedia.org/wiki/Optimization_problem
.. _sources: https://en.wikipedia.org/wiki/Mathematical_optimization
.. _GAMS: http://www.gams.com/
.. _AMPL: http://www.ampl.com/
-.. _PDF: https://temoacloud.com/wp-content/uploads/2020/02/toolsforenergymodeloptimizationandanalysistemoa.pdf
-.. _HTML: http://temoaproject.org/docs/
+.. _PDF: https://assets.temoaproject.org/pdf_docs/temoa_docs.pdf
+.. _HTML: https://docs.temoaproject.org/en/latest/
.. _GitHub Issue tracker: https://github.com/TemoaProject/temoa/issues
-.. _HTML version: http://temoaproject.org/docs/
+.. _HTML version: https://docs.temoaproject.org/en/latest/
.. _code smell: https://en.wikipedia.org/wiki/Code_smell
.. _PEP 8: http://www.python.org/dev/peps/pep-0008/
.. _PEP 3120: http://www.python.org/dev/peps/pep-3120/
@@ -91,9 +63,9 @@ The Temoa Computational Implementation
.. _lambda function: http://docs.python.org/tutorial/controlflow.html\#lambda-forms
.. _generally accepted relative rates: http://www.forecasts.org/inflation.htm
.. _Pull Request: https://help.github.com/articles/using-pull-requests
-.. _quick start guide: http://rogerdudler.github.io/git-guide/
+.. _quick start guide: https://rogerdudler.github.io/git-guide/
.. _sqlite: https://www.sqlite.org/
-.. _Graphviz: http://www.graphviz.org/
+.. _Graphviz: https://graphviz.org/
.. _ruff: https://docs.astral.sh/ruff/
.. bibliography:: References.bib
diff --git a/docs/source/visualization.rst b/docs/source/visualization.rst
index c94e8f2b..f8d29b4e 100644
--- a/docs/source/visualization.rst
+++ b/docs/source/visualization.rst
@@ -1,3 +1,7 @@
+=============
+Visualization
+=============
+
Network Diagrams
----------------