Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 19 additions & 21 deletions DEVELOPER.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,9 +46,9 @@ installation process varies widely. We are looking for a conda-based approach
to obtaining compilers, but currently do not have a solution. Compilers are
needed for two applications:

1. Compiling and running C/Fortran PRMS code to generate testing/verification
data 2. Compiling (installing) and running fortran backends/kernels for some
hydrological process representations in pywatershed
1. Compiling and running C/Fortran PRMS code to generate testing/verification
data 2. Compiling (installing) and running fortran backends/kernels for some
hydrological process representations in pywatershed

On Apple Silicon, the PRMS source code is only currently known to compile with
intel while the fortran kernels in pywatershed only compile with gnu.
Expand Down Expand Up @@ -83,7 +83,7 @@ To install all dependencies with `pip`:
pip install ".[all]"
```

Several dependency groups are defined in `pyproject.toml` and can be selected
Several dependency groups are defined in `pyproject.toml` and can be selected
instead of `all` for a more lightweight environment:

- `lint`
Expand All @@ -99,8 +99,7 @@ in the root, `source venv/bin/activate`), `pywatershed` can be installed in
mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html)
with:

``` pip install -e . ```

`pip install -e . `

#### F2PY

Expand All @@ -110,7 +109,7 @@ numpy](https://numpy.org/doc/stable/f2py/index.html). This repository is
configured NOT to compile on install by default. Currently, we have not
established this compilation procedure for Windows. On Linux and MacOS,
compilation of fortran kernels on package installation is achieved by setting
several environent variables before installing the `pywatershed` module. For
several environent variables before installing the `pywatershed` module. For
instance, from the project root:

```
Expand All @@ -123,23 +122,23 @@ pip install -e .

Note that an editable (`-e` above) is required to compile the fotran code.


## Branching model

This project uses the [git
flow](https://nvie.com/posts/a-successful-git-branching-model/): development
occurs on the `develop` branch, while `main` is reserved for the state of the
latest release. Development PRs are typically squashed to `develop`, to avoid
merge commits. At release time, release branches are merged to `main`, and then
`main` is merged back into `develop`.


## CI

The automated practices of installing, linting, and testing described below are
all formally encoded in `.github/workflows/ci.yaml` and
`.github/workflows/ci_examples.yaml` files.


## Testing

Once the dependencies are available, we want to verify the software by running
its test suite. However, we first need to generate the test data. This consists
of running binaries (PRMS) and then converting the output to netcdf files used
Expand All @@ -165,22 +164,23 @@ machine.

For more details on the autotests, see [`autotest/README.md`](autotest/README.md).


## Linting

Automated linting procedures are performed in CI and enforced, these are

```shell
ruff check .
ruff format .
```

And you'll need to run these locally to pass CI checks.


## Committing Jupyter Notebooks

All outputs are required to be stripped from jupyter notebooks prior to
committing. To facilitate this we have
[pre-commit hooks](https://pre-commit.com/) which will strip
outputs and metadata from jupyter notebooks. When a `git commit` is attempted,
outputs and metadata from jupyter notebooks. When a `git commit` is attempted,
the hook will check all staged `*.ipynb` files. If the file is modified after
running the hook (which runs
[nbstripout](https://github.com/kynan/nbstripout)), then the
Expand All @@ -194,6 +194,7 @@ time to keep very large diffs out of the repository history. If you are using
The maximal amount of metadata can be stripped from Jupyter notebooks by following the example configuration found in the [nbstripout section on stripping metadata](https://github.com/kynan/nbstripout#stripping-metadata).

## pre-commit hooks

Pre-commit hooks apply actionas at commit-time. These are available when
`pre-commit` is installed in the environment, as in the `environment.yml`
supplied. To install yourself
Expand All @@ -205,24 +206,21 @@ pre-commit install
As specified in `.pre-commit-config.yaml`, we adopt the following pre-commit
hooks

* [nbstripout](https://github.com/kynan/nbstripout):
- [nbstripout](https://github.com/kynan/nbstripout):
strip outputs from jupyter notebooks
* [blackdoc](https://github.com/keewis/blackdoc):
- [blackdoc](https://github.com/keewis/blackdoc):
apply black within documentation
* [doctoc](https://github.com/thlorenz/doctoc): auto generate tables of
- [doctoc](https://github.com/thlorenz/doctoc): auto generate tables of
contents in markdown docs


## Documentation

[Google-style docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
are used for documenting source code. (Though numpy style is supposedly handled
as well by Napolean, preference is for google-style.)



## Miscellaneous


### Locating the root

Python scripts often need to reference files elsewhere in the project. To allow
Expand All @@ -233,4 +231,4 @@ for file access, rather than using relative paths (e.g., `../some/path`).
For a script in a subdirectory of the root, for instance, the conventional
approach would be:

```Python project_root_path = Path(__file__).parent.parent ```
`Python project_root_path = Path(__file__).parent.parent `
2 changes: 2 additions & 0 deletions asv_benchmarks/asv.conf.json
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@
// Customizable commands for building, installing, and
// uninstalling the project. See asv.conf.json documentation.
//
// "install_command": ["python -mpip install ."],
// "uninstall_command": ["return-code=any python -mpip uninstall -y {project}"],
// "install_command": ["in-dir={env_dir} python -mpip install {wheel_file}"],
// "uninstall_command": ["return-code=any python -mpip uninstall -y {project}"],
// "build_command": [
Expand Down
4 changes: 2 additions & 2 deletions pywatershed/hydrology/prms_channel_flow_graph.py
Original file line number Diff line number Diff line change
Expand Up @@ -383,8 +383,8 @@ def _calculate_subtimestep_numpy(
)


numba_msg = "prms_channel_flow_graph jit compiling with numba"
print(numba_msg, flush=True)
# numba_msg = "prms_channel_flow_graph jit compiling with numba"
# print(numba_msg, flush=True)

_calculate_subtimestep_numba = nb.njit(
nb.types.UniTuple(nb.float64, 5)(
Expand Down
Loading