fvs2py 0.2.1__py3-none-any.whl
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/__init__.py +3 -0
- fvs2py/_base.py +93 -0
- fvs2py/_core.py +155 -0
- fvs2py/_mixins/__init__.py +25 -0
- fvs2py/_mixins/control.py +215 -0
- fvs2py/_mixins/events.py +226 -0
- fvs2py/_mixins/simulation.py +209 -0
- fvs2py/_mixins/species.py +186 -0
- fvs2py/_mixins/stand.py +102 -0
- fvs2py/_mixins/svs.py +166 -0
- fvs2py/_mixins/trees.py +163 -0
- fvs2py/_routines.py +704 -0
- fvs2py/cli.py +78 -0
- fvs2py/common.py +280 -0
- fvs2py/constants.py +328 -0
- fvs2py/enums.py +317 -0
- fvs2py/keyfile.py +91 -0
- fvs2py/py.typed +0 -0
- fvs2py-0.2.1.dist-info/METADATA +95 -0
- fvs2py-0.2.1.dist-info/RECORD +24 -0
- fvs2py-0.2.1.dist-info/WHEEL +5 -0
- fvs2py-0.2.1.dist-info/entry_points.txt +2 -0
- fvs2py-0.2.1.dist-info/licenses/LICENSE +21 -0
- fvs2py-0.2.1.dist-info/top_level.txt +1 -0
fvs2py/enums.py
ADDED
|
@@ -0,0 +1,317 @@
|
|
|
1
|
+
"""Symbolic names for FVS integer status codes and string accessors.
|
|
2
|
+
|
|
3
|
+
All status-code enums are `IntEnum` subclasses, so their members compare
|
|
4
|
+
equal to the corresponding raw integers returned/accepted by FVS. This keeps
|
|
5
|
+
call-site ergonomics unchanged (`fvs.itrncd == FvsItrnCode.NOT_STARTED` works
|
|
6
|
+
alongside `fvs.itrncd == -1`) while giving callers readable constants.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from enum import IntEnum, StrEnum
|
|
12
|
+
from typing import Self
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class FvsVariant(StrEnum):
|
|
16
|
+
"""Enumeration of supported FVS Variants."""
|
|
17
|
+
|
|
18
|
+
ALASKA = "AK" # Southeast Alaska and Coastal British Columbia
|
|
19
|
+
BLUE_MOUNTAINS = "BM" # Blue Mountains
|
|
20
|
+
INLAND_CALIFORNIA = "CA" # Inland California and Southern Cascades (ICASCA)
|
|
21
|
+
CENTRAL_IDAHO = "CI" # Central Idaho
|
|
22
|
+
CENTRAL_ROCKIES = "CR" # Central Rockies
|
|
23
|
+
CENTRAL_STATES = "CS" # Central States
|
|
24
|
+
EASTERN_CASCADES = "EC" # East Cascades
|
|
25
|
+
EASTERN_MONTANA = "EM" # Eastern Montana
|
|
26
|
+
INLAND_EMPIRE = "IE" # Inland Empire
|
|
27
|
+
KOOTENAI = "KT" # Kootenai, Kaniksu, and Tally Lake (KooKanTL)
|
|
28
|
+
LAKE_STATES = "LS" # Lake States
|
|
29
|
+
KLAMATH_MOUNTAINS = "NC" # Klamath Mountains (and northern California)
|
|
30
|
+
NORTHEAST_US = "NE" # Northeastern US
|
|
31
|
+
ORGANON_SOUTHWEST = "OC" # Organon Southwest
|
|
32
|
+
ORGANON_PACIFIC = "OP" # Organon Pacific Northwest
|
|
33
|
+
PACIFIC_COAST = "PN" # Pacific Northwest Coast
|
|
34
|
+
SOUTHERN_US = "SN" # Southern US
|
|
35
|
+
SOUTHERN_OREGON = (
|
|
36
|
+
"SO" # South Central Oregon and Northeast California (SORNEC)
|
|
37
|
+
)
|
|
38
|
+
TETONS = "TT" # Tetons
|
|
39
|
+
UTAH = "UT" # Utah
|
|
40
|
+
WESTERN_CASCADES = "WC" # Westside Cascades
|
|
41
|
+
WESTERN_SIERRAS = "WS" # Western Sierra Nevada
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class FvsAttributeAccessor(StrEnum):
|
|
45
|
+
"""How an FVS attribute is to be accessed."""
|
|
46
|
+
|
|
47
|
+
GET = "get"
|
|
48
|
+
SET = "set"
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
class FvsItrnCode(IntEnum):
|
|
52
|
+
"""Return-code values reported by `fvsGetRtnCode` / `FVS.itrncd`."""
|
|
53
|
+
|
|
54
|
+
NOT_STARTED = -1
|
|
55
|
+
GOOD_RUNNING_STATE = 0
|
|
56
|
+
ERROR = 1
|
|
57
|
+
FINISHED_ALL_STANDS = 2
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class FvsExitCode(IntEnum):
|
|
61
|
+
"""Exit-code values reported by `fvsGetICCode` / `FVS.exit_code`."""
|
|
62
|
+
|
|
63
|
+
NO_ERROR = 0
|
|
64
|
+
INPUT_DATA_ERROR = 1
|
|
65
|
+
KEYWORD_ERROR = 2
|
|
66
|
+
EXTENSION_OR_GROUP_ACTIVITIES_ERROR = 3
|
|
67
|
+
SCRATCH_FILE_ERROR = 4
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
class FvsRestartCode(IntEnum):
|
|
71
|
+
"""Restart-code values reported by `fvsGetRestartCode`.
|
|
72
|
+
|
|
73
|
+
Indicates where inside a cycle FVS stopped after the most recent call to
|
|
74
|
+
`FVS.run`.
|
|
75
|
+
"""
|
|
76
|
+
|
|
77
|
+
INITIALIZED = 0
|
|
78
|
+
BEFORE_FIRST_EVMON = 1
|
|
79
|
+
AFTER_FIRST_EVMON = 2
|
|
80
|
+
BEFORE_SECOND_EVMON = 3
|
|
81
|
+
AFTER_SECOND_EVMON = 4
|
|
82
|
+
AFTER_GROWTH_AND_MORTALITY = 5
|
|
83
|
+
BEFORE_ESTAB = 6
|
|
84
|
+
DONE_RUNNING_STAND = 100
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
class FvsStopPointCode(IntEnum):
|
|
88
|
+
"""Stop-point-code values accepted by `fvsSetStoppointCodes`.
|
|
89
|
+
|
|
90
|
+
Selects where inside a cycle FVS should pause during `FVS.run`.
|
|
91
|
+
"""
|
|
92
|
+
|
|
93
|
+
EVERY_STOP_LOCATION = -1
|
|
94
|
+
NEVER_STOP = 0
|
|
95
|
+
BEFORE_FIRST_EVMON = 1
|
|
96
|
+
AFTER_FIRST_EVMON = 2
|
|
97
|
+
BEFORE_SECOND_EVMON = 3
|
|
98
|
+
AFTER_SECOND_EVMON = 4
|
|
99
|
+
AFTER_GROWTH_AND_MORTALITY = 5
|
|
100
|
+
BEFORE_ESTAB = 6
|
|
101
|
+
AFTER_INPUT_BEFORE_IMPUTE = 7
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
class FvsAttrReturnCode(IntEnum):
|
|
105
|
+
"""Return-code values reported by attribute-accessor FVS routines.
|
|
106
|
+
|
|
107
|
+
Produced by `fvsSpeciesAttr`, `fvsTreeAttr`, and sibling routines with
|
|
108
|
+
the same convention in the trailing `rtncode` parameter. Each member
|
|
109
|
+
carries a `message` attribute describing the condition, suitable for
|
|
110
|
+
use in an error message. Codes 2 and 3 are only reported by
|
|
111
|
+
`fvsTreeAttr`; they're documented on the shared enum so a single
|
|
112
|
+
policy can cover every attr accessor.
|
|
113
|
+
"""
|
|
114
|
+
|
|
115
|
+
message: str
|
|
116
|
+
|
|
117
|
+
OK = 0, "OK"
|
|
118
|
+
NAME_NOT_FOUND = 1, "name not found"
|
|
119
|
+
NTREES_EXCEEDS_MAX = 2, "ntrees is greater than the maximum allowed"
|
|
120
|
+
TREE_COUNT_MISMATCH = 3, "there were more or fewer trees than ntrees"
|
|
121
|
+
NAME_LENGTH_INVALID = 4, "length of name string was too large or small"
|
|
122
|
+
|
|
123
|
+
def __new__(cls, value: int, message: str) -> Self:
|
|
124
|
+
"""Construct a member that carries both the int value and a message.
|
|
125
|
+
|
|
126
|
+
Args:
|
|
127
|
+
value: Integer value reported by FVS.
|
|
128
|
+
message: Human-readable description of the return code.
|
|
129
|
+
|
|
130
|
+
Returns:
|
|
131
|
+
A new `FvsAttrReturnCode` member with `message` attached.
|
|
132
|
+
"""
|
|
133
|
+
obj = int.__new__(cls, value)
|
|
134
|
+
obj._value_ = value
|
|
135
|
+
obj.message = message
|
|
136
|
+
return obj
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
class FvsBaseActivity(IntEnum):
|
|
140
|
+
"""Activity codes for the FVS base model.
|
|
141
|
+
|
|
142
|
+
Names match the keywords in the FVS Keyword Guide (no extension prefix,
|
|
143
|
+
since the extension is implicit in this enum's type).
|
|
144
|
+
"""
|
|
145
|
+
|
|
146
|
+
TREELIST = 80
|
|
147
|
+
CRNMULT = 81
|
|
148
|
+
MANAGED = 82
|
|
149
|
+
FIXCW = 90
|
|
150
|
+
BAIMULT = 91
|
|
151
|
+
HTGMULT = 92
|
|
152
|
+
REGHMULT = 93
|
|
153
|
+
MORTMULT = 94
|
|
154
|
+
REGDMULT = 96
|
|
155
|
+
FIXMORT = 97
|
|
156
|
+
FIXDG = 98
|
|
157
|
+
FIXHTG = 99
|
|
158
|
+
SYSTEM = 100
|
|
159
|
+
HTGSTOP = 110
|
|
160
|
+
TOPKILL = 111
|
|
161
|
+
SETSITE = 120
|
|
162
|
+
ATRTLIST = 198
|
|
163
|
+
CUTLIST = 199
|
|
164
|
+
MINHARV = 200
|
|
165
|
+
SPECPREF = 201
|
|
166
|
+
TCONDMLT = 202
|
|
167
|
+
YARDLOSS = 203
|
|
168
|
+
FVSSTAND = 204
|
|
169
|
+
CRUZFILE = 205
|
|
170
|
+
MCDEFECT = 215
|
|
171
|
+
BFDEFECT = 216
|
|
172
|
+
VOLUME = 217
|
|
173
|
+
BFVOLUME = 218
|
|
174
|
+
THINAUTO = 222
|
|
175
|
+
THINBTA = 223
|
|
176
|
+
THINATA = 224
|
|
177
|
+
THINBBA = 225
|
|
178
|
+
THINABA = 226
|
|
179
|
+
THINPRSC = 227
|
|
180
|
+
THINDBH = 228
|
|
181
|
+
SALVAGE = 229
|
|
182
|
+
THINSDI = 230
|
|
183
|
+
THINCC = 231
|
|
184
|
+
THINHT = 232
|
|
185
|
+
THINMIST = 233
|
|
186
|
+
THINRDEN = 234
|
|
187
|
+
THINPT = 235
|
|
188
|
+
THINRDSL = 236
|
|
189
|
+
SETPTHIN = 248
|
|
190
|
+
PRUNE = 249
|
|
191
|
+
COMPRESS = 250
|
|
192
|
+
FERTILIZ = 260
|
|
193
|
+
RESETAGE = 443
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
class FvsDatabaseActivity(IntEnum):
|
|
197
|
+
"""Activity codes for the FVS database input/output extension."""
|
|
198
|
+
|
|
199
|
+
SQLIN = 101
|
|
200
|
+
SQLOUT = 102
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
class FvsEstablishmentActivity(IntEnum):
|
|
204
|
+
"""Activity codes for the FVS Establishment extension."""
|
|
205
|
+
|
|
206
|
+
SPECMULT = 95
|
|
207
|
+
TALLY = 427
|
|
208
|
+
TALLYONE = 428
|
|
209
|
+
TALLYTWO = 429
|
|
210
|
+
PLANT = 430
|
|
211
|
+
NATURAL = 431
|
|
212
|
+
ADDTREES = 432
|
|
213
|
+
STOCKADJ = 440
|
|
214
|
+
HTADJ = 442
|
|
215
|
+
SPROUT = 450
|
|
216
|
+
# NATURAL (490) is documented in some FVS variant guides but is
|
|
217
|
+
# omitted from rFVS's activity table and from this enum until we
|
|
218
|
+
# have evidence it is live in the shared library we target.
|
|
219
|
+
BURNPREP = 491
|
|
220
|
+
MECHPREP = 493
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
class FvsCoverActivity(IntEnum):
|
|
224
|
+
"""Activity codes for the FVS Cover extension."""
|
|
225
|
+
|
|
226
|
+
COVER = 900
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
class FvsMistletoeActivity(IntEnum):
|
|
230
|
+
"""Activity codes for the FVS Dwarf Mistletoe extension."""
|
|
231
|
+
|
|
232
|
+
MISTMULT = 2001
|
|
233
|
+
MISTPREF = 2002
|
|
234
|
+
MISTMORT = 2003
|
|
235
|
+
MISTHMOD = 2004
|
|
236
|
+
MISTGMOD = 2005
|
|
237
|
+
MISTPINF = 2006
|
|
238
|
+
MISTABLE = 2007
|
|
239
|
+
|
|
240
|
+
|
|
241
|
+
class FvsFireAndFuelsActivity(IntEnum):
|
|
242
|
+
"""Activity codes for the FVS Fire and Fuels extension."""
|
|
243
|
+
|
|
244
|
+
SALVSP = 2501
|
|
245
|
+
SOILHEAT = 2503
|
|
246
|
+
BURNREPT = 2504
|
|
247
|
+
MOISTURE = 2505
|
|
248
|
+
SIMFIRE = 2506
|
|
249
|
+
FLAMEADJ = 2507
|
|
250
|
+
POTFIRE = 2508
|
|
251
|
+
SNAGOUT = 2512
|
|
252
|
+
FUELOUT = 2515
|
|
253
|
+
SALVAGE = 2520
|
|
254
|
+
FUELINIT = 2521
|
|
255
|
+
SNAGINIT = 2522
|
|
256
|
+
PILEBURN = 2523
|
|
257
|
+
FUELTRET = 2525
|
|
258
|
+
FUELREPT = 2527
|
|
259
|
+
MORTREPT = 2528
|
|
260
|
+
DROUGHT = 2529
|
|
261
|
+
FUELMOVE = 2530
|
|
262
|
+
FUELMODL = 2538
|
|
263
|
+
DEFULMOD = 2539
|
|
264
|
+
CARBREPT = 2544
|
|
265
|
+
CARBCUT = 2545
|
|
266
|
+
CANFPROF = 2547
|
|
267
|
+
FUELFOTO = 2548
|
|
268
|
+
FIRECALC = 2549
|
|
269
|
+
FMODLIST = 2550
|
|
270
|
+
DWDVLOUT = 2551
|
|
271
|
+
DWDCVOUT = 2552
|
|
272
|
+
FUELSOFT = 2553
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
class FvsEconomicsActivity(IntEnum):
|
|
276
|
+
"""Activity codes for the FVS Economics extension."""
|
|
277
|
+
|
|
278
|
+
PRETEND = 2605
|
|
279
|
+
SEVSTART = 2606
|
|
280
|
+
SPECCST = 2607
|
|
281
|
+
SPECRVN = 2608
|
|
282
|
+
STRTECON = 2609
|
|
283
|
+
|
|
284
|
+
|
|
285
|
+
FvsActivity = (
|
|
286
|
+
FvsBaseActivity
|
|
287
|
+
| FvsDatabaseActivity
|
|
288
|
+
| FvsEstablishmentActivity
|
|
289
|
+
| FvsCoverActivity
|
|
290
|
+
| FvsMistletoeActivity
|
|
291
|
+
| FvsFireAndFuelsActivity
|
|
292
|
+
| FvsEconomicsActivity
|
|
293
|
+
)
|
|
294
|
+
"""Union of every per-extension FVS activity enum.
|
|
295
|
+
|
|
296
|
+
Any `IntEnum` member from the extension-scoped activity enums is a
|
|
297
|
+
valid `FvsActivity`. Callers pass a member from the appropriate
|
|
298
|
+
extension enum (`FvsBaseActivity.SALVAGE` vs. `FvsFireAndFuelsActivity.SALVAGE`);
|
|
299
|
+
`int(activity)` unwraps it to the underlying FVS code for the library
|
|
300
|
+
call.
|
|
301
|
+
"""
|
|
302
|
+
|
|
303
|
+
|
|
304
|
+
class FvsSimulationState(StrEnum):
|
|
305
|
+
"""Python-side state of the FVS simulation lifecycle.
|
|
306
|
+
|
|
307
|
+
Tracked on `FVS._state` so that `FVS.run` can guard against
|
|
308
|
+
re-entrant invocation and so callers (or future batch helpers) can reason
|
|
309
|
+
about whether a simulation is idle, in-flight, finished, or has failed.
|
|
310
|
+
These values are opaque identifiers; they do not correspond to any FVS
|
|
311
|
+
return code.
|
|
312
|
+
"""
|
|
313
|
+
|
|
314
|
+
IDLE = "idle"
|
|
315
|
+
RUNNING = "running"
|
|
316
|
+
COMPLETE = "complete"
|
|
317
|
+
ERROR = "error"
|
fvs2py/keyfile.py
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
"""Lightweight keyfile inspection helpers used by `FVS.load_keyfile`.
|
|
2
|
+
|
|
3
|
+
The only question this module is trying to answer is "does the keyfile appear
|
|
4
|
+
to describe a single stand?". We choose to answer that question by requiring a
|
|
5
|
+
keyfile to contain single instances of `STDIDENT`, `PROCESS`, and `STOP`.
|
|
6
|
+
|
|
7
|
+
Known limitations:
|
|
8
|
+
|
|
9
|
+
- `COMMENT ... END` blocks are not tracked. A free-form comment that
|
|
10
|
+
happens to begin a line with the literal string `STDIDENT` (or similar)
|
|
11
|
+
would be counted.
|
|
12
|
+
- `OPEN`-based include files are not followed; only the text of the
|
|
13
|
+
file passed directly to `FVS.load_keyfile` is inspected.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import re
|
|
19
|
+
from collections.abc import Mapping
|
|
20
|
+
from types import MappingProxyType
|
|
21
|
+
|
|
22
|
+
_KEYWORD_RE: re.Pattern[str] = re.compile(r"^([A-Za-z]{1,10})", re.MULTILINE)
|
|
23
|
+
"""Match an FVS keyword token in columns 1-10 of a line.
|
|
24
|
+
|
|
25
|
+
Captures the leading run of ASCII letters at column 1, up to the 10th column.
|
|
26
|
+
The match stops naturally at the first non-letter (space, digit, punctuation,
|
|
27
|
+
end-of-line) or at the 10-letter cap, whichever comes first. Lines that do
|
|
28
|
+
not start with a letter (data rows, format specs, comment bodies) produce no
|
|
29
|
+
match.
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
SINGLE_STAND_REQUIRED: Mapping[str, int] = MappingProxyType({
|
|
33
|
+
"STDIDENT": 1,
|
|
34
|
+
"PROCESS": 1,
|
|
35
|
+
"STOP": 1,
|
|
36
|
+
})
|
|
37
|
+
"""Keywords that must appear exactly this many times in a single-stand keyfile."""
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def count_keywords(keyfile: str) -> dict[str, int]:
|
|
41
|
+
"""Count keyword occurrences in a keyfile body.
|
|
42
|
+
|
|
43
|
+
Scans each line for a 1-10 letter token anchored at column 1 and followed
|
|
44
|
+
by whitespace or end-of-line. Matches are upper-cased, so the returned
|
|
45
|
+
counts are case-insensitive.
|
|
46
|
+
|
|
47
|
+
Args:
|
|
48
|
+
keyfile: Full text of the FVS keyword file.
|
|
49
|
+
|
|
50
|
+
Returns:
|
|
51
|
+
A mapping from upper-cased keyword name to the number of occurrences
|
|
52
|
+
found. Keywords that do not appear are absent from the mapping.
|
|
53
|
+
"""
|
|
54
|
+
counts: dict[str, int] = {}
|
|
55
|
+
for m in _KEYWORD_RE.finditer(keyfile):
|
|
56
|
+
kw = m.group(1).upper()
|
|
57
|
+
counts[kw] = counts.get(kw, 0) + 1
|
|
58
|
+
return counts
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def validate_single_stand(keyfile: str) -> None:
|
|
62
|
+
"""Verify a keyfile appears to describe a single-stand simulation.
|
|
63
|
+
|
|
64
|
+
Uses `count_keywords` to check that each keyword in
|
|
65
|
+
`SINGLE_STAND_REQUIRED` appears exactly the required number of
|
|
66
|
+
times. Missing or duplicated keywords are reported together in a single
|
|
67
|
+
error.
|
|
68
|
+
|
|
69
|
+
Args:
|
|
70
|
+
keyfile: Full text of the FVS keyword file.
|
|
71
|
+
|
|
72
|
+
Raises:
|
|
73
|
+
ValueError: If any required keyword is missing or appears more times
|
|
74
|
+
than expected. The error message lists every failing keyword.
|
|
75
|
+
"""
|
|
76
|
+
counts = count_keywords(keyfile)
|
|
77
|
+
errors: list[str] = []
|
|
78
|
+
for kw, expected in SINGLE_STAND_REQUIRED.items():
|
|
79
|
+
found = counts.get(kw, 0)
|
|
80
|
+
if found == 0:
|
|
81
|
+
errors.append(f"missing required keyword {kw!r}")
|
|
82
|
+
elif found > expected:
|
|
83
|
+
errors.append(
|
|
84
|
+
f"found {found} instances of {kw!r} (expected {expected}); "
|
|
85
|
+
"keyfile may define multiple stands"
|
|
86
|
+
)
|
|
87
|
+
if errors:
|
|
88
|
+
msg = "Keyfile failed single-stand validation:\n" + "\n".join(
|
|
89
|
+
f" - {e}" for e in errors
|
|
90
|
+
)
|
|
91
|
+
raise ValueError(msg)
|
fvs2py/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fvs2py
|
|
3
|
+
Version: 0.2.1
|
|
4
|
+
Summary: Python wrapper for the Forest Vegetation Simulator API.
|
|
5
|
+
Author-email: David Diaz <ddiaz@vibrantplanet.net>
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Vibrant-Planet-Open-Science/fvs2py
|
|
8
|
+
Project-URL: Repository, https://github.com/Vibrant-Planet-Open-Science/fvs2py
|
|
9
|
+
Project-URL: Issues, https://github.com/Vibrant-Planet-Open-Science/fvs2py/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/Vibrant-Planet-Open-Science/fvs2py/blob/main/CHANGELOG.md
|
|
11
|
+
Keywords: forest,growth,yield,fvs
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering
|
|
20
|
+
Classifier: Typing :: Typed
|
|
21
|
+
Requires-Python: >=3.12
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE
|
|
24
|
+
Requires-Dist: numpy<3,>=2.1
|
|
25
|
+
Requires-Dist: pandas<4,>=3.0
|
|
26
|
+
Provides-Extra: dev
|
|
27
|
+
Requires-Dist: ipykernel==7.2.0; extra == "dev"
|
|
28
|
+
Requires-Dist: mypy==2.1.0; extra == "dev"
|
|
29
|
+
Requires-Dist: nbval==0.11.0; extra == "dev"
|
|
30
|
+
Requires-Dist: pandas-stubs==3.0.0.260204; extra == "dev"
|
|
31
|
+
Requires-Dist: pre-commit==4.6.0; extra == "dev"
|
|
32
|
+
Requires-Dist: pytest-mock==3.15.1; extra == "dev"
|
|
33
|
+
Requires-Dist: pytest==9.0.3; extra == "dev"
|
|
34
|
+
Requires-Dist: ruff==0.15.13; extra == "dev"
|
|
35
|
+
Dynamic: license-file
|
|
36
|
+
|
|
37
|
+
# fvs2py
|
|
38
|
+
A Python wrapper of the [Forest Vegetation Simulator (FVS)](https://www.fs.usda.gov/fvs/).
|
|
39
|
+
|
|
40
|
+
This project has been designed to provide programmatic access to FVS through the [`FVS-API`](https://github.com/USDAForestService/ForestVegetationSimulator/wiki/FVS-API) from Python. It is inspired by and generally follows the pattern demonstrated by [`rFVS`](https://github.com/USDAForestService/ForestVegetationSimulator/wiki/rFVS), which loads a pre-compiled shared library of a single FVS variant and provides the user access to FVS variables and commands from a modern programming language.
|
|
41
|
+
|
|
42
|
+
Our initial focus is to replicate the functionality provided by `rFVS`.
|
|
43
|
+
|
|
44
|
+
We will then build upon the addition of new subroutines in Fortran that extend the underlying `FVS-API` and to produce corresponding wrapper functions here in `fvs2py` that will allow users access to get and set a broader suite of FVS parameters. The ultimate goal for this Python API is to allow users to run FVS, get and set simulation parameters at runtime, and to retrieve FVS output tables at runtime and in-memory without needing to interact with an external database or other output files.
|
|
45
|
+
|
|
46
|
+
## Installation
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
pip install fvs2py
|
|
50
|
+
```
|
|
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`.
|
|
53
|
+
|
|
54
|
+
## Usage
|
|
55
|
+
|
|
56
|
+
```python
|
|
57
|
+
from fvs2py import FVS
|
|
58
|
+
|
|
59
|
+
fvs = FVS("/path/to/FVSpn.so")
|
|
60
|
+
fvs.load_keyfile("name.key")
|
|
61
|
+
fvs.run()
|
|
62
|
+
fvs.summary # pandas DataFrame
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Command line
|
|
66
|
+
|
|
67
|
+
fvs2py also installs an `fvs` command that works like FVS executables do. These two commands are equivalent:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
FVSpn --keywordfile=name.key
|
|
71
|
+
fvs --lib=/path/to/FVSpn.so --keywordfile=name.key
|
|
72
|
+
```
|
|
73
|
+
|
|
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
|
+
|
|
76
|
+
## Development
|
|
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.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
fvs2py/__init__.py,sha256=uavqnCuwpPhK-HYgcEM9PmHjuxw8KPy5W-4xAgVKY_I,42
|
|
2
|
+
fvs2py/_base.py,sha256=5pCGPazqrsCfWBPE6NATJHMwPRYZu53aNWadH-aI2Xo,2870
|
|
3
|
+
fvs2py/_core.py,sha256=k8RSfMeaDRg6bm-ivAdsAfQvFdpi_c0bYFeuXjDC8Fw,6051
|
|
4
|
+
fvs2py/_routines.py,sha256=NTqFORW-9F3Ct1s2QdkaNHwRLPRfMjmbmlSbXqMbZpM,24088
|
|
5
|
+
fvs2py/cli.py,sha256=5TlnDbXBHT296ZVym8YsuD1ypQPlvedBY-BjIsKsRZw,2249
|
|
6
|
+
fvs2py/common.py,sha256=_u-NOiVW_5jZkNsIAwoMLrIn1BOXBDvncI16beuAMaM,9728
|
|
7
|
+
fvs2py/constants.py,sha256=sggTrAvHlWA2b7lnQGRg6-HqZXrMvOU9ahdj3mnl2u0,5175
|
|
8
|
+
fvs2py/enums.py,sha256=MOZWBfpGIjr81laO9B0FQf0m3IxDswqXT15nPsR2ehY,8385
|
|
9
|
+
fvs2py/keyfile.py,sha256=E3Wq3sIEl6v1yb2NF8ASpKWrepnLRElrd_xwCukKIIA,3261
|
|
10
|
+
fvs2py/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
11
|
+
fvs2py/_mixins/__init__.py,sha256=lK0s6sz5KG83EA37pHKXOSRfJnUgwkHawmkAEREEBNI,797
|
|
12
|
+
fvs2py/_mixins/control.py,sha256=8cmd2EIuYfzMT1_brRAenvumtnEaMM1VLdKsRr8-fco,8086
|
|
13
|
+
fvs2py/_mixins/events.py,sha256=CeQL5FaiO3V1fR6GrKAfH5S9jewGNsaOLsRRkpJaJSk,8939
|
|
14
|
+
fvs2py/_mixins/simulation.py,sha256=4_7ZV5TGhciGeswJfBrec0MXVpFXe8k9R-40opeQQCM,8835
|
|
15
|
+
fvs2py/_mixins/species.py,sha256=lDC8JGFqK38Jjx6bdRCcFDCW7jXHgHtnk4GAaw6MZHA,6797
|
|
16
|
+
fvs2py/_mixins/stand.py,sha256=vJB0d2f4qxCBMbDq82xmDZOBpWQm2zT100ow_hcZp1A,3210
|
|
17
|
+
fvs2py/_mixins/svs.py,sha256=Y9K8ey3_TsYcswP9c5u4-WIxpKz9J513V66LeJAD2PU,5885
|
|
18
|
+
fvs2py/_mixins/trees.py,sha256=VCPmiYWMxWH1Q-_X6ARyo9vfLOTJOr3-elIQdc4sdQs,5503
|
|
19
|
+
fvs2py-0.2.1.dist-info/licenses/LICENSE,sha256=xbA955yVyqcd8K1r5UvXpXPcjQ2mYZWxb4t_L59VzpA,1076
|
|
20
|
+
fvs2py-0.2.1.dist-info/METADATA,sha256=2r9RB_uUd5F8LlWIldp0lJX2sANRix7IgctQ85Haa8Q,4986
|
|
21
|
+
fvs2py-0.2.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
22
|
+
fvs2py-0.2.1.dist-info/entry_points.txt,sha256=sXw1iHXknExWrfbtK5fqxwGfKMYwefcdoliJr1uFQeg,40
|
|
23
|
+
fvs2py-0.2.1.dist-info/top_level.txt,sha256=WJcbzLPIImEejenGLoDvbP9jjkZy0pwNIKeaMoXrXjE,7
|
|
24
|
+
fvs2py-0.2.1.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Vibrant Planet, PBC
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
fvs2py
|