diff --git a/CHANGELOG.md b/CHANGELOG.md index 375b4c81..c3d92ec2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,16 +6,13 @@ All notable changes to this project will be documented in this file. ### πŸ› Bug Fixes - * updates on documentation and improvements ([#168](https://github.com/NatLabRockies/plexosdb/issues/168)) ([b1ecf1b](https://github.com/NatLabRockies/plexosdb/commit/b1ecf1b8fcf4d3f902160adf514c73c58a0e323b)) - + ([827b2dd](https://github.com/NatLabRockies/plexosdb/commit/827b2ddaa24cd5c9531d4f78fab8f4e1cb441ff2)) ### πŸ“¦ Build -* **deps-dev:** bump pytest from 9.0.3 to 9.1.1 ([#167](https://github.com/NatLabRockies/plexosdb/issues/167)) ([e7d3a2f](https://github.com/NatLabRockies/plexosdb/commit/e7d3a2f5df0fd9c8798f437bb514487ff613c7d3)) * **deps-dev:** bump sphinx-book-theme from 1.1.4 to 1.4.0 ([#165](https://github.com/NatLabRockies/plexosdb/issues/165)) ([9f86a54](https://github.com/NatLabRockies/plexosdb/commit/9f86a5499c5c57abcf6c8ed19d2d76dcff053c50)) * **deps:** bump actions/cache from 5.0.5 to 6.1.0 ([#164](https://github.com/NatLabRockies/plexosdb/issues/164)) ([c71be7e](https://github.com/NatLabRockies/plexosdb/commit/c71be7e76001358c01e6806a592163d3857249d8)) -* **deps:** bump actions/checkout from 6.0.2 to 7.0.1 ([#162](https://github.com/NatLabRockies/plexosdb/issues/162)) ([fab6d4f](https://github.com/NatLabRockies/plexosdb/commit/fab6d4f2848be2bfbc4b7c81bc91f716432c5d17)) * **deps:** bump actions/labeler from 6.1.0 to 6.2.0 ([#166](https://github.com/NatLabRockies/plexosdb/issues/166)) ([4b21ca5](https://github.com/NatLabRockies/plexosdb/commit/4b21ca59806a2e20e2a5d3585f01be438e988846)) * **deps:** bump actions/setup-python from 6.2.0 to 7.0.0 ([#163](https://github.com/NatLabRockies/plexosdb/issues/163)) ([7d9fbf5](https://github.com/NatLabRockies/plexosdb/commit/7d9fbf5f9be567145eeb5da168549230a706b7c8)) * **deps:** bump astral-sh/setup-uv from 8.1.0 to 9.0.0 ([#161](https://github.com/NatLabRockies/plexosdb/issues/161)) ([e908746](https://github.com/NatLabRockies/plexosdb/commit/e908746c5c987f6b35af2ec2e57bbc6394b5e744)) @@ -23,56 +20,45 @@ All notable changes to this project will be documented in this file. ## [1.6.0](https://github.com/NatLabRockies/plexosdb/compare/v1.5.0...v1.6.0) (2026-07-17) -### πŸš€ Features -* add agentic skills guide for llms interactions ([#125](https://github.com/NatLabRockies/plexosdb/issues/125)) ([f8d6430](https://github.com/NatLabRockies/plexosdb/commit/f8d6430ac17345b421440e3da5d4e16096b51506)) + ([e247e67](https://github.com/NatLabRockies/plexosdb/commit/e247e6731f05eeef792cf8de09f0123e6f9d2995)) * implement PLEXOS solution reader and setup master files for 9-12 versions ([#141](https://github.com/NatLabRockies/plexosdb/issues/141)) ([903cdcc](https://github.com/NatLabRockies/plexosdb/commit/903cdcca9cca9a98e6b8ac9c7473bfc4008b923d)) * MCP server integration ([#124](https://github.com/NatLabRockies/plexosdb/issues/124)) ([db1e77e](https://github.com/NatLabRockies/plexosdb/commit/db1e77e835e392d9e59c435248bc9d6c03fc3f9f)) ### πŸ“¦ Build - * **deps-dev:** bump pytest from 9.0.2 to 9.0.3 ([#150](https://github.com/NatLabRockies/plexosdb/issues/150)) ([8e0b42f](https://github.com/NatLabRockies/plexosdb/commit/8e0b42f3300ac0d12aa85cd5acb71d3234739bf5)) -* **deps-dev:** bump sphinx-autobuild from 2024.10.3 to 2025.8.25 ([#151](https://github.com/NatLabRockies/plexosdb/issues/151)) ([1502ee1](https://github.com/NatLabRockies/plexosdb/commit/1502ee11a26338e4fd1a59713037d7c74dc970ed)) + ([1776d2a](https://github.com/NatLabRockies/plexosdb/commit/1776d2a614facef29d5a2a3df1f3a27dd154e359)) * **deps:** bump actions/cache from 5.0.4 to 5.0.5 ([#147](https://github.com/NatLabRockies/plexosdb/issues/147)) ([82bef37](https://github.com/NatLabRockies/plexosdb/commit/82bef3718a167f1122d525934c58daec6f794ed8)) * **deps:** bump actions/labeler from 6.0.1 to 6.1.0 ([#146](https://github.com/NatLabRockies/plexosdb/issues/146)) ([60ffbdb](https://github.com/NatLabRockies/plexosdb/commit/60ffbdb6b4f53028701504bb339de5c338614be1)) * **deps:** bump benchmark-action/github-action-benchmark from 1.22.0 to 1.22.1 ([#149](https://github.com/NatLabRockies/plexosdb/issues/149)) ([4bb7b74](https://github.com/NatLabRockies/plexosdb/commit/4bb7b744dc193266aaa341b151e270c7f2cbb6b9)) * **deps:** bump googleapis/release-please-action from 4.4.1 to 5.0.0 ([#148](https://github.com/NatLabRockies/plexosdb/issues/148)) ([d5df7d1](https://github.com/NatLabRockies/plexosdb/commit/d5df7d166008f47e52424354c318e223ca88f6a4)) * **deps:** bump peaceiris/actions-gh-pages from 4.0.0 to 4.1.0 ([#145](https://github.com/NatLabRockies/plexosdb/issues/145)) ([a5d2b26](https://github.com/NatLabRockies/plexosdb/commit/a5d2b26f64ea1d5ee050f594b8a82bdbb1e2c562)) - ## [1.5.0](https://github.com/NatLabRockies/plexosdb/compare/v1.4.1...v1.5.0) (2026-06-25) + ([1e6e018](https://github.com/NatLabRockies/plexosdb/commit/1e6e01852e46fba89b16120c07d472f4c84f94ab)) -### πŸš€ Features - -* add agent markdown for better integration call ([#142](https://github.com/NatLabRockies/plexosdb/issues/142)) ([3003e52](https://github.com/NatLabRockies/plexosdb/commit/3003e523aa916e3a52ea1c59743c60fef45f51c2)) - + ([9062baa](https://github.com/NatLabRockies/plexosdb/commit/9062baa8db1eb611dcb7364e952bbdb898fe36a)) -### πŸ› Bug Fixes + ([00d533b](https://github.com/NatLabRockies/plexosdb/commit/00d533b4b547822a09984cf59e40738fea330f4a)) * attributes ([#130](https://github.com/NatLabRockies/plexosdb/issues/130)) ([b4d276b](https://github.com/NatLabRockies/plexosdb/commit/b4d276bc1e0cb5ee8dbbdd6db534582c7bea10ce)) -## [1.4.1](https://github.com/NatLabRockies/plexosdb/compare/v1.4.0...v1.4.1) (2026-05-22) -### πŸ› Bug Fixes + ([1f8da38](https://github.com/NatLabRockies/plexosdb/commit/1f8da384a9deb3edfa7a343e91999d3d37e07b17)) - copy_object date range metadata copying ([#143](https://github.com/NatLabRockies/plexosdb/issues/143)) - ([b60e5ad](https://github.com/NatLabRockies/plexosdb/commit/b60e5ad21032f05702ed74bb345f3f4579e2379d)) - -## [1.4.0](https://github.com/NatLabRockies/plexosdb/compare/v1.3.4...v1.4.0) (2026-05-21) + ([bb7be8d](https://github.com/NatLabRockies/plexosdb/commit/bb7be8d0e36c332051ec1a1767b8862f4baec359)) ### πŸš€ Features - -- add new Purchaser enum for handling new type of loads + ([18a0d9d](https://github.com/NatLabRockies/plexosdb/commit/18a0d9d26db2056d79bbdda6cec168e895abe0e9)) ([#127](https://github.com/NatLabRockies/plexosdb/issues/127)) - ([c5d9a38](https://github.com/NatLabRockies/plexosdb/commit/c5d9a38e29ba929869c0194da4fddca3860bcc3c)) -- address mixed issues + ([3dd6463](https://github.com/NatLabRockies/plexosdb/commit/3dd64632666e31a38f6ed8f8bb15f9d333e64791)) ([#128](https://github.com/NatLabRockies/plexosdb/issues/128)) - ([eabaa5b](https://github.com/NatLabRockies/plexosdb/commit/eabaa5bdd80e3898a5ddb37aa082b4736f4579e9)) - + ([ca687df](https://github.com/NatLabRockies/plexosdb/commit/ca687dfa466990e59c273c26908496c1fd5a8878)) ### πŸ› Bug Fixes - + ([5864d85](https://github.com/NatLabRockies/plexosdb/commit/5864d85e69e5e6cc865fc389e6b15f8e63785001)) - add safe parsing for long int values ([#140](https://github.com/NatLabRockies/plexosdb/issues/140)) ([c565313](https://github.com/NatLabRockies/plexosdb/commit/c565313d5b37839def642261ab05dd493ab1e879)) @@ -107,28 +93,28 @@ All notable changes to this project will be documented in this file. ## [1.3.4](https://github.com/NatLabRockies/plexosdb/compare/v1.3.3...v1.3.4) (2026-03-27) ### 🧩 CI - + ([9062baa](https://github.com/NatLabRockies/plexosdb/commit/9062baa8db1eb611dcb7364e952bbdb898fe36a)) - use release/v1 tag for pypa/gh-action-pypi-publish ([#107](https://github.com/NatLabRockies/plexosdb/issues/107)) - ([c4e58b8](https://github.com/NatLabRockies/plexosdb/commit/c4e58b8dc062f3302216b3caa7c9c6c1cc423c86)) + ([00d533b](https://github.com/NatLabRockies/plexosdb/commit/00d533b4b547822a09984cf59e40738fea330f4a)) ### πŸ“¦ Build - + ([1f8da38](https://github.com/NatLabRockies/plexosdb/commit/1f8da384a9deb3edfa7a343e91999d3d37e07b17)) - **deps:** bump actions/cache from 5.0.3 to 5.0.4 ([#115](https://github.com/NatLabRockies/plexosdb/issues/115)) - ([1ff162a](https://github.com/NatLabRockies/plexosdb/commit/1ff162afe66dfe3bcad7d0dbb0a534b4a9d3374a)) + ([bb7be8d](https://github.com/NatLabRockies/plexosdb/commit/bb7be8d0e36c332051ec1a1767b8862f4baec359)) - **deps:** bump astral-sh/setup-uv from 7.5.0 to 7.6.0 ([#117](https://github.com/NatLabRockies/plexosdb/issues/117)) - ([13fb3cf](https://github.com/NatLabRockies/plexosdb/commit/13fb3cfb4c7a2affd7df504a2e152c9a2b0c1295)) + ([18a0d9d](https://github.com/NatLabRockies/plexosdb/commit/18a0d9d26db2056d79bbdda6cec168e895abe0e9)) - **deps:** bump astral-sh/setup-uv from b75dde52aef63a238519e7aecbbe79a4a52e4315 to - e06108dd0aef18192324c70427afc47652e63a82 + ([3dd6463](https://github.com/NatLabRockies/plexosdb/commit/3dd6463e1f38d43586e1ba306b09b7b73c04b7b59)) ([#114](https://github.com/NatLabRockies/plexosdb/issues/114)) ([96f3975](https://github.com/NatLabRockies/plexosdb/commit/96f397540b06e68e45075a5d700d2b0a91ebe112)) -- **deps:** bump codecov/codecov-action from 5.5.2 to 5.5.3 + ([ca687df](https://github.com/NatLabRockies/plexosdb/commit/ca687dfa466990e59c273c26908496c1fd5a8878)) ([#116](https://github.com/NatLabRockies/plexosdb/issues/116)) ([c86c8e2](https://github.com/NatLabRockies/plexosdb/commit/c86c8e254a85909043c8a7b25a10ff7d169d1e02)) -- **deps:** bump googleapis/release-please-action from + ([5864d85](https://github.com/NatLabRockies/plexosdb/commit/5864d85e69e5e6cc865fc389e6b15f8e63785001)) c3fc4de07084f75a2b61a5b933069bda6edf3d5c to 16a9c90856f42705d54a6fda1823352bdc62cf38 ([#112](https://github.com/NatLabRockies/plexosdb/issues/112)) @@ -198,77 +184,77 @@ All notable changes to this project will be documented in this file. ([#88](https://github.com/NatLabRockies/plexosdb/issues/88)) ([fc840f8](https://github.com/NatLabRockies/plexosdb/commit/fc840f85991f803817a7910a09ca0ff06c6f4713)) -## [1.3.0](https://github.com/NREL/plexosdb/compare/v1.2.2...v1.3.0) (2025-12-11) +## [1.3.0](https://github.com/NatLabRockies/plexosdb/compare/v1.2.2...v1.3.0) (2025-12-11) ### πŸš€ Features - Making add_from_records more robust - ([#85](https://github.com/NREL/plexosdb/issues/85)) - ([827b2dd](https://github.com/NREL/plexosdb/commit/827b2ddaa24cd5c9531d4f78fab8f4e1cb441ff2)) + ([#85](https://github.com/NatLabRockies/plexosdb/issues/85)) + ([827b2dd](https://github.com/NatLabRockies/plexosdb/commit/827b2ddaa24cd5c9531d4f78fab8f4e1cb441ff2)) ### πŸ“¦ Build - **deps:** bump pre-commit from 4.2.0 to 4.5.0 - ([#82](https://github.com/NREL/plexosdb/issues/82)) - ([a590ce9](https://github.com/NREL/plexosdb/commit/a590ce949bef17e8bfa81fe70bf75293d2e88aa8)) + ([#82](https://github.com/NatLabRockies/plexosdb/issues/82)) + ([a590ce9](https://github.com/NatLabRockies/plexosdb/commit/a590ce949bef17e8bfa81fe70bf75293d2e88aa8)) - **deps:** bump ruff from 0.14.7 to 0.14.8 - ([#83](https://github.com/NREL/plexosdb/issues/83)) - ([c4123e1](https://github.com/NREL/plexosdb/commit/c4123e13f38d43586e1ba306b09b7b73c04b7b59)) + ([#83](https://github.com/NatLabRockies/plexosdb/issues/83)) + ([c4123e1](https://github.com/NatLabRockies/plexosdb/commit/c4123e13f38d43586e1ba306b09b7b73c04b7b59)) -## [1.2.2](https://github.com/NREL/plexosdb/compare/v1.2.1...v1.2.2) (2025-12-06) +## [1.2.2](https://github.com/NatLabRockies/plexosdb/compare/v1.2.1...v1.2.2) (2025-12-06) ### πŸ› Bug Fixes - Update battery collection enum naming and add increment to rank for same class - enum ([#80](https://github.com/NREL/plexosdb/issues/80)) - ([e247e67](https://github.com/NREL/plexosdb/commit/e247e6731f05eeef792cf8de09f0123e6f9d2995)) + enum ([#80](https://github.com/NatLabRockies/plexosdb/issues/80)) + ([e247e67](https://github.com/NatLabRockies/plexosdb/commit/e247e6731f05eeef792cf8de09f0123e6f9d2995)) -## [1.2.1](https://github.com/NREL/plexosdb/compare/v1.2.0...v1.2.1) (2025-12-04) +## [1.2.1](https://github.com/NatLabRockies/plexosdb/compare/v1.2.0...v1.2.1) (2025-12-04) ### πŸ› Bug Fixes - handle property related attributes on "add_properties_from_records" method - ([#78](https://github.com/NREL/plexosdb/issues/78)) - ([1776d2a](https://github.com/NREL/plexosdb/commit/1776d2a614facef29d5a2a3df1f3a27dd154e359)) + ([#78](https://github.com/NatLabRockies/plexosdb/issues/78)) + ([1776d2a](https://github.com/NatLabRockies/plexosdb/commit/1776d2a614facef29d5a2a3df1f3a27dd154e359)) -## [1.2.0](https://github.com/NREL/plexosdb/compare/v1.1.3...v1.2.0) (2025-12-02) +## [1.2.0](https://github.com/NatLabRockies/plexosdb/compare/v1.1.3...v1.2.0) (2025-12-02) ### πŸš€ Features - Adding method `add_datafile_tag` and refactor add_properties/add_properties_from_records - ([#69](https://github.com/NREL/plexosdb/issues/69)) - ([1e6e018](https://github.com/NREL/plexosdb/commit/1e6e01852e46fba89b16120c07d472f4c84f94ab)) + ([#69](https://github.com/NatLabRockies/plexosdb/issues/69)) + ([1e6e018](https://github.com/NatLabRockies/plexosdb/commit/1e6e01852e46fba89b16120c07d472f4c84f94ab)) - Adding new fixtures for cleaner testing. - ([#68](https://github.com/NREL/plexosdb/issues/68)) - ([9062baa](https://github.com/NREL/plexosdb/commit/9062baab8db1eb611dcb7364e952bbdb898fe36a)) + ([#68](https://github.com/NatLabRockies/plexosdb/issues/68)) + ([9062baa](https://github.com/NatLabRockies/plexosdb/commit/9062baab8db1eb611dcb7364e952bbdb898fe36a)) - Adding query date_from and date_to to properties - ([#67](https://github.com/NREL/plexosdb/issues/67)) - ([00d533b](https://github.com/NREL/plexosdb/commit/00d533b4b547822a09984cf59e40738fea330f4a)) + ([#67](https://github.com/NatLabRockies/plexosdb/issues/67)) + ([00d533b](https://github.com/NatLabRockies/plexosdb/commit/00d533b4b547822a09984cf59e40738fea330f4a)) ### πŸ› Bug Fixes - Adding new release-please workflow - ([#71](https://github.com/NREL/plexosdb/issues/71)) - ([1f8da38](https://github.com/NREL/plexosdb/commit/1f8da384a9deb3edfa7a343e91999d3d37e07b17)) + ([#71](https://github.com/NatLabRockies/plexosdb/issues/71)) + ([1f8da38](https://github.com/NatLabRockies/plexosdb/commit/1f8da384a9deb3edfa7a343e91999d3d37e07b17)) ### πŸ“¦ Build - **deps:** bump actions/checkout from 4 to 6 - ([#74](https://github.com/NREL/plexosdb/issues/74)) - ([bb7be8d](https://github.com/NREL/plexosdb/commit/bb7be8d0e36c332051ec1a1767b8862f4baec359)) + ([#74](https://github.com/NatLabRockies/plexosdb/issues/74)) + ([bb7be8d](https://github.com/NatLabRockies/plexosdb/commit/bb7be8d0e36c332051ec1a1767b8862f4baec359)) - **deps:** bump actions/setup-python from 5 to 6 - ([#73](https://github.com/NREL/plexosdb/issues/73)) - ([18a0d9d](https://github.com/NREL/plexosdb/commit/18a0d9d26db2056d79bbdda6cec168e895abe0e9)) + ([#73](https://github.com/NatLabRockies/plexosdb/issues/73)) + ([18a0d9d](https://github.com/NatLabRockies/plexosdb/commit/18a0d9d26db2056d79bbdda6cec168e895abe0e9)) - **deps:** bump furo from 2024.8.6 to 2025.9.25 - ([#77](https://github.com/NREL/plexosdb/issues/77)) - ([3dd6463](https://github.com/NREL/plexosdb/commit/3dd64632666e31a38f6ed8f8bb15f9d333e64791)) + ([#77](https://github.com/NatLabRockies/plexosdb/issues/77)) + ([3dd6463](https://github.com/NatLabRockies/plexosdb/commit/3dd64632666e31a38f6ed8f8bb15f9d333e64791)) - **deps:** bump ipython from 9.4.0 to 9.7.0 - ([#76](https://github.com/NREL/plexosdb/issues/76)) - ([ca687df](https://github.com/NREL/plexosdb/commit/ca687dfa466990e59c273c26908496c1fd5a8878)) + ([#76](https://github.com/NatLabRockies/plexosdb/issues/76)) + ([ca687df](https://github.com/NatLabRockies/plexosdb/commit/ca687dfa466990e59c273c26908496c1fd5a8878)) - **deps:** bump pytest from 8.4.1 to 9.0.1 - ([#75](https://github.com/NREL/plexosdb/issues/75)) - ([5864d85](https://github.com/NREL/plexosdb/commit/5864d85e69e5e6cc865fc389e6b15f8e63785001)) + ([#75](https://github.com/NatLabRockies/plexosdb/issues/75)) + ([5864d85](https://github.com/NatLabRockies/plexosdb/commit/5864d85e69e5e6cc865fc389e6b15f8e63785001)) ## [0.0.1] - 2024-08-21 diff --git a/README.md b/README.md index 9f096d65..37669fbc 100644 --- a/README.md +++ b/README.md @@ -134,7 +134,7 @@ This software is released under a BSD-3-Clause [License](https://github.com/NatLabRockies/plexosdb/blob/main/LICENSE.txt). This software was developed under software record SWR-24-90 at the National -Renewable Energy Laboratory ([NREL](https://www.nrel.gov)). +Laboratory of the Rockies (NLR). ## Disclaimer diff --git a/docs/source/CHANGELOG.md b/docs/source/CHANGELOG.md index e5d936e1..a03be4af 100644 --- a/docs/source/CHANGELOG.md +++ b/docs/source/CHANGELOG.md @@ -2,6 +2,20 @@ All notable changes to this project will be documented in this file. +## [1.6.1] - 2026-08-11 + +### Documentation + +- Updated property examples to use the current `datafile_text` and `timeslice` + arguments. +- Documented the current bulk property-record formats and deprecation warning + for the legacy nested format. +- Expanded solution inspection guidance for the 1.6.1 release. + +## Current Documentation Updates + +- Corrected simulation phase mappings in the report how-to and tutorial. + ## [1.0.0] - 2025-04-07 ### πŸš€ Features diff --git a/docs/source/api/checks.md b/docs/source/api/checks.md new file mode 100644 index 00000000..7c831ed5 --- /dev/null +++ b/docs/source/api/checks.md @@ -0,0 +1,16 @@ +# Checks + +Validation helpers for checking classes, objects, collections, memberships, +properties, attributes, scenarios, data records, and tags in a `PlexosDB` +database. + +```{eval-rst} +.. automodule:: plexosdb.checks + :members: + :undoc-members: + :show-inheritance: +``` + +The helpers accept a `PlexosDB` instance as their first argument. The same +checks are also available as convenience methods on `PlexosDB` where the class +exposes them. diff --git a/docs/source/api/db_solution.md b/docs/source/api/db_solution.md new file mode 100644 index 00000000..dc6bae9c --- /dev/null +++ b/docs/source/api/db_solution.md @@ -0,0 +1,28 @@ +# DuckDB Solution Reader + +The DuckDB solution reader converts a PLEXOS solution ZIP with `plexos2duckdb` +and exposes lazy DuckDB relations for analysis. Import it explicitly to +distinguish it from the SQLite-backed solution reader: + +```python +from plexosdb.db_solution import PlexosSolution +``` + +```{eval-rst} +.. automodule:: plexosdb.db_solution + :members: + :undoc-members: + :show-inheritance: +``` + +## Result Types + +```{eval-rst} +.. automodule:: plexosdb.db_solution_models + :members: + :undoc-members: + :show-inheritance: +``` + +See [Reading a PLEXOS Solution](../howtos/read_solution.md) for a complete +ZIP-to-DuckDB workflow. diff --git a/docs/source/api/index.md b/docs/source/api/index.md index b350aafb..cc8dca4f 100644 --- a/docs/source/api/index.md +++ b/docs/source/api/index.md @@ -13,6 +13,9 @@ behavior. :maxdepth: 2 plexosdb +checks +db_solution +solution_reader model_attributes production_attributes performance_attributes diff --git a/docs/source/api/plexosdb.md b/docs/source/api/plexosdb.md index dc6f7e26..dcbca4e8 100644 --- a/docs/source/api/plexosdb.md +++ b/docs/source/api/plexosdb.md @@ -1,5 +1,19 @@ # PlexosDB Class +The reference below includes the complete `PlexosDB` class surface. Some +declared methods are reserved for future implementation and currently raise +`NotImplementedError`; they are listed in the API for transparency but should +not be used as supported workflows yet. + +Currently unimplemented methods include `add_custom_column`, `add_metadata`, +`add_time_slice`, `add_variable_tag`, `backup_database`, +`create_object_scenario`, `delete_category`, `delete_membership`, +`delete_metadata`, `delete_text`, `get_config`, `get_custom_columns`, +`get_metadata`, `get_property_unit`, `get_text`, `get_unit`, `import_from_csv`, +`list_reports`, `set_config`, `set_date_range`, `to_csv`, `update_attribute`, +`update_category`, `update_properties`, `update_property`, `update_scenario`, +`update_text`, and `validate_database`. + ```{eval-rst} .. automodule:: plexosdb.db :members: diff --git a/docs/source/api/solution_reader.md b/docs/source/api/solution_reader.md new file mode 100644 index 00000000..ecf77735 --- /dev/null +++ b/docs/source/api/solution_reader.md @@ -0,0 +1,37 @@ +# SQLite Solution Reader + +The SQLite solution reader imports a PLEXOS solution ZIP into SQLite and +materializes derived result tables for analysis. Import it explicitly to +distinguish it from the DuckDB-backed solution wrapper: + +```python +from plexosdb.solution_reader import PlexosSolution +``` + +```{eval-rst} +.. automodule:: plexosdb.solution_reader.solution + :members: + :undoc-members: + :show-inheritance: +``` + +## Display Helpers + +```{eval-rst} +.. automodule:: plexosdb.solution_reader.display + :members: + :undoc-members: + :show-inheritance: +``` + +## Result Types + +```{eval-rst} +.. automodule:: plexosdb.solution_reader.types + :members: + :undoc-members: + :show-inheritance: +``` + +See [Inspecting a PLEXOS Solution](../howtos/inspect_solution.md) for a complete +ZIP-to-SQLite workflow. diff --git a/docs/source/conf.py b/docs/source/conf.py index b3125741..fcac4c0b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -2,7 +2,7 @@ project = "plexosdb" copyright = "2024, Alliance for Sustainable Energy LLC, All rights reserved." author = "pesap" -release = "1.0" +release = "1.6.1" extensions = [ "myst_parser", "sphinx.ext.githubpages", @@ -29,13 +29,13 @@ html_title = "plexosdb" html_theme_options = { "navigation_with_keys": True, - "source_repository": "https://github.com/NREL/plexosdb/", + "source_repository": "https://github.com/NatLabRockies/plexosdb/", "source_branch": "main", "source_directory": "docs/", "footer_icons": [ { "name": "GitHub", - "url": "https://github.com/NREL/plexosdb", + "url": "https://github.com/NatLabRockies/plexosdb", "html": """ diff --git a/docs/source/howtos/add_attributes.md b/docs/source/howtos/add_attributes.md index 3376b9a0..ca439f46 100644 --- a/docs/source/howtos/add_attributes.md +++ b/docs/source/howtos/add_attributes.md @@ -38,7 +38,7 @@ from plexosdb.enums import ClassEnum, CollectionEnum # Initialize database db = PlexosDB() -db.create_schema() +db.create_schema(version=10) # Create a generator object if it doesn't exist if not db.check_object_exists(ClassEnum.Generator, "Generator1"): diff --git a/docs/source/howtos/add_objects.md b/docs/source/howtos/add_objects.md index 232bbf1d..28d30008 100644 --- a/docs/source/howtos/add_objects.md +++ b/docs/source/howtos/add_objects.md @@ -11,7 +11,7 @@ from plexosdb.enums import ClassEnum # Initialize database db = PlexosDB() -db.create_schema() +db.create_schema(version=10) # Add a generator object db.add_object( diff --git a/docs/source/howtos/add_properties.md b/docs/source/howtos/add_properties.md index c3f60c80..348a973e 100644 --- a/docs/source/howtos/add_properties.md +++ b/docs/source/howtos/add_properties.md @@ -3,6 +3,10 @@ Properties define attributes of objects in your PLEXOS model, such as a generator's capacity or a node's location. +The examples in this guide use the PlexosDB 1.6.1 API. The first argument to +`add_property` is positional-only; the remaining property arguments are passed +by name where that makes the example easier to read. + ## Basic Property Addition ```python @@ -11,11 +15,12 @@ from plexosdb.enums import ClassEnum, CollectionEnum # Initialize database db = PlexosDB() -db.create_schema() +db.create_schema(version=10) # Create a generator object if it doesn't exist -if not db.check_object_exists(ClassEnum.Generator, "Generator1"): - db.add_object(ClassEnum.Generator, "Generator1") +for generator_name in ("Generator1", "Generator2", "Generator3"): + if not db.check_object_exists(ClassEnum.Generator, generator_name): + db.add_object(ClassEnum.Generator, generator_name) # Add a property to the generator db.add_property( @@ -28,7 +33,7 @@ db.add_property( # Add another property db.add_property( ClassEnum.Generator, - object_name="Generator1", + object_name="Generator2", name="Min Stable Level", value=20.0 ) @@ -64,34 +69,81 @@ db.add_property( ) ``` -## Adding Text Data to Properties +## Adding DataFile and Timeslice Text -Properties can include additional text information: +Use `datafile_text` to attach file-path metadata to a property. This is the +supported replacement for the older `text` example; `add_property` does not +accept a `text` keyword. Use `timeslice` for timeslice metadata. ```python -from plexosdb.enums import ClassEnum +# Attach DataFile metadata to the property data record. +db.add_property( + ClassEnum.Generator, + object_name="Generator1", + name="Max Capacity", + value=100.0, + datafile_text="gen1.csv", +) -# Add a property with text data +# Attach timeslice metadata when the property is timeslice-specific. db.add_property( ClassEnum.Generator, object_name="Generator1", - name="Max Capacity", # Use a valid property name - value="Main unit", - text={ClassEnum.Generator: "Primary generation unit"} + name="Max Capacity", + value=110.0, + timeslice="Peak", +) +``` + +`datafile_text` and `timeslice` store text metadata on the property data record; +they do not change the property's numeric or string `value`. A DataFile or +Timeslice object does not need to be created manually for these associations. + +## Adding Date- and Scenario-Specific Properties + +Scenarios are created automatically when the supplied scenario does not yet +exist. Date bounds must be `datetime` objects. + +```python +from datetime import datetime + +db.add_property( + ClassEnum.Generator, + "Generator1", + "Max Capacity", + 120.0, + scenario="High Demand", + date_from=datetime(2030, 1, 1), + date_to=datetime(2030, 12, 31), + band=1, ) ``` +For non-default memberships, pass `collection_enum`, `parent_class_enum`, and +optionally `parent_object_name` to select the membership to which the property +is added. When omitted, the default collection is selected, the parent class +defaults to `ClassEnum.System`, and the membership is resolved from the object +and collection. + ## Bulk Adding Properties -For efficiency when adding many properties at once (use the flat format; the -nested format is accepted but deprecated and will emit a warning): +For efficiency when adding many properties at once, use flat records. Each flat +record contains `name`, `property`, and `value`; `band`, `datafile_text`, and +`timeslice` are optional per-record fields. The legacy nested format is still +accepted but deprecated and emits a warning. ```python # Flat format (recommended) flat_records = [ {"name": "Generator1", "property": "Max Capacity", "value": 100, "band": 1}, {"name": "Generator1", "property": "Max Capacity", "value": 200, "band": 2}, - {"name": "Generator2", "property": "Heat Rate", "value": 9.9, "datafile_text": "gen2.csv"}, + { + "name": "Generator2", + "property": "Heat Rate", + "value": 9.9, + "datafile_text": "gen2.csv", + "timeslice": "Peak", + }, ] # Nested format (legacy; will be removed in the future) @@ -108,6 +160,11 @@ db.add_properties_from_records( ) ``` +The bulk method applies the supplied `scenario` to all records, defaults +`parent_class` to `ClassEnum.System`, and processes records in chunks of 10,000 +by default. Set `chunksize` to tune memory use for larger imports. It uses a +transaction, so an insertion error rolls back the bulk operation. + ## Checking Valid Properties Before adding properties, you can check if they are valid for a collection: @@ -123,5 +180,7 @@ print(f"Valid generator properties: {valid_props}") ``` ```{warning} -Adding an invalid property will raise a NameError. Always check if properties are valid for your collection. +Adding an invalid property raises `NameError`; a missing object raises +`NotFoundError`. Always check if properties are valid for your collection and +create the target object before adding its properties. ``` diff --git a/docs/source/howtos/add_reports.md b/docs/source/howtos/add_reports.md index 41592feb..93ae06a1 100644 --- a/docs/source/howtos/add_reports.md +++ b/docs/source/howtos/add_reports.md @@ -15,7 +15,7 @@ from plexosdb.enums import ClassEnum, CollectionEnum # Create or open a database db = PlexosDB() -db.create_schema() +db.create_schema(version=10) # First, create a Report object db.add_object(ClassEnum.Report, "Generator Outputs") diff --git a/docs/source/howtos/bulk_operations.md b/docs/source/howtos/bulk_operations.md index 5cad05fe..b3fc85f3 100644 --- a/docs/source/howtos/bulk_operations.md +++ b/docs/source/howtos/bulk_operations.md @@ -18,7 +18,7 @@ from plexosdb.enums import ClassEnum, CollectionEnum # Initialize the database db = PlexosDB() -db.create_schema() +db.create_schema(version=10) # Create the objects first db.add_object(ClassEnum.Generator, "Generator1") @@ -134,7 +134,7 @@ from plexosdb.utils import create_membership_record # Initialize the database db = PlexosDB() -db.create_schema() +db.create_schema(version=10) # Create parent and child objects region_id = db.add_object(ClassEnum.Region, "MainRegion") diff --git a/docs/source/howtos/delete_objects.md b/docs/source/howtos/delete_objects.md index a7f4d104..bf8b38a6 100644 --- a/docs/source/howtos/delete_objects.md +++ b/docs/source/howtos/delete_objects.md @@ -15,7 +15,7 @@ from plexosdb.enums import ClassEnum # Initialize database db = PlexosDB() -db.create_schema() +db.create_schema(version=10) # Add a simple test generator object db.add_object( diff --git a/docs/source/howtos/import_export.md b/docs/source/howtos/import_export.md index 1a7366b7..c0c92a7a 100644 --- a/docs/source/howtos/import_export.md +++ b/docs/source/howtos/import_export.md @@ -65,63 +65,23 @@ else: print("Export failed") ``` -## Importing from CSV +## CSV and database backups -Import data from CSV files: +The `import_from_csv()`, `to_csv()`, and `backup_database()` methods are part of +the declared API but currently raise `NotImplementedError`. Use XML import and +export for supported file-based workflows. -```python -# Import specific tables from CSV files -db.import_from_csv( - "/path/to/csv_directory", - tables=["t_object", "t_data", "t_property"] -) -``` - -## Exporting to CSV - -Export database tables to CSV files: - -```python -# Export all tables to CSV -db.to_csv("/path/to/output_directory") - -# Export specific tables -db.to_csv( - "/path/to/output_directory", - tables=["t_object", "t_data", "t_property"] -) -``` - -## Database Backup - -Create a backup of your in-memory database: - -```python -# Backup the database to a file -db.backup_database("/path/to/backup.db") -``` - -## Creating and Optimizing Databases +## Creating databases ```python # Create an empty database db = PlexosDB() -db.create_schema() - -# After making many changes, optimize the database -db._db.optimize() -``` +db.create_schema(version=10) -## Converting Between Formats - -Converting from XML to CSV: - -```python -# Import from XML then export to CSV -db = PlexosDB.from_xml("/path/to/model.xml") -db.to_csv("/path/to/csv_output") ``` ```{warning} -When working with large files, ensure you have sufficient memory and disk space for the operations. +When working with large XML files, ensure you have sufficient memory and disk +space for the operations. CSV conversion and database backup are not currently +implemented. ``` diff --git a/docs/source/howtos/index.md b/docs/source/howtos/index.md index 3775b6a6..90b5eea5 100644 --- a/docs/source/howtos/index.md +++ b/docs/source/howtos/index.md @@ -14,6 +14,7 @@ create_db add_objects add_properties add_attributes +add_reports delete_objects query_database work_with_scenarios diff --git a/docs/source/howtos/inspect_solution.md b/docs/source/howtos/inspect_solution.md index 5d074abc..b1ba5eae 100644 --- a/docs/source/howtos/inspect_solution.md +++ b/docs/source/howtos/inspect_solution.md @@ -1,8 +1,13 @@ -# Inspecting a PLEXOS Solution +# Inspecting a PLEXOS Solution with SQLite This guide shows how to import a PLEXOS solution ZIP file into SQLite and inspect its table catalog using the `show_db_tables` helper. +This guide uses the SQLite-backed `PlexosSolution` imported from +`plexosdb.solution_reader`. It is separate from the DuckDB-backed class in +`plexosdb.db_solution`. See the +[SQLite solution API reference](../api/solution_reader.md) for the complete API. + ## Converting a solution Use `PlexosSolution` to import the ZIP into SQLite. Pass @@ -13,7 +18,7 @@ only needs the XML metadata tables and is then fast even for large solutions: from plexosdb.solution_reader import PlexosSolution, show_db_tables sol = PlexosSolution.from_zip("my_solution.zip") -sol.to_sqlite("output.sqlite", if_exists="replace") +sol.to_sqlite("output.sqlite", if_exists="replace", decode_bin_values=False) ``` :::{note} `decode_bin_values=False` is only appropriate for catalog inspection. @@ -67,8 +72,8 @@ Rows that do not fit within `max_rows` are replaced by three `Β·` rows. The default limit is 20; pass a different value to show more: ```python -with client as db: - show_db_tables(db, max_rows=50) +with sol as db: + show_db_tables(db, max_rows=50) ``` ## Columns diff --git a/docs/source/howtos/manage_relationships.md b/docs/source/howtos/manage_relationships.md index 4b22b9f3..ff69392e 100644 --- a/docs/source/howtos/manage_relationships.md +++ b/docs/source/howtos/manage_relationships.md @@ -13,7 +13,7 @@ from plexosdb.enums import ClassEnum, CollectionEnum # Initialize database db = PlexosDB() -db.create_schema() +db.create_schema(version=10) # Create parent and child objects db.add_object(ClassEnum.Region, "Region1") diff --git a/docs/source/howtos/read_solution.md b/docs/source/howtos/read_solution.md index ad0f34de..5d200b82 100644 --- a/docs/source/howtos/read_solution.md +++ b/docs/source/howtos/read_solution.md @@ -1,7 +1,12 @@ -# Reading a PLEXOS Solution +# Reading a PLEXOS Solution with DuckDB -Use the DuckDB-backed `PlexosSolution` API when you need to read result tables -from a PLEXOS solution ZIP file. +Use the DuckDB-backed `PlexosSolution` API when you need lazy DuckDB relations +and SQL queries over result tables from a PLEXOS solution ZIP file. Import it +from `plexosdb.db_solution`; the SQLite-backed class in +`plexosdb.solution_reader` is a separate implementation. + +See the [DuckDB solution API reference](../api/db_solution.md) for the full +method and result-type documentation. ## Converting a solution diff --git a/docs/source/howtos/remove_non_ascii.md b/docs/source/howtos/remove_non_ascii.md index 448d4599..ef73f572 100644 --- a/docs/source/howtos/remove_non_ascii.md +++ b/docs/source/howtos/remove_non_ascii.md @@ -13,7 +13,7 @@ def clean_international_text(text: str) -> str: from plexosdb import PlexosDB from plexosdb.enums import ClassEnum, CollectionEnum db = PlexosDB() -db.create_schema() +db.create_schema(version=10) original_name="PΓ€lli") db.add_object(ClassEnum.Generator, original_name) diff --git a/docs/source/howtos/work_with_scenarios.md b/docs/source/howtos/work_with_scenarios.md index 6392a7a7..ee19bef4 100644 --- a/docs/source/howtos/work_with_scenarios.md +++ b/docs/source/howtos/work_with_scenarios.md @@ -12,7 +12,7 @@ from plexosdb import PlexosDB # Initialize database db = PlexosDB() -db.create_schema() +db.create_schema(version=10) db.add_scenario("TestScenario") ``` @@ -27,7 +27,7 @@ from plexosdb.enums import ClassEnum # Initialize database db = PlexosDB() -db.create_schema() +db.create_schema(version=10) # Create a generator db.add_object(ClassEnum.Generator, "Generator1") diff --git a/docs/source/installation.md b/docs/source/installation.md index 49e2f6af..e390a804 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -23,7 +23,7 @@ pip install plexosdb==1.2.3 To install the latest development version directly from GitHub: ```bash -pip install git+https://github.com/NREL/plexosdb.git +pip install git+https://github.com/NatLabRockies/plexosdb.git ``` ## Using uv diff --git a/docs/source/tutorial.md b/docs/source/tutorial.md index 116b96a1..0f288cef 100644 --- a/docs/source/tutorial.md +++ b/docs/source/tutorial.md @@ -32,8 +32,8 @@ from plexosdb import PlexosDB # Create a new in-memory database db = PlexosDB() -# Initialize with the built-in default schema -ok = db.create_schema() +# Initialize with the version 10 master template +ok = db.create_schema(version=10) assert ok # Option A: initialize schema + minimal defaults for object workflows @@ -55,8 +55,8 @@ db_versioned = PlexosDB() db_versioned.create_schema(version=10) ``` -This creates an in-memory database with the PLEXOS schema and minimal lookup -data so object APIs work immediately. +This creates an in-memory database with the PLEXOS schema and versioned master +template data so object APIs work immediately. If you call `db.create_schema()` without `seed_defaults=True`, only the table structure is created. For `add_object(...)` and related workflows, use