Cost report module

CostReportProtocol

Bases: Protocol

A Protocol defining the properties of a report in Koswat.

Infrastructure cost calculator

ProfileZoneCalculator dataclass

Calculator to determine the width of zones A and B of a reinforced profile (ReinforcementProfileProtocol). It requires its original base profile to be in its definition.

calculate() -> tuple[float, float]

Calculates the width of zones A and B for the defined instance of ReinforcementProfileProtocol. The calculation is as follows: - When dh0 has not varied with respect to the base profile, then zones A and B are calculated. - When dh0 has increased then only zone B is calculated.

Returns:

Type Description
tuple[float, float]

tuple[float, float]: Calculated zone A and B respectively.

ReinforcementProfileProtocol

Bases: KoswatProfileProtocol, Protocol

Extension of the KoswatProfileProtocol to define the properties of a calculated reinforcement.

InfrastructureLocationCosts dataclass

Simple data structure containing the results of the costs calculations for a given ReinforcementProfileProtocol profile. The values related to zone_a and zone_b are calculated in the ProfileZoneCalculator.

InfrastructureProfileCostsCalculator dataclass

Calculator to generate all InfrastructureLocationCosts instances based on the locations of the contained infrastructure (SurroundingsInfrastructure.points) and the width of zone_a and zone_b.

calculate(zone_a_width: float, zone_b_width: float) -> list[InfrastructureLocationCosts]

Calculates the costs affecting this instance's infrastructure at all points where it is present.

Parameters:

Name Type Description Default
zone_a_width float

Width of zone type A.

required
zone_b_width float

Width of zone type `B .

required

Returns:

Type Description
list[InfrastructureLocationCosts]

list[InfrastructureLocationCosts]: Resulting cost summaries.

PointSurroundings dataclass

Object representing a meter with x, y coordinates in a polder (or else).

__eq__(__value: object) -> bool

Overriding of the "magic" equality operator required so that PointSurroundings can be used as a key in a python dict.

__hash__() -> int

Overriding of the "magic" hash operator required so that PointSurroundings can be used as a key in a python dict.

closest_obstacle: float property

Distance to the closest (obstacle) surrounding. When no surroundings are given the value will be NaN (Not A Number), so that the value 0 is reserved for buildings at distance 0.

Returns:

Name Type Description
float float

Distance to the closest surrounding.

get_total_infrastructure_per_zone(*zone_limit_collection: tuple[float, float]) -> list[float]

Gets the total infrastructure width at each of the provided zones zone_limit_collection (tuple[float, float]). The zone limits are matched by rounding up their upper limit to the surroundings_matrix keys (distances to the location in the real world). When two zones have overlapping limits (as expected) the lower one will "claim" the corresponding surrounding distance.

Example
  • zone_limit_collection = (0, 4), (4, 11)
  • surroundings_matrix = {5: 1.5, 10: 3, 15: 6}
  • "Taken" distances per zone:
    • (0, 4) takes key 5.
    • (4, 11) takes key(s) 10 and 15 because 5 was already taken.
  • Total infrastructure width at zones = (1.5, 9)

Returns:

Type Description
list[float]

list[float]: list with total width corresponding to each provided zone.

SurroundingsInfrastructure dataclass

Bases: KoswatSurroundingsProtocol

Defines surroundings point collections that can be repaired or replaced.

The PointSurroundings contain a matrix (dictionary) where the keys represent the distances to an obstacle, and the values a float representing how long that infrastructure is.

InfrastructureProfileCostsCalculator dataclass

Calculator to generate all InfrastructureLocationCosts instances based on the locations of the contained infrastructure (SurroundingsInfrastructure.points) and the width of zone_a and zone_b.

calculate(zone_a_width: float, zone_b_width: float) -> list[InfrastructureLocationCosts]

Calculates the costs affecting this instance's infrastructure at all points where it is present.

Parameters:

Name Type Description Default
zone_a_width float

Width of zone type A.

required
zone_b_width float

Width of zone type `B .

required

Returns:

Type Description
list[InfrastructureLocationCosts]

list[InfrastructureLocationCosts]: Resulting cost summaries.

MultiInfrastructureProfileCostsCalculator dataclass

Calculator that contains all possible "infrastructure" calculators (InfrastructureProfileCostsCalculator) one for each of the available infrastructures in the current KoswatScenario. Its calculate method only requires a reinforcement (ReinforcementProfileProtocol) to determine all infrastructures' costs.

calculate(reinforced_profile: ReinforcementProfileProtocol) -> list[InfrastructureLocationProfileCostReport]

Calculates the costs related to appyling the provided reinforcement_profile at all the locations where an infrastructure is present. It first determines zone A and B and then provides their widths to the inner infrastructure calculators (InfrastructureProfileCostsCalculator).

Parameters:

Name Type Description Default
reinforced_profile ReinforcementProfileProtocol

Reinforcement to be applied.

required

Returns:

Type Description
list[InfrastructureLocationProfileCostReport]

list[InfrastructureLocationProfileCostReport]: Collection of reports summarizing the cost-impact of a reinforced_profile.

ProfileZoneCalculator dataclass

Calculator to determine the width of zones A and B of a reinforced profile (ReinforcementProfileProtocol). It requires its original base profile to be in its definition.

calculate() -> tuple[float, float]

Calculates the width of zones A and B for the defined instance of ReinforcementProfileProtocol. The calculation is as follows: - When dh0 has not varied with respect to the base profile, then zones A and B are calculated. - When dh0 has increased then only zone B is calculated.

Returns:

Type Description
tuple[float, float]

tuple[float, float]: Calculated zone A and B respectively.

ReinforcementProfileProtocol

Bases: KoswatProfileProtocol, Protocol

Extension of the KoswatProfileProtocol to define the properties of a calculated reinforcement.

BuilderProtocol

Bases: Protocol

build() -> Any

Instantiates a concrete object to separate its initalization from the data structure.

Returns:

Name Type Description
Any Any

Intance of a created object within Koswat domain.

InfrastructureProfileCostsCalculator dataclass

Calculator to generate all InfrastructureLocationCosts instances based on the locations of the contained infrastructure (SurroundingsInfrastructure.points) and the width of zone_a and zone_b.

calculate(zone_a_width: float, zone_b_width: float) -> list[InfrastructureLocationCosts]

Calculates the costs affecting this instance's infrastructure at all points where it is present.

Parameters:

Name Type Description Default
zone_a_width float

Width of zone type A.

required
zone_b_width float

Width of zone type `B .

required

Returns:

Type Description
list[InfrastructureLocationCosts]

list[InfrastructureLocationCosts]: Resulting cost summaries.

MultiInfrastructureProfileCostsCalculator dataclass

Calculator that contains all possible "infrastructure" calculators (InfrastructureProfileCostsCalculator) one for each of the available infrastructures in the current KoswatScenario. Its calculate method only requires a reinforcement (ReinforcementProfileProtocol) to determine all infrastructures' costs.

calculate(reinforced_profile: ReinforcementProfileProtocol) -> list[InfrastructureLocationProfileCostReport]

Calculates the costs related to appyling the provided reinforcement_profile at all the locations where an infrastructure is present. It first determines zone A and B and then provides their widths to the inner infrastructure calculators (InfrastructureProfileCostsCalculator).

Parameters:

Name Type Description Default
reinforced_profile ReinforcementProfileProtocol

Reinforcement to be applied.

required

Returns:

Type Description
list[InfrastructureLocationProfileCostReport]

list[InfrastructureLocationProfileCostReport]: Collection of reports summarizing the cost-impact of a reinforced_profile.

MultiInfrastructureProfileCostsCalculatorBuilder dataclass

Bases: BuilderProtocol

Builder to set up "fix" information such as costs derived from the koswat settings (InfraCostsEnum, SurtaxFactorEnum) which directly determines the zone A and/or B costs that will be applied for each infrastructure.

SurroundingsInfrastructure dataclass

Bases: KoswatSurroundingsProtocol

Defines surroundings point collections that can be repaired or replaced.

The PointSurroundings contain a matrix (dictionary) where the keys represent the distances to an obstacle, and the values a float representing how long that infrastructure is.

Quantity cost parameters calculator

CostParameterProtocol

Bases: Protocol

total_cost: float property

The total cost (quantity * unit cost)

total_cost_with_surtax: float property

The total cost including surtaxes

IO

Summary

KoswatExporterProtocol

Bases: Protocol

export(**kwargs) -> None

Exports an object model into a concrete file format.

KoswatSummary dataclass

get_infrastructure_costs() -> dict[type[ReinforcementProfileProtocol], tuple[float, float]]

Gets the infrastructure costs for each profile type for those locations for which the profile type is selected.

Returns:

Type Description
dict[type[ReinforcementProfileProtocol], tuple[float, float]]

dict[type[ReinforcementProfileProtocol], tuple[float, float]]: infrastructure costs without and with surtax per reinforcement type.

get_report_by_profile(profile_type: type[ReinforcementProfileProtocol]) -> MultiLocationProfileCostReport | None

Get the report for a specific profile type.

Parameters:

Name Type Description Default
profile_type type[ReinforcementProfileProtocol]

Type of reinforcement profile.

required

Returns:

Type Description
MultiLocationProfileCostReport | None

MultiLocationProfileCostReport | None: Report for the profile type.

Summary costs

KoswatExporterProtocol

Bases: Protocol

export(**kwargs) -> None

Exports an object model into a concrete file format.

KoswatSummary dataclass

get_infrastructure_costs() -> dict[type[ReinforcementProfileProtocol], tuple[float, float]]

Gets the infrastructure costs for each profile type for those locations for which the profile type is selected.

Returns:

Type Description
dict[type[ReinforcementProfileProtocol], tuple[float, float]]

dict[type[ReinforcementProfileProtocol], tuple[float, float]]: infrastructure costs without and with surtax per reinforcement type.

get_report_by_profile(profile_type: type[ReinforcementProfileProtocol]) -> MultiLocationProfileCostReport | None

Get the report for a specific profile type.

Parameters:

Name Type Description Default
profile_type type[ReinforcementProfileProtocol]

Type of reinforcement profile.

required

Returns:

Type Description
MultiLocationProfileCostReport | None

MultiLocationProfileCostReport | None: Report for the profile type.

BuilderProtocol

Bases: Protocol

build() -> Any

Instantiates a concrete object to separate its initalization from the data structure.

Returns:

Name Type Description
Any Any

Intance of a created object within Koswat domain.

CostParameterProtocol

Bases: Protocol

total_cost: float property

The total cost (quantity * unit cost)

total_cost_with_surtax: float property

The total cost including surtaxes

KoswatSummary dataclass

get_infrastructure_costs() -> dict[type[ReinforcementProfileProtocol], tuple[float, float]]

Gets the infrastructure costs for each profile type for those locations for which the profile type is selected.

Returns:

Type Description
dict[type[ReinforcementProfileProtocol], tuple[float, float]]

dict[type[ReinforcementProfileProtocol], tuple[float, float]]: infrastructure costs without and with surtax per reinforcement type.

get_report_by_profile(profile_type: type[ReinforcementProfileProtocol]) -> MultiLocationProfileCostReport | None

Get the report for a specific profile type.

Parameters:

Name Type Description Default
profile_type type[ReinforcementProfileProtocol]

Type of reinforcement profile.

required

Returns:

Type Description
MultiLocationProfileCostReport | None

MultiLocationProfileCostReport | None: Report for the profile type.

ReinforcementProfileProtocol

Bases: KoswatProfileProtocol, Protocol

Extension of the KoswatProfileProtocol to define the properties of a calculated reinforcement.

Summary infrastructure costs

KoswatExporterProtocol

Bases: Protocol

export(**kwargs) -> None

Exports an object model into a concrete file format.

KoswatSummary dataclass

get_infrastructure_costs() -> dict[type[ReinforcementProfileProtocol], tuple[float, float]]

Gets the infrastructure costs for each profile type for those locations for which the profile type is selected.

Returns:

Type Description
dict[type[ReinforcementProfileProtocol], tuple[float, float]]

dict[type[ReinforcementProfileProtocol], tuple[float, float]]: infrastructure costs without and with surtax per reinforcement type.

get_report_by_profile(profile_type: type[ReinforcementProfileProtocol]) -> MultiLocationProfileCostReport | None

Get the report for a specific profile type.

Parameters:

Name Type Description Default
profile_type type[ReinforcementProfileProtocol]

Type of reinforcement profile.

required

Returns:

Type Description
MultiLocationProfileCostReport | None

MultiLocationProfileCostReport | None: Report for the profile type.

SummaryInfrastructureCostsCsvFomBuilder dataclass

BuilderProtocol

Bases: Protocol

build() -> Any

Instantiates a concrete object to separate its initalization from the data structure.

Returns:

Name Type Description
Any Any

Intance of a created object within Koswat domain.

InfrastructureLocationCosts dataclass

Simple data structure containing the results of the costs calculations for a given ReinforcementProfileProtocol profile. The values related to zone_a and zone_b are calculated in the ProfileZoneCalculator.

KoswatSummary dataclass

get_infrastructure_costs() -> dict[type[ReinforcementProfileProtocol], tuple[float, float]]

Gets the infrastructure costs for each profile type for those locations for which the profile type is selected.

Returns:

Type Description
dict[type[ReinforcementProfileProtocol], tuple[float, float]]

dict[type[ReinforcementProfileProtocol], tuple[float, float]]: infrastructure costs without and with surtax per reinforcement type.

get_report_by_profile(profile_type: type[ReinforcementProfileProtocol]) -> MultiLocationProfileCostReport | None

Get the report for a specific profile type.

Parameters:

Name Type Description Default
profile_type type[ReinforcementProfileProtocol]

Type of reinforcement profile.

required

Returns:

Type Description
MultiLocationProfileCostReport | None

MultiLocationProfileCostReport | None: Report for the profile type.

MultiLocationProfileCostReport dataclass

Bases: CostReportProtocol

get_infra_costs_per_location() -> dict[PointSurroundings, tuple[float, float]]

Gets the total costs related to infrastructures at each of the points for the profile type in profile_cost_report

Returns:

Type Description
dict[PointSurroundings, tuple[float, float]]

dict[PointSurroundings, tuple[float, float]]: Total cost per location (without and with surtax).

total_cost: float property

Calculates the cost of the measure for all possible locations, regardless whether that measure is chosen by the order strategy or not.

PointSurroundings dataclass

Object representing a meter with x, y coordinates in a polder (or else).

__eq__(__value: object) -> bool

Overriding of the "magic" equality operator required so that PointSurroundings can be used as a key in a python dict.

__hash__() -> int

Overriding of the "magic" hash operator required so that PointSurroundings can be used as a key in a python dict.

closest_obstacle: float property

Distance to the closest (obstacle) surrounding. When no surroundings are given the value will be NaN (Not A Number), so that the value 0 is reserved for buildings at distance 0.

Returns:

Name Type Description
float float

Distance to the closest surrounding.

get_total_infrastructure_per_zone(*zone_limit_collection: tuple[float, float]) -> list[float]

Gets the total infrastructure width at each of the provided zones zone_limit_collection (tuple[float, float]). The zone limits are matched by rounding up their upper limit to the surroundings_matrix keys (distances to the location in the real world). When two zones have overlapping limits (as expected) the lower one will "claim" the corresponding surrounding distance.

Example
  • zone_limit_collection = (0, 4), (4, 11)
  • surroundings_matrix = {5: 1.5, 10: 3, 15: 6}
  • "Taken" distances per zone:
    • (0, 4) takes key 5.
    • (4, 11) takes key(s) 10 and 15 because 5 was already taken.
  • Total infrastructure width at zones = (1.5, 9)

Returns:

Type Description
list[float]

list[float]: list with total width corresponding to each provided zone.

StrategyLocationReinforcement dataclass

get_infrastructure_costs(reinforcement_type: type[ReinforcementProfileProtocol]) -> tuple[float, float]

Returns the infrastructure costs for the given reinforcement type (without and with surtax).

Parameters:

Name Type Description Default
reinforcement_type type[ReinforcementProfileProtocol]

Reinforcement type.

required

Returns:

Type Description
tuple[float, float]

tuple[float, float]: Tuple containing the infrastructure costs without and with surtax.

SummaryInfrastructureCostsCsvFomBuilder dataclass

Summary locations

KoswatExporterProtocol

Bases: Protocol

export(**kwargs) -> None

Exports an object model into a concrete file format.

KoswatSummary dataclass

get_infrastructure_costs() -> dict[type[ReinforcementProfileProtocol], tuple[float, float]]

Gets the infrastructure costs for each profile type for those locations for which the profile type is selected.

Returns:

Type Description
dict[type[ReinforcementProfileProtocol], tuple[float, float]]

dict[type[ReinforcementProfileProtocol], tuple[float, float]]: infrastructure costs without and with surtax per reinforcement type.

get_report_by_profile(profile_type: type[ReinforcementProfileProtocol]) -> MultiLocationProfileCostReport | None

Get the report for a specific profile type.

Parameters:

Name Type Description Default
profile_type type[ReinforcementProfileProtocol]

Type of reinforcement profile.

required

Returns:

Type Description
MultiLocationProfileCostReport | None

MultiLocationProfileCostReport | None: Report for the profile type.

BuilderProtocol

Bases: Protocol

build() -> Any

Instantiates a concrete object to separate its initalization from the data structure.

Returns:

Name Type Description
Any Any

Intance of a created object within Koswat domain.

KoswatSummary dataclass

get_infrastructure_costs() -> dict[type[ReinforcementProfileProtocol], tuple[float, float]]

Gets the infrastructure costs for each profile type for those locations for which the profile type is selected.

Returns:

Type Description
dict[type[ReinforcementProfileProtocol], tuple[float, float]]

dict[type[ReinforcementProfileProtocol], tuple[float, float]]: infrastructure costs without and with surtax per reinforcement type.

get_report_by_profile(profile_type: type[ReinforcementProfileProtocol]) -> MultiLocationProfileCostReport | None

Get the report for a specific profile type.

Parameters:

Name Type Description Default
profile_type type[ReinforcementProfileProtocol]

Type of reinforcement profile.

required

Returns:

Type Description
MultiLocationProfileCostReport | None

MultiLocationProfileCostReport | None: Report for the profile type.

PointSurroundings dataclass

Object representing a meter with x, y coordinates in a polder (or else).

__eq__(__value: object) -> bool

Overriding of the "magic" equality operator required so that PointSurroundings can be used as a key in a python dict.

__hash__() -> int

Overriding of the "magic" hash operator required so that PointSurroundings can be used as a key in a python dict.

closest_obstacle: float property

Distance to the closest (obstacle) surrounding. When no surroundings are given the value will be NaN (Not A Number), so that the value 0 is reserved for buildings at distance 0.

Returns:

Name Type Description
float float

Distance to the closest surrounding.

get_total_infrastructure_per_zone(*zone_limit_collection: tuple[float, float]) -> list[float]

Gets the total infrastructure width at each of the provided zones zone_limit_collection (tuple[float, float]). The zone limits are matched by rounding up their upper limit to the surroundings_matrix keys (distances to the location in the real world). When two zones have overlapping limits (as expected) the lower one will "claim" the corresponding surrounding distance.

Example
  • zone_limit_collection = (0, 4), (4, 11)
  • surroundings_matrix = {5: 1.5, 10: 3, 15: 6}
  • "Taken" distances per zone:
    • (0, 4) takes key 5.
    • (4, 11) takes key(s) 10 and 15 because 5 was already taken.
  • Total infrastructure width at zones = (1.5, 9)

Returns:

Type Description
list[float]

list[float]: list with total width corresponding to each provided zone.

ReinforcementProfileProtocol

Bases: KoswatProfileProtocol, Protocol

Extension of the KoswatProfileProtocol to define the properties of a calculated reinforcement.

StrategyLocationReinforcement dataclass

get_infrastructure_costs(reinforcement_type: type[ReinforcementProfileProtocol]) -> tuple[float, float]

Returns the infrastructure costs for the given reinforcement type (without and with surtax).

Parameters:

Name Type Description Default
reinforcement_type type[ReinforcementProfileProtocol]

Reinforcement type.

required

Returns:

Type Description
tuple[float, float]

tuple[float, float]: Tuple containing the infrastructure costs without and with surtax.