# PyCUP
<img src="https://img.shields.io/badge/Version-0.1.7-brightgreen" /><img src="https://img.shields.io/badge/Language-Python-blue" />
This is an open-source package designed for (environmental) model calibration and uncertainty analysis. The current version is the very first version, we welcome all comments, suggestions, and improvements.
## v 0.1.7 Update
1. A new superior algorithm MOMFO (multi-objective moth-flame optimizer) based on archive and crowding distance non-domination sort, and its elite-opposition improved version (EO-MOMFO) have been designed and provided in the new version. The elite opposition mechanism was modified based on the concept of non-domination and was embedded for updating the flame population of MOMFO. The implemented MOMFO has a similar principle as the current literature, although with some differences in details, while the elite-opposition version is original in this package.
1. A "Mode" variable for MFO and MOMFO for switching the flame updating mechanism has been provided. A "Mode" value of 0 is for Mirjalili's original version, while a "Mode" value of 1 (default) is my modification. Details about the differences will be given in the upcoming algorithm introduction documentations.
## What does it have
### (1) For model calibration/optimization
1. Single-objective heuristic algorithms including PSO, GWO, MFO, SOA, SCA, SSA, TSA, and WOA.
2. Multi-objective heuristic algorithms including MOPSO, MODE, and NSGA-II.
3. Elite opposition strategy modified heuristic algorithms -- with better optimum search abilities.
4. Statistic based-method LHS-GLUE.
5. Three kinds of algorithm border check mechanisms including Absorb, Random, and Rebound, designed for different problems.
### (2) For sensitivity & uncertainty analysis
1. Likelihood uncertainty estimation used in the GLUE framework for the parameter uncertainty analysis/prediction uncertainty estimation.
2. The frequency based-uncertainty estimation method for the prediction uncertainty estimation.
3. The multi-linear regression method for the all-at-a-time parameter sensitivity based on statmodels.
### (3) Other convenient features
1. Multi-processing calibration.
2. Recording and resuming during the calibration task.
3. Several result plotting functions.
4. A special simulation result object for multi-station & multi-event results (of environmental models) in pycup.ResLib.
### (4) Package/Tools integration
1. PyCUP can be linked to spotpy database for post-processing, a pycup objective function can also be generated from the spotpy objective function using the module named pycup.integrate.
2. A basic integration with PEST++ IO operations for model-agnostic calibrations. Details and limitations are provided in the specific documentation. The required objective function for pycup calibration can be easily generated using a PEST++ optimization project with/without a tsproc.exe. The PESTconvertor object in pycup.integrate provides several APIs for reading PEST++ files such as .pst, .ins, and .tpl.
## How to install
The project has been uploaded onto the PyPI https://pypi.org/project/pycup/ . Or install the .whl file in the dist folder.
```
pip install pycup
```
## How to use
Here is a simple example. For more details, please see the documentation.
```python
import pycup as cp
import numpy as np
def uni_fun1(X):
# X for example np.array([1,2,3,...,30])
fitness = np.sum(np.power(X,2)) + 1 # example: 1.2
result = fitness.reshape(1,-1) # example ([1.2,])
return fitness,result
lb = -100 * np.ones(30)
ub = 100 * np.ones(30)
cp.SSA.run(pop = 1000, dim = 30, lb = lb, ub = ub, MaxIter = 30, fun = uni_fun1)
```
## Example SWMM (Storm Water Management Model) calibration projects
***IMPORTANT: PLEASE OPEN YOUR IDE (e.g. PYCHARM) OR COMMAND LINE WITH THE ADMINISTRATOR RIGHTS BEFORE EXECUTING THE EXAMPLE PROJECT***
#### Location: https://github.com/QianyangWang/PyCUP
1. The example in folder 'Example01-GLUE' contains an SWMM calibration project using single-processing GLUE. Install the dependencies (for example: pip install swmm-api==0.2.0.18.3, pip install pyswmm). Execute the 'Calibrate.py' to calibrate the model. Then, execute the 'PostProcessing.py' for uncertainty analysis.
2. The example in folder 'Example02-multiprocessing' contains an SWMM calibration project using multi-processing EOGWO.
3. The example in folder 'Example03-multiobjective' contains an SWMM multi-objective calibration project using EOMOPSO.
4. The example in folder 'Example04-validation&prediction' shows how to use our (Ensemble)Validator/(Ensemble)Predictor objects for the validation and prediction of the model using the calibrated parameter (set).
5. The example in folder 'Example05-multi-station&event' shows how to use the pycup.Reslib.SimulationResult object for the storage of multi-station & multi-event simulation results, as well as the further analysis using them.
<div align=center>
<img src="https://user-images.githubusercontent.com/116932670/209893309-e67c425f-0eff-47b4-a552-b30d717a138b.png">
</div>
## Example PEST++ conversion project (with a Xinanjiang hydrologic model)
1. The example in folder 'Example06-PESTintegration' contains a PEST++ Xinanjiang model calibration project and the python script to run a PyCUP calibration based on it.
Raw data
{
"_id": null,
"home_page": "https://github.com/QianyangWang/PyCUP",
"name": "pycup",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "",
"keywords": "optimization",
"author": "Qianyang Wang",
"author_email": "wqy07010944@hotmail.com",
"download_url": "https://files.pythonhosted.org/packages/b6/bf/02ae31c4285ac8357d06a670d56549882ee134306e8bdae3239ee345aa19/pycup-0.1.7.2.tar.gz",
"platform": null,
"description": "# PyCUP\n\n<img src=\"https://img.shields.io/badge/Version-0.1.7-brightgreen\" /><img src=\"https://img.shields.io/badge/Language-Python-blue\" />\t\n\nThis is an open-source package designed for (environmental) model calibration and uncertainty analysis. The current version is the very first version, we welcome all comments, suggestions, and improvements.\n\n## v 0.1.7 Update\n\n1. A new superior algorithm MOMFO (multi-objective moth-flame optimizer) based on archive and crowding distance non-domination sort, and its elite-opposition improved version (EO-MOMFO) have been designed and provided in the new version. The elite opposition mechanism was modified based on the concept of non-domination and was embedded for updating the flame population of MOMFO. The implemented MOMFO has a similar principle as the current literature, although with some differences in details, while the elite-opposition version is original in this package.\n1. A \"Mode\" variable for MFO and MOMFO for switching the flame updating mechanism has been provided. A \"Mode\" value of 0 is for Mirjalili's original version, while a \"Mode\" value of 1 (default) is my modification. Details about the differences will be given in the upcoming algorithm introduction documentations.\n\n## What does it have\n\n### (1) For model calibration/optimization\n\n1. Single-objective heuristic algorithms including PSO, GWO, MFO, SOA, SCA, SSA, TSA, and WOA.\n2. Multi-objective heuristic algorithms including MOPSO, MODE, and NSGA-II.\n3. Elite opposition strategy modified heuristic algorithms -- with better optimum search abilities.\n4. Statistic based-method LHS-GLUE.\n5. Three kinds of algorithm border check mechanisms including Absorb, Random, and Rebound, designed for different problems.\n\n### (2) For sensitivity & uncertainty analysis\n\n1. Likelihood uncertainty estimation used in the GLUE framework for the parameter uncertainty analysis/prediction uncertainty estimation.\n2. The frequency based-uncertainty estimation method for the prediction uncertainty estimation.\n3. The multi-linear regression method for the all-at-a-time parameter sensitivity based on statmodels.\n\n### (3) Other convenient features\n\n1. Multi-processing calibration.\n2. Recording and resuming during the calibration task.\n3. Several result plotting functions.\n4. A special simulation result object for multi-station & multi-event results (of environmental models) in pycup.ResLib.\n\n### (4) Package/Tools integration\n\n1. PyCUP can be linked to spotpy database for post-processing, a pycup objective function can also be generated from the spotpy objective function using the module named pycup.integrate.\n2. A basic integration with PEST++ IO operations for model-agnostic calibrations. Details and limitations are provided in the specific documentation. The required objective function for pycup calibration can be easily generated using a PEST++ optimization project with/without a tsproc.exe. The PESTconvertor object in pycup.integrate provides several APIs for reading PEST++ files such as .pst, .ins, and .tpl.\n\n## How to install\n\n\u200b\tThe project has been uploaded onto the PyPI https://pypi.org/project/pycup/ . Or install the .whl file in the dist folder.\n\n```\npip install pycup\n```\n\n## How to use\n\n\u200b\tHere is a simple example. For more details, please see the documentation.\n\n```python\nimport pycup as cp\nimport numpy as np\n\ndef uni_fun1(X):\n\t# X for example np.array([1,2,3,...,30])\n fitness = np.sum(np.power(X,2)) + 1 # example: 1.2\n result = fitness.reshape(1,-1) # example ([1.2,])\n\n return fitness,result\n\nlb = -100 * np.ones(30)\nub = 100 * np.ones(30)\ncp.SSA.run(pop = 1000, dim = 30, lb = lb, ub = ub, MaxIter = 30, fun = uni_fun1)\n```\n\n## Example SWMM (Storm Water Management Model) calibration projects\n\n***IMPORTANT: PLEASE OPEN YOUR IDE (e.g. PYCHARM) OR COMMAND LINE WITH THE ADMINISTRATOR RIGHTS BEFORE EXECUTING THE EXAMPLE PROJECT***\n\n#### Location: https://github.com/QianyangWang/PyCUP\n\n1. The example in folder 'Example01-GLUE' contains an SWMM calibration project using single-processing GLUE. Install the dependencies (for example: pip install swmm-api==0.2.0.18.3, pip install pyswmm). Execute the 'Calibrate.py' to calibrate the model. Then, execute the 'PostProcessing.py' for uncertainty analysis.\n2. The example in folder 'Example02-multiprocessing' contains an SWMM calibration project using multi-processing EOGWO.\n3. The example in folder 'Example03-multiobjective' contains an SWMM multi-objective calibration project using EOMOPSO. \n4. The example in folder 'Example04-validation&prediction' shows how to use our (Ensemble)Validator/(Ensemble)Predictor objects for the validation and prediction of the model using the calibrated parameter (set).\n5. The example in folder 'Example05-multi-station&event' shows how to use the pycup.Reslib.SimulationResult object for the storage of multi-station & multi-event simulation results, as well as the further analysis using them.\n\n<div align=center>\n<img src=\"https://user-images.githubusercontent.com/116932670/209893309-e67c425f-0eff-47b4-a552-b30d717a138b.png\">\n</div>\n\n## Example PEST++ conversion project (with a Xinanjiang hydrologic model)\n\n1. The example in folder 'Example06-PESTintegration' contains a PEST++ Xinanjiang model calibration project and the python script to run a PyCUP calibration based on it.\n\n\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "An auto-calibration tool for environmental models based on heuristic algorithms and uncertainty estimation theory.",
"version": "0.1.7.2",
"project_urls": {
"Documentation": "https://github.com/QianyangWang/PyCUP/DOCUMENT",
"Homepage": "https://github.com/QianyangWang/PyCUP",
"Source": "https://github.com/QianyangWang/PyCUP/pycup"
},
"split_keywords": [
"optimization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5e544d23077693c62dce1485d5bd93a443e1831109b56a91fb4fe9196a6420d2",
"md5": "893c59926f1ca81011cde80de5761484",
"sha256": "f8edc12d0ac3afabb92fca2590e3f0ff0f0bc498e6bcf089d949bb4322721e51"
},
"downloads": -1,
"filename": "pycup-0.1.7.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "893c59926f1ca81011cde80de5761484",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 890996,
"upload_time": "2023-06-08T11:39:41",
"upload_time_iso_8601": "2023-06-08T11:39:41.359479Z",
"url": "https://files.pythonhosted.org/packages/5e/54/4d23077693c62dce1485d5bd93a443e1831109b56a91fb4fe9196a6420d2/pycup-0.1.7.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b6bf02ae31c4285ac8357d06a670d56549882ee134306e8bdae3239ee345aa19",
"md5": "3c98fc567f9c800195ad14e3c2c45deb",
"sha256": "5fa88b87e93c3987496dc1b3a8b9320e18d4d62c2f5e9d0cef9765bd64140f92"
},
"downloads": -1,
"filename": "pycup-0.1.7.2.tar.gz",
"has_sig": false,
"md5_digest": "3c98fc567f9c800195ad14e3c2c45deb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 866070,
"upload_time": "2023-06-08T11:39:43",
"upload_time_iso_8601": "2023-06-08T11:39:43.835463Z",
"url": "https://files.pythonhosted.org/packages/b6/bf/02ae31c4285ac8357d06a670d56549882ee134306e8bdae3239ee345aa19/pycup-0.1.7.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-08 11:39:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "QianyangWang",
"github_project": "PyCUP",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pycup"
}
JSON
