From 19c38342d779b86650aac030caed03bd97dcdfed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Carles=20S=2E=20Soriano=20P=C3=A9rez?= Date: Tue, 5 Nov 2024 11:47:12 +0100 Subject: [PATCH] chore: Made `InfraPriorityStrategy` default for `KoswatSummaryBuilder` (#214) * chore: Modified summary builder to run by default with the infra strategy * docs: Updated docstrings documentation * docs: Updated Koswat documentation * docs: Updated missing README documentation * docs: Processed review remarks --- docs/reference/koswat_cost_report.md | 4 ++-- .../koswat_docstrings/cost_report.md | 11 +++++++++++ .../reference/koswat_docstrings/strategies.md | 16 +++++++++++++++- docs/reference/koswat_strategies.md | 19 +++++++++++++------ .../summary/koswat_summary_builder.py | 8 ++++++-- koswat/strategies/README.md | 4 ++-- .../summary/test_koswat_summary_builder.py | 4 ++++ 7 files changed, 53 insertions(+), 13 deletions(-) diff --git a/docs/reference/koswat_cost_report.md b/docs/reference/koswat_cost_report.md index 6cbab1ce..032e2429 100644 --- a/docs/reference/koswat_cost_report.md +++ b/docs/reference/koswat_cost_report.md @@ -86,13 +86,13 @@ After running a Koswat analysis, several files and directories will be generated - Images: Visual description of each of the possible reinforcements being applied. - `summary_costs.csv`: A csv file containing all the costs information of the summary. - Represents the Summary, Profile and Layer report. - - `summary_locations.csv` (phased out): A csv file containing per-location a breakdown of available reinforcements and selected reinforcement ( see [strategies](koswat_strategies.md)). + - `summary_locations.csv`: A csv file containing per-location a breakdown of available reinforcements and selected reinforcement ( see [strategies](koswat_strategies.md)). - Represents the Location report. - `/summary_locations` directory: contains the following `.shp` files (and their related binaries): -`summary_locations_measures`: The same data as present in `summary_locations.csv` is used to shape the geometry of a dike's traject. We keep as well the type of chosen reinforcement. - `summary_locations_new`: an overlay of `summary_locations_measures` with the geometry buffered in relation to the new selected reinforcement. - `summary_locations_old`: an overlay of `summary_locations_measures` with the geometry buffered in relation to the original selected reinforcement. - - `summary_locations_step`: an overlay of `summary_locations_measures` with the geometry buffered in relation to the [Ordered Strategy](koswat_strategies.md#order-based-default) step. + - `summary_locations_step`: an overlay of `summary_locations_measures` with the geometry buffered in relation to the [Ordered Strategy](koswat_strategies.md#order-based) step. - `summary_infrastructure_costs.csv`: A csv file contaning all the infrastructure costs at each location for each of the supported reinforcement profile types. - Represents the [Infrastructure Report](#infrastructure-report). diff --git a/docs/reference/koswat_docstrings/cost_report.md b/docs/reference/koswat_docstrings/cost_report.md index 2ed97a39..349a5246 100644 --- a/docs/reference/koswat_docstrings/cost_report.md +++ b/docs/reference/koswat_docstrings/cost_report.md @@ -3,6 +3,7 @@ ::: koswat.cost_report.cost_report_protocol ## Infrastructure cost calculator + ::: koswat.cost_report.infrastructure.profile_zone_calculator ::: koswat.cost_report.infrastructure.infrastructure_profile_costs_calculator ::: koswat.cost_report.infrastructure.multi_infrastructure_profile_costs_calculator @@ -10,22 +11,32 @@ ## Quantity cost parameters calculator + ::: koswat.cost_report.profile.quantity_cost_parameters_calculator ::: koswat.cost_report.profile.quantity_cost_parameters ## IO ### Summary + ::: koswat.cost_report.io.summary.koswat_summary_exporter #### Summary costs + ::: koswat.cost_report.io.summary.summary_costs.summary_costs_csv_exporter ::: koswat.cost_report.io.summary.summary_costs.summary_costs_csv_fom_builder #### Summary infrastructure costs + ::: koswat.cost_report.io.summary.summary_infrastructure_costs.summary_infrastructure_costs_csv_exporter ::: koswat.cost_report.io.summary.summary_infrastructure_costs.summary_infrastructure_costs_csv_fom_builder #### Summary locations + ::: koswat.cost_report.io.summary.summary_locations.summary_locations_csv_exporter ::: koswat.cost_report.io.summary.summary_locations.summary_locations_csv_fom_builder +::: koswat.cost_report.io.summary.summary_locations.cluster_shp_fom +::: koswat.cost_report.io.summary.summary_locations.cluster_collection_shp_fom +::: koswat.cost_report.io.summary.summary_locations.cluster_geodataframe_output_fom +::: koswat.cost_report.io.summary.summary_locations.summary_locations_shp_exporter + diff --git a/docs/reference/koswat_docstrings/strategies.md b/docs/reference/koswat_docstrings/strategies.md index 9bf8aa89..fecabdb4 100644 --- a/docs/reference/koswat_docstrings/strategies.md +++ b/docs/reference/koswat_docstrings/strategies.md @@ -1,7 +1,10 @@ # Strategies ::: koswat.strategies.strategy_input +::: koswat.strategies.strategy_location_input ::: koswat.strategies.strategy_location_reinforcement +::: koswat.strategies.strategy_reinforcement_input +::: koswat.strategies.strategy_reinforcement_type_costs ::: koswat.strategies.strategy_protocol ## Order Strategy @@ -10,4 +13,15 @@ ::: koswat.strategies.order_strategy.order_strategy_base ::: koswat.strategies.order_strategy.order_strategy_buffering ::: koswat.strategies.order_strategy.order_strategy_clustering -::: koswat.strategies.order_strategy.order_cluster \ No newline at end of file +::: koswat.strategies.order_strategy.order_cluster + +## Infra Priority Strategy + +::: koswat.strategies.infra_priority_strategy.infra_priority_strategy +::: koswat.strategies.infra_priority_strategy.infra_cluster +::: koswat.strategies.infra_priority_strategy.infra_cluster_option + +## Strategy step + +::: koswat.strategies.strategy_step.strategy_step_assignment +::: koswat.strategies.strategy_step.strategy_step_enum \ No newline at end of file diff --git a/docs/reference/koswat_strategies.md b/docs/reference/koswat_strategies.md index fa7f1dbc..0ac8e887 100644 --- a/docs/reference/koswat_strategies.md +++ b/docs/reference/koswat_strategies.md @@ -7,15 +7,21 @@ A strategy requires a strategy input (`StrategyInput`), this input contains info By default a strategy is applied as follows: 1. For each point (meter) in the traject, determine which reinforcements can be applied to it. -2. Choose one of the available reinforcements based on the chosen [strategy](#order-based-default). When no reinforcement is available the most restrictive will be chosen (`CofferDam`). +2. Choose one of the available reinforcements based on the chosen [strategy](#order-based). When no reinforcement is available the most restrictive will be chosen (`CofferDam`). 3. Apply a buffer (`reinforcement_min_buffer`) for each one of the reinforcements. 4. Check if the minimal distance between constructions is met (`reinforcement_min_length`), otherwise change it into one of the reinforcements next to it. 5. Repeat 4 until all reinforcements have enough distance between themselves. -6. Return list of mapped locations (`list[StrategyLocationReinforcement]`). +6. Find based on the strategy for [infrastructure derived costs](#infrastructure-priority), mapped locations (`list[StrategyLocationReinforcement]`) whose reinforcement can be increased into a most restrictive one with total lower costs. +7. Return list of mapped locations (`list[StrategyLocationReinforcement]`). ## Available strategies -### Order based (default) +Currently the following strategies are implemented: + +- [Order based](#order-based) +- [Infrastructure priority](#infrastructure-priority), by default the strategy to run during a Koswat analysis. + +### Order based This strategy is the first and default of all defined strategies. Its criteria is based on a pre-defined ['order'](#reinforcement-order) of each reinforcement. In steps, it can be seen as: @@ -234,11 +240,12 @@ Resulting cluster: ### Infrastructure priority -This (experimental) strategy checks whether the clusters resulting from the [order based strategy](#order-based-default) can change their selected reinforcement to one with cheaper costs. These costs are extracted from the [cost report](koswat_cost_report.md#cost-report) and relate to the reinforcement profile costs (dike's materials for the required space) and the possible [infrastructure costs](koswat_cost_report.md#infrastructure-report). In steps, this strategy can be broke down as: +**DEFAULT STRATEGY** +This strategy checks whether the clusters resulting from the [order based strategy](#order-based) can change their selected reinforcement to one with cheaper costs. These costs are extracted from the [cost report](koswat_cost_report.md#cost-report) and relate to the reinforcement profile costs (dike's materials for the required space) and the possible [infrastructure costs](koswat_cost_report.md#infrastructure-report). In steps, this strategy can be broke down as: __Steps breakdown__: -1. Assignment of [order based clusters](#order-based-default), +1. Assignment of [order based clusters](#order-based), 2. [Cluster options](#cluster-options) evaluation, 1. [Common available measures](#cluster-common-available-measure-costs) cost calculation, 2. Cheapest option selection, @@ -254,7 +261,7 @@ __Conditions__: - We only create subclusters when the cluster's original size is, at least, twice the required minimal cluster's length. - We estimate the cluster's minimal length to be at least twice the size of the buffer so: `min_cluster_length = (2 * reinforcement_min_buffer) + 1`. -- We create subclusters based on the immediate results of the [order based strategy](#order-based-default). We do not try to combine or create new clusters based on a "greedier" strategy. +- We create subclusters based on the immediate results of the [order based strategy](#order-based). We do not try to combine or create new clusters based on a "greedier" strategy. ##### Cluster option example diff --git a/koswat/cost_report/summary/koswat_summary_builder.py b/koswat/cost_report/summary/koswat_summary_builder.py index 63e654c1..d5caa6bb 100644 --- a/koswat/cost_report/summary/koswat_summary_builder.py +++ b/koswat/cost_report/summary/koswat_summary_builder.py @@ -26,7 +26,9 @@ from koswat.dike_reinforcements.reinforcement_profile.reinforcement_profile_protocol import ( ReinforcementProfileProtocol, ) -from koswat.strategies.order_strategy.order_strategy import OrderStrategy +from koswat.strategies.infra_priority_strategy.infra_priority_strategy import ( + InfraPriorityStrategy, +) from koswat.strategies.strategy_input import StrategyInput from koswat.strategies.strategy_protocol import StrategyProtocol @@ -34,7 +36,9 @@ @dataclass class KoswatSummaryBuilder(BuilderProtocol): run_scenario_settings: KoswatRunScenarioSettings = None - strategy_type: type[StrategyProtocol] = field(default_factory=lambda: OrderStrategy) + strategy_type: type[StrategyProtocol] = field( + default_factory=lambda: InfraPriorityStrategy + ) @staticmethod def _get_corrected_koswat_scenario( diff --git a/koswat/strategies/README.md b/koswat/strategies/README.md index 1e822f87..e1d26fb0 100644 --- a/koswat/strategies/README.md +++ b/koswat/strategies/README.md @@ -37,6 +37,6 @@ This modules contains the logic to choose which measure will be applied for a gi The following strategies are currently available, please refer to the official documentation for a more in-detail explanation of each of them: -- [__Default__] Order based (`OrderBased`). A strategy is chosen based on a dynamically determined order of reinforcements. This order is determined from least to most restrictive, where reinforcements are omitted when they are less restrictive and more expensive than other reinforcement(s). Cofferdam is forced as the last reinforcement of this order. -- Infra-priority based (`InfraPriorityStrategy`). Clusters are created based on the cheapest total cost (including infrastructure reworks). This strategy is applied __after__ _Order based_, the clusters are then modified into a reinforcement that requires less space (thus more expensive) but induce less infrastructure costs, therefore becoming cheaper. We apply this strategy based on sub-clusters, this means that only at a specific contiguous subset of locations the new reinforcement will be applied, therefore optimizing costs. +- Order based (`OrderBased`). A strategy is chosen based on a dynamically determined order of reinforcements. This order is determined from least to most restrictive, where reinforcements are omitted when they are less restrictive and more expensive than other reinforcement(s). Cofferdam is forced as the last reinforcement of this order. +- [__Default__] Infra-priority based (`InfraPriorityStrategy`). Clusters are created based on the cheapest total cost (including infrastructure reworks). This strategy is applied __after__ _Order based_, the clusters are then modified into a reinforcement that requires less space (thus more expensive) but induce less infrastructure costs, therefore becoming cheaper. We apply this strategy based on sub-clusters, this means that only at a specific contiguous subset of locations the new reinforcement will be applied, therefore optimizing costs. diff --git a/tests/cost_report/summary/test_koswat_summary_builder.py b/tests/cost_report/summary/test_koswat_summary_builder.py index 34b6d38d..925a700c 100644 --- a/tests/cost_report/summary/test_koswat_summary_builder.py +++ b/tests/cost_report/summary/test_koswat_summary_builder.py @@ -34,6 +34,9 @@ from koswat.dike_reinforcements.reinforcement_profile.reinforcement_profile_protocol import ( ReinforcementProfileProtocol, ) +from koswat.strategies.infra_priority_strategy.infra_priority_strategy import ( + InfraPriorityStrategy, +) from tests.acceptance_scenarios.koswat_input_profile_base_cases import InputProfileCases from tests.acceptance_scenarios.koswat_scenario_test_cases import ScenarioCases from tests.acceptance_scenarios.layers_cases import LayersCases @@ -44,6 +47,7 @@ def test_initialize(self): _builder = KoswatSummaryBuilder() assert isinstance(_builder, KoswatSummaryBuilder) assert not _builder.run_scenario_settings + assert _builder.strategy_type == InfraPriorityStrategy def test_get_calculated_profile_list(self): # 1. Define test data.