From 01e9f06cfcb1472f26e21c534955dff6a61c958f Mon Sep 17 00:00:00 2001 From: trevorb1 Date: Mon, 14 Aug 2023 19:08:19 -0700 Subject: [PATCH] validation docs update --- docs/_static/validation-data.txt | 202 +++++++++++++++++++++++++ docs/conf.py | 10 +- docs/data.rst | 2 +- docs/examples-validation.rst | 213 +++++++++++++++++++++++++++ docs/examples.rst | 244 ++++++++++++++++++++----------- 5 files changed, 576 insertions(+), 95 deletions(-) create mode 100644 docs/_static/validation-data.txt create mode 100644 docs/examples-validation.rst diff --git a/docs/_static/validation-data.txt b/docs/_static/validation-data.txt new file mode 100644 index 00000000..2f0f8132 --- /dev/null +++ b/docs/_static/validation-data.txt @@ -0,0 +1,202 @@ +# Model file written by *otoole* +param default 0 : AccumulatedAnnualDemand := +; +param default -1 : AnnualEmissionLimit := +; +param default 0 : AnnualExogenousEmission := +; +param default 1 : AvailabilityFactor := +; +param default 1 : CapacityFactor := +; +param default 0 : CapacityOfOneTechnologyUnit := +; +param default 1 : CapacityToActivityUnit := +R PWRWND 31.536 +R PWRCOA 31.536 +R TRNELC 31.536 +; +param default 0 : CapitalCost := +R PWRWND 2020 1500 +R PWRWND 2021 1500 +R PWRWND 2022 1500 +R PWRCOA 2020 5000 +R PWRCOA 2021 5000 +R PWRCOA 2022 5000 +; +param default 0 : CapitalCostStorage := +; +param default 0 : Conversionld := +; +param default 0 : Conversionlh := +; +param default 0 : Conversionls := +; +set DAILYTIMEBRACKET := +; +set DAYTYPE := +; +param default 0.00137 : DaySplit := +; +param default 7 : DaysInDayType := +; +param default 1 : DepreciationMethod := +; +param default 0.05 : DiscountRate := +; +param default 0.05 : DiscountRateStorage := +; +set EMISSION := +; +param default 0 : EmissionActivityRatio := +; +param default 0 : EmissionsPenalty := +; +set FUEL := +WND00 +COA00 +ELC01 +ELC02 +; +param default 0 : FixedCost := +; +param default 0 : InputActivityRatio := +R PWRWND WND00 1 2020 1 +R PWRWND WND00 1 2021 1 +R PWRWND WND00 1 2022 1 +R PWRCOA COA00 1 2020 1 +R PWRCOA COA00 1 2021 1 +R PWRCOA COA00 1 2022 1 +R TRNELC ELC01 1 2020 1 +R TRNELC ELC01 1 2021 1 +R TRNELC ELC01 1 2022 1 +; +set MODE_OF_OPERATION := +1 +; +param default 0 : MinStorageCharge := +; +param default -1 : ModelPeriodEmissionLimit := +; +param default 0 : ModelPeriodExogenousEmission := +; +param default 1 : OperationalLife := +R PWRWND 20 +R PWRCOA 30 +; +param default 0 : OperationalLifeStorage := +; +param default 0 : OutputActivityRatio := +R MINWND WND00 1 2020 1 +R MINWND WND00 1 2021 1 +R MINWND WND00 1 2022 1 +R MINCOA COA00 1 2020 1 +R MINCOA COA00 1 2021 1 +R MINCOA COA00 1 2022 1 +R PWRWND ELC01 1 2020 1 +R PWRWND ELC01 1 2021 1 +R PWRWND ELC01 1 2022 1 +R PWRCOA ELC01 1 2020 1 +R PWRCOA ELC01 1 2021 1 +R PWRCOA ELC01 1 2022 1 +R TRNELC ELC02 1 2020 1 +R TRNELC ELC02 1 2021 1 +R TRNELC ELC02 1 2022 1 +; +set REGION := +R +; +param default 0 : REMinProductionTarget := +; +param default 0 : RETagFuel := +; +param default 0 : RETagTechnology := +; +param default 1 : ReserveMargin := +; +param default 0 : ReserveMarginTagFuel := +; +param default 0 : ReserveMarginTagTechnology := +; +param default 0 : ResidualCapacity := +R PWRCOA 2020 0.25 +R PWRCOA 2021 0.25 +R PWRCOA 2022 0.25 +; +param default 999 : ResidualStorageCapacity := +; +set SEASON := +; +set STORAGE := +; +param default 0 : SpecifiedAnnualDemand := +R ELC02 2020 10 +R ELC02 2021 15 +R ELC02 2022 20 +; +param default 0 : SpecifiedDemandProfile := +R ELC02 S 2020 0.5 +R ELC02 W 2020 0.5 +R ELC02 S 2021 0.5 +R ELC02 W 2021 0.5 +R ELC02 S 2022 0.5 +R ELC02 W 2022 0.5 +; +param default 0 : StorageLevelStart := +; +param default 0 : StorageMaxChargeRate := +; +param default 0 : StorageMaxDischargeRate := +; +set TECHNOLOGY := +MINWND +MINCOA +PWRWND +PWRCOA +TRNELC +; +set TIMESLICE := +S +W +; +param default 0 : TechnologyFromStorage := +; +param default 0 : TechnologyToStorage := +; +param default -1 : TotalAnnualMaxCapacity := +; +param default -1 : TotalAnnualMaxCapacityInvestment := +; +param default 0 : TotalAnnualMinCapacity := +; +param default 0 : TotalAnnualMinCapacityInvestment := +; +param default 0 : TotalTechnologyAnnualActivityLowerLimit := +; +param default -1 : TotalTechnologyAnnualActivityUpperLimit := +; +param default 0 : TotalTechnologyModelPeriodActivityLowerLimit := +; +param default -1 : TotalTechnologyModelPeriodActivityUpperLimit := +; +param default 0 : TradeRoute := +; +param default 0 : VariableCost := +R MINCOA 1 2020 5 +R MINCOA 1 2021 5 +R MINCOA 1 2022 5 +; +set YEAR := +2020 +2021 +2022 +; +param default 0 : YearSplit := +S 2020 0.5 +W 2020 0.5 +S 2021 0.5 +W 2021 0.5 +S 2022 0.5 +W 2022 0.5 +; +end; diff --git a/docs/conf.py b/docs/conf.py index c005bcc8..2a5fbc5c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -172,11 +172,11 @@ "path_to_docs": "docs", "use_repository_button": True, "use_edit_page_button": True, - "extra_navbar": - """ -

Theme by the Executable Book Project

-

Logo by looka.com

- """, + # "extra_navbar": + # """ + #

Theme by the Executable Book Project

+ #

Logo by looka.com

+ # """, "icon_links": [], } diff --git a/docs/data.rst b/docs/data.rst index 6d144aa7..c6f68974 100644 --- a/docs/data.rst +++ b/docs/data.rst @@ -69,7 +69,7 @@ Sets are defined as follows:: It's convention in OSeMOSYS to capitalize set names Parameters Format -~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~ Parameters are defined as follows. When referencing set indices use the full name, **not** the ``short_name``:: diff --git a/docs/examples-validation.rst b/docs/examples-validation.rst new file mode 100644 index 00000000..03988427 --- /dev/null +++ b/docs/examples-validation.rst @@ -0,0 +1,213 @@ +:orphan: + +.. _examples-validation: + +----------------------- +Example Validation File +----------------------- + +This page holds the datafile used in the validation example. The file can +either be copy/pasted from below, or directly downloaded from :download:`here <_static/validation-data.txt>` :: + + # Model file written by *otoole* + param default 0 : AccumulatedAnnualDemand := + ; + param default -1 : AnnualEmissionLimit := + ; + param default 0 : AnnualExogenousEmission := + ; + param default 1 : AvailabilityFactor := + ; + param default 1 : CapacityFactor := + ; + param default 0 : CapacityOfOneTechnologyUnit := + ; + param default 1 : CapacityToActivityUnit := + R PWRWND 31.536 + R PWRCOA 31.536 + R TRNELC 31.536 + ; + param default 0 : CapitalCost := + R PWRWND 2020 1500 + R PWRWND 2021 1500 + R PWRWND 2022 1500 + R PWRCOA 2020 5000 + R PWRCOA 2021 5000 + R PWRCOA 2022 5000 + ; + param default 0 : CapitalCostStorage := + ; + param default 0 : Conversionld := + ; + param default 0 : Conversionlh := + ; + param default 0 : Conversionls := + ; + set DAILYTIMEBRACKET := + ; + set DAYTYPE := + ; + param default 0.00137 : DaySplit := + ; + param default 7 : DaysInDayType := + ; + param default 1 : DepreciationMethod := + ; + param default 0.05 : DiscountRate := + ; + param default 0.05 : DiscountRateStorage := + ; + set EMISSION := + ; + param default 0 : EmissionActivityRatio := + ; + param default 0 : EmissionsPenalty := + ; + set FUEL := + WND00 + COA00 + ELC01 + ELC02 + ; + param default 0 : FixedCost := + ; + param default 0 : InputActivityRatio := + R PWRWND WND00 1 2020 1 + R PWRWND WND00 1 2021 1 + R PWRWND WND00 1 2022 1 + R PWRCOA COA00 1 2020 1 + R PWRCOA COA00 1 2021 1 + R PWRCOA COA00 1 2022 1 + R TRNELC ELC01 1 2020 1 + R TRNELC ELC01 1 2021 1 + R TRNELC ELC01 1 2022 1 + ; + set MODE_OF_OPERATION := + 1 + ; + param default 0 : MinStorageCharge := + ; + param default -1 : ModelPeriodEmissionLimit := + ; + param default 0 : ModelPeriodExogenousEmission := + ; + param default 1 : OperationalLife := + R PWRWND 20 + R PWRCOA 30 + ; + param default 0 : OperationalLifeStorage := + ; + param default 0 : OutputActivityRatio := + R MINWND WND00 1 2020 1 + R MINWND WND00 1 2021 1 + R MINWND WND00 1 2022 1 + R MINCOA COA00 1 2020 1 + R MINCOA COA00 1 2021 1 + R MINCOA COA00 1 2022 1 + R PWRWND ELC01 1 2020 1 + R PWRWND ELC01 1 2021 1 + R PWRWND ELC01 1 2022 1 + R PWRCOA ELC01 1 2020 1 + R PWRCOA ELC01 1 2021 1 + R PWRCOA ELC01 1 2022 1 + R TRNELC ELC02 1 2020 1 + R TRNELC ELC02 1 2021 1 + R TRNELC ELC02 1 2022 1 + ; + set REGION := + R + ; + param default 0 : REMinProductionTarget := + ; + param default 0 : RETagFuel := + ; + param default 0 : RETagTechnology := + ; + param default 1 : ReserveMargin := + ; + param default 0 : ReserveMarginTagFuel := + ; + param default 0 : ReserveMarginTagTechnology := + ; + param default 0 : ResidualCapacity := + R PWRCOA 2020 0.25 + R PWRCOA 2021 0.25 + R PWRCOA 2022 0.25 + ; + param default 999 : ResidualStorageCapacity := + ; + set SEASON := + ; + set STORAGE := + ; + param default 0 : SpecifiedAnnualDemand := + R ELC02 2020 10 + R ELC02 2021 15 + R ELC02 2022 20 + ; + param default 0 : SpecifiedDemandProfile := + R ELC02 S 2020 0.5 + R ELC02 W 2020 0.5 + R ELC02 S 2021 0.5 + R ELC02 W 2021 0.5 + R ELC02 S 2022 0.5 + R ELC02 W 2022 0.5 + ; + param default 0 : StorageLevelStart := + ; + param default 0 : StorageMaxChargeRate := + ; + param default 0 : StorageMaxDischargeRate := + ; + set TECHNOLOGY := + MINWND + MINCOA + PWRWND + PWRCOA + TRNELC + ; + set TIMESLICE := + S + W + ; + param default 0 : TechnologyFromStorage := + ; + param default 0 : TechnologyToStorage := + ; + param default -1 : TotalAnnualMaxCapacity := + ; + param default -1 : TotalAnnualMaxCapacityInvestment := + ; + param default 0 : TotalAnnualMinCapacity := + ; + param default 0 : TotalAnnualMinCapacityInvestment := + ; + param default 0 : TotalTechnologyAnnualActivityLowerLimit := + ; + param default -1 : TotalTechnologyAnnualActivityUpperLimit := + ; + param default 0 : TotalTechnologyModelPeriodActivityLowerLimit := + ; + param default -1 : TotalTechnologyModelPeriodActivityUpperLimit := + ; + param default 0 : TradeRoute := + ; + param default 0 : VariableCost := + R MINCOA 1 2020 5 + R MINCOA 1 2021 5 + R MINCOA 1 2022 5 + ; + set YEAR := + 2020 + 2021 + 2022 + ; + param default 0 : YearSplit := + S 2020 0.5 + W 2020 0.5 + S 2021 0.5 + W 2021 0.5 + S 2022 0.5 + W 2022 0.5 + ; + end; diff --git a/docs/examples.rst b/docs/examples.rst index 2638f7ae..c4f2aab8 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -15,10 +15,86 @@ functionality in seperate simple use cases. git clone https://github.com/OSeMOSYS/simplicity.git cd simplicity -.. CAUTION:: - While ``otoole`` does not require a solver, these examples - will use the free and open source solvers GLPK_ and CBC_. - Installation instructions are described in the `Solver Setup`_ section. +Solver Setup +------------ + +Objective +~~~~~~~~~ + +Install GLPK_ (required) and CBC_ (optional) to use in the otoole examples. +While ``otoole`` does not require a solver, these examples will use the free +and open source solvers GLPK_ and CBC_. + +1. Install GLPK +~~~~~~~~~~~~~~~~ + +GLPK_ is a free and open-source linear program solver. Full +install instructions can be found on the `GLPK Website`_, however, the +abbreviated instructions are shown below + +To install GLPK on **Linux**, run the command:: + + sudo apt-get update + sudo apt-get install glpk glpk-utils + +To install GLPK on **Mac**, run the command:: + + brew install glpk + +To install GLPK on **Windows**, follow the instructions on the +`GLPK Website`_. Be sure to add GLPK to +your environment variables after installation + +Alternatively, if you use Anaconda_ to manage +your Python packages, you can install GLPK via the command:: + + conda install -c conda-forge glpk + +2. Test the GLPK install +~~~~~~~~~~~~~~~~~~~~~~~~ +Once installed, you should be able to call the ``glpsol`` command:: + + $ glpsol + GLPSOL: GLPK LP/MIP Solver, v4.65 + No input problem file specified; try glpsol --help + +3. Install CBC +~~~~~~~~~~~~~~ + +CBC_ is a free and open-source mixed integer linear programming solver. Full +install instructions can be found on the CBC_ website, however, the abbreviated +instructions are shown below + +To install CBC on **Linux**, run the command:: + + sudo apt-get install coinor-cbc coinor-libcbc-dev + +To install CBC on **Mac**, run the command:: + + brew install coin-or-tools/coinor/cbc + +To install CBC on **Windows**, follow the install instruction on the CBC_ +website. + +Alternatively, if you use Anaconda_ to manage +your Python packages, you can install CBC via the command:: + + conda install -c conda-forge coincbc + +4. Test the CBC install +~~~~~~~~~~~~~~~~~~~~~~~ +Once installed, you should be able to directly call CBC:: + + $ cbc + Welcome to the CBC MILP Solver + Version: 2.10.3 + Build Date: Mar 24 2020 + + CoinSolver takes input from arguments ( - switches to stdin) + Enter ? for list of commands or help + Coin: + +You can exit the solver by typing ``quit`` Data Conversion with CSVs ------------------------- @@ -211,13 +287,18 @@ codes are shown in bold face. .. image:: _static/validataion_model.png -1. Create the Validation File +1. Download the example datafile +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The MathProg datafile describing this model can be found on the +:ref:`examples-validation` page. Download the file and save it as ``data.txt`` + +2. Create the Validation File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Create a configuration validation ``yaml`` file:: $ touch validate.yaml -2. Create ``FUEL`` Codes +3. Create ``FUEL`` Codes ~~~~~~~~~~~~~~~~~~~~~~~~ Create the fuel codes and descriptions in the validation configuration file:: @@ -227,11 +308,11 @@ Create the fuel codes and descriptions in the validation configuration file:: 'COA': Coal 'ELC': Electricity indetifiers: - '00': Raw Resource + '00': Primary Resource '01': Intermediate '02': End Use -3. Create ``TECHNOLOGY`` Codes +4. Create ``TECHNOLOGY`` Codes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Add the technology codes to the validation configuration file. Note that the powerplant types are the same codes as the fuels, so there is no need to @@ -243,49 +324,40 @@ redefine these codes:: 'PWR': Generator 'TRN': Transmission -4. Create ``FUEL`` Schema +5. Create ``FUEL`` Schema ~~~~~~~~~~~~~~~~~~~~~~~~~ Use the defined codes to create a schema for the fuel codes:: schema: FUEL: - name: fuel_name - items: - - name: fuels + items: + - name: type valid: fuels position: (1, 3) - - name: indetifiers + - name: indentifier valid: indetifiers position: (4, 5) -5. Create ``TECHNOLOGY`` Schema +6. Create ``TECHNOLOGY`` Schema ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use the defined codes to create a schema for the technology codes:: schema: TECHNOLOGY: - name: technology_name - items: - - name: techs + items: + - name: tech valid: techs position: (1, 3) - - name: fuels + - name: fuel valid: fuels position: (4, 6) -6. ``otoole`` validate -~~~~~~~~~~~~~~~~~~~~~~ -Use otoole to validate the input data (can be any of a ``datafile``, ``csv``, or ``excel``) -against the validation configuration file:: - - $ otoole validate datafile data.txt config.yaml --validate_config validate.yaml - -.. WARNING:: - Do not confuse the user configuration file (``config.yaml``) and the - validation configuration file (``validate.yaml``). Both configuration files - are required for validation functionality. +7. Save changes +~~~~~~~~~~~~~~~ -The final validation configuration file in this example will look like:: +The final validation configuration file for this example will look like:: codes: fuels: @@ -293,7 +365,7 @@ The final validation configuration file in this example will look like:: 'COA': Coal 'ELC': Electricity indetifiers: - '00': Raw Resource + '00': Primary Resource '01': Intermediate '02': End Use techs: @@ -304,103 +376,97 @@ The final validation configuration file in this example will look like:: schema: FUEL: - name: fuel_name - items: - - name: fuels + items: + - name: type valid: fuels position: (1, 3) - - name: indetifiers + - name: indentifier valid: indetifiers position: (4, 5) TECHNOLOGY: - name: technology_name - items: - - name: techs + items: + - name: tech valid: techs position: (1, 3) - - name: fuels + - name: fuel valid: fuels position: (4, 6) -Solver Setup ------------- - -Objective -~~~~~~~~~ - -Install GLPK_ (required) and CBC_ (optional) to use in the otoole examples. - -1. Install GLPK -~~~~~~~~~~~~~~~~ +8. ``otoole validate`` +~~~~~~~~~~~~~~~~~~~~~~ +Use otoole to validate the input data (can be any of a ``datafile``, ``csv``, or ``excel``) +against the validation configuration file:: -GLPK_ is a free and open-source linear program solver. + $ otoole validate datafile data.txt config.yaml --validate_config validate.yaml -To install GLPK on **Linux**, run the command:: + ***Beginning validation*** - sudo apt-get update - sudo apt-get install glpk glpk-utils + Validating FUEL with fuel_name -To install GLPK on **Mac**, run the command:: + ^(WND|COA|ELC)(00|01|02) + 4 valid names: + WND00, COA00, ELC01, ELC02 - brew install glpk + Validating TECHNOLOGY with technology_name -To install GLPK on **Windows**, follow the instructions on the -`GLPK Website `. Be sure to add GLPK to -your environment variables if installing on Windows. + ^(MIN|PWR|TRN)(WND|COA|ELC) + 5 valid names: + MINWND, MINCOA, PWRWND, PWRCOA, TRNELC -Alternatively, if you use `Anaconda ` to manage -your Python packages, you can install GLPK via the command:: - conda install -c conda-forge glpk + ***Checking graph structure*** -2. Test the GLPK install -~~~~~~~~~~~~~~~~~~~~~~~~ -Once installed, you should be able to call the ``glpsol`` command:: +.. WARNING:: + Do not confuse the user configuration file (``config.yaml``) and the + validation configuration file (``validate.yaml``). Both configuration files + are required for validation functionality. - $ glpsol - GLPSOL: GLPK LP/MIP Solver, v4.65 - No input problem file specified; try glpsol --help +9. Use ``otoole validate`` to identify an issue +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +In the datafile create a new technology that does not follow the specified schema. +For example, add the value ``ELC03`` to the ``FUEL`` set:: -3. Install CBC -~~~~~~~~~~~~~~ + set FUEL := + WND00 + COA00 + ELC01 + ELC02 + ELC03 -CBC_ is a free and open-source mixed integer linear programming solver. Full -install instructions can be found on the CBC_ website. However, the abbreviated -instructions are shown below +Running ``otoole validate`` again will flag this improperly named value. Moreover it +will also flag it as an isolated fuel. This means the fuel is unconnected from the model:: -To install CBC on **Linux**, run the command:: + $ otoole validate datafile data.txt config.yaml --validate_config validate.yaml - sudo apt-get install coinor-cbc coinor-libcbc-dev + ***Beginning validation*** -To install CBC on **Mac**, run the command:: + Validating FUEL with fuel_name - brew install coin-or-tools/coinor/cbc + ^(WND|COA|ELC)(00|01|02) + 1 invalid names: + ELC03 -To install CBC on **Windows**, follow the install instruction on the CBC_ -website. + 4 valid names: + WND00, COA00, ELC01, ELC02 -Alternatively, if you use `Anaconda ` to manage -your Python packages, you can install CBC via the command:: + Validating TECHNOLOGY with technology_name - conda install -c conda-forge coincbc + ^(MIN|PWR|TRN)(WND|COA|ELC) + 5 valid names: + MINWND, MINCOA, PWRWND, PWRCOA, TRNELC -4. Test the CBC install -~~~~~~~~~~~~~~~~~~~~~~~ -Once installed, you should be able to directly call CBC:: - $ cbc - Welcome to the CBC MILP Solver - Version: 2.10.3 - Build Date: Mar 24 2020 + ***Checking graph structure*** - CoinSolver takes input from arguments ( - switches to stdin) - Enter ? for list of commands or help - Coin: + 1 'fuel' nodes are isolated: + ELC03 -You can exit the solver by typing ``quit`` .. _Simplicity: https://github.com/OSeMOSYS/simplicity .. _GLPK: https://www.gnu.org/software/glpk/ .. _GLPK Wiki: https://en.wikibooks.org/wiki/GLPK/Using_GLPSOL +.. _GLPK Website: https://winglpk.sourceforge.net/ .. _CBC: https://github.com/coin-or/Cbc .. _CPLEX: https://www.ibm.com/products/ilog-cplex-optimization-studio/cplex-optimizer -.. _instructions: http://www.osemosys.org/uploads/1/8/5/0/18504136/glpk_installation_guide_for_windows10_-_201702.pdf +.. _Anaconda: https://www.anaconda.com/