business.commons package¶

business.commons.no_piped_segments = <business.commons.definitions.NoPipedSegments object>¶: Prescribes the handle to the singleton of ‘spurious piped segment’ when the linear optimization algorithm fails to find a solution.

business.commons.simplex_failure_list = SimplexFailure¶: Prescribes the handle to the singleton of ‘list of spurious piped segments’ when the linear optimization algorithm fails to find a solution. It may be due to either a numerical issue or to ‘flat’ or ‘steep’ profile. See SlopeOutsideFeasibleRange.

Subpackages¶

business.commons.mixins package

Submodules¶

business.commons.TODO_settings module¶

business.commons.adapters module¶

Provide the adapters reading altimetric data from external files.

class business.commons.adapters.AltimeterFileAdapter(fullpath)¶

Bases: object

Adapter from field surveys carried with ‘rope and barometric altimeter’

cleaned_data¶: return the csv data, packed in ElevationProfilePoint namedtuples

property cleaned_data¶

Return the elevation profile as a tuple of points.

Each point bears dimensional data.

Returns: the elevation profile, each point packed in a namedtuple.
Return type: Tuple[ElevationProfilePoint]

class business.commons.adapters.CacheCsvRows(*args, **kwargs)¶

Bases: dict

A dictionary that caches the data returned by a csv reader.

Functionality: cache for csv reader, when data must be iterated over multiple times.

The keys are the paths (strings) to the csv files. When a key is missing, this dictionary reads and stores the csv file rows. When a key is present, this dictionary returns the csv rows.

This class is used to read a csv file once and then to be able to iterate over the rows multiple times without reading again the source file. It is used when an adapter iterates multiple times over the rows, once for data cleaning, then for adapting the data into a required format.

Important

It inherits from dict directly because we are changing functionality that’s limited to a single method.

class business.commons.adapters.LevelrodFileAdapter(_fullpath: str)¶

Bases: business.commons.loggers.InitLoggerMixin

Adapter from field surveys carried with the ‘level rod’.

Open, read and validate data from the file describing the field readings taken from a level rod survey.

Parameters: fullpath (str) – the full path to the external source which contains the data.

class TurningPointReading(back_low: int, back_mid: int, back_high: int, fore_low: int, fore_mid: int, fore_high: int, remarks: any)¶

Bases: business.commons.loggers.InitLoggerMixin

A dataclass record to represent one levelrod reading.

back_high: int¶

back_low: int¶

back_mid: int¶

fore_high: int¶

fore_low: int¶

fore_mid: int¶

remarks: any¶

property cleaned_data¶

Return the elevation profile as a tuple of points.

Each point bears dimensional data. The values of each point (downrange, elevation, pathlength) are evaluated according to levelrod trigonometry. Refer to textbooks for the theory.

Returns: the elevation profile, each point packed in a namedtuple.
Return type: Tuple[ElevationProfilePoint]

class business.commons.adapters.MapQuestApiAdapter(fullpath)¶

Bases: business.commons.adapters.TrustedRawAltimetricFileAdapter

Adapter from MapQuest api service (https://www.mapquest.com/)

Important

There is no need to clean the data: they are provided by an external service (MapQuest) and are therefore assumed to be correct.

class business.commons.adapters.TrustedRawAltimetricFileAdapter(fullpath)¶

Bases: object

Adapter from a ‘trusted’ source: no data cleaning performed.

cleaned_data¶: return the csv data, packed in ElevationProfilePoint namedtuples

property cleaned_data¶

Return the elevation profile as a tuple of points.

Each point bears dimensional data.

Returns: the elevation profile, each point packed in a namedtuple.
Return type: Tuple[ElevationProfilePoint]

class business.commons.adapters.UntrustedRawAltimetricFileAdapter(fullpath)¶

Bases: business.commons.adapters.TrustedRawAltimetricFileAdapter

Adapter from an ‘untrusted’ source: data cleaning is provided.

property cleaned_data¶: Return the elevation profile as a tuple of points. Each point bears dimensional data.

business.commons.constants module¶

Collection of constants used by gravity and pumpstation folders.

business.commons.constants.FLOW_EXPONENT = 2¶: Prescribes the exponents used in the Darcy-Weisbach hydraulic friction formulae.

business.commons.constants.MIN_TO_MAX_WIGGLE_DEMAND_PERCENT = 0.6¶: Prescribes a default ration between forecasted demand and a minimal acceptable demand.

business.commons.coroutines module¶

Avoid running useless heavy computations.

class business.commons.coroutines.CoroutineMinima(*args, **kwargs)¶

Bases: collections.defaultdict, business.commons.loggers.InitLogger

Cache to store the best result so far in a systematic seach process.

Functionality: store the best result so far in a systematic search optimization process.

When the coroutines perform a systematic search process aiming at optimizing the design of a rural system, the penalty of each solution may be compared with the ‘best minimum so far’ available from this class. If the best minimum is exceeded, then the coroutine may skip calculations. INGLESE, QUESTA E’ UNA FRASE CHE NON SO COME SCRIVERE.

store(root_slug, candidate_minimum)¶

Set the value for a given key.

Parameters

root_slug (str) – the key where to set the value
candidate_minimum (decimal.Decimal) – the value to be set.

business.commons.defaults module¶

Collection of default input values used by gravity and pumpstation folders.

business.commons.defaults.design_years = 20¶: Prescribes the default number of years to evaluate the forecasted demand.

business.commons.defaults.population_growth_rate = 0.15¶: Prescribes the default demographic growth to evaluate the forecasted demand.

business.commons.definitions module¶

Provide definitions used when solving the ‘hydraulic design problem’.

class business.commons.definitions.CheckCalculationsReport(check_is_completed: bool = None, check_solution: business.commons.definitions.CheckSolution = None, errors: dict = None)¶

Bases: object

check_is_completed: bool = None¶

check_solution: business.commons.definitions.CheckSolution = None¶

errors: dict = None¶

class business.commons.definitions.CheckSolution(status: Any = None)¶

Bases: tuple

Store the report from the hydraulic check problem calculations..

property status¶: Alias for field number 0

class business.commons.definitions.DesignCalculationsReport(design_is_successful: bool = None, optimized_solution: Set[business.commons.definitions.TraversalSolution] = None, errors: dict = None)¶

Bases: object

design_is_successful: bool = None¶

errors: dict = None¶

optimized_solution: Set[business.commons.definitions.TraversalSolution] = None¶

class business.commons.definitions.DesignSolution(cost_per_beneficiary: decimal.Decimal = Decimal('0'), cost_per_liter: decimal.Decimal = Decimal('0'), design_details: Any = None, errors: Any = None, investment_cost: decimal.Decimal = Decimal('0'), running_cost: decimal.Decimal = Decimal('0'), water_flow: pint.quantity.build_quantity_class.<locals>.Quantity = None)¶

Bases: tuple

Store the report from the ‘hydraulic design problem’ calculations..

property cost_per_beneficiary¶: Alias for field number 0

property cost_per_liter¶: Alias for field number 1

property design_details¶: Alias for field number 2

property errors¶: Alias for field number 3

property investment_cost¶: Alias for field number 4

property running_cost¶: Alias for field number 5

property water_flow¶: Alias for field number 6

class business.commons.definitions.NoPipedSegments(*args, **kwargs)¶

Bases: object

An empty iterable.

Functionality: interpreted by calling code as ‘no solution found by the simplex algorithm’

Notes

Implements an Iterable because the simplex solution is iterable.

class business.commons.definitions.SimplexFailureList(*args, **kwargs)¶

Bases: object

A spurious sequence of PipedSegments.

Functionaity: it means that the simplex design algorithm could not find a solution.

Notes

Returned by returned by SingleLinprogStretchMixin. SingleLinprogStretchMixin is in charge of solving a linear problem. However, if a solution cannot be found, it returns this class so to comply with the interface returned when a solution is found. INGLESE DA MIGLIORARE

piped_segment = <business.commons.definitions.NoPipedSegments object>¶

class business.commons.definitions.TraversalSolution(energy_at_tail_point: pint.quantity.build_quantity_class.<locals>.Quantity = None, energy_at_head_point: pint.quantity.build_quantity_class.<locals>.Quantity = None, is_failed: bool = None, penalty: decimal.Decimal = Decimal('0'), piped_segments: Tuple[business.helpers.definitions.PipedSegment] = (), trunk: Any = None, water_flow: pint.quantity.build_quantity_class.<locals>.Quantity = None)¶

Bases: tuple

Store the result of CoroutineMixin.solve_traversal.

property energy_at_head_point¶: Alias for field number 1

property energy_at_tail_point¶: Alias for field number 0

property is_failed¶: Alias for field number 2

property penalty¶: Alias for field number 3

property piped_segments¶: Alias for field number 4

property trunk¶: Alias for field number 5

property water_flow¶: Alias for field number 6

business.commons.energy module¶

Collection of classes used to represent the ‘hydraulic grade line’.

classes

EnergyProfilePoint: A point belonging to the water energy line along a pipe trench.
ElevationProfilePoint: A point belonging to altimetric elevation profile along a pipe trench.
BaseEnergyProfileMixin: A base class for other classes which bear the name ‘profile’.
ElevationProfile: The altimetric elevation profile along a pipe trench.
EnergyProfile: The profile of the hydraulic energy line along a pipe trench.

class business.commons.energy.BaseEnergyProfileMixin¶

Bases: business.commons.energy.PlotBaseEnergyProfileMixin

A mixin class gathering methods used to do geometric calculations.

downrange()¶: Return the horizontal span of the hydraulic energy line.

pathlength()¶: Return the linear length of the hydraulic energy line.

translate_vertically(vertical_shift=Quantity('length'))¶: Shift vertically the energy line by vertical_shift

get_unique_intersection_with(other: BaseEnergyProfileMixin)¶: Return the unique intersection point with another energy line

get_tailmost_intersection_with(other: BaseEnergyProfileMixin)¶: Return the first intersection point with another energy line

get_headmost_intersection_with(other: BaseEnergyProfileMixin)¶: Return the last intersection point with another energy line

as_linestring()¶: Return the energy line represented as a Shapely LineString object

intersects_with()¶: Boolean test checking if two energy lines do intersect or not

get_section_inbetween_downranges(from_downrange, until_downrange: Quantity(‘length’))¶: Create a new energy line by slicing the current one among given ends

property as_linestring¶

Return this instance as a shapely linestring object.

The Shapely LineString instance generated will have the same coordinates as those of ElevationProfilePoint’s which constitute this energy line.

The linestring is a collection of adimensional 2-tuples. You may feed matplotlib ‘plot’ method with linestring.xy method.

>>> elevation_profile.as_linestring
[(20, 35), (22, 36), (23, 37), ..., (800, 145)]

property downrange¶

Return the horizontal span of the BaseProfile.

Returns: a dimensional value
Return type: Quantity(“length”)

get_headmost_intersection_with(other: business.commons.energy.EnergyProfile) → business.commons.energy.ElevationProfilePoint ¶

Return the last (rightmost) intersection between two energy lines.

If there is more than one intersection point, this method will return the one nearest to the head end of the energy line.

Parameters: other (EnergyProfile) – the energy line that might intersect this energy line
Raises: NonExistentIntersection – If no intersection point was found. This exception is raised from method _get_intersections_with

get_section_inbetween_downranges(from_downrange: pint.quantity.build_quantity_class.<locals>.Quantity, until_downrange: pint.quantity.build_quantity_class.<locals>.Quantity) → business.commons.energy.EnergyProfile ¶

Create a new energy line by slicing the current one among given ends.

If the ends provided (see parameters) exceed the horizontal span of the current energy line, then no exception is raised and the slicing will include the beginning (or the end) of this energy line. This is the same behaviour as python’s list slicing.

Parameters

from_downrange (Quantity("length")) – the downrange the new energy line starts from
until_downrange (Quantity("length")) – the downrange the new energy line ends to

Returns

a new profile whose first and last point are evaluated by interpolating on the pathlengths of this energy line, while all inner points are the copied from this energy line.

Return type

EnergyProfile

get_tailmost_intersection_with(other: business.commons.energy.EnergyProfile) → business.commons.energy.ElevationProfilePoint ¶

Return the first (leftmost) intersection between two energy lines.

If there is more than one intersection point, this method will return the one nearest to the tail end of the energy line.

Parameters: other (EnergyProfile) – the energy line that might intersect this energy line
Raises: NonExistentIntersection – If no intersection point was found. This exception is raised from method _get_intersections_with
Returns: whose downrange, elevation fields store the (dimensionalized) geometrical intersection point between ‘self’ profile and other profile.
Return type: ElevationProfilePoint

get_unique_intersection_with(other: business.commons.energy.EnergyProfile) → business.commons.energy.ElevationProfilePoint ¶

Return the unique intersection between two energy lines.

It is responsibility of the caller to ensure that the two energy lines may intersect at most once. A typical use case is when the hydraulic design algorithms attempt to find the swivel point from the simplex solution.

Parameters: other (EnergyProfile) – the energy line that might intersect this energy line
Raises: UnforeseenMultipleIntersection – If more than one intersection point was found or no intersections were found.
Returns: whose downrange, elevation fields store the values (dimensionalized) from .x and .y coordinated of the intersection point
Return type: ElevationProfilePoint

intersects_with(other: business.commons.energy.EnergyProfile) → bool¶

Return boolean test if this energy line intersects with another.

Parameters: other (EnergyProfile) – the energy line that might intersect this one

property pathlength¶

Return the linear length of the hydraulic energy line.

Returns: a dimensional value
Return type: Quantity(“length”)

translate_vertically(vertical_shift: pint.quantity.build_quantity_class.<locals>.Quantity) → None¶

Shift the current instance vertically by vertical_shift.

The shift is done ‘in-place’, no new instance of EnergyProfile is created.

property x_axis_coordinates_array¶

Return the sequence of x coordinates of the energy line.

The data are formatted to match matplotlib library interface.

property y_axis_coordinates_array¶

Return the sequence of y coordinates of the energy line.

The data are formatted to match matplotlib library interface.

class business.commons.energy.ElevationProfile(iterable: Iterable = [])¶

Bases: business.commons.mixins.interpolation.PointFactoryMixin, business.commons.mixins.interpolation.ProfileInterpolationMixin, business.commons.energy.BaseEnergyProfileMixin, business.helpers.utils.TypedList

A class to represent the altimetric elevation profile along a pipe trench.

get_pressure_limit_profile(pressure_limit=Quantity[pressure])¶: return the elevation profile shifted vertically by the pressure limit

property elevation_at_tail_end¶: Return the elevation measured at the first point of this profile.

get_pressure_limit_profile(pressure_limit: pint.quantity.build_quantity_class.<locals>.Quantity) → business.commons.energy.EnergyProfile ¶

Return an EnergyProfile raised from this altrimetric profile by pressure_limit.

It is used to check geometrically if an energy line, once calculated, will lie between the elevation profile and the pressure limit profile.

Parameters: pressure_limit (Quantity("length")) – a value of pressure expressed, as per hydarulic engineering, HAESTADT expressed in units of length (usually ‘meters of water’). The value of pressure_limit passed to this function is usually taken from one of the rated working pressures available from the catalog of pipes: manufacturers.catalogs.pipes
Returns: the energy profile fit for pressure_limit rating.
Return type: EnergyProfile

class business.commons.energy.ElevationProfilePoint(downrange: float, elevation: float, remarks: Optional[Dict] = None, pathlength: Optional[float] = None)¶

Bases: business.commons.energy.EnergyProfilePoint

Represent point belonging to altimetric elevation profile.

pathlength¶

the pathlength measured along the pipe trench.

Type: Quantity(“length”)

pathlength: float = None¶

class business.commons.energy.EnergyProfile(iterable: Iterable = [])¶

Bases: business.commons.energy.BaseEnergyProfileMixin, business.helpers.utils.TypedList

A class to represent the hydraulic grade line HAESTADT.

property as_serializable¶

class business.commons.energy.EnergyProfilePoint(downrange: float, elevation: float, remarks: Optional[Dict] = None)¶

Bases: object

Represent a point along the water energy line.

The water energy line is defined piecewise as a collection of instances belonging to this class.

downrange¶

the x coordinate of the point in a 2-d plan

Type: Quantity(“length”)

elevation¶

the y coordinate of the point in a 2-d plan

Type: Quantity(“length”)

remarks¶

any information added to the point, typically from field notes. Example: “soil is hard to dig starting from this point”

Type: dict

property as_geometry¶

Return a Shapely object from the current instance.

Returns

A new *shapely.geometry.Point instance whose coordinates are given*
by the magnitude of the *ElevationProfilePoint coordinates.*

property as_humanised¶

Return a string having field values truncated to few decimals.

It is used for improved readability.

downrange: float¶

elevation: float¶

remarks: Dict = None¶

class business.commons.energy.PlotBaseEnergyProfileMixin¶

Bases: object

A mixin class gathering methods used to do geometric calculations.

x_axis_coordinates_array¶: Return the sequence of x coordinates of the energy line

y_axis_coordinates_array¶: Return the sequence of y coordinates of the energy line

property as_matplotlib_curve¶: Return this instance as a Matplotlib curve, ready to be plotted.

business.commons.exceptions module¶

Collection of exceptions raised by ‘gravity’ and ‘pumpstation’ folders.

exception business.commons.exceptions.CorruptedLandElevationFile¶

Bases: business.commons.exceptions.ImproperlyConfiguredTrunk

The trunk topographic survey file contains nonsensical data.

exception business.commons.exceptions.ImproperlyConfiguredTrunk¶

Bases: business.commons.exceptions.ImproperlyConfiguredWaterSystem

Exception class to indicate errors during Trunk initialization.

Some data needed to describe a Trunk were not provided by the user. It may be raised by any class that extends Watermain

exception business.commons.exceptions.ImproperlyConfiguredWaterSystem¶

Bases: business.commons.exceptions.RuralwaterException

Exception class to indicate errors during water supply initialization.

Some data needed to solve the hydraulic design/check problem were not provided by the user.

It may be raised by any class that extends Station or BaseGravity

exception business.commons.exceptions.NonExistentIntersection¶

Bases: business.commons.exceptions.RuralwaterException

The HGL tract and the PN-_elevation_profile do not intersect.

Raised by the algorithms that seach for optimization of the hydraulic grade line: * commons.energy * gravity.mixins.trimming * gravity.stretches * gravity.stretching.pressure * pumpstation.climb

exception business.commons.exceptions.NonsensicalLandElevationData¶

Bases: business.commons.exceptions.ImproperlyConfiguredTrunk

A file can be read but the data make no logical sense.

exception business.commons.exceptions.NotImplementedInRuralwater¶

Bases: business.commons.exceptions.RuralwaterException

Invoked method is not implemented in this version of ruralwater.

exception business.commons.exceptions.RuralwaterException¶

Bases: Exception

Basic exception for all errors raised by ruralwater.

Base exception class for all exceptions raised in ruralwater/webapp/business. No code in the business logic will raise this exception directly; it serves solely to provide a distinguishing parent class for other errors.

exception business.commons.exceptions.UnadvisableDuty¶

Bases: business.commons.exceptions.RuralwaterException

The working conditions exceed the limits imposed by hydraulic hardware or by available water sources.

Exceptions that ovveride this one are found in the pumpstation and groundwater modules.

The message attached to the Exception, carries the information about the exact nature of the engineering problem identified.

Examples:

“water hammer exceeds pipes pressure ratings”:: raised by australia.system when tripping the “monopump” results in water hammer transient above the feeder pipes classes.
“diesel engine carbonation”: raised by australia.system when the continuous working conditions impose a load on DieselEngine below 50%.

exception business.commons.exceptions.UnforeseenMultipleIntersection¶

Bases: business.commons.exceptions.RuralwaterException

The HGL tract and the PN-_elevation_profile intersect (unexpectedly) more than once.

This exceptions should never be raised. If it will occour it is likely that it will have been caused by a bug not yet detected or fixed.

business.commons.loggers module¶

class business.commons.loggers.InitLogger¶

Bases: business.commons.loggers.LoggerMixin

Allow the class instances to use python logging mechanism.

class business.commons.loggers.InitLoggerMixin¶

Bases: business.commons.loggers.LoggerMixin

Allow hooking into __post_init__ to use python logging mechanism.

class business.commons.loggers.LoggerMixin¶

Bases: object

Algorithms to use python logging mechanism.

business.commons.traversals module¶

Provide common methods aspects of a ‘subnode’ and a ‘soil stretch’.

class business.commons.traversals.PipeDesignPoolMixin¶

Bases: object

Mixin to get a handle to the catalog of commercial pipes.

Functionality: accessor to the catalog of pipes for the trunk.

commercial_pipes¶: return a handle to the catalog of commercial pipes available to run the hydraulic calculations.

property commercial_pipes¶

Return a handle to the catalog of commercial pipes.

Pipes may be either plastic or metallic. Further typologies of pipes might be added in the future.

class business.commons.traversals.TraversalsTrunkOrStretchMixin¶

Bases: object

Algorithms common to Trunk and Subtrunk.

Functionality: algorithms dealing with the rated working pressure.

Notes

Algorithms fired by __init__ of ‘subnode’ and ‘soil stretch’.

_tail_point_pressure¶: return the hydraulic pressure felt at the tail point of the ‘subnode’ or ‘soil stretch’.

_head_point_pressure¶: return the hydraulic pressure felt at the head point of the ‘subnode’ or ‘soil stretch’.

business.commons.watermains module¶

Provide commons elements of DendridicTrunks and Feeders.

Functionality: ‘gravity’ has a tree of pathways, while ‘station’ has a single feeder. Since the single feeder is a ‘spurious’ tree, we can say that ‘gravity’ and ‘station’ share common elements of directed acyclic graph. This module provides the common functionalities of a tree (the gravity’s pathway topology) and of a ‘single node’ (the station’s pathways topology).

class business.commons.watermains.Watermain(**kwargs)¶

Bases: business.commons.watermains.WatermainMixin, business.commons.mixins.cost.PipesCostMixin, business.commons.loggers.InitLogger

Represent a pathway with or without the pipes defined.

Common to trunks and feeders, both in design and check calculations.

Notes

Along the watermain the flow of water is the same. The Watermain is composed of a sequence of different diameters, pipe materials and pipe pressure specifications. Along the pipeline the flow of water is constant, i.e.: there are no water flow abstractions from the ‘tail end’ to the ‘head end’.

pathlength¶

the linear distance of a man walking along the pipeline.

Type: Quantity(“length”)

profile_elevation_at_head_end¶

the altimetric elevation at the ‘beginning’, i.e.: where the water flows from.

Type: Quantity(“length”)

profile_elevation_at_tail_end¶

the altimetric elevation at the ‘end’, i.e.: where the water flows to.

Type: Quantity(“length”)

get_hydraulic_friction¶

the energy burned off in the pipeline by the water flowing inside it.

Type: Quantity(“length”)

class business.commons.watermains.WatermainCheck(**kwargs)¶

Bases: business.commons.watermains.Watermain

Represent a pathway with the pipes defined

Functionality: common to trunks and feeders, specific for hydraulic check calculations.

Overrides Watermain and sets the catalog of pipes available to run the hydraulic check calculations. The catalog of pipes corresponds to “ALL_PIPE_MATERIALS_ALLOWED” since check calculations must access data from any possible typology of pipe.

property get_hgl_profile¶

evaluate the hydraulic energy profile arising from the piped segments set in the __init__ of the TrunkCheck and with: * the hydraulic energy at head and tail points and… * …the water flow… …following to the solution of the ‘hydraulic check problem’.

business.commons package¶

Subpackages¶

Submodules¶

business.commons.TODO_settings module¶

business.commons.adapters module¶

business.commons.constants module¶

business.commons.coroutines module¶

business.commons.defaults module¶

business.commons.definitions module¶

business.commons.energy module¶

business.commons.exceptions module¶

business.commons.loggers module¶

business.commons.traversals module¶

business.commons.watermains module¶

Page Contents

Previous topic

Next topic

This Page

Navigation

business.commons package¶

Subpackages¶

Submodules¶

business.commons.TODO_settings module¶

business.commons.adapters module¶

business.commons.constants module¶

business.commons.coroutines module¶

business.commons.defaults module¶

business.commons.definitions module¶

business.commons.energy module¶

business.commons.exceptions module¶

business.commons.loggers module¶

business.commons.traversals module¶

business.commons.watermains module¶