From 5c5245c46300032ac09d717f0cf095228024c37d Mon Sep 17 00:00:00 2001 From: John Vouvakis Manousakis Date: Tue, 5 Nov 2024 14:35:24 -0800 Subject: [PATCH 1/3] Unreleased change log. Update `Unreleased` change log. This section will always be there to document the changes that are worthy of mention in in the change log of the next release, so that we don't have to painstakingly monitor the commit logs to write a change log before making each release. When a release is made, the log will be transferred from this page to the page associated with the new version. --- doc/source/release_notes/index.rst | 1 + doc/source/release_notes/unreleased.rst | 67 +++++++++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 doc/source/release_notes/unreleased.rst diff --git a/doc/source/release_notes/index.rst b/doc/source/release_notes/index.rst index 31bc46847..9367dbcd1 100644 --- a/doc/source/release_notes/index.rst +++ b/doc/source/release_notes/index.rst @@ -13,6 +13,7 @@ Version 3.0 .. toctree:: :maxdepth: 2 + unreleased v3.3.0 v3.2.0 v3.1.0 diff --git a/doc/source/release_notes/unreleased.rst b/doc/source/release_notes/unreleased.rst new file mode 100644 index 000000000..c66dd334f --- /dev/null +++ b/doc/source/release_notes/unreleased.rst @@ -0,0 +1,67 @@ +.. _changes_unreleased: + +========== +Unreleased +========== + +Added +----- + +**Documentation pages**: Documentation for pelicun 3 is back online. The documentation includes guides for users and developers as well as an auto-generated API reference. A lineup of examples is planned to be featured in the documentation, highlighting specific features, including the new features listed in this section. + +**Consequence scaling**: This feature can be used to apply scaling factors to estimated losses based on specific decision variables, component types, locations and directions. This can make it easier to examining several different consequence scaling schemes without the need to repeat all calculations or write extensive custom code. + +**Loss functions**: Loss functions are used to estimate losses directly from the demands. The damage and loss models were substantially restructured to facilitate the addition of loss functions. + +**Loss combinations**: Loss combinations allow for the combination of two types of losses using a multi-dimensional lookup table. For example, independently calculated wind and flooding losses can be combined to produce a single loss estimate considering their combined occurrence. + +**Utility demand**: Utility demands are compound demands calculated using a mathematical expression involving other demands. Application examples could include the application of a mathematical expression to a demand column before using it to estimate damage, or combining multiple columns with an arbitrary multivariate expression to generate a combined demand. + +**Normal with standard deviation**: Added a few variants of "normal" in ``uq.py``: ``normal_COV`` and ``normal_STD``. Since the variance of the default normal random variables is currently defined via the coefficient of variation, ``normal_STD`` enables the definition of normal random variables with zero mean. ``normal_COV`` is treated in the same way as the default ``normal``. + +**Weibull random variable**: Added a Weibull random variable class in ``uq.py``. + +**New ``DL_calculation.py`` input file options**: We expanded configuration options in the ``DL_calculation.py`` input file specification. Specifically, we added ``CustomDLDataFolder`` for specifying additional user-defined components. + +**Warnings in red**: Added support for colored outputs. Warnings are now shown in red, conditioned on what the execution environment supports. + +Code base related additions, which are not directly implementing new features but are nonetheless enhancing robustness, include the following: +- pelicun-specific warnings with the option to disable them +- a JSON schema for the ``DL_calculation.py`` input file +- addition of type hints in the entire code base +- addition of slots in all classes, preventing on-the-fly definition of new attributes which is prone to bugs + +Changed +------- + +- Updated random variable class names in ``uq.py``. +- Extensive code refactoring for improved organization and to support the added features. We made a good-faith effort to maintain backwards compatibility, and issue helpful warnings to assist migration to the new syntax. +- Moved code from DL_calculation.py to assessment.py and created an assessment class. +- Migrated to Ruff for linting and code formatting. Began using mypy for type checking and codespell for spell checking. + +Deprecated +---------- + +- ``.bldg_repair`` attribute was renamed to ``.loss`` +- ``.repair`` had also been used in the past, please use ``.loss`` instead. +- In the damage and loss model library, ``fragility_DB`` was renamed to ``damage_DB`` and ``bldg_repair_DB`` was renamed to ``loss_repair_DB``. +- ``load_damage_model`` was renamed to ``load_model_parameters`` and the syntax has changed. Please see the applicable warning message when using ``load_damage_model`` for the updated syntax. +- ``{damage model}.sample`` was deprecated in favor of ``{damage model}.ds_model.sample``. +- The ``DMG-`` flag in the loss_map index is no longer required. +- ``BldgRepair`` column is deprecated in favor of ``Repair``. +- ``load_model`` -> ``load_model_parameters`` +- ``{loss model}.save_sample`` -> ``'{loss model}.ds_model.save_sample``. The same applies to ``load_sample``. + +Removed +------- + +- No features were removed in this version. +- We suspended the use of flake8 and pylint after adopting the use of ruff. + +Fixed +----- + +- Fixed a bug affecting the random variable classes, where the anchor random variable was not being correctly set. +- Enforced a value of 1.0 for non-directional multipliers for HAZUS analyses. +- Fixed bug in demand cloning: Previously demand unit data were being left unmodified during demand cloning operations, leading to missing values. +- Reviewed and improved docstrings in the entire code base. From 83f1209ce3f697dae0699337fd572228eb132e3d Mon Sep 17 00:00:00 2001 From: Adam Zsarnoczay <33822153+zsarnoczay@users.noreply.github.com> Date: Thu, 7 Nov 2024 00:11:21 -0800 Subject: [PATCH 2/3] Review and edit unreleased.rst Minor adjustments to the first draft of the changelog for the next release --- doc/source/release_notes/unreleased.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/source/release_notes/unreleased.rst b/doc/source/release_notes/unreleased.rst index c66dd334f..3100f0f27 100644 --- a/doc/source/release_notes/unreleased.rst +++ b/doc/source/release_notes/unreleased.rst @@ -7,27 +7,27 @@ Unreleased Added ----- -**Documentation pages**: Documentation for pelicun 3 is back online. The documentation includes guides for users and developers as well as an auto-generated API reference. A lineup of examples is planned to be featured in the documentation, highlighting specific features, including the new features listed in this section. +**Documentation pages**: Documentation for pelicun 3 is back online. The documentation includes guides for users and developers as well as an auto-generated API reference. A lineup of examples is planned to be part of the documentation, highlighting specific features, including the new ones listed in this section. -**Consequence scaling**: This feature can be used to apply scaling factors to estimated losses based on specific decision variables, component types, locations and directions. This can make it easier to examining several different consequence scaling schemes without the need to repeat all calculations or write extensive custom code. +**Consequence scaling**: This feature can be used to apply scaling factors to consequence and loss functions for specific decision variables, component types, locations and directions. This can make it easier to examine several different consequence scaling schemes without the need to repeat all calculations or write extensive custom code. -**Loss functions**: Loss functions are used to estimate losses directly from the demands. The damage and loss models were substantially restructured to facilitate the addition of loss functions. +**Loss functions**: Loss functions are used to estimate losses directly from the demands. The damage and loss models were substantially restructured to facilitate the use of loss functions. -**Loss combinations**: Loss combinations allow for the combination of two types of losses using a multi-dimensional lookup table. For example, independently calculated wind and flooding losses can be combined to produce a single loss estimate considering their combined occurrence. +**Loss combinations**: Loss combinations allow for the combination of two types of losses using a multi-dimensional lookup table. For example, independently calculated losses from wind and flood can be combined to produce a single loss estimate considering both demands. -**Utility demand**: Utility demands are compound demands calculated using a mathematical expression involving other demands. Application examples could include the application of a mathematical expression to a demand column before using it to estimate damage, or combining multiple columns with an arbitrary multivariate expression to generate a combined demand. +**Utility demand**: Utility demands are compound demands calculated using a mathematical expression involving other demands. Practical examples include the application of a mathematical expression on a demand before using it to estimate damage, or combining multiple demands with a multivariate expression to generate a combined demand.Such utility demands can be used to implement those multidimensional fragility models that utilize a single, one-dimensional distribution that is defined through a combination of multiple input variables. -**Normal with standard deviation**: Added a few variants of "normal" in ``uq.py``: ``normal_COV`` and ``normal_STD``. Since the variance of the default normal random variables is currently defined via the coefficient of variation, ``normal_STD`` enables the definition of normal random variables with zero mean. ``normal_COV`` is treated in the same way as the default ``normal``. +**Normal distribution with standard deviation**: Added two new variants of "normal" in ``uq.py``: ``normal_COV`` and ``normal_STD``. Since the variance of the default normal random variables is currently defined via the coefficient of variation, the new ``normal_STD`` is required to define a normal random variable with zero mean. ``normal_COV`` is treated the same way as the default ``normal``. **Weibull random variable**: Added a Weibull random variable class in ``uq.py``. **New ``DL_calculation.py`` input file options**: We expanded configuration options in the ``DL_calculation.py`` input file specification. Specifically, we added ``CustomDLDataFolder`` for specifying additional user-defined components. -**Warnings in red**: Added support for colored outputs. Warnings are now shown in red, conditioned on what the execution environment supports. +**Warnings in red**: Added support for colored outputs. In execution enviornments that support colored outputs, warnings are now shown in red. Code base related additions, which are not directly implementing new features but are nonetheless enhancing robustness, include the following: - pelicun-specific warnings with the option to disable them -- a JSON schema for the ``DL_calculation.py`` input file +- a JSON schema for the input file used to configure simulations through ``DL_calculation.py`` - addition of type hints in the entire code base - addition of slots in all classes, preventing on-the-fly definition of new attributes which is prone to bugs @@ -35,8 +35,8 @@ Changed ------- - Updated random variable class names in ``uq.py``. -- Extensive code refactoring for improved organization and to support the added features. We made a good-faith effort to maintain backwards compatibility, and issue helpful warnings to assist migration to the new syntax. -- Moved code from DL_calculation.py to assessment.py and created an assessment class. +- Extensive code refactoring for improved organization and to support the new features. We made a good-faith effort to maintain backwards compatibility, and issue helpful warnings to assist migration to the new syntax. +- Moved most of the code in DL_calculation.py to assessment.py and created an assessment class. - Migrated to Ruff for linting and code formatting. Began using mypy for type checking and codespell for spell checking. Deprecated From 5724433b489fd457d1028059ba4e12e79cffe0af Mon Sep 17 00:00:00 2001 From: Adam Zsarnoczay <33822153+zsarnoczay@users.noreply.github.com> Date: Thu, 7 Nov 2024 09:23:07 -0800 Subject: [PATCH 3/3] Fix spell check issue --- doc/source/release_notes/unreleased.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/release_notes/unreleased.rst b/doc/source/release_notes/unreleased.rst index 3100f0f27..0c0e11ced 100644 --- a/doc/source/release_notes/unreleased.rst +++ b/doc/source/release_notes/unreleased.rst @@ -23,7 +23,7 @@ Added **New ``DL_calculation.py`` input file options**: We expanded configuration options in the ``DL_calculation.py`` input file specification. Specifically, we added ``CustomDLDataFolder`` for specifying additional user-defined components. -**Warnings in red**: Added support for colored outputs. In execution enviornments that support colored outputs, warnings are now shown in red. +**Warnings in red**: Added support for colored outputs. In execution environments that support colored outputs, warnings are now shown in red. Code base related additions, which are not directly implementing new features but are nonetheless enhancing robustness, include the following: - pelicun-specific warnings with the option to disable them