# pftools
This is a package to run ParFlow via a Python interface. This package allows
the user to build a script in Python that builds the database (.pfidb file)
which ParFlow reads as input.
## How to use this package
1. Install with the following command:
pip install pftools
2. Open a new Python script in your favorite text editor or IDE.
- You can find example Python scripts in the main ParFlow repo under
*/parflow/test/python/*
3. At the top of the script, make sure you include the following lines:
from parflow import Run
runname = Run("runname", __file__)
This imports the package and initializes your run as the object "runname"
4. Set your desired keys and values on your ParFlow run object, such as:
runname.FileVersion = 4
Note: for user-defined key names, make sure you've defined the names before
you use them as a key name. For example:
runname.GeomInput.Names = 'domain_input'
needs to be set before:
runname.GeomInput.domain_input.InputType = 'SolidFile'
5. After you have assigned values to your keys, you can call multiple methods on your
ParFlow run object:
- `validate()`: This will validate your set of key/value pairs and print validation
messages. This does not require ParFlow.
- `write(file_name=None, file_format='pfidb')`: This will write your key/value
pairs to a file with your choice of format (default is the ParFlow database `pfidb`
format). Other acceptable formats passed as the `file_format` argument include
`yml`, `yaml`, and `json`. This method does not require ParFlow.
- `clone(name)`: This will generate a clone object of your run with the given `name`.
See `parflow/test/python/new_features/serial_runs/serial_runs.py` for an example of
how to use this.
- `run(working_directory=None, skip_validation=False)`: This will execute the
`write()` method. If `skip_validation` is set to `False`, it will also execute the
`validate()` method. The `working_directory` can be defined as an argument if you
would like to change the directory where the output files will be written, but it
defaults to the directory of the Python script. Finally, `run()` will execute
ParFlow. This will print the data for your environment (ParFlow directory,
ParFlow version, working directory, and the generated ParFlow database file).
If ParFlow runs successfully, you will get a message `ParFlow ran successfully`.
Otherwise, you will get a message `ParFlow run failed.` followed by a print of the
contents of the `runname.out.txt` file.
6. Once you have completed your input script, save and run it via the Python terminal
or command line:
python3 runname.py
You can append one or more of the following arguments to the run:
- `--parflow-directory [None]`: overrides environment variable for
`$PARFLOW_DIR`.
- `--parflow-version [None]`: overrides the sourced version of ParFlow used to validate
keys.
- `--working-directory [None]`: overrides the working directory for the ParFlow run.
This is identical to specifying `working_directory` in the `run()` method.
- `--skip-validation [False]`: skips the `validate()` method if set to `True`. This is
identical to specifying `skip_validation` in the `run()` method.
- `--show-line-error [False]`: shows the line where an error occurs when set to `True`.
- `--exit-on-error [False]`: causes the run to exit whenever it encounters an error when
set to `True`.
- `--write-yaml [False]`: writes the key/value pairs to a yaml file when set to `True`.
This is identical to calling the method `runname.write(file_format='yaml)`.
- `-p [0]`: overrides the value for `Process.Topology.P` (must be an integer).
- `-q [0]`: overrides the value for `Process.Topology.Q` (must be an integer).
- `-r [0]`: overrides the value for `Process.Topology.R` (must be an integer).
## How to update this package (developers only)
This assumes that you are using CMake with the pftools package as it is
contained within the main ParFlow repo (see https://github.com/parflow/parflow)
1. Update the version number in `setup.py`.
2. Build with the cmake command line. Make sure that Python is enabled through
the `PARFLOW_ENABLE_PYTHON` option.
mkdir build
cd build
cmake .. \
-D PARFLOW_ENABLE_PYTHON=TRUE
3. Run the following command to create and test a source archive and a wheel
distribution of the package. Make sure you are running this command in an
environment with the `twine` Python package installed.
make PythonCreatePackage
4. If the distributions pass, run the following command to publish the
distributions. In order to run this command successfully, you must first set the
`TWINE_USERNAME` and `TWINE_PASSWORD` environment variables to the username
and password that you will use to authenticate with PyPI.
make PythonPublishPackage
5. Check PyPI to make sure your package update was published correctly. Thanks
for contributing!
## Getting help
If you have any issues or questions about the code, please refer to one of the
following options:
- User mailing list: [Parflow-Users](https://groups.google.com/g/parflow)
- ParFlow blog: [Parflow Blog](http://parflow.blogspot.com/)
- GitHub repo (for tracking issues and requesting features): [Parflow Issue Tracker](https://github.com/parflow/parflow/issues)
Raw data
{
"_id": null,
"home_page": "https://github.com/parflow/parflow/tree/master/pftools/python",
"name": "pftools",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "ParFlow, groundwater model, surface water model",
"author": "HydroFrame",
"author_email": "parflow@parflow.org",
"download_url": "https://files.pythonhosted.org/packages/69/d3/fcc040f38223cf331bc8bdb8f5a233d79ecc5611ea0d8a942f04b8a3203d/pftools-1.3.11.tar.gz",
"platform": null,
"description": "# pftools\n\nThis is a package to run ParFlow via a Python interface. This package allows\nthe user to build a script in Python that builds the database (.pfidb file)\nwhich ParFlow reads as input.\n\n## How to use this package\n\n1. Install with the following command:\n\n pip install pftools\n\n2. Open a new Python script in your favorite text editor or IDE.\n\n - You can find example Python scripts in the main ParFlow repo under\n */parflow/test/python/*\n\n\n3. At the top of the script, make sure you include the following lines:\n\n from parflow import Run\n runname = Run(\"runname\", __file__)\n\n This imports the package and initializes your run as the object \"runname\"\n\n\n4. Set your desired keys and values on your ParFlow run object, such as:\n\n runname.FileVersion = 4\n\n Note: for user-defined key names, make sure you've defined the names before\n you use them as a key name. For example:\n\n runname.GeomInput.Names = 'domain_input'\n\n needs to be set before:\n\n runname.GeomInput.domain_input.InputType = 'SolidFile'\n\n\n5. After you have assigned values to your keys, you can call multiple methods on your\nParFlow run object:\n\n - `validate()`: This will validate your set of key/value pairs and print validation\n messages. This does not require ParFlow.\n - `write(file_name=None, file_format='pfidb')`: This will write your key/value\n pairs to a file with your choice of format (default is the ParFlow database `pfidb`\n format). Other acceptable formats passed as the `file_format` argument include\n `yml`, `yaml`, and `json`. This method does not require ParFlow.\n - `clone(name)`: This will generate a clone object of your run with the given `name`.\n See `parflow/test/python/new_features/serial_runs/serial_runs.py` for an example of\n how to use this.\n - `run(working_directory=None, skip_validation=False)`: This will execute the\n `write()` method. If `skip_validation` is set to `False`, it will also execute the\n `validate()` method. The `working_directory` can be defined as an argument if you\n would like to change the directory where the output files will be written, but it\n defaults to the directory of the Python script. Finally, `run()` will execute\n ParFlow. This will print the data for your environment (ParFlow directory,\n ParFlow version, working directory, and the generated ParFlow database file).\n If ParFlow runs successfully, you will get a message `ParFlow ran successfully`.\n Otherwise, you will get a message `ParFlow run failed.` followed by a print of the\n contents of the `runname.out.txt` file.\n\n\n6. Once you have completed your input script, save and run it via the Python terminal\nor command line:\n\n python3 runname.py\n\n You can append one or more of the following arguments to the run:\n\n - `--parflow-directory [None]`: overrides environment variable for\n `$PARFLOW_DIR`.\n - `--parflow-version [None]`: overrides the sourced version of ParFlow used to validate\n keys.\n - `--working-directory [None]`: overrides the working directory for the ParFlow run.\n This is identical to specifying `working_directory` in the `run()` method.\n - `--skip-validation [False]`: skips the `validate()` method if set to `True`. This is\n identical to specifying `skip_validation` in the `run()` method.\n - `--show-line-error [False]`: shows the line where an error occurs when set to `True`.\n - `--exit-on-error [False]`: causes the run to exit whenever it encounters an error when\n set to `True`.\n - `--write-yaml [False]`: writes the key/value pairs to a yaml file when set to `True`.\n This is identical to calling the method `runname.write(file_format='yaml)`.\n - `-p [0]`: overrides the value for `Process.Topology.P` (must be an integer).\n - `-q [0]`: overrides the value for `Process.Topology.Q` (must be an integer).\n - `-r [0]`: overrides the value for `Process.Topology.R` (must be an integer).\n\n## How to update this package (developers only)\n\nThis assumes that you are using CMake with the pftools package as it is\ncontained within the main ParFlow repo (see https://github.com/parflow/parflow)\n\n1. Update the version number in `setup.py`.\n\n2. Build with the cmake command line. Make sure that Python is enabled through \n the `PARFLOW_ENABLE_PYTHON` option.\n\n mkdir build\n cd build\n cmake .. \\\n -D PARFLOW_ENABLE_PYTHON=TRUE\n\n3. Run the following command to create and test a source archive and a wheel\n distribution of the package. Make sure you are running this command in an \n environment with the `twine` Python package installed.\n\n make PythonCreatePackage\n\n4. If the distributions pass, run the following command to publish the\n distributions. In order to run this command successfully, you must first set the\n `TWINE_USERNAME` and `TWINE_PASSWORD` environment variables to the username\n and password that you will use to authenticate with PyPI.\n\n make PythonPublishPackage\n\n5. Check PyPI to make sure your package update was published correctly. Thanks\n for contributing!\n\n## Getting help\n\nIf you have any issues or questions about the code, please refer to one of the\nfollowing options:\n\n - User mailing list: [Parflow-Users](https://groups.google.com/g/parflow)\n - ParFlow blog: [Parflow Blog](http://parflow.blogspot.com/)\n - GitHub repo (for tracking issues and requesting features): [Parflow Issue Tracker](https://github.com/parflow/parflow/issues)\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "A Python package creating an interface with the ParFlow hydrologic model.",
"version": "1.3.11",
"project_urls": {
"Homepage": "https://github.com/parflow/parflow/tree/master/pftools/python"
},
"split_keywords": [
"parflow",
" groundwater model",
" surface water model"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d8adf3716d7f399d35184af52f5f48928918af1d0f6241e126737d577dd7e3ce",
"md5": "00807ea11c8dfbe4443da1d27d1db24a",
"sha256": "7364be2f18de25482b05e8bd81e98b2ed06f747904e3f913e4cb0e73a3b05d26"
},
"downloads": -1,
"filename": "pftools-1.3.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "00807ea11c8dfbe4443da1d27d1db24a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 124163,
"upload_time": "2024-04-17T22:45:00",
"upload_time_iso_8601": "2024-04-17T22:45:00.215892Z",
"url": "https://files.pythonhosted.org/packages/d8/ad/f3716d7f399d35184af52f5f48928918af1d0f6241e126737d577dd7e3ce/pftools-1.3.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "69d3fcc040f38223cf331bc8bdb8f5a233d79ecc5611ea0d8a942f04b8a3203d",
"md5": "1e7c7a06d2e0806b750a76ad92189838",
"sha256": "a3b80b9950033da17c6b4c17a6be41fd38ce12f14dffc87ae91b6b805df28514"
},
"downloads": -1,
"filename": "pftools-1.3.11.tar.gz",
"has_sig": false,
"md5_digest": "1e7c7a06d2e0806b750a76ad92189838",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 119008,
"upload_time": "2024-04-17T22:45:02",
"upload_time_iso_8601": "2024-04-17T22:45:02.967465Z",
"url": "https://files.pythonhosted.org/packages/69/d3/fcc040f38223cf331bc8bdb8f5a233d79ecc5611ea0d8a942f04b8a3203d/pftools-1.3.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-17 22:45:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "parflow",
"github_project": "parflow",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pftools"
}
JSON
