Welcome to pvpumpingsystem’s documentation!

pvpumpingsystem is a package providing tools for modeling and sizing offgrid photovoltaic water pumping systems. It is specially designed for small to medium size systems, the type of pumping system typically used for isolated communities.

It can model the whole functioning of such pumping system on an hourly basis and eventually provide key financial and technical findings on a year. Conversely it can help choose some elements of the pumping station depending on output values wanted (like daily water consumption and acceptable risk of water shortage). Find more on the scope of the software in the section Package Overview.

The source code for pvpumpingsystem is hosted on GitHub: https://github.com/tylunel/pvpumpingsystem

The package was originally developped at T3E research group, in Ecole de Technologie Superieure, Montreal, Qc, Canada, by Tanguy Lunel.

The software is published under the open source license GPL-v3.

Package Overview

Introduction

Scope

Pvpumpingsystem is an open source package providing various tools aimed at facilitating the modeling and sizing of photovoltaic powered water pumping systems.

This package helps users to model, test and validate different photovoltaic pumping systems before actually installing it in situ. In order to guide the designer in her/his choice, pvpumpingsystem provides both technical and financial information on the system. Even though the package is originally targeted at researchers and engineers, three practical examples are provided in order to help anyone to use pvpumpingsystem

It models pumping systems minimally made of PV generator, DC motor-pump and pipes. Each component can be precisely defined by the user in such a way it corresponds closely to any actual system wanted. User can choose to add a MPPT/DC-DC converter to increase the energy yield of the PV array or to directly couple PV array and motor-pump. The software also allows to add water tank to mitigate the effect of intermittency.

The simulation eventually compute numerous outputs like hourly flow rates of a given pump, efficiencies of components, risk of water shortage and life cycle cost of the whole system.

Pvpumpingsystem also offers to automate the process of sizing. In this case, the user can provide a set of PV module, a set of motor-pumps and a water needs file, and the software looks for the cheapest assembly while making sure that it respects a minimum risk of water shortage.

Nevertheless, the number of sizing processes can be infinite, and this module is expected to significantly expand with time, welcoming new sizing process based on different selection criteria or algorithms. In particular, the reservoir size, the orientation of the PV array, the coupling strategy or even the diameter of pipes are inputs that could ultimately become outputs of the sizing process as well.

To better understand the possibilities of pvpumpingsystem and how it works, you are invited to consult the examples available in the form of Jupyter Notebook in Examples or the corresponding python files in docs/examples.

Code characteristics

Python is the programming language used in the software, and the code is structured within an object-oriented approach. Continuous integration services allow checking for lint in the code and to automatize the tests. Each class and function are documented in the docstring with reference to the literature when applicable.

In pvpumpingsystem, in order to increase the understandability of the code, the physical components of the PV pumping system corresponds to a class when possible, like for example the classes Pump(), MPPT(), PipeNetwork(), Reservoir() and PVGeneration(). Moreover, each of these classes are gathered into separate modules with appropriate names (pump.py, mppt.py, etc). The previous objects are then gathered in the class PVPumpSystem() which allows running partial or comprehensive modeling of the pumping system.

A separate module sizing.py is dedicated to functions allowing to size these systems. These functions are globally numerical methods, relying on numerous simulations run according to an algorithm or to a factorial design. sizing.py module can be expanded a lot as many strategies can be imagined to size such a system.

Pvpumpingsystem relies on already existing packages for photovoltaic and fluid mechanics modeling, namely pvlib-python and fluids. pvpumpingsystem’s originality lies in the implementation of various motor-pump models for finite power sources and in the coupling of the distinct components models.

Pvpumpingsystem is released under a GPL-v3 license.

Databases accessible

The PV module database of the California Energy Commission (CEC) is made accessible through PVGeneration (being itself a wrapper of pvlib-python). As this database is nearly comprehensive (more than 22,000 modules) and regularly updated, it was considered that having a function to define its own PV module was not relevant yet. Therefore, PV modules must be declared by giving the reference in the corresponding attribute in declaration of any PVGeneration instance.

Furthermore, the package also provide some pump and weather files in the folder pvpumpingsystem/data.

Concerning pump files, a template is provided in the folder in order to help anyone fill it in with the specification of the pump they want to model. A limited database coming from the company SunPumps is also accessible. Nevertheless, it does not mean that the developers particularly encourage their use, it rather reflects the difficulty to find other sources easily accessible online. Any addition to the database is warmly welcomed here.

The weather files consist in a very restricted list of .epw files coming from diverse climates and that users can exploit to learn and test the software. Similar files for many location around the world are available at EnergyPlus website, or can be constructed using PVGIS.

Getting support and contribute

If you need help, you think you have discovered a bug, or if you would like to edit pvpumpingsystem, then do not hesitate to open an issue on our GitHub issues page or on our GitHub pull request page.

Credits

The T3E research group would like to acknowledge Mr. Michel Trottier for his generous support, as well as the NSERC and the FRQNT for their grants and subsidies. We also acknowledges the contributions and fruitful discussions with Louis Lamarche and Sergio Gualteros that inspired and helped with the current work.

Installation

Installing pvpumpingsystem can be done through different processes. Two of them are detailled here, mainly thought for newcomers. Experienced users can modify it to their liking.

For people uncomfortable with package management, but who still plan on contributing or editing the code, follow the Install pvpumpingsystem with Anaconda and Git instructions to install pvpumpingsystem along with Anaconda and Git.

For people only interested in the use of the package, follow the Install pvpumpingsystem alone instructions to install pvpumpingsystem alone.

Installing pvpumpingsystem is similar to installing most scientific python packages, so in case of trouble see the References section for further help.

Please see the Compatibility section for information on the optional packages that are needed for some pvpumpingsystem features.

Install pvpumpingsystem with Anaconda and Git

• Anaconda:

The Anaconda distribution is an open source distribution providing Python and others softwares and libraries useful for data science. Anaconda includes many of the libraries needed for pvpumpingsystem (Pandas, NumPy, SciPy, etc). Anaconda is especially recommended when using Windows.

Anaconda Python distribution is available at https://www.anaconda.com/download/.

See What is Anaconda? and the Anaconda Documentation for more information.

• Git:

Git is a version control system that widely help contribution and development for open source softwares. Git should be native on most of Linux distribution, but must be installed on Windows.

Git for Windows is available at https://gitforwindows.org/.

• pvpumpingsystem:

Once you have Anaconda and git installed, open a command line interface (‘Anaconda Prompt’ on Windows, terminal in Linux and macOS), change directory to the one you want to install pvpumpingsystem in, and type:

pip install -e git+https://github.com/tylunel/pvpumpingsystem#egg=pvpumpingsystem

• Test pvpumpingsystem:

To ensure pvpumpingsystem and its dependencies are properly installed, run the tests by going to the directory of pvpumpingsystem and by running pytest:

cd <relative/path/to/pvpumpingsystem/directory>
pytest

Install pvpumpingsystem alone

Note

Even if you decide not to use Anaconda or Git, you minimally need a Python version superior to 3.5, and to have pip and setuptools installed (installed by default with recent version of Python).

This second option simply uses pip:

pip install pvpumpingsystem

If you have troubles with the use of pip, here is the pip documentation to help you.

To ensure pvpumpingsystem and its dependencies are properly installed, you can consult the package information through pip:

pip show pvpumpingsystem

Compatibility

pvpumpingsystem is compatible with Python 3.5 and above.

Besides the libraries contained in Anaconda, pvpumpingsystem also requires:

• pvlib-python
• fluids
• numpy-financial

The full list of dependencies is detailled in setup.py.

References

Note

This section was adapted from the pvlib-python documentation. Thanks to them for this useful listing!

Here are a few recommended references for installing Python packages:

• Python Packaging Authority tutorial
• Conda User Guide

Here are a few recommended references for git and GitHub:

• The git documentation: detailed explanations, videos, more links, and cheat sheets. Go here first!
• Forking Projects
• Fork A Repo
• Cloning a repository

Getting started

To begin, a global view of how the code may be used is given here. Afterward, it is recommended to go through the two first examples provided below in order to get further step-by-step explanations.

General layout

The code make use of the possibilities provided by the object-oriented paradigm of python. In particular, the code tries to match physical components with objects (in the computer sense of the term) as much as possible.

Therefore, modeling a PV pumping system requires to start by defining each object, i.e each component represented in below diagram.

Once all components have been declared in objects, they are gathered in a parent object (an instance of class PVPumpSystem) where the type of coupling between PV array and pump is declared. Ultimately, the method run_model() launches the whole simulation. It is also the step where the financial parameters can be provided if a cost analysis is wanted.

Afterward, the results are contained in the object PVPumpSystem. At this point, it is useful to have an IDE like Spyder or Pycharm to explore the values internally contained. Otherwise, most of the results are actually stored in the attributes flow, efficiency, water_stored, npv, llp.

The examples below, in particular the jupyter notebook ones, provide further details on each step of a standard simulation.

Examples

Three examples of how the software can be used are in the folder docs/examples. The examples are provided under two forms, as Jupyter Notebook files or as Python files.

Jupyter Notebook

Following examples can be run locally with Jupyter Notebook, or by clicking on the corresponding icon in the upper right-hand corner of nbviewer pages, or by accessing through the binder build.

Simulation

The first two examples focus on simulation. These examples are important to understand because the modeling tools used here are the core of the software. These tools can be used later to get programs that fit a more particular use (for ex.: sizing process, parametric study, etc). For a given system, the examples show how to obtain the values of interest for the user (output flow rates, total water pumped in a year, loss of load probability (llp), net present value (npv), efficiencies and others):

Basic usage example

More advanced usage example

Once you went through these 2 examples, you are quite ready to dive into the code and adapt it to your needs.

Sizing

The third example shows how to use a sizing function written from the modeling tools presented in the two examples above. This function aims at optimizing the selection of the pump and the PV module, based on user requirements.

Sizing example

Python files

These examples are also available in the form of python files in order to freely adapt the code to your wishes. Directly check out in docs/examples.

API reference

Classes

The different classes of pvpumpingsystem.

pvgeneration.PVGeneration(…[, …])	Class representing the power generation through the photovoltaic system.
mppt.MPPT([efficiency, price, idname, …])	Class defining a DC/DC converter with a MPPT controller.
pump.Pump(path[, …])	Class representing a motor-pump.
pipenetwork.PipeNetwork(h_stat, l_tot, diam)	Class representing a simple hydraulic network.
reservoir.Reservoir([size, water_volume, …])	Class defining a water tank with its main characteristics.
consumption.Consumption([flow_rate, …])	The Consumption class defines a consumption schedule, typically through a year.
pvpumpsystem.PVPumpSystem(pvgeneration, …)	Class defining a PV pumping system made of:

Functions and methods

Pump modeling

The core of the software’s originality lies in the implementation of different motor-pump models and in their coupling with the PV generator.

pump.Pump.iv_curve_data(head[, nbpoint])	Function returning the data needed for plotting the IV curve at a given head.
pump.Pump.functIforVH()	Function computing the IV characteristics of the pump depending on head H.
pump.Pump.functIforVH_Arab()	Function using Hadj Arab model for modeling I vs V of pump.
pump.Pump.functIforVH_Kou()	Function using Kou model for modeling I vs V of pump.
pump.Pump.functIforVH_theoretical()	Function using electrical architecture for modeling V vs I of pump.
pump.Pump.functQforVH()	Function redirecting to functQforPH.
pump.Pump.functQforPH()	Function computing the output flow rate of the pump.
pump.Pump.functQforPH_Hamidat()	Function using Hamidat model for output flow rate modeling.
pump.Pump.functQforPH_Arab()	Function using Hadj Arab model for output flow rate modeling.
pump.Pump.functQforPH_Kou()	Function using Kou model for output flow rate modeling.
pump.Pump.functQforPH_theoretical()	Function using theoretical approach for output flow rate modeling.
pump.get_data_pump(path)	Loads the pump data from the .txt file designated by the path.
pump.specs_completeness(specs, …)	Evaluates the data completeness of a motor-pump.
pump._curves_coeffs_Arab06(specs, …)	Compute curve-fitting coefficient with method of Hadj Arab [1] and Djoudi Gherbi [2].
pump._curves_coeffs_Kou98(specs, …)	Compute curve-fitting coefficient with method of Kou [1].
pump._curves_coeffs_Hamidat08(specs, …)	Compute curve-fitting coefficient with method of Hamidat [1].
pump._curves_coeffs_theoretical(specs, …)	Compute curve-fitting coefficient following theoretical analysis of motor architecture.
pump._curves_coeffs_theoretical_variable_efficiency(…)	Compute curve-fitting coefficient following theoretical analysis of motor architecture.
pump._curves_coeffs_theoretical_constant_efficiency(…)	Compute curve-fitting coefficient following theoretical analysis of motor architecture.
pump._curves_coeffs_theoretical_basic(specs, …)	Compute curve-fitting coefficient following theoretical analysis of motor architecture.
pump._domain_V_H(specs, data_completeness)	Function giving the range of voltage and head in which the pump will work.
pump._domain_P_H(specs, data_completeness)	Function giving the range of power and head in which the pump will work.
pump._extrapolate_pow_eff_with_cst_efficiency(specs)	Adapt/complete specifications of a limite pump datasheet.
pump.plot_Q_vs_P_H_3d(pump)	Print the graph of Q [L/min] vs tdh [m] and P [W] in 3 dimensions.
pump.plot_I_vs_V_H_3d(pump)	Print the graph of I [A] vs tdh [m] and V [V] in 3 dimensions.
pump.plot_Q_vs_V_H_2d(pump)	Print the graph of Q [L/min] vs tdh [m] for each voltage available.

Other components modeling

reservoir.Reservoir.change_water_volume(quantity)	Function for adding or removing water in the reservoir.
consumption.adapt_to_flow_pumped(…)	Method for shrinking the consumption flow_rate attribute at the same size than the corresponding pumped flow rate data.
pipenetwork.PipeNetwork.dynamichead(Qlpm[, …])	Calculates the dynamic head of the pipe network according to the flow given Q, and using the Darcy-Weisbach equation.
pvgeneration.PVGeneration.run_model()	Runs the modelchain of the PV generation.

Global modeling

pvpumpsystem.PVPumpSystem.define_motorpump_model(model)
pvpumpsystem.PVPumpSystem.operating_point([…])	Finds the IV operating point(s) of the PV array and the pump (load).
pvpumpsystem.PVPumpSystem.calc_flow([…])	Computes the flow at the output of the PVPS, and assigns the value to the attribute ‘flow’.
pvpumpsystem.PVPumpSystem.calc_efficiency()	Computes the efficiencies between PV array output and motorpump output, between irradiance and PV output, and global efficiency.
pvpumpsystem.PVPumpSystem.calc_reservoir([…])	Computes the water volume in the reservoir and extra or lacking water compared to the consumption at any time step.
pvpumpsystem.PVPumpSystem.run_model([…])	Comprehensive modeling of the PVPS.
pvpumpsystem.function_i_from_v(V, I_L, I_o, …)	Deprecated: ‘function_i_from_v’ deprecated.
pvpumpsystem.operating_point(params, …[, …])	Finds the IV operating point(s) between PV array and load (motor-pump).
pvpumpsystem.calc_flow_directly_coupled(…)	Computes input electrical characteristics, total dynamic head, and flow at pump output.
pvpumpsystem.calc_flow_mppt_coupled(…[, …])	Computes input electrical characteristics, total dynamic head, and flow at pump output.
pvpumpsystem.calc_efficiency(df, irradiance, …)	Computes the efficiencies between PV array output and motorpump output, between irradiance and PV output, and global efficiency.

Sizing tools

sizing.shrink_weather_representative(…[, …])	Create a new weather_data object representing the range of weather that can be found in the weather_data given.
sizing.shrink_weather_worst_month(weather_data)	Create a new weather_data object with only the worst month of the weather_data given, according to the global horizontal irradiance (ghi) data.
sizing.subset_respecting_llp_direct(…[, …])	Function returning the configurations of PV modules and pump that will minimize the net present value of the system and will insure the Loss of Load Probability (llp) is inferior to the one given.
sizing.size_nb_pv_direct(pvps_fixture, …)	Function sizing the PV generator (i.e.
sizing.subset_respecting_llp_mppt(…[, …])	Function returning the configurations of PV modules and pump that will minimize the net present value of the system and will ensure the Loss of Load Probability (llp) is inferior to the one given.
sizing.size_nb_pv_mppt(pvps_fixture, …)	Function sizing the PV generator (i.e.
sizing.sizing_minimize_npv(pv_database, …)	Function returning the configuration of PV modules and pump that minimizes the net present value (NPV) of the system and ensures that the Loss of Load Probability (llp) is inferior to the ‘llp_accepted’.

Ancillary functions

function_models.correlation_stats(funct_mod, …)	Compute statistical figures to assess quality of curve fitting.
function_models.compound_polynomial_1_2(…)	Model of a compound polynomial function made of a global equation of first order on x, for which each coefficient follows a second order equation on y.
function_models.compound_polynomial_1_3(…)	Model of a compound polynomial function made of a global equation of first order on x, for which each coefficient follows a third order equation on y.
function_models.compound_polynomial_2_2(…)	Model of a compound polynomial function made of a global equation of second order on x, for which each coefficient follows a third order equation on y.
function_models.compound_polynomial_2_3(…)	Model of a compound polynomial function made of a global equation of second order on x, for which each coefficient follows a third order equation on y.
function_models.compound_polynomial_3_3(…)	Model of a compound polynomial function made of a global equation of third order on x, for which each coefficient follows a third order equation on y.
function_models.polynomial_multivar_3_3_4(…)	Model of a multivariate polynomial function of third order on x and y, and with 1 interaction term.
function_models.polynomial_multivar_3_3_1(…)	Model of a multivariate polynomial function of third order on x and y, and with 1 interaction term.
function_models.polynomial_multivar_2_2_1(…)	Model of a multivariate polynomial function of second order on x and y, and with 1 interaction term.
function_models.polynomial_multivar_2_2_0(…)	Model of a multivariate polynomial function of second order on x and y, and with no interaction term.
function_models.polynomial_multivar_1_1_0(…)	Model of a multivariate polynomial function of first order on x and y, and with no interaction term.
function_models.polynomial_multivar_0_1_0(…)	Model of a multivariate polynomial function of first order on y (actually not really multivariate so).
function_models.polynomial_5(x, y_intercept, …)	Model of a polynomial function of fifth order.
function_models.polynomial_4(x, y_intercept, …)	Model of a polynomial function of fourth order.
function_models.polynomial_3(x, y_intercept, …)	Model of a polynomial function of third order.
function_models.polynomial_2(x, y_intercept, …)	Model of a polynomial function of second order.
function_models.polynomial_1(x, y_intercept, a)	Model of a polynomial function of first order, i.e.
function_models.polynomial_divided_2_1(x, a, …)	Model of a polynomial function of second order divided by x.
waterproperties.water_prop(name, T)	Function giving water property requested.
finance.initial_investment(pvps[, …])	Function computing the initial investment cost.
finance.net_present_value(pvps[, …])	Function computing the net present value of a PVPS

Citing pvpumpingsystem

—–still to come—— Paper currently under review at Journal of Open Source Software.