├── .github └── workflows │ ├── linting.yml │ ├── publish.yml │ └── testing.yml ├── .gitignore ├── LICENSE ├── MANIFEST.in ├── README.md ├── docs ├── api │ ├── filereader.md │ ├── swatproblem.md │ ├── swatproblemmultimodel.md │ └── txtinoutreader.md ├── citation.md ├── examples │ ├── basic_examples.ipynb │ ├── calibration.ipynb │ └── sensitivity_analysis.ipynb ├── getting-started.md └── index.md ├── mkdocs.yml ├── pySWATPlus ├── FileReader.py ├── PymooBestSolution.py ├── SWATProblem.py ├── SWATProblemMultimodel.py ├── TxtinoutReader.py └── __init__.py ├── pyproject.toml ├── requirements.txt ├── setup.cfg └── tests ├── sample_data └── aquifer_yr.txt └── test_filereader.py /.github/workflows/linting.yml: -------------------------------------------------------------------------------- 1 | name: flake8 2 | 3 | on: 4 | push: 5 | branches: 6 | - main # Your branch name 7 | paths: 8 | - '**/*.py' # Trigger only for changes in Python files 9 | pull_request: 10 | branches: 11 | - main # Your branch name 12 | paths: 13 | - '**/*.py' # Trigger only for changes in Python files 14 | 15 | jobs: 16 | build: 17 | runs-on: ubuntu-latest 18 | strategy: 19 | fail-fast: false 20 | matrix: 21 | python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"] 22 | 23 | steps: 24 | - uses: actions/checkout@v4 25 | 26 | - name: Set up Python ${{ matrix.python-version }} 27 | uses: actions/setup-python@v3 28 | with: 29 | python-version: ${{ matrix.python-version }} 30 | 31 | - name: Install dependencies 32 | run: | 33 | python -m pip install --upgrade pip 34 | python -m pip install flake8 35 | 36 | - name: Lint with flake8 37 | run: | 38 | flake8 . --count --exit-zero --max-complexity=10 --statistics -------------------------------------------------------------------------------- /.github/workflows/publish.yml: -------------------------------------------------------------------------------- 1 | name: Publish to PyPI and GitHub Release 2 | 3 | on: 4 | push: 5 | tags: 6 | - "v*" # Only trigger when pushing a version tag like v1.2.3 7 | 8 | jobs: 9 | build-and-publish: 10 | runs-on: ubuntu-latest 11 | 12 | permissions: 13 | contents: write # Required to create a release 14 | 15 | steps: 16 | - name: Checkout repository 17 | uses: actions/checkout@v4 18 | with: 19 | fetch-depth: 0 # Ensure full Git history for setuptools-scm 20 | 21 | - name: Set up Python 22 | uses: actions/setup-python@v4 23 | with: 24 | python-version: '3.x' 25 | 26 | - name: Install dependencies 27 | run: | 28 | python -m pip install --upgrade pip 29 | pip install build twine setuptools-scm 30 | 31 | - name: Verify version from tag 32 | id: get_version 33 | run: | 34 | TAG_VERSION=${GITHUB_REF#refs/tags/v} # Extract version from 'vX.Y.Z' 35 | echo "VERSION=$TAG_VERSION" >> $GITHUB_ENV 36 | echo "Publishing version: $TAG_VERSION" 37 | 38 | - name: Build package (pyproject.toml) 39 | run: python -m build 40 | 41 | - name: Publish to PyPI 42 | env: 43 | TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }} 44 | TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }} 45 | run: | 46 | twine upload dist/* 47 | 48 | - name: Create GitHub Release 49 | env: 50 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 51 | run: | 52 | gh release create ${{ github.ref_name }} dist/* --title "Release ${{ github.ref_name }}" --notes "Automated release for version ${{ github.ref_name }}" 53 | 54 | 55 | deploy-docs: 56 | runs-on: ubuntu-latest 57 | 58 | permissions: 59 | contents: write # Allow pushing to the repository 60 | 61 | needs: build-and-publish # Ensure this runs after the build-and-publish job 62 | steps: 63 | - name: Checkout repository 64 | uses: actions/checkout@v4 65 | 66 | - name: Set up Python 67 | uses: actions/setup-python@v4 68 | with: 69 | python-version: '3.x' 70 | 71 | - name: Install MkDocs and dependencies 72 | run: | 73 | pip install mkdocs mkdocs-material mkdocstrings mkdocstrings-python mkdocs-jupyter pymdown-extensions 74 | 75 | - name: Build MkDocs documentation 76 | run: | 77 | mkdocs build --site-dir public 78 | 79 | - name: Deploy to GitHub Pages 80 | uses: peaceiris/actions-gh-pages@v3 81 | with: 82 | github_token: ${{ secrets.GITHUB_TOKEN }} 83 | publish_dir: ./public -------------------------------------------------------------------------------- /.github/workflows/testing.yml: -------------------------------------------------------------------------------- 1 | name: pytest 2 | 3 | on: 4 | push: 5 | branches: 6 | - main # Your branch name 7 | paths: 8 | - '**/*.py' # Trigger for changes in Python files 9 | pull_request: 10 | branches: 11 | - main # Your branch name 12 | paths: 13 | - '**/*.py' # Trigger for changes in Python files 14 | 15 | jobs: 16 | build: 17 | runs-on: ubuntu-latest 18 | strategy: 19 | fail-fast: false 20 | matrix: 21 | python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"] 22 | 23 | steps: 24 | - uses: actions/checkout@v4 25 | 26 | - name: Set up Python ${{ matrix.python-version }} 27 | uses: actions/setup-python@v3 28 | with: 29 | python-version: ${{ matrix.python-version }} 30 | 31 | - name: Install dependencies 32 | run: | 33 | python -m pip install --upgrade pip 34 | python -m pip install -r requirements.txt # Install dependencies 35 | 36 | - name: Run tests with pytest 37 | run: | 38 | export PYTHONPATH=$(pwd) 39 | pytest --cov-report=xml:coverage.xml 40 | 41 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | 2 | #folder generated by mkdocs 3 | public/ 4 | 5 | # Byte-compiled / optimized / DLL files 6 | __pycache__/ 7 | *.py[cod] 8 | *$py.class 9 | 10 | # C extensions 11 | *.so 12 | 13 | # Distribution / packaging 14 | *.egg-info/ 15 | *.egg 16 | *.egg-info 17 | *.tar.gz 18 | *.whl 19 | .Python 20 | build/ 21 | develop-eggs/ 22 | dist/ 23 | downloads/ 24 | eggs/ 25 | .eggs/ 26 | lib/ 27 | lib64/ 28 | parts/ 29 | sdist/ 30 | var/ 31 | wheels/ 32 | share/python-wheels/ 33 | *.egg-info/ 34 | .installed.cfg 35 | *.egg 36 | MANIFEST 37 | 38 | # PyInstaller 39 | # Usually these files are written by a python script from a template 40 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 41 | *.manifest 42 | *.spec 43 | 44 | # Installer logs 45 | pip-log.txt 46 | pip-delete-this-directory.txt 47 | 48 | # Unit test / coverage reports 49 | htmlcov/ 50 | .tox/ 51 | .nox/ 52 | .coverage 53 | .coverage.* 54 | .cache 55 | nosetests.xml 56 | coverage.xml 57 | *.cover 58 | *.py,cover 59 | .hypothesis/ 60 | .pytest_cache/ 61 | cover/ 62 | 63 | # Translations 64 | *.mo 65 | *.pot 66 | 67 | # Django stuff: 68 | *.log 69 | local_settings.py 70 | db.sqlite3 71 | db.sqlite3-journal 72 | 73 | # Flask stuff: 74 | instance/ 75 | .webassets-cache 76 | 77 | # Scrapy stuff: 78 | .scrapy 79 | 80 | # Sphinx documentation 81 | docs/_build/ 82 | 83 | # PyBuilder 84 | .pybuilder/ 85 | target/ 86 | 87 | # Jupyter Notebook 88 | .ipynb_checkpoints 89 | 90 | # IPython 91 | profile_default/ 92 | ipython_config.py 93 | 94 | # pyenv 95 | # For a library or package, you might want to ignore these files since the code is 96 | # intended to run in multiple environments; otherwise, check them in: 97 | # .python-version 98 | 99 | # pipenv 100 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. 101 | # However, in case of collaboration, if having platform-specific dependencies or dependencies 102 | # having no cross-platform support, pipenv may install dependencies that don't work, or not 103 | # install all needed dependencies. 104 | #Pipfile.lock 105 | 106 | # poetry 107 | # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. 108 | # This is especially recommended for binary packages to ensure reproducibility, and is more 109 | # commonly ignored for libraries. 110 | # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control 111 | #poetry.lock 112 | 113 | # pdm 114 | # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. 115 | #pdm.lock 116 | # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it 117 | # in version control. 118 | # https://pdm.fming.dev/#use-with-ide 119 | .pdm.toml 120 | 121 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm 122 | __pypackages__/ 123 | 124 | # Celery stuff 125 | celerybeat-schedule 126 | celerybeat.pid 127 | 128 | # SageMath parsed files 129 | *.sage.py 130 | 131 | # Environments 132 | .env 133 | .venv 134 | env/ 135 | venv/ 136 | ENV/ 137 | env.bak/ 138 | venv.bak/ 139 | 140 | # Spyder project settings 141 | .spyderproject 142 | .spyproject 143 | 144 | # Rope project settings 145 | .ropeproject 146 | 147 | # mkdocs documentation 148 | /site 149 | 150 | # mypy 151 | .mypy_cache/ 152 | .dmypy.json 153 | dmypy.json 154 | 155 | # Pyre type checker 156 | .pyre/ 157 | 158 | # pytype static type analyzer 159 | .pytype/ 160 | 161 | # Cython debug symbols 162 | cython_debug/ 163 | 164 | # PyCharm 165 | # JetBrains specific template is maintained in a separate JetBrains.gitignore that can 166 | # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore 167 | # and can be added to the global gitignore or merged into this file. For a more nuclear 168 | # option (not recommended) you can uncomment the following to ignore the entire idea folder. 169 | #.idea/ 170 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 3, 29 June 2007 3 | 4 | Copyright (C) 2007 Free Software Foundation, Inc. 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | The GNU General Public License is a free, copyleft license for 11 | software and other kinds of works. 12 | 13 | The licenses for most software and other practical works are designed 14 | to take away your freedom to share and change the works. By contrast, 15 | the GNU General Public License is intended to guarantee your freedom to 16 | share and change all versions of a program--to make sure it remains free 17 | software for all its users. We, the Free Software Foundation, use the 18 | GNU General Public License for most of our software; it applies also to 19 | any other work released this way by its authors. You can apply it to 20 | your programs, too. 21 | 22 | When we speak of free software, we are referring to freedom, not 23 | price. Our General Public Licenses are designed to make sure that you 24 | have the freedom to distribute copies of free software (and charge for 25 | them if you wish), that you receive source code or can get it if you 26 | want it, that you can change the software or use pieces of it in new 27 | free programs, and that you know you can do these things. 28 | 29 | To protect your rights, we need to prevent others from denying you 30 | these rights or asking you to surrender the rights. Therefore, you have 31 | certain responsibilities if you distribute copies of the software, or if 32 | you modify it: responsibilities to respect the freedom of others. 33 | 34 | For example, if you distribute copies of such a program, whether 35 | gratis or for a fee, you must pass on to the recipients the same 36 | freedoms that you received. You must make sure that they, too, receive 37 | or can get the source code. And you must show them these terms so they 38 | know their rights. 39 | 40 | Developers that use the GNU GPL protect your rights with two steps: 41 | (1) assert copyright on the software, and (2) offer you this License 42 | giving you legal permission to copy, distribute and/or modify it. 43 | 44 | For the developers' and authors' protection, the GPL clearly explains 45 | that there is no warranty for this free software. For both users' and 46 | authors' sake, the GPL requires that modified versions be marked as 47 | changed, so that their problems will not be attributed erroneously to 48 | authors of previous versions. 49 | 50 | Some devices are designed to deny users access to install or run 51 | modified versions of the software inside them, although the manufacturer 52 | can do so. This is fundamentally incompatible with the aim of 53 | protecting users' freedom to change the software. The systematic 54 | pattern of such abuse occurs in the area of products for individuals to 55 | use, which is precisely where it is most unacceptable. Therefore, we 56 | have designed this version of the GPL to prohibit the practice for those 57 | products. If such problems arise substantially in other domains, we 58 | stand ready to extend this provision to those domains in future versions 59 | of the GPL, as needed to protect the freedom of users. 60 | 61 | Finally, every program is threatened constantly by software patents. 62 | States should not allow patents to restrict development and use of 63 | software on general-purpose computers, but in those that do, we wish to 64 | avoid the special danger that patents applied to a free program could 65 | make it effectively proprietary. To prevent this, the GPL assures that 66 | patents cannot be used to render the program non-free. 67 | 68 | The precise terms and conditions for copying, distribution and 69 | modification follow. 70 | 71 | TERMS AND CONDITIONS 72 | 73 | 0. Definitions. 74 | 75 | "This License" refers to version 3 of the GNU General Public License. 76 | 77 | "Copyright" also means copyright-like laws that apply to other kinds of 78 | works, such as semiconductor masks. 79 | 80 | "The Program" refers to any copyrightable work licensed under this 81 | License. Each licensee is addressed as "you". "Licensees" and 82 | "recipients" may be individuals or organizations. 83 | 84 | To "modify" a work means to copy from or adapt all or part of the work 85 | in a fashion requiring copyright permission, other than the making of an 86 | exact copy. The resulting work is called a "modified version" of the 87 | earlier work or a work "based on" the earlier work. 88 | 89 | A "covered work" means either the unmodified Program or a work based 90 | on the Program. 91 | 92 | To "propagate" a work means to do anything with it that, without 93 | permission, would make you directly or secondarily liable for 94 | infringement under applicable copyright law, except executing it on a 95 | computer or modifying a private copy. Propagation includes copying, 96 | distribution (with or without modification), making available to the 97 | public, and in some countries other activities as well. 98 | 99 | To "convey" a work means any kind of propagation that enables other 100 | parties to make or receive copies. Mere interaction with a user through 101 | a computer network, with no transfer of a copy, is not conveying. 102 | 103 | An interactive user interface displays "Appropriate Legal Notices" 104 | to the extent that it includes a convenient and prominently visible 105 | feature that (1) displays an appropriate copyright notice, and (2) 106 | tells the user that there is no warranty for the work (except to the 107 | extent that warranties are provided), that licensees may convey the 108 | work under this License, and how to view a copy of this License. If 109 | the interface presents a list of user commands or options, such as a 110 | menu, a prominent item in the list meets this criterion. 111 | 112 | 1. Source Code. 113 | 114 | The "source code" for a work means the preferred form of the work 115 | for making modifications to it. "Object code" means any non-source 116 | form of a work. 117 | 118 | A "Standard Interface" means an interface that either is an official 119 | standard defined by a recognized standards body, or, in the case of 120 | interfaces specified for a particular programming language, one that 121 | is widely used among developers working in that language. 122 | 123 | The "System Libraries" of an executable work include anything, other 124 | than the work as a whole, that (a) is included in the normal form of 125 | packaging a Major Component, but which is not part of that Major 126 | Component, and (b) serves only to enable use of the work with that 127 | Major Component, or to implement a Standard Interface for which an 128 | implementation is available to the public in source code form. A 129 | "Major Component", in this context, means a major essential component 130 | (kernel, window system, and so on) of the specific operating system 131 | (if any) on which the executable work runs, or a compiler used to 132 | produce the work, or an object code interpreter used to run it. 133 | 134 | The "Corresponding Source" for a work in object code form means all 135 | the source code needed to generate, install, and (for an executable 136 | work) run the object code and to modify the work, including scripts to 137 | control those activities. However, it does not include the work's 138 | System Libraries, or general-purpose tools or generally available free 139 | programs which are used unmodified in performing those activities but 140 | which are not part of the work. For example, Corresponding Source 141 | includes interface definition files associated with source files for 142 | the work, and the source code for shared libraries and dynamically 143 | linked subprograms that the work is specifically designed to require, 144 | such as by intimate data communication or control flow between those 145 | subprograms and other parts of the work. 146 | 147 | The Corresponding Source need not include anything that users 148 | can regenerate automatically from other parts of the Corresponding 149 | Source. 150 | 151 | The Corresponding Source for a work in source code form is that 152 | same work. 153 | 154 | 2. Basic Permissions. 155 | 156 | All rights granted under this License are granted for the term of 157 | copyright on the Program, and are irrevocable provided the stated 158 | conditions are met. This License explicitly affirms your unlimited 159 | permission to run the unmodified Program. The output from running a 160 | covered work is covered by this License only if the output, given its 161 | content, constitutes a covered work. This License acknowledges your 162 | rights of fair use or other equivalent, as provided by copyright law. 163 | 164 | You may make, run and propagate covered works that you do not 165 | convey, without conditions so long as your license otherwise remains 166 | in force. You may convey covered works to others for the sole purpose 167 | of having them make modifications exclusively for you, or provide you 168 | with facilities for running those works, provided that you comply with 169 | the terms of this License in conveying all material for which you do 170 | not control copyright. Those thus making or running the covered works 171 | for you must do so exclusively on your behalf, under your direction 172 | and control, on terms that prohibit them from making any copies of 173 | your copyrighted material outside their relationship with you. 174 | 175 | Conveying under any other circumstances is permitted solely under 176 | the conditions stated below. Sublicensing is not allowed; section 10 177 | makes it unnecessary. 178 | 179 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law. 180 | 181 | No covered work shall be deemed part of an effective technological 182 | measure under any applicable law fulfilling obligations under article 183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or 184 | similar laws prohibiting or restricting circumvention of such 185 | measures. 186 | 187 | When you convey a covered work, you waive any legal power to forbid 188 | circumvention of technological measures to the extent such circumvention 189 | is effected by exercising rights under this License with respect to 190 | the covered work, and you disclaim any intention to limit operation or 191 | modification of the work as a means of enforcing, against the work's 192 | users, your or third parties' legal rights to forbid circumvention of 193 | technological measures. 194 | 195 | 4. Conveying Verbatim Copies. 196 | 197 | You may convey verbatim copies of the Program's source code as you 198 | receive it, in any medium, provided that you conspicuously and 199 | appropriately publish on each copy an appropriate copyright notice; 200 | keep intact all notices stating that this License and any 201 | non-permissive terms added in accord with section 7 apply to the code; 202 | keep intact all notices of the absence of any warranty; and give all 203 | recipients a copy of this License along with the Program. 204 | 205 | You may charge any price or no price for each copy that you convey, 206 | and you may offer support or warranty protection for a fee. 207 | 208 | 5. Conveying Modified Source Versions. 209 | 210 | You may convey a work based on the Program, or the modifications to 211 | produce it from the Program, in the form of source code under the 212 | terms of section 4, provided that you also meet all of these conditions: 213 | 214 | a) The work must carry prominent notices stating that you modified 215 | it, and giving a relevant date. 216 | 217 | b) The work must carry prominent notices stating that it is 218 | released under this License and any conditions added under section 219 | 7. This requirement modifies the requirement in section 4 to 220 | "keep intact all notices". 221 | 222 | c) You must license the entire work, as a whole, under this 223 | License to anyone who comes into possession of a copy. This 224 | License will therefore apply, along with any applicable section 7 225 | additional terms, to the whole of the work, and all its parts, 226 | regardless of how they are packaged. This License gives no 227 | permission to license the work in any other way, but it does not 228 | invalidate such permission if you have separately received it. 229 | 230 | d) If the work has interactive user interfaces, each must display 231 | Appropriate Legal Notices; however, if the Program has interactive 232 | interfaces that do not display Appropriate Legal Notices, your 233 | work need not make them do so. 234 | 235 | A compilation of a covered work with other separate and independent 236 | works, which are not by their nature extensions of the covered work, 237 | and which are not combined with it such as to form a larger program, 238 | in or on a volume of a storage or distribution medium, is called an 239 | "aggregate" if the compilation and its resulting copyright are not 240 | used to limit the access or legal rights of the compilation's users 241 | beyond what the individual works permit. Inclusion of a covered work 242 | in an aggregate does not cause this License to apply to the other 243 | parts of the aggregate. 244 | 245 | 6. Conveying Non-Source Forms. 246 | 247 | You may convey a covered work in object code form under the terms 248 | of sections 4 and 5, provided that you also convey the 249 | machine-readable Corresponding Source under the terms of this License, 250 | in one of these ways: 251 | 252 | a) Convey the object code in, or embodied in, a physical product 253 | (including a physical distribution medium), accompanied by the 254 | Corresponding Source fixed on a durable physical medium 255 | customarily used for software interchange. 256 | 257 | b) Convey the object code in, or embodied in, a physical product 258 | (including a physical distribution medium), accompanied by a 259 | written offer, valid for at least three years and valid for as 260 | long as you offer spare parts or customer support for that product 261 | model, to give anyone who possesses the object code either (1) a 262 | copy of the Corresponding Source for all the software in the 263 | product that is covered by this License, on a durable physical 264 | medium customarily used for software interchange, for a price no 265 | more than your reasonable cost of physically performing this 266 | conveying of source, or (2) access to copy the 267 | Corresponding Source from a network server at no charge. 268 | 269 | c) Convey individual copies of the object code with a copy of the 270 | written offer to provide the Corresponding Source. This 271 | alternative is allowed only occasionally and noncommercially, and 272 | only if you received the object code with such an offer, in accord 273 | with subsection 6b. 274 | 275 | d) Convey the object code by offering access from a designated 276 | place (gratis or for a charge), and offer equivalent access to the 277 | Corresponding Source in the same way through the same place at no 278 | further charge. You need not require recipients to copy the 279 | Corresponding Source along with the object code. If the place to 280 | copy the object code is a network server, the Corresponding Source 281 | may be on a different server (operated by you or a third party) 282 | that supports equivalent copying facilities, provided you maintain 283 | clear directions next to the object code saying where to find the 284 | Corresponding Source. Regardless of what server hosts the 285 | Corresponding Source, you remain obligated to ensure that it is 286 | available for as long as needed to satisfy these requirements. 287 | 288 | e) Convey the object code using peer-to-peer transmission, provided 289 | you inform other peers where the object code and Corresponding 290 | Source of the work are being offered to the general public at no 291 | charge under subsection 6d. 292 | 293 | A separable portion of the object code, whose source code is excluded 294 | from the Corresponding Source as a System Library, need not be 295 | included in conveying the object code work. 296 | 297 | A "User Product" is either (1) a "consumer product", which means any 298 | tangible personal property which is normally used for personal, family, 299 | or household purposes, or (2) anything designed or sold for incorporation 300 | into a dwelling. In determining whether a product is a consumer product, 301 | doubtful cases shall be resolved in favor of coverage. For a particular 302 | product received by a particular user, "normally used" refers to a 303 | typical or common use of that class of product, regardless of the status 304 | of the particular user or of the way in which the particular user 305 | actually uses, or expects or is expected to use, the product. A product 306 | is a consumer product regardless of whether the product has substantial 307 | commercial, industrial or non-consumer uses, unless such uses represent 308 | the only significant mode of use of the product. 309 | 310 | "Installation Information" for a User Product means any methods, 311 | procedures, authorization keys, or other information required to install 312 | and execute modified versions of a covered work in that User Product from 313 | a modified version of its Corresponding Source. The information must 314 | suffice to ensure that the continued functioning of the modified object 315 | code is in no case prevented or interfered with solely because 316 | modification has been made. 317 | 318 | If you convey an object code work under this section in, or with, or 319 | specifically for use in, a User Product, and the conveying occurs as 320 | part of a transaction in which the right of possession and use of the 321 | User Product is transferred to the recipient in perpetuity or for a 322 | fixed term (regardless of how the transaction is characterized), the 323 | Corresponding Source conveyed under this section must be accompanied 324 | by the Installation Information. But this requirement does not apply 325 | if neither you nor any third party retains the ability to install 326 | modified object code on the User Product (for example, the work has 327 | been installed in ROM). 328 | 329 | The requirement to provide Installation Information does not include a 330 | requirement to continue to provide support service, warranty, or updates 331 | for a work that has been modified or installed by the recipient, or for 332 | the User Product in which it has been modified or installed. Access to a 333 | network may be denied when the modification itself materially and 334 | adversely affects the operation of the network or violates the rules and 335 | protocols for communication across the network. 336 | 337 | Corresponding Source conveyed, and Installation Information provided, 338 | in accord with this section must be in a format that is publicly 339 | documented (and with an implementation available to the public in 340 | source code form), and must require no special password or key for 341 | unpacking, reading or copying. 342 | 343 | 7. Additional Terms. 344 | 345 | "Additional permissions" are terms that supplement the terms of this 346 | License by making exceptions from one or more of its conditions. 347 | Additional permissions that are applicable to the entire Program shall 348 | be treated as though they were included in this License, to the extent 349 | that they are valid under applicable law. If additional permissions 350 | apply only to part of the Program, that part may be used separately 351 | under those permissions, but the entire Program remains governed by 352 | this License without regard to the additional permissions. 353 | 354 | When you convey a copy of a covered work, you may at your option 355 | remove any additional permissions from that copy, or from any part of 356 | it. (Additional permissions may be written to require their own 357 | removal in certain cases when you modify the work.) You may place 358 | additional permissions on material, added by you to a covered work, 359 | for which you have or can give appropriate copyright permission. 360 | 361 | Notwithstanding any other provision of this License, for material you 362 | add to a covered work, you may (if authorized by the copyright holders of 363 | that material) supplement the terms of this License with terms: 364 | 365 | a) Disclaiming warranty or limiting liability differently from the 366 | terms of sections 15 and 16 of this License; or 367 | 368 | b) Requiring preservation of specified reasonable legal notices or 369 | author attributions in that material or in the Appropriate Legal 370 | Notices displayed by works containing it; or 371 | 372 | c) Prohibiting misrepresentation of the origin of that material, or 373 | requiring that modified versions of such material be marked in 374 | reasonable ways as different from the original version; or 375 | 376 | d) Limiting the use for publicity purposes of names of licensors or 377 | authors of the material; or 378 | 379 | e) Declining to grant rights under trademark law for use of some 380 | trade names, trademarks, or service marks; or 381 | 382 | f) Requiring indemnification of licensors and authors of that 383 | material by anyone who conveys the material (or modified versions of 384 | it) with contractual assumptions of liability to the recipient, for 385 | any liability that these contractual assumptions directly impose on 386 | those licensors and authors. 387 | 388 | All other non-permissive additional terms are considered "further 389 | restrictions" within the meaning of section 10. If the Program as you 390 | received it, or any part of it, contains a notice stating that it is 391 | governed by this License along with a term that is a further 392 | restriction, you may remove that term. If a license document contains 393 | a further restriction but permits relicensing or conveying under this 394 | License, you may add to a covered work material governed by the terms 395 | of that license document, provided that the further restriction does 396 | not survive such relicensing or conveying. 397 | 398 | If you add terms to a covered work in accord with this section, you 399 | must place, in the relevant source files, a statement of the 400 | additional terms that apply to those files, or a notice indicating 401 | where to find the applicable terms. 402 | 403 | Additional terms, permissive or non-permissive, may be stated in the 404 | form of a separately written license, or stated as exceptions; 405 | the above requirements apply either way. 406 | 407 | 8. Termination. 408 | 409 | You may not propagate or modify a covered work except as expressly 410 | provided under this License. Any attempt otherwise to propagate or 411 | modify it is void, and will automatically terminate your rights under 412 | this License (including any patent licenses granted under the third 413 | paragraph of section 11). 414 | 415 | However, if you cease all violation of this License, then your 416 | license from a particular copyright holder is reinstated (a) 417 | provisionally, unless and until the copyright holder explicitly and 418 | finally terminates your license, and (b) permanently, if the copyright 419 | holder fails to notify you of the violation by some reasonable means 420 | prior to 60 days after the cessation. 421 | 422 | Moreover, your license from a particular copyright holder is 423 | reinstated permanently if the copyright holder notifies you of the 424 | violation by some reasonable means, this is the first time you have 425 | received notice of violation of this License (for any work) from that 426 | copyright holder, and you cure the violation prior to 30 days after 427 | your receipt of the notice. 428 | 429 | Termination of your rights under this section does not terminate the 430 | licenses of parties who have received copies or rights from you under 431 | this License. If your rights have been terminated and not permanently 432 | reinstated, you do not qualify to receive new licenses for the same 433 | material under section 10. 434 | 435 | 9. Acceptance Not Required for Having Copies. 436 | 437 | You are not required to accept this License in order to receive or 438 | run a copy of the Program. Ancillary propagation of a covered work 439 | occurring solely as a consequence of using peer-to-peer transmission 440 | to receive a copy likewise does not require acceptance. However, 441 | nothing other than this License grants you permission to propagate or 442 | modify any covered work. These actions infringe copyright if you do 443 | not accept this License. Therefore, by modifying or propagating a 444 | covered work, you indicate your acceptance of this License to do so. 445 | 446 | 10. Automatic Licensing of Downstream Recipients. 447 | 448 | Each time you convey a covered work, the recipient automatically 449 | receives a license from the original licensors, to run, modify and 450 | propagate that work, subject to this License. You are not responsible 451 | for enforcing compliance by third parties with this License. 452 | 453 | An "entity transaction" is a transaction transferring control of an 454 | organization, or substantially all assets of one, or subdividing an 455 | organization, or merging organizations. If propagation of a covered 456 | work results from an entity transaction, each party to that 457 | transaction who receives a copy of the work also receives whatever 458 | licenses to the work the party's predecessor in interest had or could 459 | give under the previous paragraph, plus a right to possession of the 460 | Corresponding Source of the work from the predecessor in interest, if 461 | the predecessor has it or can get it with reasonable efforts. 462 | 463 | You may not impose any further restrictions on the exercise of the 464 | rights granted or affirmed under this License. For example, you may 465 | not impose a license fee, royalty, or other charge for exercise of 466 | rights granted under this License, and you may not initiate litigation 467 | (including a cross-claim or counterclaim in a lawsuit) alleging that 468 | any patent claim is infringed by making, using, selling, offering for 469 | sale, or importing the Program or any portion of it. 470 | 471 | 11. Patents. 472 | 473 | A "contributor" is a copyright holder who authorizes use under this 474 | License of the Program or a work on which the Program is based. The 475 | work thus licensed is called the contributor's "contributor version". 476 | 477 | A contributor's "essential patent claims" are all patent claims 478 | owned or controlled by the contributor, whether already acquired or 479 | hereafter acquired, that would be infringed by some manner, permitted 480 | by this License, of making, using, or selling its contributor version, 481 | but do not include claims that would be infringed only as a 482 | consequence of further modification of the contributor version. For 483 | purposes of this definition, "control" includes the right to grant 484 | patent sublicenses in a manner consistent with the requirements of 485 | this License. 486 | 487 | Each contributor grants you a non-exclusive, worldwide, royalty-free 488 | patent license under the contributor's essential patent claims, to 489 | make, use, sell, offer for sale, import and otherwise run, modify and 490 | propagate the contents of its contributor version. 491 | 492 | In the following three paragraphs, a "patent license" is any express 493 | agreement or commitment, however denominated, not to enforce a patent 494 | (such as an express permission to practice a patent or covenant not to 495 | sue for patent infringement). To "grant" such a patent license to a 496 | party means to make such an agreement or commitment not to enforce a 497 | patent against the party. 498 | 499 | If you convey a covered work, knowingly relying on a patent license, 500 | and the Corresponding Source of the work is not available for anyone 501 | to copy, free of charge and under the terms of this License, through a 502 | publicly available network server or other readily accessible means, 503 | then you must either (1) cause the Corresponding Source to be so 504 | available, or (2) arrange to deprive yourself of the benefit of the 505 | patent license for this particular work, or (3) arrange, in a manner 506 | consistent with the requirements of this License, to extend the patent 507 | license to downstream recipients. "Knowingly relying" means you have 508 | actual knowledge that, but for the patent license, your conveying the 509 | covered work in a country, or your recipient's use of the covered work 510 | in a country, would infringe one or more identifiable patents in that 511 | country that you have reason to believe are valid. 512 | 513 | If, pursuant to or in connection with a single transaction or 514 | arrangement, you convey, or propagate by procuring conveyance of, a 515 | covered work, and grant a patent license to some of the parties 516 | receiving the covered work authorizing them to use, propagate, modify 517 | or convey a specific copy of the covered work, then the patent license 518 | you grant is automatically extended to all recipients of the covered 519 | work and works based on it. 520 | 521 | A patent license is "discriminatory" if it does not include within 522 | the scope of its coverage, prohibits the exercise of, or is 523 | conditioned on the non-exercise of one or more of the rights that are 524 | specifically granted under this License. You may not convey a covered 525 | work if you are a party to an arrangement with a third party that is 526 | in the business of distributing software, under which you make payment 527 | to the third party based on the extent of your activity of conveying 528 | the work, and under which the third party grants, to any of the 529 | parties who would receive the covered work from you, a discriminatory 530 | patent license (a) in connection with copies of the covered work 531 | conveyed by you (or copies made from those copies), or (b) primarily 532 | for and in connection with specific products or compilations that 533 | contain the covered work, unless you entered into that arrangement, 534 | or that patent license was granted, prior to 28 March 2007. 535 | 536 | Nothing in this License shall be construed as excluding or limiting 537 | any implied license or other defenses to infringement that may 538 | otherwise be available to you under applicable patent law. 539 | 540 | 12. No Surrender of Others' Freedom. 541 | 542 | If conditions are imposed on you (whether by court order, agreement or 543 | otherwise) that contradict the conditions of this License, they do not 544 | excuse you from the conditions of this License. If you cannot convey a 545 | covered work so as to satisfy simultaneously your obligations under this 546 | License and any other pertinent obligations, then as a consequence you may 547 | not convey it at all. For example, if you agree to terms that obligate you 548 | to collect a royalty for further conveying from those to whom you convey 549 | the Program, the only way you could satisfy both those terms and this 550 | License would be to refrain entirely from conveying the Program. 551 | 552 | 13. Use with the GNU Affero General Public License. 553 | 554 | Notwithstanding any other provision of this License, you have 555 | permission to link or combine any covered work with a work licensed 556 | under version 3 of the GNU Affero General Public License into a single 557 | combined work, and to convey the resulting work. The terms of this 558 | License will continue to apply to the part which is the covered work, 559 | but the special requirements of the GNU Affero General Public License, 560 | section 13, concerning interaction through a network will apply to the 561 | combination as such. 562 | 563 | 14. Revised Versions of this License. 564 | 565 | The Free Software Foundation may publish revised and/or new versions of 566 | the GNU General Public License from time to time. Such new versions will 567 | be similar in spirit to the present version, but may differ in detail to 568 | address new problems or concerns. 569 | 570 | Each version is given a distinguishing version number. If the 571 | Program specifies that a certain numbered version of the GNU General 572 | Public License "or any later version" applies to it, you have the 573 | option of following the terms and conditions either of that numbered 574 | version or of any later version published by the Free Software 575 | Foundation. If the Program does not specify a version number of the 576 | GNU General Public License, you may choose any version ever published 577 | by the Free Software Foundation. 578 | 579 | If the Program specifies that a proxy can decide which future 580 | versions of the GNU General Public License can be used, that proxy's 581 | public statement of acceptance of a version permanently authorizes you 582 | to choose that version for the Program. 583 | 584 | Later license versions may give you additional or different 585 | permissions. However, no additional obligations are imposed on any 586 | author or copyright holder as a result of your choosing to follow a 587 | later version. 588 | 589 | 15. Disclaimer of Warranty. 590 | 591 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY 592 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT 593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY 594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, 595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 596 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM 597 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF 598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 599 | 600 | 16. Limitation of Liability. 601 | 602 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS 604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY 605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE 606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF 607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD 608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), 609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF 610 | SUCH DAMAGES. 611 | 612 | 17. Interpretation of Sections 15 and 16. 613 | 614 | If the disclaimer of warranty and limitation of liability provided 615 | above cannot be given local legal effect according to their terms, 616 | reviewing courts shall apply local law that most closely approximates 617 | an absolute waiver of all civil liability in connection with the 618 | Program, unless a warranty or assumption of liability accompanies a 619 | copy of the Program in return for a fee. 620 | 621 | END OF TERMS AND CONDITIONS 622 | 623 | How to Apply These Terms to Your New Programs 624 | 625 | If you develop a new program, and you want it to be of the greatest 626 | possible use to the public, the best way to achieve this is to make it 627 | free software which everyone can redistribute and change under these terms. 628 | 629 | To do so, attach the following notices to the program. It is safest 630 | to attach them to the start of each source file to most effectively 631 | state the exclusion of warranty; and each file should have at least 632 | the "copyright" line and a pointer to where the full notice is found. 633 | 634 | 635 | Copyright (C) 636 | 637 | This program is free software: you can redistribute it and/or modify 638 | it under the terms of the GNU General Public License as published by 639 | the Free Software Foundation, either version 3 of the License, or 640 | (at your option) any later version. 641 | 642 | This program is distributed in the hope that it will be useful, 643 | but WITHOUT ANY WARRANTY; without even the implied warranty of 644 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 645 | GNU General Public License for more details. 646 | 647 | You should have received a copy of the GNU General Public License 648 | along with this program. If not, see . 649 | 650 | Also add information on how to contact you by electronic and paper mail. 651 | 652 | If the program does terminal interaction, make it output a short 653 | notice like this when it starts in an interactive mode: 654 | 655 | Copyright (C) 656 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 657 | This is free software, and you are welcome to redistribute it 658 | under certain conditions; type `show c' for details. 659 | 660 | The hypothetical commands `show w' and `show c' should show the appropriate 661 | parts of the General Public License. Of course, your program's commands 662 | might be different; for a GUI interface, you would use an "about box". 663 | 664 | You should also get your employer (if you work as a programmer) or school, 665 | if any, to sign a "copyright disclaimer" for the program, if necessary. 666 | For more information on this, and how to apply and follow the GNU GPL, see 667 | . 668 | 669 | The GNU General Public License does not permit incorporating your program 670 | into proprietary programs. If your program is a subroutine library, you 671 | may consider it more useful to permit linking proprietary applications with 672 | the library. If this is what you want to do, use the GNU Lesser General 673 | Public License instead of this License. But first, please read 674 | . 675 | -------------------------------------------------------------------------------- /MANIFEST.in: -------------------------------------------------------------------------------- 1 | include README.md 2 | include LICENSE -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # pySWATPlus 2 | 3 | 4 | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14889320.svg)](https://doi.org/10.5281/zenodo.14889320) 5 | [![flake8](https://github.com/swat-model/pySWATPlus/actions/workflows/linting.yml/badge.svg)](https://github.com/swat-model/pySWATPlus/actions/workflows/linting.yml) 6 | 7 | 8 | **pySWATPlus** is a Python package that makes working with SWAT+ models easier and more powerful. Whether you're running default setups or custom projects, this tool lets you interact with SWAT+ programmatically, so you can focus on optimizing and analyzing your models like a pro! 🚀 9 | 10 | --- 11 | 12 | ## ✨ Key Features 13 | 14 | - **Access and Modify SWAT+ Files**: Navigate, read, modify, and write files in the `TxtInOut` folder used by SWAT+. 📂 15 | - **Model Calibration**: Optimize SWAT+ input parameters using the [Pymoo](https://pymoo.org/) optimization framework to get the best results. 🎯 16 | 17 | --- 18 | 19 | ## 📦 About 20 | 21 | pySWATPlus is an open-source software developed and maintained by [ICRA](https://icra.cat/). It’s available for download and installation via [PyPI](https://pypi.org/project/pySWATPlus/). 22 | 23 | --- 24 | 25 | ## 📥 Install pySWATPlus 26 | 27 | To use this package, a Python version above 3.6 is required. You can install pySWATPlus using this simple command: 28 | 29 | ````py 30 | pip install pySWATPlus 31 | ```` 32 | 33 | --- 34 | 35 | ## 📚 Documentation 36 | 37 | For detailed documentation, tutorials, and examples, visit the **[pySWATPlus documentation](https://swat-model.github.io/pySWATPlus/)**. The documentation includes: 38 | 39 | - **[Getting Started](https://swat-model.github.io/pySWATPlus/examples/basic_examples/)**: A beginner-friendly guide to setting up and running your first SWAT+ project. 40 | - **[API Reference](https://swat-model.github.io/pySWATPlus/api/txtinoutreader/)**: Comprehensive documentation of all functions, input arguments, and usage examples. 41 | - **[TxtinoutReader](https://swat-model.github.io/pySWATPlus/api/txtinoutreader/)**: Work with SWAT+ input and output files. 42 | - **[FileReader](https://swat-model.github.io/pySWATPlus/api/filereader/)**: Read and manipulate SWAT+ files. 43 | - **[SWATProblem](https://swat-model.github.io/pySWATPlus/api/swatproblem/)**: Define and solve SWAT+ optimization problems. 44 | - **[SWATProblemMultimodel](https://swat-model.github.io/pySWATPlus/api/swatproblemmultimodel/)**: Handle multi-model calibration scenarios. 45 | 46 | 47 | --- 48 | 49 | 50 | ## 📖 Citation 51 | To cite pySWATPlus, use: 52 | 53 | ```tex 54 | @misc{Salo_Llorente_2023, 55 | author = {Saló, Joan and Llorente, Oliu}, 56 | title = {{pySWATPlus: A Python Interface for SWAT+ Model Calibration and Analysis}}, 57 | year = {2023}, 58 | month = dec, 59 | publisher = {Zenodo}, 60 | version = {0.1.0}, 61 | doi = {10.5281/zenodo.14889320}, 62 | url = {https://doi.org/10.5281/zenodo.14889320} 63 | } 64 | ``` 65 | -------------------------------------------------------------------------------- /docs/api/filereader.md: -------------------------------------------------------------------------------- 1 | # FileReader 2 | 3 | ::: pySWATPlus.FileReader 4 | options: 5 | heading_level: 2 6 | show_root_heading: false 7 | members: 8 | - FileReader -------------------------------------------------------------------------------- /docs/api/swatproblem.md: -------------------------------------------------------------------------------- 1 | # SWATProblem 2 | 3 | ::: pySWATPlus.SWATProblem 4 | options: 5 | heading_level: 2 6 | show_root_heading: false 7 | members: 8 | - SWATProblem 9 | - minimize_pymoo -------------------------------------------------------------------------------- /docs/api/swatproblemmultimodel.md: -------------------------------------------------------------------------------- 1 | # SWATProblemMultimodel 2 | !!! warning "Advanced Users Only" 3 | This feature requires special expertise 4 | 5 | ::: pySWATPlus.SWATProblemMultimodel 6 | options: 7 | heading_level: 2 8 | show_root_heading: false 9 | members: 10 | - SWATProblemMultimodel -------------------------------------------------------------------------------- /docs/api/txtinoutreader.md: -------------------------------------------------------------------------------- 1 | # TxtinoutReader 2 | 3 | ::: pySWATPlus.TxtinoutReader 4 | options: 5 | heading_level: 2 6 | show_root_heading: false 7 | members: 8 | - TxtinoutReader -------------------------------------------------------------------------------- /docs/citation.md: -------------------------------------------------------------------------------- 1 | # Citation 2 | 3 | To cite pySWATPlus, use: 4 | 5 | ```tex 6 | @misc{Salo_Llorente_2023, 7 | author = {Saló, Joan and Llorente, Oliu}, 8 | title = {{pySWATPlus: A Python Interface for SWAT+ Model Calibration and Analysis}}, 9 | year = {2023}, 10 | month = dec, 11 | publisher = {Zenodo}, 12 | version = {0.1.0}, 13 | doi = {10.5281/zenodo.14889320}, 14 | url = {https://doi.org/10.5281/zenodo.14889320} 15 | } 16 | ``` 17 | 18 | **Human-readable format:** 19 | Saló, J. & Llorente, O. (2023). pySWATPlus: A Python Interface for SWAT+ Model Calibration and Analysis (Version 0.1.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.14889320 -------------------------------------------------------------------------------- /docs/examples/basic_examples.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "code", 5 | "execution_count": 1, 6 | "metadata": {}, 7 | "outputs": [], 8 | "source": [ 9 | "%load_ext autoreload" 10 | ] 11 | }, 12 | { 13 | "cell_type": "markdown", 14 | "metadata": {}, 15 | "source": [ 16 | "# SWAT+ Model Simulation with `pySWATPlus`\n", 17 | "\n", 18 | "This notebook demonstrates how to use the `pySWATPlus` library to interact with SWAT+ models, modify input files, and run simulations. We'll cover the following steps:\n", 19 | "\n", 20 | "- **Loading the necessary libraries.**\n", 21 | "- **Initializing the `TxtinoutReader` to interact with the SWAT+ model.**\n", 22 | "- **Reading and modifying input files (e.g., `plants.plt`).**\n", 23 | "- **Running the SWAT+ simulation and analyzing results.**\n", 24 | "- **Running multiple simulations in parallel.**\n", 25 | "\n", 26 | "Let’s get started!\n", 27 | "\n", 28 | "---\n", 29 | "\n", 30 | "## 1. Importing Required Libraries\n", 31 | "\n", 32 | "First, we import the `pySWATPlus` module.\n" 33 | ] 34 | }, 35 | { 36 | "cell_type": "code", 37 | "execution_count": 2, 38 | "metadata": {}, 39 | "outputs": [], 40 | "source": [ 41 | "from pySWATPlus import TxtinoutReader" 42 | ] 43 | }, 44 | { 45 | "cell_type": "markdown", 46 | "metadata": {}, 47 | "source": [ 48 | "---\n", 49 | "\n", 50 | "## 2. Setting Up the SWAT+ Model\n", 51 | "\n", 52 | "To work with a SWAT+ model, we need to specify the path to the `txtinout` folder. This folder contains all the input files required for the simulation, including the SWAT+ executable." 53 | ] 54 | }, 55 | { 56 | "cell_type": "code", 57 | "execution_count": 3, 58 | "metadata": {}, 59 | "outputs": [], 60 | "source": [ 61 | "# Path to the SWAT+ model folder\n", 62 | "txtinout_folder = '/mnt/c/Users/joans/OneDrive/Escriptori/icra/muga_windows'\n", 63 | "filename = 'plants.plt'" 64 | ] 65 | }, 66 | { 67 | "cell_type": "markdown", 68 | "metadata": {}, 69 | "source": [ 70 | "---\n", 71 | "## 3. Initializing the `TxtinoutReader`\n", 72 | "\n", 73 | "The `TxtinoutReader` class is used to interact with the SWAT+ model. It allows us to read, modify, and run simulations." 74 | ] 75 | }, 76 | { 77 | "cell_type": "code", 78 | "execution_count": 4, 79 | "metadata": {}, 80 | "outputs": [], 81 | "source": [ 82 | "# Initialize the TxtinoutReader\n", 83 | "# Note: The folder must contain a .exe file to run the simulation.\n", 84 | "reader = TxtinoutReader(txtinout_folder)" 85 | ] 86 | }, 87 | { 88 | "cell_type": "markdown", 89 | "metadata": {}, 90 | "source": [ 91 | "---\n", 92 | "## 4. Reading Input Files\n", 93 | "\n", 94 | "We can read specific input files, such as `plants.plt`, using the `register_file` method. This method returns a `FileReader` object that allows us to manipulate the file.\n" 95 | ] 96 | }, 97 | { 98 | "cell_type": "code", 99 | "execution_count": 5, 100 | "metadata": {}, 101 | "outputs": [ 102 | { 103 | "data": { 104 | "text/plain": [ 105 | "'plants.plt: written by SWAT+ editor v2.2.0 on 2023-09-25 11:54 for SWAT+ rev.60.5.4\\n'" 106 | ] 107 | }, 108 | "execution_count": 5, 109 | "metadata": {}, 110 | "output_type": "execute_result" 111 | } 112 | ], 113 | "source": [ 114 | "# Read the 'plants.plt' file\n", 115 | "plants_reader = reader.register_file(\n", 116 | " filename, \n", 117 | " has_units=False, # Indicates if the file has units information\n", 118 | " index='name' # Use the 'name' column as the index\n", 119 | ")\n", 120 | "\n", 121 | "# Display the header of the file\n", 122 | "plants_reader.header_file" 123 | ] 124 | }, 125 | { 126 | "cell_type": "markdown", 127 | "metadata": {}, 128 | "source": [ 129 | "---\n", 130 | "## 5. Exploring the Input Data \n", 131 | "\n", 132 | "The `plants.plt` file contains information about different plant species used in the SWAT+ model. Let’s take a look at the data." 133 | ] 134 | }, 135 | { 136 | "cell_type": "code", 137 | "execution_count": 6, 138 | "metadata": {}, 139 | "outputs": [ 140 | { 141 | "data": { 142 | "text/html": [ 143 | "
\n", 144 | "\n", 157 | "\n", 158 | " \n", 159 | " \n", 160 | " \n", 161 | " \n", 162 | " \n", 163 | " \n", 164 | " \n", 165 | " \n", 166 | " \n", 167 | " \n", 168 | " \n", 169 | " \n", 170 | " \n", 171 | " \n", 172 | " \n", 173 | " \n", 174 | " \n", 175 | " \n", 176 | " \n", 177 | " \n", 178 | " \n", 179 | " \n", 180 | " \n", 181 | " \n", 182 | " \n", 183 | " \n", 184 | " \n", 185 | " \n", 186 | " \n", 187 | " \n", 188 | " \n", 189 | " \n", 190 | " \n", 191 | " \n", 192 | " \n", 193 | " \n", 194 | " \n", 195 | " \n", 196 | " \n", 197 | " \n", 198 | " \n", 199 | " \n", 200 | " \n", 201 | " \n", 202 | " \n", 203 | " \n", 204 | " \n", 205 | " \n", 206 | " \n", 207 | " \n", 208 | " \n", 209 | " \n", 210 | " \n", 211 | " \n", 212 | " \n", 213 | " \n", 214 | " \n", 215 | " \n", 216 | " \n", 217 | " \n", 218 | " \n", 219 | " \n", 220 | " \n", 221 | " \n", 222 | " \n", 223 | " \n", 224 | " \n", 225 | " \n", 226 | " \n", 227 | " \n", 228 | " \n", 229 | " \n", 230 | " \n", 231 | " \n", 232 | " \n", 233 | " \n", 234 | " \n", 235 | " \n", 236 | " \n", 237 | " \n", 238 | " \n", 239 | " \n", 240 | " \n", 241 | " \n", 242 | " \n", 243 | " \n", 244 | " \n", 245 | " \n", 246 | " \n", 247 | " \n", 248 | " \n", 249 | " \n", 250 | " \n", 251 | " \n", 252 | " \n", 253 | " \n", 254 | " \n", 255 | " \n", 256 | " \n", 257 | " \n", 258 | " \n", 259 | " \n", 260 | " \n", 261 | " \n", 262 | " \n", 263 | " \n", 264 | " \n", 265 | " \n", 266 | " \n", 267 | " \n", 268 | " \n", 269 | " \n", 270 | " \n", 271 | " \n", 272 | " \n", 273 | " \n", 274 | " \n", 275 | " \n", 276 | " \n", 277 | " \n", 278 | " \n", 279 | " \n", 280 | " \n", 281 | " \n", 282 | " \n", 283 | " \n", 284 | " \n", 285 | " \n", 286 | " \n", 287 | " \n", 288 | " \n", 289 | " \n", 290 | " \n", 291 | " \n", 292 | " \n", 293 | " \n", 294 | " \n", 295 | " \n", 296 | " \n", 297 | " \n", 298 | " \n", 299 | " \n", 300 | " \n", 301 | " \n", 302 | " \n", 303 | " \n", 304 | " \n", 305 | " \n", 306 | " \n", 307 | " \n", 308 | " \n", 309 | " \n", 310 | " \n", 311 | " \n", 312 | " \n", 313 | " \n", 314 | " \n", 315 | " \n", 316 | " \n", 317 | " \n", 318 | " \n", 319 | " \n", 320 | " \n", 321 | " \n", 322 | " \n", 323 | " \n", 324 | " \n", 325 | " \n", 326 | " \n", 327 | " \n", 328 | " \n", 329 | " \n", 330 | "
nameplnt_typgro_trignfix_codays_matbm_eharv_idxlai_potfrac_hu1lai_max1...rt_st_endplnt_pop1frac_lai1plnt_pop2frac_lai2frac_sw_groaerationwnd_deadwnd_flatdescription
agrcagrccold_annualtemp_gro0.0110.040.00.404.00.050.05...0.00.00.00.00.00.50.00.00.0agricultural_land_close_grown
agrlagrlwarm_annualtemp_gro0.0110.050.00.453.00.150.05...0.00.00.00.00.00.50.00.00.0agricultural_land_generic
agrragrrwarm_annualtemp_gro0.0110.050.00.503.00.150.05...0.00.00.00.00.00.50.00.00.0agricultural_land_row
alfaalfaperennialtemp_gro0.50.050.00.905.00.150.01...0.00.00.00.00.00.50.00.00.0alfalfa
almdalmdperennialtemp_gro0.00.050.00.051.20.050.05...0.00.00.00.00.00.50.00.00.0almond
\n", 331 | "

5 rows × 54 columns

\n", 332 | "
" 333 | ], 334 | "text/plain": [ 335 | " name plnt_typ gro_trig nfix_co days_mat bm_e harv_idx lai_pot \\\n", 336 | " \n", 337 | "agrc agrc cold_annual temp_gro 0.0 110.0 40.0 0.40 4.0 \n", 338 | "agrl agrl warm_annual temp_gro 0.0 110.0 50.0 0.45 3.0 \n", 339 | "agrr agrr warm_annual temp_gro 0.0 110.0 50.0 0.50 3.0 \n", 340 | "alfa alfa perennial temp_gro 0.5 0.0 50.0 0.90 5.0 \n", 341 | "almd almd perennial temp_gro 0.0 0.0 50.0 0.05 1.2 \n", 342 | "\n", 343 | " frac_hu1 lai_max1 ... rt_st_end plnt_pop1 frac_lai1 plnt_pop2 \\\n", 344 | " ... \n", 345 | "agrc 0.05 0.05 ... 0.0 0.0 0.0 0.0 \n", 346 | "agrl 0.15 0.05 ... 0.0 0.0 0.0 0.0 \n", 347 | "agrr 0.15 0.05 ... 0.0 0.0 0.0 0.0 \n", 348 | "alfa 0.15 0.01 ... 0.0 0.0 0.0 0.0 \n", 349 | "almd 0.05 0.05 ... 0.0 0.0 0.0 0.0 \n", 350 | "\n", 351 | " frac_lai2 frac_sw_gro aeration wnd_dead wnd_flat \\\n", 352 | " \n", 353 | "agrc 0.0 0.5 0.0 0.0 0.0 \n", 354 | "agrl 0.0 0.5 0.0 0.0 0.0 \n", 355 | "agrr 0.0 0.5 0.0 0.0 0.0 \n", 356 | "alfa 0.0 0.5 0.0 0.0 0.0 \n", 357 | "almd 0.0 0.5 0.0 0.0 0.0 \n", 358 | "\n", 359 | " description \n", 360 | " \n", 361 | "agrc agricultural_land_close_grown \n", 362 | "agrl agricultural_land_generic \n", 363 | "agrr agricultural_land_row \n", 364 | "alfa alfalfa \n", 365 | "almd almond \n", 366 | "\n", 367 | "[5 rows x 54 columns]" 368 | ] 369 | }, 370 | "execution_count": 6, 371 | "metadata": {}, 372 | "output_type": "execute_result" 373 | } 374 | ], 375 | "source": [ 376 | "# Display the first few rows of the 'plants.plt' file\n", 377 | "plants_reader.df.head()" 378 | ] 379 | }, 380 | { 381 | "cell_type": "markdown", 382 | "metadata": {}, 383 | "source": [ 384 | "---\n", 385 | "## 6. Modifying Input Parameters\n", 386 | "\n", 387 | "We can modify the input parameters directly in the DataFrame. For example, let’s change the `bm_e` (biomass-energy ratio) for the `agrc` plant." 388 | ] 389 | }, 390 | { 391 | "cell_type": "code", 392 | "execution_count": 7, 393 | "metadata": {}, 394 | "outputs": [], 395 | "source": [ 396 | "# Modify the 'bm_e' value for the 'agrc' plant\n", 397 | "plants_reader.df.loc['agrc', 'bm_e'] = 40\n", 398 | "\n", 399 | "# Save the changes back to the file\n", 400 | "plants_reader.overwrite_file()" 401 | ] 402 | }, 403 | { 404 | "cell_type": "markdown", 405 | "metadata": {}, 406 | "source": [ 407 | "---\n", 408 | "## 7. Running the SWAT+ Simulation\n", 409 | "\n", 410 | "Now that we’ve modified the input file, let’s run the SWAT+ simulation. We can also specify additional parameters, such as the simulation period and warmup period." 411 | ] 412 | }, 413 | { 414 | "cell_type": "code", 415 | "execution_count": 8, 416 | "metadata": {}, 417 | "outputs": [], 418 | "source": [ 419 | "# Set the beginning and end years for the simulation\n", 420 | "reader.set_beginning_and_end_year(2009, 2011)\n", 421 | "\n", 422 | "# Set the warmup period (in years)\n", 423 | "reader.set_warmup(1)\n", 424 | "\n", 425 | "# Enable the 'channel_sd' object in the 'print.prt' file for daily output\n", 426 | "reader.enable_object_in_print_prt(obj='channel_sd', daily=True, monthly=False, yearly=False, avann=False)" 427 | ] 428 | }, 429 | { 430 | "cell_type": "markdown", 431 | "metadata": {}, 432 | "source": [ 433 | "### Handling Simulation Output\n", 434 | "\n", 435 | "To avoid cluttering the notebook with long simulation output:\n", 436 | "- Set `show_output=False` to suppress all output.\n", 437 | "- Use `%%capture` to store the output and print only a portion (e.g., the first 20 lines)." 438 | ] 439 | }, 440 | { 441 | "cell_type": "code", 442 | "execution_count": 9, 443 | "metadata": {}, 444 | "outputs": [], 445 | "source": [ 446 | "%%capture captured_output\n", 447 | "simulation_path = reader.run_swat(show_output=True)" 448 | ] 449 | }, 450 | { 451 | "cell_type": "code", 452 | "execution_count": 10, 453 | "metadata": {}, 454 | "outputs": [ 455 | { 456 | "name": "stdout", 457 | "output_type": "stream", 458 | "text": [ 459 | "Simulation Output (First 20 Lines):\n", 460 | "SWAT+\n", 461 | "Revision 60.5.7\n", 462 | "Soil & Water Assessment Tool\n", 463 | "PC Version\n", 464 | "Program reading . . . executing\n", 465 | "Date of Sim 3/23/2025 Time 19:59: 1\n", 466 | "reading from precipitation file Time 19:59: 1\n", 467 | "reading from temperature file Time 19:59: 1\n", 468 | "reading from solar radiation file Time 19:59: 2\n", 469 | "reading from relative humidity file Time 19:59: 2\n", 470 | "reading from wind file Time 19:59: 2\n", 471 | "reading from wgn file Time 19:59: 3\n", 472 | "reading from wx station file Time 19:59: 3\n", 473 | "Original Simulation 1 1 2009 Yr 1 of 3 Time 19:59: 4\n", 474 | "Original Simulation 1 2 2009 Yr 1 of 3 Time 19:59: 4\n", 475 | "Original Simulation 1 3 2009 Yr 1 of 3 Time 19:59: 4\n", 476 | "Original Simulation 1 4 2009 Yr 1 of 3 Time 19:59: 5\n", 477 | "Original Simulation 1 5 2009 Yr 1 of 3 Time 19:59: 5\n", 478 | "Original Simulation 1 6 2009 Yr 1 of 3 Time 19:59: 5\n", 479 | "Original Simulation 1 7 2009 Yr 1 of 3 Time 19:59: 5\n" 480 | ] 481 | } 482 | ], 483 | "source": [ 484 | "# Print the first 20 lines of the output\n", 485 | "print(\"Simulation Output (First 20 Lines):\")\n", 486 | "print(\"\\n\".join(captured_output.stdout.splitlines()[:20]))" 487 | ] 488 | }, 489 | { 490 | "cell_type": "markdown", 491 | "metadata": {}, 492 | "source": [ 493 | "---\n", 494 | "## 8. Reading Simulation Results\n", 495 | "\n", 496 | "After running the simulation, we can read the results from the output files. For example, let’s read the daily channel output (`channel_sd_day.txt`)." 497 | ] 498 | }, 499 | { 500 | "cell_type": "code", 501 | "execution_count": 11, 502 | "metadata": {}, 503 | "outputs": [ 504 | { 505 | "data": { 506 | "text/html": [ 507 | "
\n", 508 | "\n", 521 | "\n", 522 | " \n", 523 | " \n", 524 | " \n", 525 | " \n", 526 | " \n", 527 | " \n", 528 | " \n", 529 | " \n", 530 | " \n", 531 | " \n", 532 | " \n", 533 | " \n", 534 | " \n", 535 | " \n", 536 | " \n", 537 | " \n", 538 | " \n", 539 | " \n", 540 | " \n", 541 | " \n", 542 | " \n", 543 | " \n", 544 | " \n", 545 | " \n", 546 | " \n", 547 | " \n", 548 | " \n", 549 | " \n", 550 | " \n", 551 | " \n", 552 | " \n", 553 | " \n", 554 | " \n", 555 | " \n", 556 | " \n", 557 | " \n", 558 | " \n", 559 | " \n", 560 | " \n", 561 | " \n", 562 | " \n", 563 | " \n", 564 | " \n", 565 | " \n", 566 | " \n", 567 | " \n", 568 | " \n", 569 | " \n", 570 | " \n", 571 | " \n", 572 | " \n", 573 | " \n", 574 | " \n", 575 | " \n", 576 | " \n", 577 | " \n", 578 | " \n", 579 | " \n", 580 | " \n", 581 | " \n", 582 | " \n", 583 | " \n", 584 | " \n", 585 | " \n", 586 | " \n", 587 | " \n", 588 | " \n", 589 | " \n", 590 | " \n", 591 | " \n", 592 | " \n", 593 | " \n", 594 | " \n", 595 | " \n", 596 | " \n", 597 | " \n", 598 | " \n", 599 | " \n", 600 | " \n", 601 | " \n", 602 | " \n", 603 | " \n", 604 | " \n", 605 | " \n", 606 | " \n", 607 | " \n", 608 | " \n", 609 | " \n", 610 | " \n", 611 | " \n", 612 | " \n", 613 | " \n", 614 | " \n", 615 | " \n", 616 | " \n", 617 | " \n", 618 | " \n", 619 | " \n", 620 | " \n", 621 | " \n", 622 | " \n", 623 | " \n", 624 | " \n", 625 | " \n", 626 | " \n", 627 | " \n", 628 | " \n", 629 | " \n", 630 | " \n", 631 | " \n", 632 | " \n", 633 | " \n", 634 | " \n", 635 | " \n", 636 | " \n", 637 | " \n", 638 | " \n", 639 | " \n", 640 | " \n", 641 | " \n", 642 | " \n", 643 | " \n", 644 | " \n", 645 | " \n", 646 | " \n", 647 | " \n", 648 | " \n", 649 | " \n", 650 | " \n", 651 | " \n", 652 | " \n", 653 | " \n", 654 | " \n", 655 | " \n", 656 | " \n", 657 | " \n", 658 | " \n", 659 | " \n", 660 | " \n", 661 | " \n", 662 | " \n", 663 | " \n", 664 | " \n", 665 | " \n", 666 | " \n", 667 | " \n", 668 | " \n", 669 | " \n", 670 | "
jdaymondayyrunitgis_idnameareaprecipevap...cbod_outdox_outsan_outsil_outcla_outsag_outlag_outgrv_outnull.2water_temp
01.01.01.02010.01.01.0cha0122.3601521.00119.30...869.100278.1000.00.00.00.00.00.010.7410.74
11.01.01.02010.02.02.0cha0224.660616.40132.10...1.56433.4800.00.00.00.00.00.010.7010.74
21.01.01.02010.03.03.0cha032.618133.5014.14...5.03723.6300.00.00.00.00.00.010.5310.74
31.01.01.02010.04.04.0cha042.99974.9616.06...1.83123.0700.00.00.00.00.00.010.7010.74
41.01.01.02010.05.05.0cha058.043160.9043.47...84.5307.4420.00.00.00.00.00.012.2910.74
\n", 671 | "

5 rows × 66 columns

\n", 672 | "
" 673 | ], 674 | "text/plain": [ 675 | " jday mon day yr unit gis_id name area precip evap ... \\\n", 676 | "0 1.0 1.0 1.0 2010.0 1.0 1.0 cha01 22.360 1521.00 119.30 ... \n", 677 | "1 1.0 1.0 1.0 2010.0 2.0 2.0 cha02 24.660 616.40 132.10 ... \n", 678 | "2 1.0 1.0 1.0 2010.0 3.0 3.0 cha03 2.618 133.50 14.14 ... \n", 679 | "3 1.0 1.0 1.0 2010.0 4.0 4.0 cha04 2.999 74.96 16.06 ... \n", 680 | "4 1.0 1.0 1.0 2010.0 5.0 5.0 cha05 8.043 160.90 43.47 ... \n", 681 | "\n", 682 | " cbod_out dox_out san_out sil_out cla_out sag_out lag_out grv_out \\\n", 683 | "0 869.100 278.100 0.0 0.0 0.0 0.0 0.0 0.0 \n", 684 | "1 1.564 33.480 0.0 0.0 0.0 0.0 0.0 0.0 \n", 685 | "2 5.037 23.630 0.0 0.0 0.0 0.0 0.0 0.0 \n", 686 | "3 1.831 23.070 0.0 0.0 0.0 0.0 0.0 0.0 \n", 687 | "4 84.530 7.442 0.0 0.0 0.0 0.0 0.0 0.0 \n", 688 | "\n", 689 | " null.2 water_temp \n", 690 | "0 10.74 10.74 \n", 691 | "1 10.70 10.74 \n", 692 | "2 10.53 10.74 \n", 693 | "3 10.70 10.74 \n", 694 | "4 12.29 10.74 \n", 695 | "\n", 696 | "[5 rows x 66 columns]" 697 | ] 698 | }, 699 | "execution_count": 11, 700 | "metadata": {}, 701 | "output_type": "execute_result" 702 | } 703 | ], 704 | "source": [ 705 | "# Read the daily channel output\n", 706 | "channel_sd = reader.register_file('channel_sd_day.txt', has_units=True)\n", 707 | "\n", 708 | "# Display the first few rows of the results\n", 709 | "channel_sd.df.head()" 710 | ] 711 | }, 712 | { 713 | "cell_type": "markdown", 714 | "metadata": {}, 715 | "source": [ 716 | "---\n", 717 | "## 9. Running SWAT+ with Specific Modifications\n", 718 | "\n", 719 | "Instead of modifying input files manually, you can directly specify the modifications when running the simulation. This is useful for quickly testing different scenarios.\n", 720 | "\n", 721 | "#### Option 1: Modify Specific Values\n", 722 | "You can specify the file, column, and value to modify. For example, let’s change the `bm_e` value for the `agrc` plant." 723 | ] 724 | }, 725 | { 726 | "cell_type": "code", 727 | "execution_count": 12, 728 | "metadata": {}, 729 | "outputs": [ 730 | { 731 | "data": { 732 | "text/plain": [ 733 | "PosixPath('/mnt/c/Users/joans/OneDrive/Escriptori/icra/muga_windows')" 734 | ] 735 | }, 736 | "execution_count": 12, 737 | "metadata": {}, 738 | "output_type": "execute_result" 739 | } 740 | ], 741 | "source": [ 742 | "# Run the simulation with specific modifications\n", 743 | "txtinout_path = reader.run_swat(\n", 744 | " params={'plants.plt': ('name', [('agrc', 'bm_e', 40)])}, \n", 745 | " show_output=False\n", 746 | ")\n", 747 | "txtinout_path" 748 | ] 749 | }, 750 | { 751 | "cell_type": "markdown", 752 | "metadata": {}, 753 | "source": [ 754 | "#### Option 2: Use Regular Expressions\n", 755 | "You can also use regular expressions to select rows for modification. For example, let’s modify the `bm_e` value for all plants whose names start with the letter \"A\".\n" 756 | ] 757 | }, 758 | { 759 | "cell_type": "code", 760 | "execution_count": 13, 761 | "metadata": {}, 762 | "outputs": [ 763 | { 764 | "data": { 765 | "text/plain": [ 766 | "PosixPath('/mnt/c/Users/joans/OneDrive/Escriptori/icra/muga_windows')" 767 | ] 768 | }, 769 | "execution_count": 13, 770 | "metadata": {}, 771 | "output_type": "execute_result" 772 | } 773 | ], 774 | "source": [ 775 | "# Run the simulation using a regular expression to select rows\n", 776 | "txtinout_path = reader.run_swat(\n", 777 | " params={'plants.plt': ('name', [(r'^A.*', 'bm_e', 40)])}, \n", 778 | " show_output=False\n", 779 | ")\n", 780 | "txtinout_path" 781 | ] 782 | }, 783 | { 784 | "cell_type": "markdown", 785 | "metadata": {}, 786 | "source": [ 787 | "---\n", 788 | "\n", 789 | "## 10. Running Multiple Simulations in Parallel\n", 790 | "\n", 791 | "If you need to run multiple simulations with different parameters, you can use the `run_parallel_swat` method. This allows you to run simulations in parallel using multiple threads or processes." 792 | ] 793 | }, 794 | { 795 | "cell_type": "code", 796 | "execution_count": 14, 797 | "metadata": {}, 798 | "outputs": [ 799 | { 800 | "data": { 801 | "text/plain": [ 802 | "[PosixPath('/tmp/tmpa7a397py'), PosixPath('/tmp/tmpa227i7m4')]" 803 | ] 804 | }, 805 | "execution_count": 14, 806 | "metadata": {}, 807 | "output_type": "execute_result" 808 | } 809 | ], 810 | "source": [ 811 | "#You can also run multiple simulations in parallel\n", 812 | "txtinout_paths = reader.run_parallel_swat(params = [{'plants.plt': ('name', [('bana', 'bm_e', 45)])}, {'plants.plt': ('name', [('bana', 'bm_e', 40)])}], n_workers = 2, parallelization='threads')\n", 813 | "txtinout_paths" 814 | ] 815 | } 816 | ], 817 | "metadata": { 818 | "kernelspec": { 819 | "display_name": "pyswatplus", 820 | "language": "python", 821 | "name": "python3" 822 | }, 823 | "language_info": { 824 | "codemirror_mode": { 825 | "name": "ipython", 826 | "version": 3 827 | }, 828 | "file_extension": ".py", 829 | "mimetype": "text/x-python", 830 | "name": "python", 831 | "nbconvert_exporter": "python", 832 | "pygments_lexer": "ipython3", 833 | "version": "undefined.undefined.undefined" 834 | } 835 | }, 836 | "nbformat": 4, 837 | "nbformat_minor": 2 838 | } 839 | -------------------------------------------------------------------------------- /docs/examples/calibration.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": {}, 6 | "source": [ 7 | "# SWAT+ Calibration Example using pySWATPlus and pymoo\n", 8 | "\n", 9 | "This notebook demonstrates how to use the `pySWATPlus` package to calibrate SWAT+ model parameters using the `pymoo` optimization library. The example focuses on calibrating parameters in the `plants.plt` file and minimizing a user-defined objective function.\n", 10 | "\n", 11 | "---\n", 12 | "\n", 13 | "## 1. Import Required Libraries\n", 14 | "\n", 15 | "First, we import the necessary libraries, including `pySWATPlus` for SWAT+ model interaction and `pymoo` for optimization.\n" 16 | ] 17 | }, 18 | { 19 | "cell_type": "code", 20 | "execution_count": 16, 21 | "metadata": {}, 22 | "outputs": [], 23 | "source": [ 24 | "import numpy as np\n", 25 | "from pySWATPlus.TxtinoutReader import TxtinoutReader\n", 26 | "from pySWATPlus import SWATProblem, minimize_pymoo\n", 27 | "from pymoo.algorithms.soo.nonconvex.cmaes import CMAES\n", 28 | "from pymoo.termination import get_termination\n", 29 | "from pymoo.util.normalization import denormalize" 30 | ] 31 | }, 32 | { 33 | "cell_type": "markdown", 34 | "metadata": {}, 35 | "source": [ 36 | "---\n", 37 | "## 2. Define the Objective Function\n", 38 | "\n", 39 | "The objective function is a user-defined function that evaluates the performance of the SWAT+ model for a given set of parameters. It must:\n", 40 | "\n", 41 | "- Accept a single dictionary argument containing the calibration parameters.\n", 42 | "- Run the SWAT+ model with the provided parameters.\n", 43 | "- Calculate and return an error metric based on the model's output." 44 | ] 45 | }, 46 | { 47 | "cell_type": "code", 48 | "execution_count": null, 49 | "metadata": {}, 50 | "outputs": [], 51 | "source": [ 52 | "def function_to_minimize(dict_of_params):\n", 53 | " \"\"\"\n", 54 | " Objective function to minimize. It runs the SWAT+ model with the provided parameters and returns an error metric.\n", 55 | "\n", 56 | " Parameters:\n", 57 | " dict_of_params (dict): A dictionary containing the calibration parameters and other necessary information.\n", 58 | " Must include the key 'calibration_params' with the format:\n", 59 | " {filename: (id_col, [(id, col, value)])}\n", 60 | "\n", 61 | " Returns:\n", 62 | " Tuple[int, Dict[str, str]]: A tuple containing the error metric and a dictionary with the simulation results.\n", 63 | " \"\"\"\n", 64 | " # Extract calibration parameters and path to the SWAT+ TxtInOut folder\n", 65 | " calibration_params = dict_of_params['calibration_params']\n", 66 | " path_to_txtinout = dict_of_params['path_to_txtinout']\n", 67 | "\n", 68 | " # Initialize the TxtinoutReader and copy the SWAT+ project to a temporary directory\n", 69 | " reader = TxtinoutReader(path_to_txtinout)\n", 70 | " tmp_path = reader.copy_swat(target_dir=None) # Copy to a temporary directory\n", 71 | " reader = TxtinoutReader(tmp_path)\n", 72 | "\n", 73 | " # Run SWAT+ with the provided calibration parameters\n", 74 | " txt_in_out_result = reader.run_swat(calibration_params, show_output=False)\n", 75 | "\n", 76 | " # Initialize a new TxtinoutReader to read the results\n", 77 | " result_reader = TxtinoutReader(txt_in_out_result)\n", 78 | "\n", 79 | " \"\"\"\n", 80 | " The following steps should include:\n", 81 | " 1. Reading the simulation results.\n", 82 | " 2. Gathering observed data.\n", 83 | " 3. Calculating the error metric based on the observed and simulated data.\n", 84 | " \"\"\"\n", 85 | "\n", 86 | " # For demonstration, we return a random error metric\n", 87 | " rng = np.random.default_rng()\n", 88 | " return (rng.random(), {'test_calibration': result_reader.root_folder})" 89 | ] 90 | }, 91 | { 92 | "cell_type": "markdown", 93 | "metadata": {}, 94 | "source": [ 95 | "---\n", 96 | "## 3. Set Up the SWAT+ Calibration Problem\n", 97 | "\n", 98 | "We define the calibration problem by specifying:\n", 99 | "- The parameters to calibrate (e.g., ```bm_e``` and ```harv_idx``` in the ```plants.plt``` file).\n", 100 | "- The objective function (```function_to_minimize```).\n", 101 | "- Additional arguments such as the path to the SWAT+ TxtInOut folder." 102 | ] 103 | }, 104 | { 105 | "cell_type": "code", 106 | "execution_count": 18, 107 | "metadata": {}, 108 | "outputs": [], 109 | "source": [ 110 | "# Path to the SWAT+ TxtInOut folder\n", 111 | "txtinout_folder = '/mnt/c/Users/joans/OneDrive/Escriptori/icra/muga_windows'\n", 112 | "\n", 113 | "# Define the SWATProblem instance\n", 114 | "swat_problem = SWATProblem(\n", 115 | " params={\n", 116 | " 'plants.plt': ('name', [('bana', 'bm_e', 40, 50), ('bana', 'harv_idx', 0.4, 0.5)])\n", 117 | " },\n", 118 | " function_to_evaluate=function_to_minimize,\n", 119 | " param_arg_name='calibration_params',\n", 120 | " n_workers=4,\n", 121 | " parallelization='threads',\n", 122 | " debug=False,\n", 123 | " path_to_txtinout=txtinout_folder\n", 124 | ")" 125 | ] 126 | }, 127 | { 128 | "cell_type": "markdown", 129 | "metadata": {}, 130 | "source": [ 131 | "---\n", 132 | "## 4. Configure the Optimization Algorithm\n", 133 | "\n", 134 | "We use the CMA-ES (Covariance Matrix Adaptation Evolution Strategy) algorithm from pymoo for optimization. The algorithm is configured with:\n", 135 | "\n", 136 | "- Initial parameter values (```x0```).\n", 137 | "- Termination criteria (e.g., maximum number of evaluations)." 138 | ] 139 | }, 140 | { 141 | "cell_type": "code", 142 | "execution_count": 19, 143 | "metadata": {}, 144 | "outputs": [], 145 | "source": [ 146 | "# Define initial parameter values and bounds\n", 147 | "x0 = denormalize(np.random.random(2), np.array([40, 0.4]), np.array([50, 0.5]))\n", 148 | "\n", 149 | "# Set the number of simulations (evaluations)\n", 150 | "n_simulations = 2\n", 151 | "\n", 152 | "# Configure the CMA-ES algorithm\n", 153 | "algorithm = CMAES(x0=x0, maxfevals=n_simulations)\n", 154 | "termination = get_termination(\"n_eval\", n_simulations)" 155 | ] 156 | }, 157 | { 158 | "cell_type": "markdown", 159 | "metadata": {}, 160 | "source": [ 161 | "---\n", 162 | "## 5. Run the Optimization\n", 163 | "\n", 164 | "We run the optimization using the ```minimize_pymoo``` function. The results include:\n", 165 | "\n", 166 | "- The best set of parameters (```x```).\n", 167 | "- The path to the best simulation results (```path```).\n", 168 | "- The error metric (```error```).\n" 169 | ] 170 | }, 171 | { 172 | "cell_type": "code", 173 | "execution_count": 20, 174 | "metadata": {}, 175 | "outputs": [], 176 | "source": [ 177 | "# Run the optimization\n", 178 | "x, path, error = minimize_pymoo(\n", 179 | " swat_problem,\n", 180 | " algorithm,\n", 181 | " termination,\n", 182 | " verbose=False,\n", 183 | ")" 184 | ] 185 | }, 186 | { 187 | "cell_type": "markdown", 188 | "metadata": {}, 189 | "source": [ 190 | "---\n", 191 | "## 6. Analyze the Results\n", 192 | "\n", 193 | "Finally, we analyze the results of the optimization:\n", 194 | "\n", 195 | "- The best combination of parameters.\n", 196 | "- The path to the simulation results.\n", 197 | "- The error metric." 198 | ] 199 | }, 200 | { 201 | "cell_type": "code", 202 | "execution_count": 21, 203 | "metadata": {}, 204 | "outputs": [ 205 | { 206 | "name": "stdout", 207 | "output_type": "stream", 208 | "text": [ 209 | "Best parameters: [42.2548061 0.41222274]\n", 210 | "Simulation results path: {'test_calibration': PosixPath('/tmp/tmp6gnrs7xq')}\n", 211 | "Error: 0.2528642743696815\n" 212 | ] 213 | } 214 | ], 215 | "source": [ 216 | "# Best combination of parameters\n", 217 | "print(\"Best parameters:\", x)\n", 218 | "\n", 219 | "# Path to the best simulation results\n", 220 | "print(\"Simulation results path:\", path)\n", 221 | "\n", 222 | "# Error metric\n", 223 | "print(\"Error:\", error)" 224 | ] 225 | } 226 | ], 227 | "metadata": { 228 | "kernelspec": { 229 | "display_name": "pyswatplus", 230 | "language": "python", 231 | "name": "python3" 232 | }, 233 | "language_info": { 234 | "codemirror_mode": { 235 | "name": "ipython", 236 | "version": 3 237 | }, 238 | "file_extension": ".py", 239 | "mimetype": "text/x-python", 240 | "name": "python", 241 | "nbconvert_exporter": "python", 242 | "pygments_lexer": "ipython3", 243 | "version": "3.12.1" 244 | } 245 | }, 246 | "nbformat": 4, 247 | "nbformat_minor": 2 248 | } 249 | -------------------------------------------------------------------------------- /docs/examples/sensitivity_analysis.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": {}, 6 | "source": [ 7 | "# Sobol Sensitivity Analysis for SWAT+ Model Parameters\n", 8 | "\n", 9 | "This notebook demonstrates how to perform a Sobol sensitivity analysis on SWAT+ model parameters using the `pySWATPlus` package and the `SALib` library. The analysis focuses on two parameters, `epco` and `esco`, in the `hydrology.hyd` file.\n", 10 | "\n", 11 | "---\n", 12 | "\n", 13 | "## 1. Import Required Libraries\n", 14 | "\n", 15 | "First, we import the necessary libraries, including `pySWATPlus` for SWAT+ model interaction, `SALib` for sensitivity analysis, and `concurrent.futures` for parallel execution." 16 | ] 17 | }, 18 | { 19 | "cell_type": "code", 20 | "execution_count": null, 21 | "metadata": {}, 22 | "outputs": [], 23 | "source": [ 24 | "from pySWATPlus.TxtinoutReader import TxtinoutReader\n", 25 | "import random\n", 26 | "from SALib.sample import saltelli\n", 27 | "from SALib.analyze import sobol\n", 28 | "import numpy as np\n", 29 | "import random\n", 30 | "import concurrent.futures" 31 | ] 32 | }, 33 | { 34 | "cell_type": "markdown", 35 | "metadata": {}, 36 | "source": [ 37 | "---\n", 38 | "\n", 39 | "## 2. Initialize the TxtinoutReader\n", 40 | "\n", 41 | "We initialize the ```TxtinoutReader``` to interact with the SWAT+ project files." 42 | ] 43 | }, 44 | { 45 | "cell_type": "code", 46 | "execution_count": 5, 47 | "metadata": {}, 48 | "outputs": [], 49 | "source": [ 50 | "txtinout_reader = TxtinoutReader('/mnt/c/Users/joans/OneDrive/Escriptori/icra/muga_windows')" 51 | ] 52 | }, 53 | { 54 | "cell_type": "markdown", 55 | "metadata": {}, 56 | "source": [ 57 | "---\n", 58 | "\n", 59 | "## 3. Configure the SWAT+ Simulation\n", 60 | "\n", 61 | "We configure the SWAT+ simulation by setting the simulation period, warmup period, and enabling the output of the ```channel_sd``` variable." 62 | ] 63 | }, 64 | { 65 | "cell_type": "code", 66 | "execution_count": 6, 67 | "metadata": {}, 68 | "outputs": [], 69 | "source": [ 70 | "txtinout_reader.set_beginning_and_end_year(2010, 2012) # Set simulation period\n", 71 | "txtinout_reader.set_warmup(1) # Set warmup period\n", 72 | "txtinout_reader.enable_object_in_print_prt('channel_sd', True, False, False, False) # Enable output for 'channel_sd'" 73 | ] 74 | }, 75 | { 76 | "cell_type": "markdown", 77 | "metadata": {}, 78 | "source": [ 79 | "---\n", 80 | "\n", 81 | "## 4. Define the Model Evaluation Function\n", 82 | "\n", 83 | "We define a function to run the SWAT+ model with specific values for `epco` and `esco` and evaluate the model's output. This function will be used in the sensitivity analysis." 84 | ] 85 | }, 86 | { 87 | "cell_type": "code", 88 | "execution_count": 7, 89 | "metadata": {}, 90 | "outputs": [], 91 | "source": [ 92 | "def run_and_evaluate_swat(epco: float = 0.5, esco: float = 0.5):\n", 93 | " \"\"\"\n", 94 | " Run the SWAT+ model with specific values for `epco` and `esco` and evaluate the output.\n", 95 | "\n", 96 | " Parameters:\n", 97 | " epco (float): Plant evaporation compensation factor.\n", 98 | " esco (float): Soil evaporation compensation factor.\n", 99 | "\n", 100 | " Returns:\n", 101 | " float: A mock error metric (to be replaced with actual evaluation logic).\n", 102 | " \"\"\"\n", 103 | " print(f'Running SWAT with epco = {epco} and esco = {esco} \\\\n')\n", 104 | "\n", 105 | " # Copy the SWAT+ project to a temporary directory for parallel execution\n", 106 | " tmp_path = txtinout_reader.copy_swat()\n", 107 | " reader = TxtinoutReader(tmp_path)\n", 108 | "\n", 109 | " # Register and modify the 'hydrology.hyd' file\n", 110 | " hydrology_hyd = reader.register_file('hydrology.hyd', has_units=False)\n", 111 | " hydrology_hyd_df = hydrology_hyd.df\n", 112 | "\n", 113 | " # Overwrite the values of `epco` and `esco`\n", 114 | " hydrology_hyd_df['epco'] = epco\n", 115 | " hydrology_hyd_df['esco'] = esco\n", 116 | "\n", 117 | " # Save the changes\n", 118 | " hydrology_hyd.overwrite_file()\n", 119 | "\n", 120 | " # Run the SWAT+ model\n", 121 | " txt_in_out_result = reader.run_swat(show_output=False)\n", 122 | "\n", 123 | " # Read the results\n", 124 | " result_reader = TxtinoutReader(txt_in_out_result)\n", 125 | " channel_sdmorph = result_reader.register_file('channel_sdmorph_day.txt', has_units=True)\n", 126 | " channel_sdmorph_df = channel_sdmorph.df\n", 127 | "\n", 128 | " # Here, you should read your observations and calculate the objective function\n", 129 | " # For now, we return a mock value\n", 130 | " return random.random()\n", 131 | "\n", 132 | "# Wrapper function for parallel execution\n", 133 | "def evaluate(params):\n", 134 | " \"\"\"\n", 135 | " Wrapper function for parallel execution of `run_and_evaluate_swat`.\n", 136 | "\n", 137 | " Parameters:\n", 138 | " params (tuple): A tuple containing the values for `epco` and `esco`.\n", 139 | "\n", 140 | " Returns:\n", 141 | " float: The result of `run_and_evaluate_swat`.\n", 142 | " \"\"\"\n", 143 | " return run_and_evaluate_swat(*params)" 144 | ] 145 | }, 146 | { 147 | "cell_type": "markdown", 148 | "metadata": {}, 149 | "source": [ 150 | "---\n", 151 | "\n", 152 | "## 5. Define the Sensitivity Analysis Problem\n", 153 | "\n", 154 | "We define the problem for the Sobol sensitivity analysis, specifying the parameters (`epco` and `esco`) and their bounds." 155 | ] 156 | }, 157 | { 158 | "cell_type": "code", 159 | "execution_count": 8, 160 | "metadata": {}, 161 | "outputs": [], 162 | "source": [ 163 | "problem = {\n", 164 | " 'num_vars': 2, # Number of parameters\n", 165 | " 'names': ['epco', 'esco'], # Parameter names\n", 166 | " 'bounds': [[0, 1]] * 2 # Parameter bounds\n", 167 | "}" 168 | ] 169 | }, 170 | { 171 | "cell_type": "markdown", 172 | "metadata": {}, 173 | "source": [ 174 | "---\n", 175 | "\n", 176 | "## 6. Generate Parameter Samples\n", 177 | "\n", 178 | "We generate parameter samples using the Saltelli sampling method from the `SALib` library." 179 | ] 180 | }, 181 | { 182 | "cell_type": "code", 183 | "execution_count": 9, 184 | "metadata": {}, 185 | "outputs": [ 186 | { 187 | "name": "stderr", 188 | "output_type": "stream", 189 | "text": [ 190 | "/tmp/ipykernel_387433/2689363164.py:1: DeprecationWarning: `salib.sample.saltelli` will be removed in SALib 1.5.1 Please use `salib.sample.sobol`\n", 191 | " param_values = saltelli.sample(problem, 2) # Generate parameter samples\n" 192 | ] 193 | } 194 | ], 195 | "source": [ 196 | "param_values = saltelli.sample(problem, 2) # Generate parameter samples" 197 | ] 198 | }, 199 | { 200 | "cell_type": "markdown", 201 | "metadata": {}, 202 | "source": [ 203 | "---\n", 204 | "\n", 205 | "## 7. Perform Parallel Model Evaluations\n", 206 | "\n", 207 | "We use parallel processing to evaluate the SWAT+ model for each set of parameter values." 208 | ] 209 | }, 210 | { 211 | "cell_type": "code", 212 | "execution_count": 10, 213 | "metadata": {}, 214 | "outputs": [ 215 | { 216 | "name": "stdout", 217 | "output_type": "stream", 218 | "text": [ 219 | "Running SWAT with epco = 0.46875 and esco = 0.46875 \\nRunning SWAT with epco = 0.46875 and esco = 0.46875 \\nRunning SWAT with epco = 0.09375 and esco = 0.65625 \\nRunning SWAT with epco = 0.09375 and esco = 0.46875 \\nRunning SWAT with epco = 0.59375 and esco = 0.15625 \\nRunning SWAT with epco = 0.46875 and esco = 0.65625 \\nRunning SWAT with epco = 0.59375 and esco = 0.96875 \\nRunning SWAT with epco = 0.96875 and esco = 0.96875 \\nRunning SWAT with epco = 0.96875 and esco = 0.96875 \\nRunning SWAT with epco = 0.96875 and esco = 0.15625 \\nRunning SWAT with epco = 0.09375 and esco = 0.65625 \\n\n", 220 | "\n", 221 | "\n", 222 | "\n", 223 | "\n", 224 | "\n", 225 | "\n", 226 | "\n", 227 | "\n", 228 | "\n", 229 | "\n", 230 | "Running SWAT with epco = 0.59375 and esco = 0.15625 \\n\n" 231 | ] 232 | } 233 | ], 234 | "source": [ 235 | "# Parallel execution of model evaluations\n", 236 | "with concurrent.futures.ProcessPoolExecutor() as executor:\n", 237 | " y = np.array(list(executor.map(evaluate, param_values)))" 238 | ] 239 | }, 240 | { 241 | "cell_type": "markdown", 242 | "metadata": {}, 243 | "source": [ 244 | "---\n", 245 | "\n", 246 | "## 8. Analyze the Results\n", 247 | "We perform the Sobol sensitivity analysis to calculate the sensitivity indices." 248 | ] 249 | }, 250 | { 251 | "cell_type": "code", 252 | "execution_count": 11, 253 | "metadata": {}, 254 | "outputs": [ 255 | { 256 | "name": "stderr", 257 | "output_type": "stream", 258 | "text": [ 259 | "/home/zephol/miniconda3/envs/pyswatplus/lib/python3.12/site-packages/SALib/util/__init__.py:274: FutureWarning: unique with argument that is not not a Series, Index, ExtensionArray, or np.ndarray is deprecated and will raise in a future version.\n", 260 | " names = list(pd.unique(groups))\n" 261 | ] 262 | } 263 | ], 264 | "source": [ 265 | "sobol_indices = sobol.analyze(problem, y) # Perform Sobol analysis" 266 | ] 267 | }, 268 | { 269 | "cell_type": "markdown", 270 | "metadata": {}, 271 | "source": [ 272 | "---\n", 273 | "\n", 274 | "## 9. Interpret the Results\n", 275 | "The `sobol_indices` object contains the first-order, second-order, and total-order sensitivity indices for `epco` and `esco`. These indices can be used to understand the relative importance of each parameter in influencing the model output." 276 | ] 277 | }, 278 | { 279 | "cell_type": "code", 280 | "execution_count": 12, 281 | "metadata": {}, 282 | "outputs": [ 283 | { 284 | "name": "stdout", 285 | "output_type": "stream", 286 | "text": [ 287 | "First-order Sobol indices: [-0.84706442 1.00546731]\n", 288 | "Total-order Sobol indices: [0.55593247 1.05855786]\n" 289 | ] 290 | } 291 | ], 292 | "source": [ 293 | "print(\"First-order Sobol indices:\", sobol_indices['S1'])\n", 294 | "print(\"Total-order Sobol indices:\", sobol_indices['ST'])" 295 | ] 296 | } 297 | ], 298 | "metadata": { 299 | "kernelspec": { 300 | "display_name": "pyswatplus", 301 | "language": "python", 302 | "name": "python3" 303 | }, 304 | "language_info": { 305 | "codemirror_mode": { 306 | "name": "ipython", 307 | "version": 3 308 | }, 309 | "file_extension": ".py", 310 | "mimetype": "text/x-python", 311 | "name": "python", 312 | "nbconvert_exporter": "python", 313 | "pygments_lexer": "ipython3", 314 | "version": "3.12.1" 315 | } 316 | }, 317 | "nbformat": 4, 318 | "nbformat_minor": 2 319 | } 320 | -------------------------------------------------------------------------------- /docs/getting-started.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | ## Installation 4 | 5 | ```bash 6 | pip install pandas numpy pymoo tqdm dask 7 | pip install pySWATPlus 8 | ``` 9 | 10 | ## Basic Usage 11 | 12 | ```python 13 | from pySWATPlus.TxtinoutReader import TxtinoutReader 14 | 15 | # Initialize with your SWAT+ project 16 | reader = TxtinoutReader("path/to/swatplus_project") 17 | 18 | # Run SWAT+ with modified parameters 19 | results = reader.run_swat( 20 | params={'plants.plt': ('name', [('bana', 'bm_e', 45)])}, 21 | show_output=False 22 | ) 23 | ``` 24 | 25 | [View more examples](https://github.com/swat-model/pySWATPlus/tree/main/examples) -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # pySWATPlus 2 | 3 | 4 | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14889320.svg)](https://doi.org/10.5281/zenodo.14889320) 5 | 6 | 7 | **pySWATPlus** is a Python package that makes working with SWAT+ models easier and more powerful. Whether you're running default setups or custom projects, this tool lets you interact with SWAT+ programmatically, so you can focus on optimizing and analyzing your models like a pro! 🚀 8 | 9 | --- 10 | 11 | ## ✨ Key Features 12 | 13 | - **Access and Modify SWAT+ Files**: Navigate, read, modify, and write files in the `TxtInOut` folder used by SWAT+. 📂 14 | - **Model Calibration**: Optimize SWAT+ input parameters using the [Pymoo](https://pymoo.org/) optimization framework to get the best results. 🎯 15 | 16 | --- 17 | 18 | ## 📦 About 19 | 20 | pySWATPlus is an open-source software developed and maintained by [ICRA](https://icra.cat/). It’s available for download and installation via [PyPI](https://pypi.org/project/pySWATPlus/). 21 | 22 | --- 23 | 24 | ## 🛠️ Installation 25 | 26 | Before installing pySWATPlus, make sure you have the following dependencies installed: 27 | 28 | ```py 29 | pip install pandas numpy pymoo tqdm dask 30 | ``` 31 | 32 | --- 33 | 34 | ## ⚙️ Requirements 35 | 36 | To use this package, a Python version above 3.6 is required. 37 | 38 | --- 39 | 40 | ## 📥 Install pySWATPlus 41 | 42 | Once the dependencies are installed, you can install pySWATPlus using this simple command: 43 | 44 | ````py 45 | pip install pySWATPlus 46 | ```` 47 | 48 | --- 49 | 50 | ## 🚀 Getting Started 51 | 52 | The **[Getting Started](getting-started.md)** page is the perfect place to begin your journey with pySWATPlus. It covers the basics and links to practical examples, from setting up and running a simple SWAT+ project to diving into parameter optimization techniques and sensitivity analysis. 53 | 54 | For a deeper dive, check out the **[API Reference](api/txtinoutreader.md)**, which documents all functions, input arguments, and provides short examples on how to use them. The API Reference includes: 55 | 56 | - **[TxtinoutReader](api/txtinoutreader.md)**: Work with SWAT+ input and output files. 57 | - **[FileReader](api/filereader.md)**: Read and manipulate SWAT+ files. 58 | - **[SWATProblem](api/swatproblem.md)**: Define and solve SWAT+ optimization problems. 59 | - **[SWATProblemMultimodel](api/swatproblemmultimodel.md)**: Handle multi-model calibration scenarios. 60 | --- 61 | 62 | 63 | ## 📖 Citation 64 | To cite pySWATPlus, use: 65 | 66 | ```tex 67 | @misc{Salo_Llorente_2023, 68 | author = {Saló, Joan and Llorente, Oliu}, 69 | title = {{pySWATPlus: A Python Interface for SWAT+ Model Calibration and Analysis}}, 70 | year = {2023}, 71 | month = dec, 72 | publisher = {Zenodo}, 73 | version = {0.1.0}, 74 | doi = {10.5281/zenodo.14889320}, 75 | url = {https://doi.org/10.5281/zenodo.14889320} 76 | } 77 | ``` -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: pySWATPlus 2 | theme: 3 | name: material 4 | features: 5 | - navigation.tabs 6 | - content.code.annotate 7 | palette: 8 | - scheme: default 9 | toggle: 10 | icon: material/toggle-switch-off-outline 11 | name: Switch to dark mode 12 | - scheme: slate 13 | toggle: 14 | icon: material/toggle-switch 15 | name: Switch to light mode 16 | 17 | plugins: 18 | - mkdocstrings: 19 | handlers: 20 | python: 21 | options: 22 | docstring_style: google 23 | show_signature_annotations: true 24 | show_source: false 25 | - mkdocs-jupyter 26 | 27 | markdown_extensions: 28 | - admonition 29 | - pymdownx.highlight 30 | - pymdownx.superfences 31 | - pymdownx.details 32 | 33 | nav: 34 | - Home: index.md 35 | - Getting Started: 36 | - Basic Usage: examples/basic_examples.ipynb 37 | - Calibration: examples/calibration.ipynb 38 | - Sensitivy Analysis: examples/sensitivity_analysis.ipynb 39 | 40 | - API Reference: 41 | - TxtinoutReader: api/txtinoutreader.md 42 | - FileReader: api/filereader.md 43 | - SWATProblem: api/swatproblem.md 44 | - SWATProblemMultimodel: api/swatproblemmultimodel.md 45 | - Citation: citation.md -------------------------------------------------------------------------------- /pySWATPlus/FileReader.py: -------------------------------------------------------------------------------- 1 | import pandas as pd 2 | import warnings 3 | import dask.dataframe as dd 4 | from pathlib import Path 5 | from typing import Union, List, Dict, Literal, Optional, Any 6 | import os 7 | import re 8 | 9 | 10 | def read_csv( 11 | path: Union[str, Path], 12 | skip_rows: List[int], 13 | usecols: List[str], 14 | filter_by: Dict[str, Union[Any, List[Any], re.Pattern]], 15 | separator: str, 16 | encoding: str, 17 | engine: Literal['c', 'python'], 18 | mode: Literal['dask', 'pandas'] = 'dask' 19 | ) -> Union[pd.DataFrame, dd.DataFrame]: 20 | 21 | ''' 22 | Read a CSV file using either Dask or Pandas and filter the data based on criteria. 23 | 24 | Parameters: 25 | path (Union[str, Path]): The path to the CSV file. 26 | skip_rows (List[int]): List of specific row numbers to skip. 27 | usecols (List[str]): A list of column names to read 28 | filter_by (Dict[str, Union[Any, List[Any], re.Pattern]): A dictionary of column names and values to filter by. 29 | separator (str): The delimiter used in the CSV file. 30 | encoding (str): The character encoding to use when reading the file. 31 | engine (Literal['c', 'python']): The CSV parsing engine to use (e.g., 'c' for C engine, 'python' for Python engine). 32 | mode (Literal['dask', 'pandas']): The mode to use for reading ('dask' or 'pandas'). 33 | 34 | Returns: 35 | Union[pd.DataFrame, dd.DataFrame]: A DataFrame containing the filtered data. The type depends on the chosen mode. 36 | 37 | Note: 38 | - When `mode` is 'dask', a Dask DataFrame is returned. 39 | - When `mode` is 'pandas', a Pandas DataFrame is returned. 40 | 41 | Example: 42 | 43 | read_csv( 44 | 'plants.plt', 45 | skip_rows=[0], 46 | usecols=['name', 'plnt_typ', 'gro_trig'], 47 | filter_by={'plnt_typ': 'perennial'}, separator=r"[ ]{2,}", 48 | encoding="utf-8", 49 | engine='python', 50 | mode='dask' 51 | ) 52 | ''' 53 | 54 | if mode == 'dask': 55 | df = dd.read_csv( 56 | path, 57 | sep=separator, 58 | skiprows=skip_rows, 59 | assume_missing=True, 60 | usecols=usecols, 61 | encoding=encoding, 62 | engine=engine 63 | ) 64 | 65 | for column, condition in filter_by.items(): 66 | if isinstance(condition, list): 67 | df = df.loc[df[column].isin(condition)] 68 | elif isinstance(condition, re.Pattern): 69 | df = df.loc[df[column].str.match(condition)] 70 | else: 71 | df = df.loc[df[column] == condition] 72 | 73 | return df.compute().reset_index(drop=True) 74 | 75 | elif mode == 'pandas': 76 | df = pd.read_csv( 77 | path, 78 | sep=separator, 79 | skiprows=skip_rows, 80 | usecols=usecols, 81 | encoding=encoding, 82 | engine=engine 83 | ) 84 | 85 | for column, condition in filter_by.items(): 86 | if isinstance(condition, list): 87 | df = df.loc[df[column].isin(condition)] 88 | elif isinstance(condition, re.Pattern): 89 | df = df.loc[df[column].str.match(condition)] 90 | else: 91 | df = df.loc[df[column] == condition] 92 | 93 | return df.reset_index(drop=True) 94 | 95 | 96 | class FileReader: 97 | 98 | def __init__( 99 | self, 100 | path: str, 101 | has_units: bool = False, 102 | index: Optional[str] = None, 103 | usecols: List[str] = None, 104 | filter_by: Dict[str, Union[Any, List[Any], re.Pattern]] = {} 105 | ): 106 | 107 | ''' 108 | Initialize a FileReader instance to read data from a file. 109 | 110 | Parameters: 111 | path (str, os.PathLike): The path to the file. 112 | has_units (bool): Indicates if the file has units (default is False). 113 | index (str, optional): The name of the index column (default is None). 114 | usecols (List[str], optional): A list of column names to read (default is None). 115 | filter_by (Dict[str, Union[Any, List[Any], re.Pattern], optional): A dictionary of column names and values to filter. 116 | 117 | Raises: 118 | FileNotFoundError: If the specified file does not exist. 119 | TypeError: If there's an issue reading the file or if the resulting DataFrame is not of type pandas.DataFrame. 120 | 121 | Attributes: 122 | df (pd.DataFrame): a dataframe containing the data from the file. 123 | 124 | 125 | Note: 126 | - When has_units is True, the file is expected to have units information, and the units_file attribute will be set. 127 | - The read_csv method is called with different parameters to attempt reading the file with various delimiters and encodings. 128 | - If an index column is specified, it will be used as the index in the DataFrame. 129 | 130 | Example: 131 | FileReader('plants.plt', has_units = False, index = 'name', usecols=['name', 'plnt_typ', 'gro_trig'], filter_by={'plnt_typ': 'perennial'}) 132 | ''' 133 | 134 | if not isinstance(path, (str, os.PathLike)): 135 | raise TypeError("path must be a string or os.PathLike object") 136 | 137 | path = Path(path).resolve() 138 | 139 | if not path.is_file(): 140 | raise FileNotFoundError("file does not exist") 141 | 142 | df = None 143 | 144 | # skips the header 145 | skip_rows = [0] 146 | # skips the units 147 | if has_units: 148 | skip_rows.append(2) 149 | 150 | # if file is txt 151 | if path.suffix == '.csv': 152 | raise TypeError("Not implemented yet") 153 | 154 | else: 155 | # read only first line of file 156 | with open(path, 'r', encoding='latin-1') as file: 157 | # Read the first line 158 | self.header_file = file.readline() 159 | 160 | if has_units: 161 | # read only third line of file 162 | with open(path, 'r', encoding='latin-1') as file: 163 | # Use a for loop to iterate through the file, reading lines 164 | for line_number, line in enumerate(file, start=1): 165 | if line_number == 3: 166 | self.units_file = line 167 | break 168 | 169 | csv_options = [ 170 | (r'\s+', 'utf-8', 'c', 'dask'), 171 | (r'\s+', 'latin-1', 'c', 'dask'), 172 | (r"[ ]{2,}", 'utf-8', 'python', 'dask'), 173 | (r"[ ]{2,}", 'latin-1', 'python', 'dask'), 174 | (r'\s+', 'utf-8', 'c', 'pandas'), 175 | (r'\s+', 'latin-1', 'c', 'pandas'), 176 | (r"[ ]{2,}", 'utf-8', 'python', 'pandas'), 177 | (r"[ ]{2,}", 'latin-1', 'python', 'pandas') 178 | ] 179 | 180 | with warnings.catch_warnings(record=True): 181 | warnings.simplefilter("error") 182 | last_exception = None 183 | for delimiter, encoding, engine, backend in csv_options: 184 | try: 185 | df = read_csv(path, skip_rows, usecols, filter_by, delimiter, encoding, engine, backend) 186 | break 187 | except Exception as e: 188 | last_exception = e 189 | else: 190 | raise Exception(f"All combinations of delimiter, encoding, engine, and backend failed. Last exception: {last_exception}") 191 | 192 | # check if df is a pandas dataframe 193 | if not isinstance(df, pd.DataFrame): 194 | raise TypeError("Something went wrong!") 195 | 196 | df.columns = df.columns.str.replace(' ', '') 197 | 198 | if index is not None: 199 | aux_index_name = 'aux_index' 200 | 201 | # Add the copied 'name' column back to the DataFrame 202 | df[aux_index_name] = df[index] 203 | 204 | # Set the 'name' column as the index 205 | df.set_index(aux_index_name, inplace=True) 206 | 207 | # Change the index name to a default name, such as 'index' 208 | df.rename_axis('', inplace=True) 209 | 210 | self.df = df 211 | self.path = path 212 | 213 | def _store_text( 214 | self 215 | ) -> None: 216 | 217 | ''' 218 | Store the DataFrame as a formatted text file. 219 | 220 | This method converts the DataFrame to a formatted string with adjusted column widths and writes it to a .txt file. 221 | The text file will contain the header and the formatted data. 222 | 223 | TODO: This function still does not write the corresponding units, in case the original file had it. 224 | 225 | Returns: 226 | None 227 | ''' 228 | 229 | data_str = self.df.to_string(index=False, justify='left', col_space=15) 230 | 231 | # Find the length of the longest string in each column 232 | max_lengths = self.df.apply(lambda x: x.astype(str).str.len()).max() 233 | 234 | # Define the column widths based on the longest string length 235 | column_widths = {column: max_length + 3 for column, max_length in max_lengths.items()} 236 | 237 | # Convert the DataFrame to a formatted string with adjusted column widths 238 | data_str = self.df.to_string(index=False, justify='right', col_space=column_widths) 239 | 240 | # Write the string to a .txt file 241 | with open(self.path, 'w') as file: 242 | file.write(self.header_file) 243 | file.write(data_str) 244 | 245 | def _store_csv( 246 | self 247 | ) -> None: 248 | 249 | ''' 250 | Store the DataFrame as a CSV file. 251 | 252 | This method raises a TypeError to indicate that storing as a CSV file is not implemented yet. 253 | 254 | Returns: 255 | None 256 | ''' 257 | 258 | raise TypeError("Not implemented yet") 259 | 260 | def overwrite_file( 261 | self 262 | ) -> None: 263 | 264 | ''' 265 | Overwrite the original file with the DataFrame. 266 | 267 | This method checks the file extension and calls the appropriate storage method (_store_csv or _store_text). 268 | 269 | Returns: 270 | None 271 | ''' 272 | 273 | if self.path.suffix == '.csv': 274 | self._store_csv() 275 | else: 276 | self._store_text() 277 | -------------------------------------------------------------------------------- /pySWATPlus/PymooBestSolution.py: -------------------------------------------------------------------------------- 1 | import numpy as np 2 | import itertools 3 | import shutil 4 | import multiprocessing 5 | from typing import Dict, List, Tuple 6 | 7 | 8 | class SolutionManager: 9 | 10 | """ 11 | Class to manage the best solution found during optimization. 12 | """ 13 | 14 | def __init__( 15 | self 16 | ): 17 | 18 | self.X = None 19 | self.path = None 20 | self.error = None 21 | self.lock = multiprocessing.Lock() 22 | 23 | def add_solution( 24 | self, 25 | X: np.ndarray, 26 | path: Dict[str, str], 27 | error: float 28 | ) -> None: 29 | 30 | """ 31 | Add a solution if it is better than the current best solution. 32 | """ 33 | 34 | with self.lock: 35 | if self.error is None or error < self.error: 36 | self.X = X 37 | self.path = path 38 | self.error = error 39 | 40 | def get_solution( 41 | self 42 | ) -> Tuple[np.ndarray, Dict[str, str], float]: 43 | 44 | """ 45 | Retrieve the best solution. 46 | """ 47 | 48 | with self.lock: 49 | return self.X, self.path, self.error 50 | 51 | def add_solutions( 52 | self, 53 | X_array: np.ndarray, 54 | paths_array: List[Dict[str, str]], 55 | errors_array: np.ndarray 56 | ) -> None: 57 | 58 | """ 59 | Update the best solution based on provided paths and errors. Only the best solution is kept; others are deleted. 60 | """ 61 | 62 | if len(errors_array) == 0: 63 | return 64 | 65 | min_idx = np.nanargmin(errors_array) 66 | path = paths_array[min_idx] 67 | error = errors_array[min_idx] 68 | X = X_array[min_idx] 69 | 70 | self.add_solution(X, path, error) 71 | 72 | with self.lock: 73 | best_paths = set(self.path.values()) if self.path else set() 74 | all_paths = set(itertools.chain.from_iterable(map(lambda x: x.values(), paths_array))) 75 | 76 | for i in all_paths: 77 | if i not in best_paths and i is not None: 78 | shutil.rmtree(i, ignore_errors=True) 79 | -------------------------------------------------------------------------------- /pySWATPlus/SWATProblem.py: -------------------------------------------------------------------------------- 1 | from typing import Callable, Tuple, Any, Dict, List 2 | from .SWATProblemMultimodel import SWATProblemMultimodel 3 | 4 | 5 | class SWATProblem(SWATProblemMultimodel): 6 | 7 | def __init__( 8 | self, 9 | params: Dict[str, Tuple[str, List[Tuple[str, str, float, float]]]], 10 | function_to_evaluate: Callable, 11 | param_arg_name: str, 12 | n_workers: int = 1, 13 | parallelization: str = 'threads', 14 | debug: bool = False, 15 | **kwargs: Dict[str, Any] 16 | ) -> None: 17 | 18 | """ 19 | This feature inicializes a SWATProblem instance, which is used to perform optimization of the desired SWAT+ parameters by using the pymoo library. 20 | 21 | Parameters: 22 | - params Dict[str, Tuple[str, List[Tuple[str, str, int, int]]]]): A dictionary containing the range of values to optimize. 23 | Format: {filename: (id_col, [(id, col, upper_bound, lower_bound)])} 24 | - function_to_evaluate (Callable): An objective function to minimize. This function, which has to be created entirely by the user, should be responsible for adjusting the necessary values based on the 25 | calibration iteration, running SWAT, reading the results, comparing them with observations, and calculating an error measure. The function can accept any user-defined arguments, but it must receive at least 26 | one argument (named as indicated by param_arg_name), which takes a dictionary in the format {filename: (id_col, [(id, col, value)])}, representing the current calibration values. 27 | Format: function_to_evaluate(Dict[Any, Any]) -> Tuple[int, Dict[str, str]] where the first element is the error produced in the observations and the second element is a dictionary containing a user-desired 28 | identifier as the key and the location where the simulation has been saved as the value. 29 | - param_arg_name (str): The name of the argument within function_to_evaluate function where the current calibration parameters are expected to be passed. This parameter must be included in **kwargs 30 | - n_workers (int, optional): The number of parallel workers to use (default is 1). 31 | - parallelization (str, optional): The parallelization method to use ('threads' or 'processes') (default is 'threads'). 32 | - debug (bool, optional): If True, print debug output during optimization (default is False). 33 | - **kwargs: Additional keyword arguments, that will be passed to function_to_evaluate. 34 | 35 | Returns: 36 | None 37 | """ 38 | 39 | super().__init__(params, function_to_evaluate, param_arg_name, n_workers, parallelization, None, None, None, None, None, debug, **kwargs) 40 | -------------------------------------------------------------------------------- /pySWATPlus/SWATProblemMultimodel.py: -------------------------------------------------------------------------------- 1 | from pymoo.core.problem import Problem 2 | from .PymooBestSolution import SolutionManager 3 | import copy 4 | import numpy as np 5 | from typing import Optional, Callable, Tuple, Any, Dict, List 6 | from pymoo.optimize import minimize 7 | from concurrent.futures import ThreadPoolExecutor 8 | import multiprocessing 9 | import warnings 10 | 11 | 12 | def minimize_pymoo( 13 | problem: Problem, 14 | algorithm: Any, 15 | termination: Any, 16 | seed: Optional[int] = None, 17 | verbose: bool = False, 18 | callback: Optional[Callable] = None 19 | ) -> Tuple[Optional[np.ndarray], Optional[str], Optional[float]]: 20 | 21 | """ 22 | Perform optimization using the pymoo library. 23 | 24 | Parameters: 25 | - problem (pyswatplus SWATProblem): The optimization problem defined using the SWATProblem class. 26 | - algorithm (pymoo Algorithm): The optimization algorithm defined using the pymoo Algorithm class. 27 | - termination (pymoo Termination): The termination criteria for the optimization defined using the pymoo Termination class. 28 | - seed (Optional[int], optional): The random seed for reproducibility (default is None). 29 | - verbose (bool, optional): If True, print verbose output during optimization (default is False). 30 | - callback (Optional[Callable], optional): A callback function that is called after each generation (default is None). 31 | 32 | Returns: 33 | - Tuple[np.ndarray, Dict[str, str], float]: The best solution found during the optimization process, in the form of a tuple containing the decision variables, 34 | the path to the output files with the identifier, and the error. 35 | """ 36 | 37 | problem.solution_manager = SolutionManager() 38 | 39 | with warnings.catch_warnings(): 40 | warnings.filterwarnings("ignore", category=DeprecationWarning) 41 | 42 | if callback is None: 43 | minimize( 44 | problem, 45 | algorithm, 46 | seed=seed, 47 | verbose=verbose, 48 | termination=termination 49 | ) 50 | else: 51 | minimize( 52 | problem, 53 | algorithm, 54 | seed=seed, 55 | verbose=verbose, 56 | callback=callback, 57 | termination=termination 58 | ) 59 | 60 | return problem.solution_manager.get_solution() 61 | 62 | 63 | class SWATProblemMultimodel(Problem): 64 | 65 | def __init__( 66 | self, 67 | params: Dict[str, Tuple[str, List[Tuple[str, str, float, float]]]], 68 | function_to_evaluate: Callable, 69 | param_arg_name: str, 70 | n_workers: int = 1, 71 | parallelization: str = 'threads', 72 | ub_prior: Optional[List[int]] = None, 73 | lb_prior: Optional[List[int]] = None, 74 | function_to_evaluate_prior: Optional[Callable] = None, 75 | args_function_to_evaluate_prior: Optional[Dict[str, Any]] = None, 76 | param_arg_name_to_modificate_by_prior_function: Optional[str] = None, 77 | debug: bool = False, 78 | **kwargs: Dict[str, Any] 79 | ) -> None: 80 | 81 | """ 82 | This class serves the same purpose as SWATProblem, with the added capability of running another model before executing SWAT+. 83 | This enables running a prior model in the same calibration process, wherein the parameters are calibrated simultaneously. 84 | For example, the prior model can modify an input file of SWAT+ before initiating SWAT+ (according to the parameters of the calibration). 85 | 86 | Parameters: 87 | - params Dict[str, Tuple[str, List[Tuple[str, str, int, int]]]]): A dictionary containing the range of values to optimize. 88 | Format: {filename: (id_col, [(id, col, upper_bound, lower_bound)])} 89 | - function_to_evaluate (Callable): An objective function to minimize. This function, which has to be created entirely by the user, should be responsible for adjusting the necessary values based on the 90 | calibration iteration, running SWAT, reading the results, comparing them with observations, and calculating an error measure. The function can accept any user-defined arguments, but it must receive at least 91 | one argument (named as indicated by param_arg_name), which takes a dictionary in the format {filename: (id_col, [(id, col, value)])}, representing the current calibration values. 92 | Format: function_to_evaluate(Dict[Any, Any]) -> Tuple[int, Dict[str, str]] where the first element is the error produced in the observations and the second element is a dictionary containing a user 93 | desired identifier as the key and the location where the simulation has been saved as the value. 94 | - param_arg_name (str): The name of the argument within function_to_evaluate function where the current calibration parameters are expected to be passed. This parameter must be included in **kwargs 95 | - n_workers (int, optional): The number of parallel workers to use (default is 1). 96 | - parallelization (str, optional): The parallelization method to use ('threads' or 'processes') (default is 'threads'). 97 | - ub_prior (List[int], optional): Upper bounds list of calibrated parameters of the prior model. Default is None. 98 | - lb_prior (List[int], optional): Lower bounds list of calibrated parameters of the prior model. Default is None. 99 | - function_to_evaluate_prior (Callable, optional): Prior function to be used for modifying parameters before SWAT+ simulation. Must take the name indicated by args_function_to_evaluate_prior as a mandatory 100 | argument, and must be a np.ndarray, so in the source code the following is done: function_to_evaluate_prior(args_function_to_evaluate_prior = np.ndarray, ...). Must return a value that will be used to 101 | modify a parameter in the kwargs dictionary. Default is None. 102 | - args_function_to_evaluate_prior (Dict[str, Any], optional): Additional arguments for function_to_evaluate_prior. args_function_to_evaluate_prior does not have to be included here. This dictionary will be unpacked and passed as keyword arguments of args_function_to_evaluate_prior. 103 | - param_arg_name_to_modificate_by_prior_function (str, optional): Parameter modified in kwargs by the return of function_to_evaluate_prior, so in the source code the following is done: kwargs[param_arg_name_to_modificate_by_prior_function] = function_to_evaluate_prior(...) 104 | - debug (bool, optional): If True, print debug output during optimization (default is False). 105 | - **kwargs: Additional keyword arguments, that will be passed to function_to_evaluate. 106 | 107 | Returns: 108 | None 109 | """ 110 | 111 | lb = [] 112 | ub = [] 113 | for _, params_file in list(params.values()): 114 | for x in params_file: 115 | lb.append(x[2]) 116 | ub.append(x[3]) 117 | n_vars = len(lb) 118 | 119 | self.n_vars_prior = 0 120 | if ub_prior is not None and lb_prior is not None: 121 | 122 | if len(ub_prior) != len(lb_prior): 123 | raise ValueError('ub_prior and lb_prior must have the same length') 124 | 125 | n_vars += len(ub_prior) 126 | lb = [*lb_prior, *lb] 127 | ub = [*ub_prior, *ub] 128 | self.n_vars_prior = len(ub_prior) 129 | 130 | self.function_to_evaluate = function_to_evaluate 131 | self.n_workers = n_workers 132 | self.parallelization = parallelization 133 | self.params = params 134 | self.kwargs = kwargs 135 | self.param_arg_name = param_arg_name 136 | self.function_to_evaluate_prior = function_to_evaluate_prior 137 | self.args_function_to_evaluate_prior = args_function_to_evaluate_prior 138 | self.param_arg_name_to_modificate_by_prior_function = param_arg_name_to_modificate_by_prior_function 139 | self.debug = debug 140 | self.solution_manager = None # it is initialized in the minize_pymoo function 141 | super().__init__(n_var=n_vars, n_obj=1, n_constr=0, xl=lb, xu=ub, elementwise_evaluation=False) 142 | 143 | def _evaluate( 144 | self, 145 | X: np.ndarray, 146 | out: Dict[str, Any], 147 | *args: Any, 148 | **kwargs: Any 149 | ): 150 | 151 | """ 152 | Evaluate the objective function for a given set of input parameters. 153 | 154 | Parameters: 155 | - X (np.ndarray): The input parameters to be evaluated. 156 | - out (Dict[str, Any]): A dictionary to store the output values. 157 | - *args (Any): Additional positional arguments. 158 | - **kwargs (Any): Additional keyword arguments. 159 | 160 | Returns: 161 | None 162 | """ 163 | 164 | if self.debug: 165 | print('starting _evaluate') 166 | 167 | args_array = [] 168 | 169 | for x in X: 170 | 171 | X_prior = x[:self.n_vars_prior] 172 | X_swat = x[self.n_vars_prior:] 173 | 174 | if self.function_to_evaluate_prior is not None: 175 | return_function_prior = self.function_to_evaluate_prior(X=X_prior, **self.args_function_to_evaluate_prior) 176 | 177 | _id = 0 178 | new_params = {} # in the end will be {filename: (id_col, [(id, col, value)])} 179 | params = self.params # {filename: (id_col, [(id, col, lb, ub)])} 180 | 181 | for file in params.keys(): 182 | index, params_tuple = params[file] 183 | new_params[file] = (index, []) 184 | for param in params_tuple: 185 | new_params[file][1].append((param[0], param[1], X_swat[_id])) 186 | _id += 1 187 | 188 | self.kwargs[self.param_arg_name] = new_params 189 | 190 | if self.param_arg_name_to_modificate_by_prior_function is not None: 191 | self.kwargs[self.param_arg_name_to_modificate_by_prior_function] = return_function_prior 192 | 193 | args_array.append(copy.deepcopy(self.kwargs)) 194 | 195 | # F = self.pool.map(self.fuction_to_evaluate, args_array) 196 | if self.parallelization == 'threads': 197 | with ThreadPoolExecutor(max_workers=self.n_workers) as executor: 198 | F = list(executor.map(self.function_to_evaluate, args_array)) 199 | elif self.parallelization == 'processes': 200 | with multiprocessing.Pool(self.n_workers) as pool: 201 | F = list(pool.map(self.function_to_evaluate, args_array)) 202 | else: 203 | raise ValueError("parallelization must be 'threads' or 'processes'") 204 | 205 | errors, paths = zip(*F) 206 | 207 | errors_array = np.array(errors) 208 | paths_array = np.array(paths) 209 | 210 | if self.debug: 211 | print(f"errors array: {errors_array}") 212 | print(f"paths array: {paths_array}") 213 | 214 | # replace nan error by 1e10 (infinity) 215 | errors_array[np.isnan(errors_array)] = 1e10 216 | 217 | # check if nans and print message 218 | if np.isnan(errors_array).any() and self.debug: 219 | print('ERROR: some errors are nan') 220 | print(errors_array) 221 | print(paths_array) 222 | 223 | if self.debug: 224 | print('adding solutions') 225 | 226 | self.solution_manager.add_solutions(X, paths_array, errors_array) 227 | 228 | if self.debug: 229 | print('exit adding solutions') 230 | 231 | # minimitzar error 232 | out["F"] = errors_array 233 | 234 | if self.debug: 235 | print('returning from _evaluate') 236 | -------------------------------------------------------------------------------- /pySWATPlus/TxtinoutReader.py: -------------------------------------------------------------------------------- 1 | import subprocess 2 | import os 3 | from .FileReader import FileReader 4 | import shutil 5 | import tempfile 6 | import multiprocessing 7 | import tqdm 8 | from pathlib import Path 9 | from typing import List, Dict, Tuple, Optional, Union, Any 10 | from concurrent.futures import ThreadPoolExecutor 11 | import re 12 | 13 | 14 | class TxtinoutReader: 15 | 16 | def __init__( 17 | self, 18 | path: str 19 | ) -> None: 20 | 21 | """ 22 | Initialize a TxtinoutReader instance for working with SWAT model data. 23 | 24 | Parameters: 25 | path (str, os.PathLike): The path to the SWAT model folder. 26 | 27 | Raises: 28 | TypeError: If the provided path is not a string or a Path object, or if the folder does not exist, 29 | or if there is more than one .exe file in the folder, or if no .exe file is found. 30 | 31 | Attributes: 32 | root_folder (Path): The path to the root folder of the SWAT model. 33 | swat_exe_path (Path): The path to the main SWAT executable file. 34 | """ 35 | 36 | # check if path is a string or a path 37 | if not isinstance(path, (str, os.PathLike)): 38 | raise TypeError("path must be a string or os.PathLike object") 39 | 40 | path = Path(path).resolve() 41 | 42 | # check if folder exists 43 | if not path.is_dir(): 44 | raise FileNotFoundError("Folder does not exist") 45 | 46 | # count files that end with .exe 47 | count = 0 48 | swat_exe = None 49 | for file in os.listdir(path): 50 | if file.endswith(".exe"): 51 | if count == 0: 52 | swat_exe = file 53 | elif count > 0: 54 | raise TypeError("More than one .exe file found in the parent folder") 55 | count += 1 56 | 57 | if count == 0: 58 | raise TypeError(".exe not found in parent folder") 59 | 60 | # find parent directory 61 | self.root_folder = path 62 | self.swat_exe_path = path / swat_exe 63 | 64 | def _build_line_to_add( 65 | self, 66 | obj: str, 67 | daily: bool, 68 | monthly: bool, 69 | yearly: bool, 70 | avann: bool 71 | ) -> str: 72 | 73 | """ 74 | Build a line to add to the 'print.prt' file based on the provided parameters. 75 | 76 | Parameters: 77 | obj (str): The object name or identifier. 78 | daily (bool): Flag for daily print frequency. 79 | monthly (bool): Flag for monthly print frequency. 80 | yearly (bool): Flag for yearly print frequency. 81 | avann (bool): Flag for average annual print frequency. 82 | 83 | Returns: 84 | str: A formatted string representing the line to add to the 'print.prt' file. 85 | """ 86 | 87 | print_periodicity = { 88 | 'daily': daily, 89 | 'monthly': monthly, 90 | 'yearly': yearly, 91 | 'avann': avann, 92 | } 93 | 94 | arg_to_add = obj.ljust(29) 95 | for value in print_periodicity.values(): 96 | if value: 97 | periodicity = 'y' 98 | else: 99 | periodicity = 'n' 100 | 101 | arg_to_add += periodicity.ljust(14) 102 | 103 | arg_to_add = arg_to_add.rstrip() 104 | arg_to_add += '\n' 105 | 106 | return arg_to_add 107 | 108 | def enable_object_in_print_prt( 109 | self, 110 | obj: str, 111 | daily: bool, 112 | monthly: bool, 113 | yearly: bool, 114 | avann: bool 115 | ) -> None: 116 | 117 | """ 118 | Enable or update an object in the 'print.prt' file. If obj is not a default identifier, it will be added at the end of the file. 119 | 120 | Parameters: 121 | obj (str): The object name or identifier. 122 | daily (bool): Flag for daily print frequency. 123 | monthly (bool): Flag for monthly print frequency. 124 | yearly (bool): Flag for yearly print frequency. 125 | avann (bool): Flag for average annual print frequency. 126 | 127 | Returns: 128 | None 129 | """ 130 | 131 | # check if obj is object itself or file 132 | if os.path.splitext(obj)[1] != '': 133 | arg_to_add = obj.rsplit('_', maxsplit=1)[0] 134 | else: 135 | arg_to_add = obj 136 | 137 | # read all print_prt file, line by line 138 | print_prt_path = self.root_folder / 'print.prt' 139 | new_print_prt = "" 140 | found = False 141 | with open(print_prt_path) as file: 142 | for line in file: 143 | if not line.startswith(arg_to_add + ' '): # Line must start exactly with arg_to_add, not a word that starts with arg_to_add 144 | new_print_prt += line 145 | else: 146 | # obj already exist, replace it in same position 147 | new_print_prt += self._build_line_to_add(arg_to_add, daily, monthly, yearly, avann) 148 | found = True 149 | 150 | if not found: 151 | new_print_prt += self._build_line_to_add(arg_to_add, daily, monthly, yearly, avann) 152 | 153 | # store new print_prt 154 | with open(print_prt_path, 'w') as file: 155 | file.write(new_print_prt) 156 | 157 | def set_beginning_and_end_year( 158 | self, 159 | beginning: int, 160 | end: int 161 | ) -> None: 162 | 163 | """ 164 | Modify the beginning and end year in the 'time.sim' file. 165 | 166 | Parameters: 167 | beginning (int): The new beginning year. 168 | end (int): The new end year. 169 | 170 | Returns: 171 | None 172 | """ 173 | 174 | nth_line = 3 175 | 176 | # time_sim_path = f"{self.root_folder}\\{'time.sim'}" 177 | time_sim_path = self.root_folder / 'time.sim' 178 | 179 | # Open the file in read mode and read its contents 180 | with open(time_sim_path, 'r') as file: 181 | lines = file.readlines() 182 | 183 | year_line = lines[nth_line - 1] 184 | 185 | # Split the input string by spaces 186 | elements = year_line.split() 187 | 188 | elements[1] = beginning 189 | elements[3] = end 190 | 191 | # Reconstruct the result string while maintaining spaces 192 | result_string = '{: >8} {: >10} {: >10} {: >10} {: >10} \n'.format(*elements) 193 | 194 | lines[nth_line - 1] = result_string 195 | 196 | with open(time_sim_path, 'w') as file: 197 | file.writelines(lines) 198 | 199 | def set_warmup( 200 | self, 201 | warmup: int 202 | ) -> None: 203 | 204 | """ 205 | Modify the warmup period in the 'time.sim' file. 206 | 207 | Parameters: 208 | warmup (int): The new warmup period value. 209 | 210 | Returns: 211 | None 212 | """ 213 | 214 | time_sim_path = self.root_folder / 'print.prt' 215 | 216 | # Open the file in read mode and read its contents 217 | with open(time_sim_path, 'r') as file: 218 | lines = file.readlines() 219 | 220 | nth_line = 3 221 | year_line = lines[nth_line - 1] 222 | 223 | # Split the input string by spaces 224 | elements = year_line.split() 225 | 226 | elements[0] = warmup 227 | 228 | # Reconstruct the result string while maintaining spaces 229 | result_string = '{: <12} {: <11} {: <11} {: <10} {: <10} {: <10} \n'.format(*elements) 230 | 231 | lines[nth_line - 1] = result_string 232 | 233 | with open(time_sim_path, 'w') as file: 234 | file.writelines(lines) 235 | 236 | def _enable_disable_csv_print( 237 | self, 238 | enable: bool = True 239 | ) -> None: 240 | 241 | """ 242 | Enable or disable CSV print in the 'print.prt' file. 243 | 244 | Parameters: 245 | enable (bool, optional): True to enable CSV print, False to disable (default is True). 246 | 247 | Returns: 248 | None 249 | """ 250 | 251 | # read 252 | nth_line = 7 253 | 254 | # time_sim_path = f"{self.root_folder}\\{'time.sim'}" 255 | print_prt_path = self.root_folder / 'print.prt' 256 | 257 | # Open the file in read mode and read its contents 258 | with open(print_prt_path, 'r') as file: 259 | lines = file.readlines() 260 | 261 | if enable: 262 | lines[nth_line - 1] = 'y' + lines[nth_line - 1][1:] 263 | else: 264 | lines[nth_line - 1] = 'n' + lines[nth_line - 1][1:] 265 | 266 | with open(print_prt_path, 'w') as file: 267 | file.writelines(lines) 268 | 269 | def enable_csv_print( 270 | self 271 | ) -> None: 272 | 273 | """ 274 | Enable CSV print in the 'print.prt' file. 275 | 276 | Returns: 277 | None 278 | """ 279 | 280 | self._enable_disable_csv_print(enable=True) 281 | 282 | def disable_csv_print( 283 | self 284 | ) -> None: 285 | 286 | """ 287 | Disable CSV print in the 'print.prt' file. 288 | 289 | Returns: 290 | None 291 | """ 292 | 293 | self._enable_disable_csv_print(enable=False) 294 | 295 | def register_file( 296 | self, 297 | filename: str, 298 | has_units: bool = False, 299 | index: Optional[str] = None, 300 | usecols: Optional[List[str]] = None, 301 | filter_by: Dict[str, Union[Any, List[Any], re.Pattern]] = {} 302 | ) -> FileReader: 303 | 304 | """ 305 | Register a file to work with in the SWAT model. 306 | 307 | Parameters: 308 | filename (str): The name of the file to register. 309 | has_units (bool): Indicates if the file has units information (default is False). 310 | index (str, optional): The name of the index column (default is None). 311 | usecols (List[str], optional): A list of column names to read (default is None). 312 | filter_by (Dict[str, Union[Any, List[Any], re.Pattern]): A dictionary of column names and values to filter by (default is an empty dictionary). 313 | 314 | Returns: 315 | FileReader: A FileReader instance for the registered file. 316 | """ 317 | 318 | file_path = os.path.join(self.root_folder, filename) 319 | 320 | return FileReader(file_path, has_units, index, usecols, filter_by) 321 | 322 | def copy_swat( 323 | self, 324 | target_dir: str = None, 325 | overwrite: bool = False 326 | ) -> str: 327 | 328 | """ 329 | Copy the SWAT model files to a specified directory. 330 | 331 | If 'overwrite' is True, the content of the 'target_dir' folder will be deleted, and the 'txtinout' folder will be copied there. 332 | If 'overwrite' is False, the 'txtinout' folder will be copied to a new folder inside 'target_dir'. 333 | 334 | Parameters: 335 | target_dir (str, optional): The target directory where the SWAT model files will be copied. If None, a temporary folder will be created (default is None). 336 | overwrite (bool, optional): If True, overwrite the content of 'target_dir'; if False, create a new folder inside target_dir (default is False). 337 | 338 | Returns: 339 | str: The path to the directory where the SWAT model files were copied. 340 | """ 341 | 342 | # if target_dir is None or target_dir is a folder and overwrite is False, create a new folder using mkdtemp 343 | if (target_dir is None) or (not overwrite and target_dir is not None): 344 | 345 | try: 346 | temp_folder_path = tempfile.mkdtemp(dir=target_dir) 347 | except FileNotFoundError: 348 | os.makedirs(dir, exist_ok=True) 349 | temp_folder_path = tempfile.mkdtemp(dir=target_dir) 350 | 351 | # if target_dir is a folder and overwrite is True, delete all contents 352 | elif overwrite: 353 | 354 | if os.path.isdir(target_dir): 355 | 356 | temp_folder_path = target_dir 357 | 358 | # delete all files in target_dir 359 | for file in os.listdir(target_dir): 360 | file_path = os.path.join(target_dir, file) 361 | try: 362 | if os.path.isfile(file_path): 363 | os.remove(file_path) 364 | except Exception as e: 365 | print(e) 366 | 367 | else: # if overwrite and dir is not a folder, create dir anyway 368 | os.makedirs(dir, exist_ok=True) 369 | temp_folder_path = dir 370 | 371 | # check if dir does not exist 372 | elif not os.path.isdir(dir): 373 | # check if dir is a file 374 | if os.path.isfile(dir): 375 | raise TypeError("target_dir must be a folder") 376 | 377 | # create dir 378 | os.makedirs(dir, exist_ok=True) 379 | temp_folder_path = dir 380 | 381 | else: 382 | raise TypeError("option not recognized") 383 | 384 | # Get the list of files in the source folder 385 | source_folder = self.root_folder 386 | files = os.listdir(source_folder) 387 | 388 | # Exclude files with the specified suffix and copy the remaining files (only the required files for running SWAT are copied) 389 | for file in files: 390 | 391 | source_file = os.path.join(source_folder, file) 392 | 393 | # Skip directories and unwanted files 394 | if os.path.isdir(source_file): 395 | continue 396 | 397 | file_suffix = ['day', 'mon', 'yr', 'aa'] 398 | file_ext = ['txt', 'csv'] 399 | ignored_file = tuple( 400 | f'_{suf}.{ext}' for suf in file_suffix for ext in file_ext 401 | ) 402 | 403 | if file.endswith(ignored_file): 404 | continue 405 | 406 | destination_file = os.path.join(temp_folder_path, file) 407 | shutil.copy2(source_file, destination_file) 408 | 409 | return temp_folder_path 410 | 411 | def _run_swat( 412 | self, 413 | show_output: bool = True 414 | ) -> None: 415 | 416 | """ 417 | Run the SWAT simulation. 418 | 419 | Parameters: 420 | show_output (bool, optional): If True, print the simulation output; if False, suppress output (default is True). 421 | 422 | Returns: 423 | None 424 | """ 425 | 426 | # Run siumulation 427 | swat_exe_path = self.swat_exe_path 428 | 429 | os.chdir(self.root_folder) 430 | 431 | with subprocess.Popen(swat_exe_path, stdout=subprocess.PIPE, stderr=subprocess.PIPE) as process: 432 | # Read and print the output while it's being produced 433 | while True: 434 | # Read a line of output 435 | raw_output = process.stdout.readline() 436 | 437 | # Check if the output is empty and the subprocess has finished 438 | if raw_output == b'' and process.poll() is not None: 439 | break 440 | 441 | # Decode the output using 'latin-1' encoding 442 | try: 443 | output = raw_output.decode('latin-1').strip() 444 | except UnicodeDecodeError: 445 | # Handle decoding errors here (e.g., skip or replace invalid characters) 446 | continue 447 | 448 | # Print the decoded output if needed 449 | if output and show_output: 450 | print(output) 451 | 452 | def run_swat( 453 | self, 454 | params: Dict[str, Tuple[str, List[Tuple[Union[None, str, List[str], re.Pattern], str, Any]]]] = {}, 455 | show_output: bool = True 456 | ) -> str: 457 | 458 | """ 459 | Run the SWAT simulation with modified input parameters. 460 | 461 | Parameters: 462 | params (Dict[str, Tuple[str, List[Tuple[Union[None, str, List[str], re.Pattern], str, Any]]]], optional): 463 | A dictionary containing modifications to input files. Format: {filename: (id_col, [(id, col, value)])}. 464 | 'id' can be None to apply the value to all rows, a single id or a regex pattern or list to match multiple IDs. 465 | show_output (bool, optional): If True, print the simulation output; if False, suppress output (default is True). 466 | 467 | Returns: 468 | str: The path to the directory where the SWAT simulation was executed. 469 | """ 470 | 471 | aux_txtinout = TxtinoutReader(self.root_folder) 472 | 473 | # Modify files for simulation 474 | for filename, file_params in params.items(): 475 | 476 | id_col, file_mods = file_params 477 | 478 | # get file 479 | file = aux_txtinout.register_file(filename, has_units=False, index=id_col) 480 | 481 | # for each col_name in file_params 482 | for id, col_name, value in file_mods: # 'id' can be None, a str or a regex pattern 483 | if id is None: 484 | file.df[col_name] = value 485 | elif isinstance(id, list): 486 | mask = file.df.index.astype(str).isin(id) 487 | file.df.loc[mask, col_name] = value 488 | elif isinstance(id, re.Pattern): 489 | mask = file.df.index.astype(str).str.match(id) 490 | file.df.loc[mask, col_name] = value 491 | else: 492 | file.df.loc[id, col_name] = value 493 | 494 | # store file 495 | file.overwrite_file() 496 | 497 | # run simulation 498 | aux_txtinout._run_swat(show_output=show_output) 499 | 500 | return self.root_folder 501 | 502 | def run_swat_star( 503 | self, 504 | args: Tuple[Dict[str, Tuple[str, List[Tuple[Union[None, str, List[str], re.Pattern], str, Any]]]], bool] 505 | ) -> str: 506 | 507 | """ 508 | Run the SWAT simulation with modified input parameters using arguments provided as a tuple. 509 | 510 | Parameters: 511 | args (Tuple[Dict[str, Tuple[str, List[Tuple[Union[None, str, List[str], re.Pattern], str, Any]]]]], bool]): 512 | A tuple containing simulation parameters. 513 | The first element is a dictionary with input parameter modifications, 514 | the second element is a boolean to show output. 515 | 516 | Returns: 517 | str: The path to the directory where the SWAT simulation was executed. 518 | """ 519 | 520 | return self.run_swat(*args) 521 | 522 | def copy_and_run( 523 | self, 524 | target_dir: str, 525 | overwrite: bool = False, 526 | params: Dict[str, Tuple[str, List[Tuple[Union[None, str, List[str], re.Pattern], str, Any]]]] = {}, 527 | show_output: bool = True 528 | ) -> str: 529 | 530 | """ 531 | Copy the SWAT model files to a specified directory, modify input parameters, and run the simulation. 532 | 533 | Parameters: 534 | target_dir (str): The target directory where the SWAT model files will be copied. 535 | overwrite (bool, optional): If True, overwrite the content of 'target_dir'; if False, create a new folder inside 'target_dir' (default is False). 536 | params (Dict[str, Tuple[str, List[Tuple[Union[None, str, List[str], re.Pattern], str, Any]]]], optional): 537 | A dictionary containing modifications to input files. Format: {filename: (id_col, [(id, col, value)])}. 538 | Format: {filename: (id_col, [(id, col, value)])}. 539 | show_output (bool, optional): If True, print the simulation output; if False, suppress output (default is True). 540 | 541 | Returns: 542 | str: The path to the directory where the SWAT simulation was executed. 543 | """ 544 | 545 | tmp_path = self.copy_swat(target_dir=target_dir, overwrite=overwrite) 546 | reader = TxtinoutReader(tmp_path) 547 | 548 | return reader.run_swat(params, show_output=show_output) 549 | 550 | def copy_and_run_star( 551 | self, 552 | args: Tuple[str, bool, Dict[str, Tuple[str, List[Tuple[Union[None, str, List[str], re.Pattern], str, Any]]]], bool] 553 | ) -> str: 554 | 555 | """ 556 | Copy the SWAT model files to a specified directory, modify input parameters, and run the simulation using arguments provided as a tuple. 557 | 558 | Parameters: 559 | args (Tuple[Dict[str, Tuple[str, List[Tuple[Union[None, str, List[str], re.Pattern], str, Any]]]]], bool]): 560 | A tuple containing simulation parameters. 561 | The first element is a dictionary with input parameter modifications, 562 | the second element is a boolean to show output. 563 | 564 | Returns: 565 | str: The path to the directory where the SWAT simulation was executed. 566 | """ 567 | 568 | return self.copy_and_run(*args) 569 | 570 | def run_parallel_swat( 571 | self, 572 | params: List[Dict[str, Tuple[str, List[Tuple[Union[None, str, List[str], re.Pattern], str, Any]]]]], 573 | n_workers: int = 1, 574 | target_dir: str = None, 575 | parallelization: str = 'threads' 576 | ) -> List[str]: 577 | 578 | """ 579 | Run SWAT simulations in parallel with modified input parameters. 580 | 581 | Parameters: 582 | params (Dict[str, Tuple[str, List[Tuple[Union[None, str, List[str], re.Pattern], str, Any]]]], optional): 583 | A dictionary containing modifications to input files. Format: {filename: (id_col, [(id, col, value)])}. 584 | n_workers (int, optional): The number of parallel workers to use (default is 1). 585 | target_dir (str, optional): The target directory where the SWAT model files will be copied (default is None). 586 | parallelization (str, optional): The parallelization method to use ('threads' or 'processes') (default is 'threads'). 587 | 588 | Returns: 589 | List[str]: A list of paths to the directories where the SWAT simulations were executed. 590 | """ 591 | 592 | max_treads = multiprocessing.cpu_count() 593 | threads = max(min(n_workers, max_treads), 1) 594 | 595 | if n_workers == 1: 596 | 597 | results_ret = [] 598 | 599 | for i in tqdm.tqdm(range(len(params))): 600 | results_ret.append( 601 | self.copy_and_run( 602 | target_dir=target_dir, 603 | overwrite=False, 604 | params=params[i], 605 | show_output=False 606 | ) 607 | ) 608 | 609 | return results_ret 610 | 611 | else: 612 | items = [[target_dir, False, params[i], False] for i in range(len(params))] 613 | if parallelization == 'threads': 614 | with ThreadPoolExecutor(max_workers=threads) as executor: 615 | results = list(executor.map(self.copy_and_run_star, items)) 616 | elif parallelization == 'processes': 617 | with multiprocessing.Pool(threads) as pool: 618 | results = list(pool.map(self.copy_and_run_star, items)) 619 | else: 620 | raise ValueError("parallelization must be 'threads' or 'processes'") 621 | 622 | return results 623 | -------------------------------------------------------------------------------- /pySWATPlus/__init__.py: -------------------------------------------------------------------------------- 1 | from .TxtinoutReader import TxtinoutReader 2 | from .FileReader import FileReader 3 | from .SWATProblem import SWATProblem 4 | from .SWATProblemMultimodel import SWATProblemMultimodel, minimize_pymoo 5 | 6 | 7 | __all__ = [ 8 | 'TxtinoutReader', 9 | 'FileReader', 10 | 'SWATProblem', 11 | 'SWATProblemMultimodel', 12 | 'minimize_pymoo' 13 | ] 14 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = ["setuptools", "setuptools-scm", "wheel"] 3 | build-backend = "setuptools.build_meta" 4 | 5 | [project] 6 | name = "pySWATPlus" 7 | description = "Running and calibrating default or custom SWAT+ projects with Python" 8 | dynamic = ["version"] 9 | readme = "README.md" 10 | requires-python = ">=3.9" 11 | license = {text = "GPL-3.0"} 12 | authors = [ 13 | { name = "Joan Saló", email = "joansalograu@gmail.com" } 14 | ] 15 | keywords = [ 16 | "SWAT+", 17 | "hydrology", 18 | "calibration", 19 | "watershed" 20 | ] 21 | classifiers = [ 22 | "Programming Language :: Python :: 3", 23 | "Programming Language :: Python :: 3.13", 24 | "Programming Language :: Python :: 3.12", 25 | "Programming Language :: Python :: 3.11", 26 | "Programming Language :: Python :: 3.10", 27 | "Programming Language :: Python :: 3.9", 28 | "License :: OSI Approved :: GNU General Public License v3 (GPLv3)", 29 | "Operating System :: OS Independent" 30 | ] 31 | dependencies = [ 32 | "pandas", 33 | "pymoo", 34 | "tqdm", 35 | "dask", 36 | "dask-expr", 37 | "pyarrow" 38 | ] 39 | 40 | [project.urls] 41 | Homepage = "https://github.com/swat-model/pySWATPlus" 42 | Repository = "https://github.com/swat-model/pySWATPlus" 43 | Issues = "https://github.com/swat-model/pySWATPlus/issues" 44 | 45 | [tool.setuptools] 46 | packages = ["pySWATPlus"] 47 | 48 | 49 | [tool.pytest.ini_options] 50 | addopts = "-rA -Wignore::DeprecationWarning --cov=pySWATPlus --cov-report=html:cov_pySWATPlus --cov-report=term -s" 51 | testpaths = [ 52 | "tests" 53 | ] 54 | 55 | [tool.setuptools_scm] 56 | version_scheme = "post-release" 57 | local_scheme = "no-local-version" -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | pytest 2 | pytest-cov 3 | pandas 4 | numpy 5 | pymoo 6 | tqdm 7 | dask 8 | dask-expr 9 | pyarrow -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [flake8] 2 | exclude = 3 | .ipynb_checkpoints 4 | __pycache__ 5 | .tox 6 | 7 | ignore = E501 8 | -------------------------------------------------------------------------------- /tests/test_filereader.py: -------------------------------------------------------------------------------- 1 | import os 2 | import pySWATPlus 3 | import pytest 4 | 5 | 6 | @pytest.fixture(scope='class') 7 | def file_reader(): 8 | 9 | # set up file path 10 | test_folder = os.path.dirname(__file__) 11 | data_folder = os.path.join(test_folder, 'sample_data') 12 | data_file = os.path.join(data_folder, 'aquifer_yr.txt') 13 | 14 | # DataFrame from input data file 15 | file_reader = pySWATPlus.FileReader( 16 | path=data_file, 17 | has_units=True 18 | ) 19 | 20 | yield file_reader 21 | 22 | 23 | def test_get_df( 24 | file_reader 25 | ): 26 | 27 | # read DataFrame 28 | df = file_reader.df 29 | 30 | assert df.shape[0] == 260 31 | 32 | 33 | 34 | --------------------------------------------------------------------------------