From 068c5963604f6ff3d5331d1369eb92bdbe8df8b0 Mon Sep 17 00:00:00 2001 From: Ana Mileva Date: Fri, 27 Oct 2023 14:38:25 -0700 Subject: [PATCH] New entry points and docs updates --- MANIFEST.in | 1 + README.md | 40 +++++++----------------- db/create_database.py | 6 ++-- db/utilities/port_csvs_to_db.py | 16 +++++----- db/utilities/scenario.py | 17 +++++----- doc/source/installation.rst | 55 ++++++++++++++------------------- setup.py | 7 +++-- 7 files changed, 61 insertions(+), 81 deletions(-) diff --git a/MANIFEST.in b/MANIFEST.in index 1a14126fb..d111485f0 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1 +1,2 @@ include gridpath/project/operations/operational_types/opchar_param_requirements.csv +include db/db_schema.sql diff --git a/README.md b/README.md index 15a187fab..9988557c4 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,10 @@ # Welcome to GridPath

- +

-![Approaches](doc/graphics/approaches.png) +![Approaches](https://github.com/blue-marble/gridpath/blob/main/doc/graphics/approaches.png?raw=true) GridPath is a versatile power-system planning platform capable of a range of @@ -24,28 +24,27 @@ 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. We recommend using Python 3.9. Get -Python -[here](https://www.python.org/downloads/ "Python download"). +GridPath is tested on Python 3.9, 3.10, and 3.11. Get one of those Python versions [here](https://www.python.org/downloads/ "Python download"). ## 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. 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 +## Install GridPath from PyPi -Once you have _created and activated_ the GridPath Python environment, you can install GridPath and the Python packages it uses. +Once you have _created and activated_ the GridPath Python environment, you +can install the latest version of GridPath from PyPi with: -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 .[ui] +pip install GridPath ``` -You can install all needed Python -packages, including the developer extras by running: +## Install GridPath from source + +You can alternatively download the GridPath source code and install from +source. + ```bash pip install .[all] ``` @@ -56,13 +55,6 @@ pip install .[all] 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 @@ -90,11 +82,3 @@ solver, check the help menu, e.g.: ```bash gridpath_run --help ``` - - -## 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 -``` diff --git a/db/create_database.py b/db/create_database.py index 2d51eda91..bb027bcb4 100644 --- a/db/create_database.py +++ b/db/create_database.py @@ -1,4 +1,4 @@ -# Copyright 2016-2020 Blue Marble Analytics LLC. +# 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. @@ -13,12 +13,12 @@ # limitations under the License. """ -This script create an empty GridPath database with the appropriate table structure. +Create an empty GridPath database with the appropriate table 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 +>>> gridpath_create_database --database PATH/DO/DB The default schema for the GridPath SQLite database is in db_schema.sql. diff --git a/db/utilities/port_csvs_to_db.py b/db/utilities/port_csvs_to_db.py index 54eb56e6c..34cb6d77e 100644 --- a/db/utilities/port_csvs_to_db.py +++ b/db/utilities/port_csvs_to_db.py @@ -1,20 +1,20 @@ -# Copyright 2016-2020 Blue Marble Analytics LLC. All rights reserved. +# Copyright 2016-2023 Blue Marble Analytics LLC. All rights reserved. """ -The *port_csvs_to_db.py* script in the db directory ports the input data -provided through CSV files to the GridPath SQLite database. This script -assumes that the user has already created the database file and loaded -the GridPath schema using the *create_database.py* script. +The *gridpath_load_csvs* command ports the input data provided through CSV +files to the GridPath SQLite database. It assumes that the user has +already created the database file and loaded the GridPath schema using the +*gridpath_create_database* command. -The *port_csvs_to_db.py* script takes several arguments. For usage info, run: +The gridpath_load_csvs command takes several arguments. For usage info, run: ->>> python port_csvs_to_db.py --help +>>> gridpath_load_csvs --help The user must specify the GridPath database path using the *--database* flag and the path to the directory where the CSVs are located using the *--csv_location* flag. ->>> python port_csvs_to_db.py --database PATH/DO/DB --csv_location PATH/TO/CSVS +>>> gridpath_load_csvs --database PATH/DO/DB --csv_location PATH/TO/CSVS Running the command above will look for the *csv_structure.csv* file in diff --git a/db/utilities/scenario.py b/db/utilities/scenario.py index 160c1c520..c51700068 100644 --- a/db/utilities/scenario.py +++ b/db/utilities/scenario.py @@ -1,21 +1,22 @@ # Copyright 2016-2023 Blue Marble Analytics LLC. All rights reserved. """ -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. +You can use the *gridpath_load_scenarios* command to create, update, or delete +a scenario. You can create a single or multiple scenarios from a CSV. +This command assumes that the user has already created the database file +using the *gridpath_create_database* command and loaded input data for the +scenario using the *gridpath_load_csvs* command. -The *scenario.py* script takes several arguments. For usage info, run: +The *gridpath_load_scenarios* command takes several arguments. For usage info, +run: ->>> python scenario.py --help +>>> gridpath_load_scenarios --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 +>>> gridpath_load_scenarios --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 diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 3d65db8aa..b8eb3d513 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -24,11 +24,7 @@ Python Running GridPath requires a Python 3 installation. GridPath is `tested nightly `__ in -Python 3.8, 3.9, and 3.10. We recommend using Python 3.9. You can get the official -CPython distribution (recommended) `here `__, the -Anaconda Python distribution `here `__, or -`another Python distribution `_. - +Python 3.9, 3.10, and 3.11. You can get Python `here `__. .. _python-virtual-env-section-ref: @@ -67,21 +63,6 @@ On Linux-based systems including MacOS, use:: source PATH/TO/PYTHON/ENV/bin/activate -^^^^^^^^ -Anaconda -^^^^^^^^ -Another way to set up a virtual environment is via the Anaconda Python -distribution. `You can obtain Anaconda here `_. Create the GridPath environment with:: - - conda env create --name gridpath - -By default, environments are installed into the `envs` directory in your -conda directory. To activate the environment before running GridPath, enter -the following:: - - source activate gridpath - Solver ------ @@ -104,17 +85,30 @@ instructions for Windows `here `**. + +Installation from PyPi +---------------------- + +You can download and install the latest version of GridPath from PyPi with:: + + pip install GridPath + +To get a specific version, e.g., v0.16.0, use:: + + pip install GridPath==0.16.0 + +Note that GridPath versions before 0.16.0 are not available on PyPi. + +Installation from Source +------------------------ GridPath's source code is stored in a GitHub repository. You can find the latest GridPath release `here `__. Download the source code zip file and extract it. We will refer to the directory where the code is extracted to as the :code:`PATH/TO/GRIDPATH` directory. -Before installing, **make sure to activate your :ref:`GridPath virtual environment -`**. - Most users should install GridPath by navigating to the GridPath directory :code:`PATH/TO/GRIDPATH` with :code:`cd PATH/TO/GRIDPATH` and running:: @@ -122,13 +116,9 @@ running:: pip install . -If you want to use the GUI, you should install additional required packages with:: - - pip install .[ui] - - +^^^^^^^^^^^^^^^^ Developer extras ----------------- +^^^^^^^^^^^^^^^^ You may need to install additional packages if you plan to edit the GridPath code and, for example, build the documentation from source, use the Black code formatter, @@ -145,8 +135,9 @@ 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:: diff --git a/setup.py b/setup.py index 85f77a792..f725c9d55 100644 --- a/setup.py +++ b/setup.py @@ -54,10 +54,10 @@ "PyUtilib==6.0.0", # used for solver temp file management "Jinja2==3.0.3", # bokeh dependency; see #904 "dill==0.3.7", # pickling - ], + ] + + extras_ui, extras_require={ "doc": extras_doc, - "ui": extras_ui, "all": extras_all, "coverage": extras_coverage, "gurobi": extras_gurobi, @@ -74,6 +74,9 @@ "gridpath_validate = gridpath.validate_inputs:main", "gridpath_run_server = ui.server.run_server:main", "gridpath_run_queue_manager = ui.server.run_queue_manager:main", + "gridpath_create_database = db.create_database:main", + "gridpath_load_csvs = db.utilities.port_csvs_to_db:main", + "gridpath_load_scenarios = db.utilities.scenario:main", ] }, )