pycup


Namepycup JSON
Version 0.1.7.2 PyPI version JSON
download
home_pagehttps://github.com/QianyangWang/PyCUP
SummaryAn auto-calibration tool for environmental models based on heuristic algorithms and uncertainty estimation theory.
upload_time2023-06-08 11:39:43
maintainer
docs_urlNone
authorQianyang Wang
requires_python>=3
licenseMIT License
keywords optimization
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 0.07664s