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.
- {fvs2py-0.2.1 → fvs2py-0.2.2}/PKG-INFO +6 -23
- {fvs2py-0.2.1 → fvs2py-0.2.2}/README.md +5 -22
- fvs2py-0.2.2/fvs2py/_attributes.py +115 -0
- fvs2py-0.2.2/fvs2py/_base.py +598 -0
- fvs2py-0.2.2/fvs2py/_calls.py +216 -0
- fvs2py-0.2.2/fvs2py/_core.py +216 -0
- fvs2py-0.2.2/fvs2py/_routines.py +466 -0
- {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py/cli.py +10 -16
- fvs2py-0.2.2/fvs2py/common.py +61 -0
- {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py/constants.py +4 -23
- {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py/enums.py +19 -41
- {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py.egg-info/PKG-INFO +6 -23
- {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py.egg-info/SOURCES.txt +3 -9
- {fvs2py-0.2.1 → fvs2py-0.2.2}/pyproject.toml +1 -1
- fvs2py-0.2.1/fvs2py/_base.py +0 -93
- fvs2py-0.2.1/fvs2py/_core.py +0 -155
- fvs2py-0.2.1/fvs2py/_mixins/__init__.py +0 -25
- fvs2py-0.2.1/fvs2py/_mixins/control.py +0 -215
- fvs2py-0.2.1/fvs2py/_mixins/events.py +0 -226
- fvs2py-0.2.1/fvs2py/_mixins/simulation.py +0 -209
- fvs2py-0.2.1/fvs2py/_mixins/species.py +0 -186
- fvs2py-0.2.1/fvs2py/_mixins/stand.py +0 -102
- fvs2py-0.2.1/fvs2py/_mixins/svs.py +0 -166
- fvs2py-0.2.1/fvs2py/_mixins/trees.py +0 -163
- fvs2py-0.2.1/fvs2py/_routines.py +0 -704
- fvs2py-0.2.1/fvs2py/common.py +0 -280
- {fvs2py-0.2.1 → fvs2py-0.2.2}/LICENSE +0 -0
- {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py/__init__.py +0 -0
- {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py/keyfile.py +0 -0
- {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py/py.typed +0 -0
- {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py.egg-info/dependency_links.txt +0 -0
- {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py.egg-info/entry_points.txt +0 -0
- {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py.egg-info/requires.txt +0 -0
- {fvs2py-0.2.1 → fvs2py-0.2.2}/fvs2py.egg-info/top_level.txt +0 -0
- {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.
|
|
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
|
|
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
|
-
##
|
|
76
|
+
## Contributing
|
|
77
77
|
|
|
78
|
-
|
|
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
|
|
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
|
-
##
|
|
40
|
+
## Contributing
|
|
41
41
|
|
|
42
|
-
|
|
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)
|