business.helpers package¶

Collection of code architectural snippets essential for bootstrapping components

Submodules¶

business.helpers.definitions module¶

Collection of data structures used throughout all the other packages that constitute ‘ruralwater’. PIERGIORGIO2: Se ‘helpers’ è un package allora ‘ruralwater’ cosa è? Mi riferisco a come scrivere la frase sopra.

Data structures

EngineWorkingConditions: requirements to select a engine from a catalog of commercial engines.
PipeWorkingConditions: (namedtuple): requirements to select a pipe from a catalog of commercial pipes.
RiserAssemblyWorkingConditions: defines the duty a down-the-hole shaft riser must be able to sustain.
SubmersibleWorkingConditions: requirements to select a submersible pump from a catalog of commercial pumps.

class business.helpers.definitions.EngineWorkingConditions(brake_power, rpm)¶

Bases: tuple

The requirements the engine must be able to satify.

Notes

May be used either to select an engine off a catalog of engines commercially available. May be used to evaluate the engine load and consumption at the given woring conditions.

brake_power¶

the engine brake power TODO: HAESTADT, cerca definizione

Type: Quantity(“TODO”) float TODO: non è un float ma una quantity; scrivi le unità di misura corrette.

rpm¶

the engine crankshaft rotational speed

Type: Quantity(“TODO”) float TODO: non è un float ma una quantity; scrivi le unità di misura corrette.

property brake_power¶: Alias for field number 0

property rpm¶: Alias for field number 1

class business.helpers.definitions.FlowVsEnergyCurve(typed_sequence)¶

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

Sequence of (water_flow, water_energy) points that approximate the flow-hydraulic_energy curve in nature.

Note

Overrides TypedList to ensure that each point of the sequence is a (flow, energy) tuple.

as_linestring:: Geometric representation of the curve in a 2-d plane.

property as_linestring¶

Return this sequence as a shapely object.

Represent a polygonal chain in the 2-d plane which is the piecewise linear approximation of the flow-hydraulic_energy curve in nature.

Important

In geometry, a polygonal chain is a connected series of line segments. Return this record as a shapely object. Refer to https://pypi.org/project/Shapely/ for a description of the shapely package.

Returns: The shapely LineString instance. For each of the points of the polygonal chain, magnitudes are expressed in the unit of measure set in ruralwater.helpers.units, see HYDRAULIC_ENERGY_UNITS for the energy and WATERFLOW_UNITS for the water flow.
Return type: shapely.geometry.LineString

get_intersection_with(other)¶

misses(other)¶

class business.helpers.definitions.FlowVsEnergyPoint(hydraulic_energy: pint.quantity.build_quantity_class.<locals>.Quantity, water_flow: pint.quantity.build_quantity_class.<locals>.Quantity)¶

Bases: object

A class used to represent the duty of a pump.

water_flow¶

the abstracted water flow from the borehole

Type: Quantity(“volume/time”)

hydraulic_energy¶

the hydraulic energy provided to or required by the water flow.

Type: Quantity(“TODO”)

as_shapely_point()¶: Geometric representation of the record in a 2-d plane.

Notes

Overloads __add__, __sub__: In a pump station (class ElectriclessDesign) the flow of water is the same through all the mechanical parts (borehole colum, feeder, pump body, shaft) therefore the duty is a sum of energy requirements, while the water_flow value remains constant.

property as_shapely_point¶

Return this record as a shapely object.

Represent a point in the 2-d plane whose abscissa matches the hydraulic energy and whose ordinate matches the water flow. Refer to https://pypi.org/project/Shapely/ for a description of the shapely package.

Returns: The shapely point instance. Magnitudes are expressed in the unit of measure set in ruralwater.helpers.units, see HYDRAULIC_ENERGY_UNITS for the energy and WATERFLOW_UNITS for the water flow.
Return type: shapely.geometry.Point

hydraulic_energy: pint.quantity.build_quantity_class.<locals>.Quantity¶

water_flow: pint.quantity.build_quantity_class.<locals>.Quantity¶

class business.helpers.definitions.PipeWorkingConditions(water_flow, rated_working_pressure)¶

Bases: tuple

The requirements the pipe must be able to satify.

Notes

May be used to select a pipe off a catalog of pipes commercially available.

water_flow¶

the water flow throughout the pipe

Type: Quantity(“volume/time”, float)

rated_working_pressure¶

the working pressure for which the pipe is rated by the manufacturer

Type: Quantity(“TODO”) float TODO: non è un float ma una quantity; scrivi le unità di misura corrette.

property rated_working_pressure¶: Alias for field number 1

property water_flow¶: Alias for field number 0

class business.helpers.definitions.PipedSegment(_commercial_pipe: str, _starts_at_pathlength: float, _ends_at_pathlength: float = None)¶

Bases: object

A class used to represent a stretch of a commercial pipe. INGLESE: non è uno stretch ma….?

_commercial_pipe¶

the commercial pipe

Type: Pipe

_starts_at_pathlength¶

the linear distance where the stretch begins

Type: Quantity(“length”)

_ends_at_pathlength¶

the linear distance where the stretch ends. It is optional: either it can be assigned or it can be evaluated looping in the ordered collection of PipedSegments.

Type: Quantity(“length”), optional

Linear distances refer to a zero which is defined in *Trunk* class.

water_flow()¶: Geometric representation of the record in a 2-d plane.

burned_energy()¶: the amount of hydraulic energy burned off at a given water_flow

pathlength()¶: the linear extension of the stretch

penalty()¶: the investment cost to build the stretch

property burned_energy¶: Return the hydraulic energy burned off by the commercial pipe.

Note

Precondition: self._ends_at_pathlength is set.

property pathlength¶: Return the linear length of the stretch instance.

Note

Precondition: self._ends_at_pathlength is set.

class business.helpers.definitions.PipedSegmentCheck(_commercial_pipe: str, _starts_at_pathlength: float, _ends_at_pathlength: float = None)¶

Bases: business.helpers.definitions.PipedSegment

get_headloss_at_sample_flow(sample_water_flow)¶

get_humanized_pipe_name()¶

Return the name of the commercial pipe, suitable for django templates.

Functionality: accessing the name of the commercial pipe cannot be achieved simply using the django template language because the language must access two custom template filters in sequence. These filters are needed to access dictionary keys (_commercial_pipe and _natural_key_as_string) wich have an underscore prepended. It’s too much logic to be put in the template (and makes the line of code to be too long). Therefore we resort to this method, which may be accessed directly using the {{ context.key }} syntax of the template language.

Returns: the unique identifier of a commercial pipe, formatted as ‘human readable’, with underscores replaced by spaces.
Return type: str

property non_fractional_burned_energy¶: Return the hydraulic energy burned off by the commercial pipe, if friction is evaluated with integer-powers only.

property water_flow¶

class business.helpers.definitions.PipedSegmentDesign(_commercial_pipe: str, _starts_at_pathlength: float, _ends_at_pathlength: float = None)¶

Bases: business.helpers.definitions.PipedSegment

property water_flow¶: Set the water flow in the commercial pipe.

class business.helpers.definitions.RiserAssemblyWorkingConditions(water_flow, pump_depth)¶

Bases: tuple

The requirements the monopump riser assembly must be able to satify.

Notes

May be used to select a riser and shaft combination off a catalog of commercially available combinations.

water_flow¶

the water flow throughout the riser assembly pipe.

Type: Quantity(“volume/time”, float)

pump_depth¶

the depth at which the pump body is set.

Type: Quantity(“length”, float)

property pump_depth¶: Alias for field number 1

property water_flow¶: Alias for field number 0

class business.helpers.definitions.SubmersibleWorkingConditions(water_flow)¶

Bases: tuple

The requirements the submersible pump must be able to satify.

Notes

May be used either to select an submersible pump off a catalog of submersible pumps commercially available. May be used to evaluate the engine load and consumption at the given woring conditions.

water_flow¶

the water flow throughout the pump.

Type: Quantity(“volume/time”, float)

property water_flow¶: Alias for field number 0

business.helpers.guards module¶

Collection of utilities to chek the dimension of a physical quantities.

All physical variables in ruralwater are expressed as dimensional quantities, thanks to the ‘pint’ package. These methods are used by property setters as precondition check.

Data structures

check_is_waterflow:: ensure the variable under observation represents a water flow.

business.helpers.guards.check_is_column_working_conditions(function)¶

business.helpers.guards.check_is_pipe_working_conditions(function)¶

business.helpers.guards.check_is_pressure(function)¶

Chek a precondition: if the ‘value’ passed to a setter is meaningful.

Checks that the value passed to a setter represents a geometric distance.

Parameters: function (@property.setter) – a setter method of a class
Raises: ValueError – If value has not the prescribed instance, dimensionality and magnitude.

Example

It is used as a guard when creating a rated pressure profile starting from an altimetric profile.

business.helpers.guards.check_is_rpm(function)¶

Chek a precondition: if the ‘value’ passed to a setter is meaningful.

Checks that the value passed to a setter represents an angular speed.

Parameters: function (@property.setter) – a setter method of a class
Raises: ValueError – If value has not the prescribed instance, dimensionality and magnitude.

Example

It is used as a guard when setting rotational speed of engines, pumps, shafts and centrifugal clutches.

business.helpers.guards.check_is_vertical_shift(function)¶

Chek a precondition: if the ‘value’ passed to a setter is meaningful.

Checks that the value passed to a setter represents a geometric distance.

Parameters: function (@property.setter) – a setter method of a class
Raises: ValueError – If value has not the prescribed instance, dimensionality and magnitude.

Example

It is used as a guard when creating a rated pressure profile starting from an altimetric profile.

business.helpers.guards.check_is_waterflow(function)¶

Chek a precondition: if the ‘value’ passed to a setter is meaningful.

Checks that the value passed to a setter represents a water flow.

Parameters: function (@property.setter) – a setter method of a class
Raises: ValueError – If value has not the prescribed instance, dimensionality and magnitude.

business.helpers.roundings module¶

Collection of constants used to round physical quantities magnitude.

It is used to render the logging of physical values easier to read, cutting away unnecessary decimal digits .

business.helpers.units module¶

Provide utilities and constants for modelling dimensional units.

Notes

This module is based on third-party <pint> library.

business.helpers.units.BSDC_UNITS = <Unit('gram / kilowatt_hour')>¶: Prescribes the units to express the specific diesel consumption

business.helpers.units.DAILY_DEMAND_UNITS = <Unit('liter / day')>¶: Prescribes the units to express the daily water demand.

business.helpers.units.DIAMETER_UNITS = <Unit('millimeter')>¶

namely, the inner diameter of the borehole and the width of the pipes inside it.

Type: Prescribes the units to express “width” inside the borehole

business.helpers.units.DISTANCE_UNITS = <Unit('meter')>¶

Prescribes the units to express linear distances. Definitions:

downrange
xxx

elevation
xxx

pathlength:
linear distance along the pipe trench

Prescribes the units to express pipe trench profiles.

business.helpers.units.ELECTRIC_ENERGY_UNITS = <Unit('hour * kilowatt')>¶: Prescribes the units to express the electric energy consumed each hour.

business.helpers.units.POWER_UNITS = <Unit('kilowatt')>¶: Prescribes the units to express the mechanical power

business.helpers.units.PULLEY_DIAMETER_UNITS = <Unit('centimeter')>¶: Prescribes the units to express pulley diameters.

business.helpers.units.PUMP_BODY_VERTICAL_ENCUMBRANCE = <Unit('meter')>¶: Prescribes the units to express how ‘long’ is the pump body.

business.helpers.units.RPM_UNITS = <Unit('revolutions_per_minute')>¶: Prescribes the units to express rotational speed of shafts.

business.helpers.units.WATERFLOW_UNITS = <Unit('liter / second')>¶: Prescribes the units to express the water flow.

business.helpers.units.as_decimal(quantity)¶

Return a Q_ with a magnitude cast to a python’s decimal.Decimal.

Example

Allows to perform cost estimates by multiplying a float (such as the length of meters of a commercial pipe) times a Decimal (that is, a unit price).

Parameters: quantity (helpers.business_units.Q_) – the quantity whose magnitude is to cast to integer.
Returns: an instance of helpers.business_units.Q_ with a magnitude cast to decimal.Decimal
Return type: helpers.business_units.Q_

business.helpers.units.as_integer(quantity)¶

Return a Q_ with a magnitude cast to an integer.

Example

Converts logs such as ‘downrange=<Quantity(3045.1000000000004, ‘meter’)> into a more readable ‘downrange=<Quantity(3045, ‘meter’)>

Parameters: quantity (helpers.business_units.Q_) – the quantity whose magnitude is to cast to integer.
Returns: an instance of helpers.business_units.Q_ with a magnitude cast to integer
Return type: helpers.business_units.Q_

business.helpers.units.as_rounded(quantity, decimal_digits=0)¶

Return a Q_ with a magnitude rounded to some decimal places.

Example

Converts logs such as ‘downrange=<Quantity(3045.1000000000004, ‘meter’)> into a more readable ‘downrange=<Quantity(3045, ‘meter’)>

Parameters

quantity (helpers.business_units.Q_) – the quantity whose magnitude is to round.
decimal_digits (int) – the number of decimal digits in the return value magnitude.

Returns

an instance of helpers.business_units.Q_ with a rounded magnitude

Return type

helpers.business_units.Q_

business.helpers.utils module¶

Programming language utilities.

class business.helpers.utils.TypedList(ok_type, iterable=[])¶

Bases: collections.abc.MutableSequence, business.commons.loggers.InitLogger

Create a list that accepts only elements of a given type.

Raises: TypedListError – if trying to add an element not conform to the required type.

exception TypedListError¶

Bases: TypeError, business.commons.exceptions.RuralwaterException

An element to append to a typed list is not of the valid type.

insert(item, value)¶: S.insert(index, value) – insert value before index

class business.helpers.utils.TypedSet(ok_type, iterable=())¶

Bases: collections.abc.MutableSet, business.commons.loggers.InitLogger

Create a list that accepts only elements of a given type.

Raises: TypedListError – if trying to add an element not conform to the required type.

exception TypedSetError¶

Bases: TypeError, business.commons.exceptions.RuralwaterException

An item to append to a typed set is not of the valid type.

add(item)¶: Add an element.

discard(item)¶: Remove an element. Do not raise an exception if absent.

business.helpers.utils.ajaxpolling(message)¶

business.helpers.utils.coroutine(func)¶: Do prime a coroutine advancing to the first yield statement.

business.helpers.utils.do_postcondition(method)¶

Invoke a method after another method is invoked.

Parameters: method (callable) – the class instance method which represents the do_postcondition. method must be decorated as @property.

business.helpers.utils.do_precondition(method)¶

Invoke a method before another method is invoked.

Parameters: method (callable) – the class instance method which represents the check_precondition. method must be decorated with @property.

business.helpers.utils.lazyprop(fn)¶: Cache and return value of property after the first time it is evaluated.

business.helpers package¶

Submodules¶

business.helpers.definitions module¶

business.helpers.guards module¶

business.helpers.roundings module¶

business.helpers.units module¶

business.helpers.utils module¶

Page Contents

Previous topic

Next topic

This Page

Navigation

business.helpers package¶

Submodules¶

business.helpers.definitions module¶

business.helpers.guards module¶

business.helpers.roundings module¶

business.helpers.units module¶

business.helpers.utils module¶