business.gravity package

Design and check projects of water supplies fed by gravity.

Classes

  • GravityCheck:

    models the ‘hydraulic check problem’ for a ‘gravity’ water supply.

  • GravityDesign:

    models the ‘hydraulic design problem’ for a ‘gravity’ water supply.

Submodules

business.gravity.constants module

Collection of constants used by the gravity foldes.

business.gravity.constants.RANDOM_SEARCH_RANGE_PAD = <Quantity(25, 'meter')>

Prescribes the minimal hydraulic energy to be burned along a Trunk during gravity tree random search. This value magnitude is expected to be an integer.

business.gravity.coroutines module

Find an optimal solution to the ‘hydraulic design problem’.

Functionality: Perform the systematic search of the optimal values of hydarulic energy at all junctions internal to a rpessure zone.

class business.gravity.coroutines.AccumulatorDuringRange

Bases: business.helpers.utils.TypedSet

Collection of solutions of the ‘hydraulic design problem’ within the subtree.

Functionality: accumulate the feasible solutions (while the ‘systmatic search’ algorithm runs) of the ‘hydraulic design problem’ so to allow, once the systematic search algorith ends, to collect the one with the least economic cost.

Notes

Extends a strongly typed set.

property best_during_range
class business.gravity.coroutines.CoroutineLeaf(trunk: business.gravity.trunks.TrunkDesign, name: str, down_elev: int)

Bases: business.gravity.coroutines.CoroutineMixin

Represent a root where the coroutine process ends (and starts sending data back towards the root)

There is one instance for each TrunkDesign whose ‘head’ end is atmospheric.

merger()

Return the optimal solution for this trunk

down_elev: int
merger() → business.gravity.coroutines.CurrentSimplexesList

Advance the coroutine pipeline and return the optimal solution at the current energy constraints.

Yields

CurrentSimplexesList – the result from linear optimization of the trunk

name: str
send(arg)
trunk: business.gravity.trunks.TrunkDesign
class business.gravity.coroutines.CoroutineMixin

Bases: business.commons.loggers.InitLoggerMixin

Algorithms common to CoroutineRoot, CoroutineNode and CoroutineLeaf.

class business.gravity.coroutines.CoroutineNode(trunk: business.gravity.trunks.TrunkDesign, name: str, down_flight: int, adj_list: Any)

Bases: business.gravity.coroutines.CoroutineMixin

Represent a pathway where the coroutine process is executed.

There is one instance for each TrunkDesign which is ‘internal’ of a PressureZone. More specifically: neither the trunk ‘tail’ nor the ‘head’ are atmospheric.

merger()

Return the optimal solution for this trunk and its children

adj_list: Any
down_flight: int
merger() → business.gravity.coroutines.CurrentSimplexesList

Advance the coroutine pipeline and return the optimal solution at the current energy constraints.

Yields

CurrentSimplexesList – the best result from linear optimization of the trunk and all of its children trunks belonging to the pressure zone.

name: str
send(arg)
trunk: business.gravity.trunks.TrunkDesign
class business.gravity.coroutines.CoroutineRoot(trunk: business.gravity.trunks.TrunkDesign, name: str, up_elev: int, down_flight: int, adj_list: Any)

Bases: business.gravity.coroutines.CoroutineMixin

Represent a root where the coroutine process starts from.

There is one instance for each TrunkDesign which is a root of a PressureZone.

merger()

Return the optimal solution for the pressure zone

adj_list: Any
down_flight: int
merger() → business.gravity.coroutines.CurrentSimplexesList

Return the optimal solution.

Returns

the list of namedtuples that describe the optimal solution for each trunk in the entire pressure zone

Return type

CurrentSimplexesList

name: str
trunk: business.gravity.trunks.TrunkDesign
up_elev: int
class business.gravity.coroutines.CurrentSimplexesList(iterable: List = [])

Bases: business.helpers.utils.TypedList

Accumulator

property get_my_cost
property is_failed

business.gravity.exceptions module

Collection of exceptions raised by ‘gravity’ folder.

exception business.gravity.exceptions.AllCommercialPipesAreUnsuitableForSimplex(message, desired_flow, required_rating)

Bases: business.manufacturers.exceptions.pipes.AllCommercialPipesAreUnsuitableSpeedwise, business.gravity.exceptions.OpenEndsTrunkEdgeCase, business.gravity.exceptions.BaseLinprogFailure

No pipe is suitable to carry the desired _water_flow within the advisable _water_flow speed limits.

Raised by BasePipePool.

exception business.gravity.exceptions.BaseLinprogFailure

Bases: business.commons.exceptions.RuralwaterException

Base exception class when the linear optimization algorithm fails.

Applies to: * Subtrunk * SoilStretch

Occours in situations where there is: (1) flat slope (2) steep slope (3) floating point arithmetic problems (raise from inside the scipy.optimize.linprog library)

Raised if both method=”simplex” and method=”interior-point” fail to find the minimum of the objective function. See “notes” section from page: https://docs.scipy.org/doc/scipy/reference/optimize.linprog-interior-point.html

exception business.gravity.exceptions.FailedSubtreeDesign

Bases: business.commons.exceptions.RuralwaterException

The ‘hydraulic design problem’ of a pressure zone could not be solved.

Raised, for example, by *business.gravity.coroutines.CoroutineRoot when no solution could be found by the coroutine algorithm.

exception business.gravity.exceptions.FlatSlope(message, subnode_headloss_slope, min_pipe_headloss)

Bases: business.gravity.exceptions.SlopeOutsideFeasibleRange

The trunk energy is too little.

Even the largest commercial pipe burns more than the hydraulic energy, at the current water flow.

exception business.gravity.exceptions.LeafNodeDemandDataMissing(message, leaf_missing_demand_data)

Bases: business.commons.exceptions.RuralwaterException

The demand data at some leaf node is missing.

A trunk may have no demand data and just carry water to its children. However, if a trunk is a ‘leaf’ (i.e.: it discarges in a reservoir at the end of the dendridi network) then it must have a demand. Otherwise, is no reason why the Trunk should exists.

Raised when the TrunkDesign._water_flow value is zero after TrunkDesign.set_flow.

exception business.gravity.exceptions.LinprogNumericalIssue

Bases: business.gravity.exceptions.BaseLinprogFailure

Package scipy.optimize.linprog failed performing the linear optimization.

exception business.gravity.exceptions.OpenChannelFlow(message, piped_segments)

Bases: business.commons.exceptions.RuralwaterException

A TrunkDesign shows MOTO A CANALETTA.

exception business.gravity.exceptions.OpenEndsTrunkEdgeCase

Bases: business.commons.exceptions.RuralwaterException

Base class for the exceptions raised by an atmospheric node.

Raised when the HGL gradient is too flat / too steep with resepct to the range of HGL gradients returned by the available pipes. Also, raised when the *MOTO A CANALETTA* occours.

exception business.gravity.exceptions.PressureLimitsExceeded(message, piped_segments)

Bases: business.gravity.exceptions.BaseLinprogFailure

Pipes result in exceeding pressure limits.

Raised for example when the solution of linear programming (simplex) results in pressure exceeding the pipes’ max allowed pressure.

exception business.gravity.exceptions.SlopeOutsideFeasibleRange

Bases: business.gravity.exceptions.BaseLinprogFailure

The constraints of the optimization problem are too stringent.

Raised when the hydraulic energy to be burned off is too high/too low for any of the commercial pipes available from the catalog of hydraulic hardware.

exception business.gravity.exceptions.SteepSlope(message, subnode_headloss_slope, candidate_pipes_headlosses, open_flow_pipe_segments)

Bases: business.gravity.exceptions.SlopeOutsideFeasibleRange

The trunk energy is too little.

Even the smallest commercial pipe burns less than the hydraulic energy, at the current water flow.

If raised by an AtmosphericTrunkDesign, it entails that the trunk shows ‘open channel flow’.

exception business.gravity.exceptions.WaterSystemIsNotATree

Bases: business.commons.exceptions.RuralwaterException

The topology of the water supply system is not a tree.

business.gravity.stretches module

Define the concept of ‘splitting’ a Subtrunk into sections.

class business.gravity.stretches.AtmosphericSubtrunk(_energy_at_tail_point: float, _energy_at_head_point: float, _elevation_profile: business.commons.energy.ElevationProfile, _pressure_limit: pint.quantity.build_quantity_class.<locals>.Quantity, _water_flow: pint.quantity.build_quantity_class.<locals>.Quantity, _pathlength_starts_at: pint.quantity.build_quantity_class.<locals>.Quantity, _requires_metallic_pipes: bool, _trunk_name: str = 'Trunk default name')

Bases: business.gravity.stretches.Subtrunk

A stretch of a Trunk whose ends are both at atmospheric pressure.

property hgl_lies_above_elevation_profile

Overrides parent’s method.

Important

This is an atmospheric TrunkDesign, therefore there are at least two intersections, found at the first and the last point of the _profile. More than two intersection points require the HGL to cross the terrain inside the pathlength. Therefore the HGL intersects the elevation profile.

class business.gravity.stretches.SubstretchMixin

Bases: object

Common ancestro of Subtrunk and SoilStretch.

class business.gravity.stretches.Subtrunk(_energy_at_tail_point: float, _energy_at_head_point: float, _elevation_profile: business.commons.energy.ElevationProfile, _pressure_limit: pint.quantity.build_quantity_class.<locals>.Quantity, _water_flow: pint.quantity.build_quantity_class.<locals>.Quantity, _pathlength_starts_at: pint.quantity.build_quantity_class.<locals>.Quantity, _requires_metallic_pipes: bool, _trunk_name: str = 'Trunk default name')

Bases: business.commons.loggers.InitLoggerMixin, business.commons.mixins.linear.SingleLinprogStretchMixin, business.gravity.mixins.trimming.TrunkStretchTrimmingMixin, business.gravity.stretching.linear.SwapStretchMixin, business.gravity.stretching.crawl.CrawlSolverStretchMixin, business.commons.traversals.PipeDesignPoolMixin, business.gravity.stretching.pressure.PressureStretchMixin, business.gravity.stretching.setters.SettersStretchMixin, business.gravity.stretches.SubstretchMixin

A class to represent a section of DendridicTrunk.

The ‘section’ is where the ‘hydraulic design problem’ is solved. The section has boundary constraints, defined by the hydraulic energy values at its ‘tail’ and ‘head’ ends. The section has a rated working pressure set, and the hydraulic design problem solution must comply with such pressure requirement. The section has the same water flow as the Trunk it belongs to.

A section may correspond to the whole TrunkDesign.

Important

A TrunkDesign’s _elevation_profile list may be sliced and each slice is then used to initialize a Subtrunk.

recursive_linear_solver()

return the economically optimal pipes, using a ‘simpex’ approach

crawl()

return the economically optimal pipes, fit for profiles traversing deep valleys or overbanking ridges

property attempt_crawling

A largest-smallest pipe approach, repeated recursively whenever a solution exceedes the rated pressure limits.

Such approach aims at ‘bending’ the hydraulic energy line and appears to be fit especially for surpassing deep valleys or to overbank ridges between two contiguous vallyes.

Return the optimal pipes by investigating recursively whenever the pressure limits are exceeded by solution obtained during the recursive process.

Returns

Return type

TODO

property pathlength

Return the linar pathlength of the stretch.

Returns

the linear length of the profile pertaining to this section.

Return type

Quantity(“length”)

property recursive_linear_solver

A linear optimization approach, repeated recursively whenever a solution exceedes the rated pressure limits.

Return the optimal pipes by investigating recursively whenever the pressure limits are exceeded by solution obtained during the recursive process.

Returns

Return type

TODO

property xxx_repr

business.gravity.trunks module

class business.gravity.trunks.AtmosphericTrunkCheck(**kwargs)

Bases: business.gravity.trunks.TrunkCheck, business.gravity.trunks.AtmosphericTrunkMixin

A TrunkCheck, with both ends at atmospheric pressure.

Functionality: a Trunk, with both ends at atmospheric pressure, modelled to solve the ‘hydarulic check problem’.

Notes

This is the case of a Trunk connecting directly two reservoirs, or a spring to a reservoir.

class business.gravity.trunks.AtmosphericTrunkDesign(**kwargs)

Bases: business.gravity.trunks.AtmosphericTrunkMixin, business.gravity.trunking.traversals.AtmosphericTraversalTrunkMixin, business.gravity.trunks.TrunkDesign

A TrunkDesign, with both ends at atmospheric pressure.

Functionality: a Trunk, with both ends at atmospheric pressure, modelled to solve the ‘hydarulic design problem’.

Notes

This is the case of a Trunk connecting directly two reservoirs, or a spring to a reservoir.

property as_subtrunk

Return a Subtrunk spanning the entire AtmosphericTrunkDesign.

The subnode._pressure_limit is the lowest available from the catalog of pipes.

Important

Used to create a Subtrunk that covers the entire _elevation_profile of this node. This is necessary when starting the get_traversal_solution method. The subnode._pressure_limit is the lowest available since the atmospheric node entails to use the lowest possible pressure.

Returns

the atmospheric stretch whose profile is the entire profile sequence of this atmospheric Trunk.

Return type

AtmosphericSubtrunk

property get_open_channel_hgl_profile

Return an EnergyProfile raised from the altrimetric profile by one meter.

Its is used to render graphically the idea of ‘open flow’

class business.gravity.trunks.AtmosphericTrunkMixin

Bases: object

Hook for a common ancestor to AtmosphericTrunkCheck and AtmosphericTrunkDesign.

class business.gravity.trunks.BaseTrunk(**kwargs)

Bases: business.commons.watermains.Watermain

Ancestor of TrunkCheck and TrunkDesign.

Functionality: define the mathematical properties of the node of a tree. The BaseTrunk is ancestor of all trunks belonging to a gravity water supply.

Note

  • The gravity water supply is modelled as a dendridic network; each node

of this network is a BaseTrunk (or child). * The Trunk is a pipeline along which the water flow is constant. * The Trunks is composed of a sequence of different diameters, pipe materials and pipe pressure specifications.

class business.gravity.trunks.TrunkCheck(**kwargs)

Bases: business.commons.watermains.WatermainCheck, business.gravity.trunks.BaseTrunk

A BaseTrunk, modelled to solve the ‘hydarulic check problem’.

Functionality: define the properties required to solve the ‘hydarulic check problem’ of a gravity-fed dendridic water supply.

property get_hydraulic_friction_per_unit_waterflow

Return the hydraulic energy burned off along the Trunk for a unitary water flow.

The hydraulic friction is dimensionless: it represents meters of energy loss per meters of pipe length; it is a percentage.

Returns

the energy burned off by friction along the whole length of the Trunk, for a water flow of magnitude ‘1’ and units defined by the pacakge constants.

Return type

float

property water_flow

Set the water flow in the Trunk, in its piped segments and pipes.

Functionality: once the ‘hydraulic check problem’ is solved, the code sets the resulting ‘water flow’ in each trunk of the gravity pipeline. This mutator allows to set such value of the water flow in each of the pipes, so that it will then be possible to plot the hydraulic energy profile with the correct water flow.

class business.gravity.trunks.TrunkDesign(**kwargs)

Bases: business.gravity.trunking.setters.TrunkDesignSettersMixin, business.gravity.trunking.traversals.TraversalsTrunkDesignMixin, business.commons.watermains.WatermainDesign, business.commons.traversals.PipeDesignPoolMixin, business.gravity.trunks.BaseTrunk

A BaseTrunk, modelled to solve the hydarulic design problem.

property as_subtrunk

Return a ‘stretch’ which stretches along the entire length of this Trunk.

Returns

the stretch whose profile is the entire profile sequence of this Trunk.

Return type

Subtrunk

property get_my_water_demand_as_steady_flow

Return the water flow required by the ‘hydraulic design problem’.

Return the steady flow, flowing continuously along the 24 hours of the day, which satisfies the water demand associated with the Trunk.