Docs updates

README.md

@@ -24,32 +24,45 @@ GridPath's documentation is hosted on [Read the Docs](https://gridpath.readthedo
 # Installation
 
 ## Python
-GridPath is tested on Python 3.8, 3.9, and 3.10. Get Python
+GridPath is tested on Python 3.8, 3.9, and 3.10. We recommend using Python 3.9. Get 
+Python
 [here](https://www.python.org/downloads/ "Python download").
 
-## Python Packages
+## GridPath Python environment
 You should create a Python environment for your GridPath installation, e.g. via 
-`venv`, [a lightweight environment manager](https://docs.python.org/3/library/venv.html, "venv") 
-that is part of the standard Python distribution. You can install all needed Python 
-packages, including the developer extras, by navigating to the GridPath root 
+`venv`, [a lightweight environment manager](https://docs.python.org/3/library/venv.html "venv") 
+that is part of the standard Python distribution. Make sure to [create](https://docs.python.org/3/library/venv.html#creating-virtual-environments "create") [activate](https://docs.python.org/3/library/venv.html#how-venvs-work "activate") the environment before installing GridPath.
+
+## Install GridPath
+
+Once you have _created and activated_ the GridPath Python environment, you can install GridPath and the Python packages it uses.
+
+For most users, installing GridPath's base set of Python packages and those needed 
+to use the graphical user interface would be sufficient. You can do so by navigating to the GridPath root 
 directory (which is where this `README.md` file is located) and running:
 ```bash
-pip install -e .[all]
+pip install .[ui]
 ```
 
-For most users, installing GridPath's base set of Python packages and those needed 
-to use the graphical user interface would be sufficient. You can do so by running:
+You can install all needed Python 
+packages, including the developer extras by running:
 ```bash
-pip install -e .[ui]
+pip install .[all]
 ```
 
-NOTE: if you don't plan to edit the GridPath code, you can install without the 
-`-e` option.
+**NOTE:** If you plan to edit the GridPath code, you should install with the `-e` flag.
 
 ## Solver
-You will need a solver to use this platform. GridPath assumes you will be 
-using Cbc (Coin-or branch and cut) by default, but you can specify a 
-different solver (see the **Usage** section).
+You will need a solver to use this platform. GridPath assumes you will be using Cbc (Coin-or branch and cut) by default, but you can specify a 
+different solver.
+
+## Testing your installation
+
+To test the GridPath codebase, [make sure the GridPath environment you installed to 
+is activated](https://docs.python.org/3/library/venv.html#how-venvs-work "activate") and use the unittest module as follows from the root directory:
+```bash
+python -m unittest discover tests
+```
 
 # Usage
 
@@ -65,7 +78,7 @@ gridpath_run --scenario SCENARIO_NAME --scenario_location
 If you are using the database, you can use the command `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.
+process them. Refer to the documentation for how to build the database.
 
 ```bash
 gridpath_run_e2e --scenario SCENARIO_NAME --scenario_location 
@@ -78,24 +91,10 @@ solver, check the help menu, e.g.:
 gridpath_run --help
 ```
 
-NOTE: To activate your gridpath environment, use the following command (
-assuming your environment is called "env", is created with `venv`, and is stored 
-in the GridPath root folder):
-```bash
-source env/bin/activate
-```
 
 ## Help
 In general, you can check usage of GridPath's scripts by calling the `--help` 
 option, e.g.:
 ```bash
 python get_scenario_inputs.py --help
 ```
-
-# Testing
-
-To test the GridPath codebase, use the unittest module as follows from the 
-root directory:
-```bash
-python -m unittest discover tests
-```

db/create_database.py

@@ -13,12 +13,14 @@
 # limitations under the License.
 
 """
-Create the database and make schema.
+This script create an empty GridPath database with the appropriate table structure.
 
-TODO: expand this description of the table naming conventions
-The schema for the GridPath SQLite database is in db_schema.sql
-Table names follow a pre-defined structure.
+The user may specify the name and location of the GridPath database path using the
+*--database* flag.
 
+>>> python create_database.py --database PATH/DO/DB
+
+The default schema for the GridPath SQLite database is in db_schema.sql.
 
 .. _database-structure-section-ref:
 
@@ -45,7 +47,7 @@ def parse_arguments(arguments):
     # Scenario name and location options
     parser.add_argument(
         "--database",
-        default="../db/io.db",
+        default="./io.db",
         help="The database file path relative to the current "
         "working directory. Defaults to ../db/io.db ",
     )

db/utilities/scenario.py

@@ -1,8 +1,25 @@
-# Copyright 2016-2020 Blue Marble Analytics LLC. All rights reserved.
+# Copyright 2016-2023 Blue Marble Analytics LLC. All rights reserved.
 
 """
-This script contains functions for creating, updating, and deleting a
-scenario. You can create a single or multiple scenarios from a CSV.
+The *scenario.py* script in the db directory contains functions for creating, updating,
+and deleting a scenario. You can create a single or multiple scenarios from a CSV.
+This script assumes that the user has already created the database file using the
+*create_database.py* script and loaded input data for the scenario using the
+*port_csvs_to_db.py* script.
+
+The *scenario.py* script takes several arguments. For usage info, run:
+
+>>> python scenario.py --help
+
+The user must specify the GridPath database path using the *--database* flag
+and the path to the directory where the scenario CSV is located using the
+*--csv_path* flag.
+
+>>> python port_csvs_to_db.py --database PATH/DO/DB --csv_path PATH/TO/SCENARIO/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.
 """
 
 from argparse import ArgumentParser

doc/source/advanced_docs.rst

@@ -6,9 +6,9 @@ This section contains the advanced documentation that is automatically generated
 from the documentation within each GridPath module.
 
 
-*******************
-Basic Functionality
-*******************
+******************
+Core Functionality
+******************
 
 This chapter describes GridPath's basic functionality if no optional
 features are included.
@@ -158,16 +158,46 @@ gridpath.project.operations.costs
 .. automodule:: gridpath.project.operations.costs
     :members: add_model_components
 
+gridpath.project.operations.carbon_emissions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: gridpath.project.operations.carbon_emissions
+    :members: add_model_components
+
+gridpath.project.operations.carbon_tax
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: gridpath.project.operations.carbon_tax
+    :members: add_model_components
+
 gridpath.project.operations.fuel_burn
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. automodule:: gridpath.project.operations.fuel_burn
     :members: add_model_components
 
+gridpath.project.operations.cycle_select
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: gridpath.project.operations.cycle_select
+    :members: add_model_components
+
+gridpath.project.operations.supplemental_firing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: gridpath.project.operations.supplemental_firing
+    :members: add_model_components
+
 gridpath.project.operations.energy_target_contributions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. automodule:: gridpath.project.operations.energy_target_contributions
     :members: add_model_components
 
+gridpath.project.operations.performance_standard
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: gridpath.project.operations.performance_standard
+    :members: add_model_components
+
+gridpath.project.operations.cap_factor_limits
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. automodule:: gridpath.project.operations.cap_factor_limits
+    :members: add_model_components
+
 gridpath.project.operations.tuning_costs
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 .. automodule:: gridpath.project.operations.tuning_costs
@@ -352,7 +382,6 @@ gridpath.objective.transmission.aggregate_hurdle_costs
 .. automodule:: gridpath.objective.transmission.aggregate_hurdle_costs
 
 
-
 Operating Reserves
 ==================
 GridPath can model operating reserve requirements and provision. Reserves
@@ -380,13 +409,29 @@ gridpath.project.operations.reserves.reserve_provision
     :members: generic_record_dynamic_components
 
 
-
 Reliability
 ===========
 GridPath currently includes the ability to require that a planning reserve
-requirement be met.
+requirement be met. Projects can contribute toward the reserve requirement via a
+simple fraction of their installed capacity or an "ELCC surface" that takes into
+account declining marginal contributions and/or portfolio effects with other projects.
+GridPath can also account for "deliverability," i.e., lower capacity contributions
+due to transmission limits.
+
+gridpath.project.reliability.prm.prm_simple
+-------------------------------------------
+
+.. automodule:: gridpath.project.reliability.prm.prm_simple
+
+gridpath.project.reliability.prm.elcc_surface
+---------------------------------------------
+
+.. automodule:: gridpath.project.reliability.prm.elcc_surface
+
+gridpath.system.reliability.prm.elcc_surface
+--------------------------------------------
 
-More documentation will be included in the future.
+.. automodule:: gridpath.system.reliability.prm.elcc_surface
 
 Policy
 ======
@@ -396,9 +441,47 @@ portfolio standard requiring that a certain percentage of demand be met with
 renewable resources, and a carbon cap, requiring that total emissions be
 below a certain level.
 
-More documentation will be included in the future.
+gridpath.system.policy.carbon_cap.carbon_cap
+--------------------------------------------
 
-Custom Modules
-==============
+.. automodule:: gridpath.system.policy.carbon_cap.carbon_cap
+
+
+gridpath.system.policy.carbon_cap.carbon_tax
+--------------------------------------------
+
+.. automodule:: gridpath.system.policy.carbon_cap.carbon_tax
+
+gridpath.system.policy.energy_targets.horizon_energy_target
+-----------------------------------------------------------
+
+.. automodule:: gridpath.system.policy.energy_targets.horizon_energy_target
+
+gridpath.system.policy.fuel_burn_limits.fuel_burn_limits
+--------------------------------------------------------
+
+.. automodule:: gridpath.system.policy.fuel_burn_limits.fuel_burn_limits
+
+gridpath.system.policy.performance_standard.performance_standard
+----------------------------------------------------------------
+
+.. automodule:: gridpath.system.policy.performance_standard.performance_standard
+
+
+Markets
+=======
+
+GridPath can model market participation of a project or a set of projects. A price
+stream is required and projects are assumed to be price-takers. The market volume can
+be constrained. In multi-stage modeling, the transactions from the previous stages
+can be fixed in the following stages.
+
+gridpath.system.policy.markets.prices
+-------------------------------------
+
+.. automodule:: gridpath.system.policy.markets.prices
+
+gridpath.system.policy.markets.volume
+-------------------------------------
 
-GridPath can include custom modules.
+.. automodule:: gridpath.system.policy.markets.volume

doc/source/database.rst

@@ -34,8 +34,16 @@ Creating the Database
 Populating the Database
 ***********************
 
+Loading Input Data
+==================
+
 .. automodule:: db.utilities.port_csvs_to_db
 
+Creating Scenarios
+==================
+
+.. automodule:: db.utilities.scenario
+
 GridPath Input Data
 ###################
 
@@ -447,3 +455,4 @@ 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
+