fvs2py 0.2.1__tar.gz → 0.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. {fvs2py-0.2.1 → fvs2py-0.2.2}/PKG-INFO +6 -23
  2. {fvs2py-0.2.1 → fvs2py-0.2.2}/README.md +5 -22
  3. fvs2py-0.2.2/fvs2py/_attributes.py +115 -0
  4. fvs2py-0.2.2/fvs2py/_base.py +598 -0
  5. fvs2py-0.2.2/fvs2py/_calls.py +216 -0
  6. fvs2py-0.2.2/fvs2py/_core.py +216 -0
  7. fvs2py-0.2.2/fvs2py/_routines.py +466 -0
  8. {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py/cli.py +10 -16
  9. fvs2py-0.2.2/fvs2py/common.py +61 -0
  10. {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py/constants.py +4 -23
  11. {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py/enums.py +19 -41
  12. {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py.egg-info/PKG-INFO +6 -23
  13. {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py.egg-info/SOURCES.txt +3 -9
  14. {fvs2py-0.2.1 → fvs2py-0.2.2}/pyproject.toml +1 -1
  15. fvs2py-0.2.1/fvs2py/_base.py +0 -93
  16. fvs2py-0.2.1/fvs2py/_core.py +0 -155
  17. fvs2py-0.2.1/fvs2py/_mixins/__init__.py +0 -25
  18. fvs2py-0.2.1/fvs2py/_mixins/control.py +0 -215
  19. fvs2py-0.2.1/fvs2py/_mixins/events.py +0 -226
  20. fvs2py-0.2.1/fvs2py/_mixins/simulation.py +0 -209
  21. fvs2py-0.2.1/fvs2py/_mixins/species.py +0 -186
  22. fvs2py-0.2.1/fvs2py/_mixins/stand.py +0 -102
  23. fvs2py-0.2.1/fvs2py/_mixins/svs.py +0 -166
  24. fvs2py-0.2.1/fvs2py/_mixins/trees.py +0 -163
  25. fvs2py-0.2.1/fvs2py/_routines.py +0 -704
  26. fvs2py-0.2.1/fvs2py/common.py +0 -280
  27. {fvs2py-0.2.1 → fvs2py-0.2.2}/LICENSE +0 -0
  28. {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py/__init__.py +0 -0
  29. {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py/keyfile.py +0 -0
  30. {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py/py.typed +0 -0
  31. {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py.egg-info/dependency_links.txt +0 -0
  32. {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py.egg-info/entry_points.txt +0 -0
  33. {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py.egg-info/requires.txt +0 -0
  34. {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py.egg-info/top_level.txt +0 -0
  35. {fvs2py-0.2.1 → fvs2py-0.2.2}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: fvs2py
3
- Version: 0.2.1
3
+ Version: 0.2.2
4
4
  Summary: Python wrapper for the Forest Vegetation Simulator API.
5
5
  Author-email: David Diaz <ddiaz@vibrantplanet.net>
6
6
  License-Expression: MIT
@@ -49,7 +49,7 @@ We will then build upon the addition of new subroutines in Fortran that extend t
49
49
  pip install fvs2py
50
50
  ```
51
51
 
52
- fvs2py doesn't include the FVS libraries. You supply a compiled FVS variant library, either your own build or one from the [`usfs-fvs` container image](https://github.com/Vibrant-Planet-Open-Science/fvs-build/pkgs/container/usfs-fvs) (`ghcr.io/vibrant-planet-open-science/usfs-fvs`), which has every variant's library at `/usr/local/lib/FVS<variant>.so`.
52
+ fvs2py is a wrapper, and doesn't currently ship with the FVS libraries included. You supply a compiled FVS variant library, either your own build, an official [USFS release](https://www.fs.usda.gov/fvs/software/variantinstaller.php) (currently Windows only), or one from the [`usfs-fvs` container image](https://github.com/Vibrant-Planet-Open-Science/fvs-build/pkgs/container/usfs-fvs) (`ghcr.io/vibrant-planet-open-science/usfs-fvs`), which has every variant's library at `/usr/local/lib/FVS<variant>.so`. We're working to make updates to this package so that it can come with FVS libraries included and will keep this documentation up-to-date when those updates land.
53
53
 
54
54
  ## Usage
55
55
 
@@ -67,29 +67,12 @@ fvs.summary # pandas DataFrame
67
67
  fvs2py also installs an `fvs` command that works like FVS executables do. These two commands are equivalent:
68
68
 
69
69
  ```bash
70
- FVSpn --keywordfile=name.key
71
- fvs --lib=/path/to/FVSpn.so --keywordfile=name.key
70
+ FVSpn --keywordfile=name.key # FVS executable (PN variant)
71
+ fvs --lib=/path/to/FVSpn.so --keywordfile=name.key # fvs2py equivalent
72
72
  ```
73
73
 
74
74
  Most users of `fvs2py` should primarily expect to use the Python interface. The CLI is for running FVS in a separate process, so a crash by FVS doesn't take down your program and its output can be captured.
75
75
 
76
- ## Development
76
+ ## Contributing
77
77
 
78
- A **dev container** is provided under [`.devcontainer/`](https://github.com/Vibrant-Planet-Open-Science/fvs2py/tree/main/.devcontainer) for VS Code. Open the repository with **Dev Containers: Reopen in Container** to get the `dev` Docker target, Python tooling, and extensions preconfigured. On first open, `postCreateCommand` runs `uv sync --frozen --extra dev` (creating a project-local `.venv` in your clone, gitignored) and installs pre-commit hooks. After pulling changes that touch the Dockerfile or lockfile, **rebuild** the dev container (or run `uv sync --extra dev` manually).
79
-
80
- The `.venv` directory lives on your host via the bind-mounted workspace (Linux binaries from the container). You can delete it and re-run `uv sync --extra dev` to recreate.
81
-
82
- If you don't want to use a dev container, install dev dependencies and hooks the same way before opening a pull request:
83
-
84
- ```bash
85
- uv sync --extra dev
86
- uv run pre-commit install
87
- ```
88
-
89
- Run tests locally or inside the dev container:
90
-
91
- ```bash
92
- uv run pytest .
93
- ```
94
-
95
- Hooks run on each commit (secret scan, Ruff, mypy). Run them manually with `uv run pre-commit run --all-files`. CI runs the same checks on pull requests via the Lint workflow, and runs pytest in the `dev` Docker image via the Pytest workflow.
78
+ See [CONTRIBUTING.md](https://github.com/Vibrant-Planet-Open-Science/fvs2py/blob/main/CONTRIBUTING.md) for development setup, tests, and pre-commit hooks.
@@ -13,7 +13,7 @@ We will then build upon the addition of new subroutines in Fortran that extend t
13
13
  pip install fvs2py
14
14
  ```
15
15
 
16
- fvs2py doesn't include the FVS libraries. You supply a compiled FVS variant library, either your own build or one from the [`usfs-fvs` container image](https://github.com/Vibrant-Planet-Open-Science/fvs-build/pkgs/container/usfs-fvs) (`ghcr.io/vibrant-planet-open-science/usfs-fvs`), which has every variant's library at `/usr/local/lib/FVS<variant>.so`.
16
+ fvs2py is a wrapper, and doesn't currently ship with the FVS libraries included. You supply a compiled FVS variant library, either your own build, an official [USFS release](https://www.fs.usda.gov/fvs/software/variantinstaller.php) (currently Windows only), or one from the [`usfs-fvs` container image](https://github.com/Vibrant-Planet-Open-Science/fvs-build/pkgs/container/usfs-fvs) (`ghcr.io/vibrant-planet-open-science/usfs-fvs`), which has every variant's library at `/usr/local/lib/FVS<variant>.so`. We're working to make updates to this package so that it can come with FVS libraries included and will keep this documentation up-to-date when those updates land.
17
17
 
18
18
  ## Usage
19
19
 
@@ -31,29 +31,12 @@ fvs.summary # pandas DataFrame
31
31
  fvs2py also installs an `fvs` command that works like FVS executables do. These two commands are equivalent:
32
32
 
33
33
  ```bash
34
- FVSpn --keywordfile=name.key
35
- fvs --lib=/path/to/FVSpn.so --keywordfile=name.key
34
+ FVSpn --keywordfile=name.key # FVS executable (PN variant)
35
+ fvs --lib=/path/to/FVSpn.so --keywordfile=name.key # fvs2py equivalent
36
36
  ```
37
37
 
38
38
  Most users of `fvs2py` should primarily expect to use the Python interface. The CLI is for running FVS in a separate process, so a crash by FVS doesn't take down your program and its output can be captured.
39
39
 
40
- ## Development
40
+ ## Contributing
41
41
 
42
- A **dev container** is provided under [`.devcontainer/`](https://github.com/Vibrant-Planet-Open-Science/fvs2py/tree/main/.devcontainer) for VS Code. Open the repository with **Dev Containers: Reopen in Container** to get the `dev` Docker target, Python tooling, and extensions preconfigured. On first open, `postCreateCommand` runs `uv sync --frozen --extra dev` (creating a project-local `.venv` in your clone, gitignored) and installs pre-commit hooks. After pulling changes that touch the Dockerfile or lockfile, **rebuild** the dev container (or run `uv sync --extra dev` manually).
43
-
44
- The `.venv` directory lives on your host via the bind-mounted workspace (Linux binaries from the container). You can delete it and re-run `uv sync --extra dev` to recreate.
45
-
46
- If you don't want to use a dev container, install dev dependencies and hooks the same way before opening a pull request:
47
-
48
- ```bash
49
- uv sync --extra dev
50
- uv run pre-commit install
51
- ```
52
-
53
- Run tests locally or inside the dev container:
54
-
55
- ```bash
56
- uv run pytest .
57
- ```
58
-
59
- Hooks run on each commit (secret scan, Ruff, mypy). Run them manually with `uv run pre-commit run --all-files`. CI runs the same checks on pull requests via the Lint workflow, and runs pytest in the `dev` Docker image via the Pytest workflow.
42
+ See [CONTRIBUTING.md](https://github.com/Vibrant-Planet-Open-Science/fvs2py/blob/main/CONTRIBUTING.md) for development setup, tests, and pre-commit hooks.
@@ -0,0 +1,115 @@
1
+ """Get and set FVS's named float64 attribute arrays.
2
+
3
+ `fvsTreeAttr`, `fvsSpeciesAttr`, `fvsFFEAttrs`, `fvsSVSObjData`, and
4
+ `fvsEvmonAttr` share one calling convention: a name, a "get"/"set" action, and
5
+ a float64 array of length `n`. FVS validates the name and reports unknown names
6
+ as `NameError` through `attr_accessor_policy`.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import ctypes as ct
12
+ import warnings
13
+ from collections.abc import Callable
14
+ from dataclasses import dataclass
15
+ from typing import Any
16
+
17
+ import numpy as np
18
+ import numpy.typing as npt
19
+ import pandas as pd
20
+
21
+ from fvs2py.constants import (
22
+ EVMON_ATTRS,
23
+ FFE_FALLYRS_ATTRS,
24
+ SPECIES_ATTRS,
25
+ STR_MAXSPECIES,
26
+ STR_NOBJS,
27
+ STR_NTREES,
28
+ SVS_OBJ_ATTRS,
29
+ TREE_ATTRS,
30
+ )
31
+
32
+ Invoke = Callable[..., Any]
33
+
34
+
35
+ @dataclass(frozen=True, slots=True)
36
+ class AttributeTable:
37
+ """One FVS attribute routine and the names it exposes.
38
+
39
+ Attributes:
40
+ routine: Registered routine name in `FVS_ROUTINES`.
41
+ names: Canonical attribute names, used by `frame`.
42
+ size_kwarg: Name of the routine's length parameter, if it has one.
43
+ empty_warning: If set, `frame` warns with this message and blanks
44
+ the frame when every value is zero (FVS has not populated it).
45
+ """
46
+
47
+ routine: str
48
+ names: tuple[str, ...]
49
+ size_kwarg: str | None = None
50
+ empty_warning: str | None = None
51
+
52
+ def get(self, invoke: Invoke, attr: str, n: int) -> npt.NDArray[np.float64]:
53
+ """Return a new array holding `attr`'s current `n` values."""
54
+ arr = np.empty(n, dtype=np.float64)
55
+ self._call(invoke, attr, "get", arr)
56
+ return arr
57
+
58
+ def set(
59
+ self, invoke: Invoke, attr: str, arr: npt.NDArray[np.float64], n: int
60
+ ) -> None:
61
+ """Write `arr` to `attr`.
62
+
63
+ Raises:
64
+ ValueError: If `arr` does not have shape `(n,)`.
65
+ """
66
+ if arr.shape != (n,):
67
+ msg = f"`arr` must have shape ({n},) for {attr!r}."
68
+ raise ValueError(msg)
69
+ self._call(invoke, attr, "set", arr)
70
+
71
+ def frame(self, invoke: Invoke, n: int) -> pd.DataFrame:
72
+ """Return every name in `names` as a column."""
73
+ df = pd.DataFrame({a: self.get(invoke, a, n) for a in self.names})
74
+ if self.empty_warning and (df == 0).all().all():
75
+ warnings.warn(self.empty_warning)
76
+ return df.replace(0, None)
77
+ return df
78
+
79
+ def _call(
80
+ self,
81
+ invoke: Invoke,
82
+ attr: str,
83
+ action: str,
84
+ arr: npt.NDArray[np.float64],
85
+ ) -> None:
86
+ size = {self.size_kwarg: ct.c_int(len(arr))} if self.size_kwarg else {}
87
+ invoke(
88
+ self.routine,
89
+ attr_name=attr.encode(),
90
+ nch=ct.c_int(len(attr)),
91
+ action=action.encode(),
92
+ arr=arr,
93
+ **size,
94
+ )
95
+
96
+
97
+ TREES = AttributeTable("fvsTreeAttr", TREE_ATTRS, size_kwarg=STR_NTREES)
98
+ SPECIES = AttributeTable(
99
+ "fvsSpeciesAttr",
100
+ SPECIES_ATTRS,
101
+ empty_warning="No species attributes initialized yet.",
102
+ )
103
+ FFE = AttributeTable(
104
+ "fvsFFEAttrs",
105
+ FFE_FALLYRS_ATTRS,
106
+ size_kwarg=STR_MAXSPECIES,
107
+ empty_warning=(
108
+ "No FFE fallyrs attributes initialized yet. "
109
+ "Is the Fire and Fuels Extension active in the loaded keyfile?"
110
+ ),
111
+ )
112
+ SVS_OBJECTS = AttributeTable(
113
+ "fvsSVSObjData", SVS_OBJ_ATTRS, size_kwarg=STR_NOBJS
114
+ )
115
+ EVMON = AttributeTable("fvsEvmonAttr", EVMON_ATTRS)