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/_routines.py ADDED
@@ -0,0 +1,704 @@
1
+ """Declarative registry of FVS routine signatures + a thin invoker.
2
+
3
+ Each FVS routine is described by a `Routine` whose parameters are
4
+ `Param` records carrying a name, a ctypes type (static or a runtime
5
+ factory closure over the call kwargs), and an `Intent` flag indicating
6
+ direction. `Routine.call` resolves dynamic types, auto-allocates
7
+ output buffers, assigns `argtypes`/`restype` on the resolved foreign
8
+ function, invokes it, and dispatches any configured return-code policy.
9
+
10
+ Mixin methods own Python-facing ergonomics and derive dependent args (e.g.
11
+ `nattr = len(attr)`, `ntrees = len(values)`) before handing a
12
+ fully-specified kwarg dict to `FvsCore._invoke`. The registry itself
13
+ stays free of derivation or validation logic.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import ctypes as ct
19
+ from collections.abc import Callable, Mapping
20
+ from dataclasses import dataclass, replace
21
+ from enum import Flag, auto
22
+ from types import MappingProxyType
23
+ from typing import Any
24
+
25
+ import numpy as np
26
+
27
+ from fvs2py.constants import (
28
+ STR_C_CONTIGUOUS,
29
+ STR_MAXCYCLES,
30
+ STR_MAXPLOTS,
31
+ STR_MAXSPECIES,
32
+ STR_MAXTREES,
33
+ STR_MXCWDOBJS,
34
+ STR_MXDEADOBJS,
35
+ STR_MXSVSOBJS,
36
+ STR_NCWDOBJS,
37
+ STR_NCYCLES,
38
+ STR_NDEADOBJS,
39
+ STR_NOBJS,
40
+ STR_NPLOTS,
41
+ STR_NSVSOBJS,
42
+ STR_NTREES,
43
+ )
44
+ from fvs2py.enums import FvsAttrReturnCode
45
+
46
+
47
+ class Intent(Flag):
48
+ """Direction flag for a `Param`.
49
+
50
+ `IN` parameters are supplied by callers as kwargs and passed through to
51
+ the foreign function unchanged. `OUT` parameters are auto-allocated by
52
+ the invoker and returned to the caller; callers must not pass them.
53
+ `INOUT` (`IN | OUT`) parameters are caller-owned buffers that the
54
+ foreign function may read from and write into in place.
55
+ """
56
+
57
+ IN = auto()
58
+ OUT = auto()
59
+ INOUT = IN | OUT
60
+
61
+
62
+ Scope = Mapping[str, Any]
63
+ ParamType = type | Callable[[Scope], type]
64
+
65
+
66
+ @dataclass(frozen=True, slots=True, kw_only=True)
67
+ class Param:
68
+ """One parameter in an FVS routine's signature.
69
+
70
+ Attributes:
71
+ name: Kwarg name used by `Routine.call`.
72
+ ctype: Either a ctypes type (static) or a callable that receives the
73
+ call-site kwargs as scope and returns a concrete ctypes type.
74
+ Factories are typically closures produced by `ndptr_f64` or
75
+ `ndptr_intc`.
76
+ intent: Direction flag; see `Intent`.
77
+ """
78
+
79
+ name: str
80
+ ctype: ParamType
81
+ intent: Intent = Intent.IN
82
+
83
+
84
+ @dataclass(frozen=True, slots=True, kw_only=True)
85
+ class Routine:
86
+ """Declarative description of an FVS routine's ctypes interface.
87
+
88
+ Attributes:
89
+ params: Parameters in Fortran declaration order.
90
+ restype: Ctypes return type, or `None` if the routine returns
91
+ nothing (the usual case for FVS subroutines).
92
+ rc_param: Name of the return-code OUT parameter, or `None` if the
93
+ routine does not report a return code.
94
+ rc_policy: Callable invoked with the return-code integer after a
95
+ successful call; should raise on error and return `None` on OK.
96
+ name: Routine identifier used in error messages. Populated from the
97
+ `FVS_ROUTINES` mapping key; construction-site entries may
98
+ leave it empty.
99
+ """
100
+
101
+ params: tuple[Param, ...]
102
+ restype: type | None = None
103
+ rc_param: str | None = "rtncode"
104
+ rc_policy: Callable[[int], None] | None = None
105
+ name: str = ""
106
+
107
+ def __post_init__(self) -> None:
108
+ """Validate the declarative shape at construction time.
109
+
110
+ Catches structural misconfigurations that would otherwise surface as
111
+ silently-skipped return-code validation at call time: declaring an
112
+ `rc_policy` without an `rc_param`, or pointing
113
+ `rc_param` at a name that isn't a declared `Intent.OUT`
114
+ parameter. Return codes are write-only by convention, so `INOUT`
115
+ and `IN` params are rejected as `rc_param` targets.
116
+ """
117
+ if self.rc_policy is None:
118
+ return
119
+ if self.rc_param is None:
120
+ msg = f"{self._label()}: rc_policy requires rc_param"
121
+ raise ValueError(msg)
122
+ out_names = {p.name for p in self.params if p.intent == Intent.OUT}
123
+ if self.rc_param not in out_names:
124
+ msg = (
125
+ f"{self._label()}: rc_param {self.rc_param!r} must name an "
126
+ f"Intent.OUT param; OUT params are {sorted(out_names)}"
127
+ )
128
+ raise ValueError(msg)
129
+
130
+ def call(self, func: Any, /, **kwargs: Any) -> Any:
131
+ """Dispatch a call to `func` using this routine's declarative shape.
132
+
133
+ Resolves any dynamic-type factories against `kwargs`, auto-allocates
134
+ OUT buffers, assigns `argtypes`/`restype` on `func`, invokes it
135
+ with positional args in declaration order, runs the configured return
136
+ code policy (if any), and returns the OUT values.
137
+
138
+ Args:
139
+ func: Resolved foreign function (ctypes `_FuncPointer`) or a
140
+ Python callable compatible with the routine's call shape (used
141
+ by tests).
142
+ **kwargs: One entry per non-OUT parameter.
143
+
144
+ Returns:
145
+ `None` if the routine has no non-rc OUT params, the unwrapped
146
+ scalar value if it has exactly one, or a `dict[name, value]` if
147
+ it has several.
148
+
149
+ Raises:
150
+ TypeError: If required kwargs are missing, unknown kwargs are
151
+ supplied, or an OUT-only param is passed by the caller.
152
+ """
153
+ param_names = {p.name for p in self.params}
154
+ expected_inputs = {
155
+ p.name for p in self.params if p.intent != Intent.OUT
156
+ }
157
+ provided = set(kwargs)
158
+
159
+ missing = expected_inputs - provided
160
+ if missing:
161
+ msg = f"{self._label()}: missing required kwargs {sorted(missing)}"
162
+ raise TypeError(msg)
163
+
164
+ unknown = provided - param_names
165
+ if unknown:
166
+ msg = f"{self._label()}: unknown kwargs {sorted(unknown)}"
167
+ raise TypeError(msg)
168
+
169
+ out_in_kwargs = provided & {
170
+ p.name for p in self.params if p.intent == Intent.OUT
171
+ }
172
+ if out_in_kwargs:
173
+ msg = (
174
+ f"{self._label()}: OUT params must not be provided by the "
175
+ f"caller: {sorted(out_in_kwargs)}"
176
+ )
177
+ raise TypeError(msg)
178
+
179
+ argtypes: list[type] = []
180
+ for p in self.params:
181
+ argtypes.append(_resolve_ctype(p.ctype, kwargs))
182
+
183
+ out_bufs: dict[str, Any] = {}
184
+ call_args: list[Any] = []
185
+ for p, t in zip(self.params, argtypes, strict=True):
186
+ if p.intent == Intent.OUT:
187
+ inner = getattr(t, "_type_", None)
188
+ if inner is None:
189
+ msg = (
190
+ f"{self._label()}: OUT param {p.name!r} has ctype "
191
+ f"{t!r} which is not a pointer-like type; cannot "
192
+ f"auto-allocate."
193
+ )
194
+ raise TypeError(msg)
195
+ buf = inner()
196
+ out_bufs[p.name] = buf
197
+ call_args.append(buf)
198
+ else:
199
+ call_args.append(kwargs[p.name])
200
+
201
+ func.argtypes = argtypes
202
+ func.restype = self.restype
203
+ func(*call_args)
204
+
205
+ if self.rc_policy is not None and self.rc_param is not None:
206
+ self.rc_policy(out_bufs[self.rc_param].value)
207
+
208
+ non_rc = {k: v for k, v in out_bufs.items() if k != self.rc_param}
209
+ if not non_rc:
210
+ return None
211
+ if len(non_rc) == 1:
212
+ return next(iter(non_rc.values())).value
213
+ return {k: v.value for k, v in non_rc.items()}
214
+
215
+ def _label(self) -> str:
216
+ """Return a short identifier for error messages.
217
+
218
+ Prefers the registry-populated `name` when present; falls back
219
+ to a generic `Routine(...)` tag for routines constructed outside
220
+ the registry (e.g. in unit tests).
221
+ """
222
+ return self.name or "Routine"
223
+
224
+
225
+ def _resolve_ctype(ctype: ParamType, scope: Scope) -> type:
226
+ """Return a concrete ctypes type, invoking `ctype` if it's a factory.
227
+
228
+ Static types (classes like `ct.c_int` or an `ndpointer` subclass
229
+ produced by `numpy.ctypeslib.ndpointer`) are returned unchanged.
230
+ Callables that are not types are invoked with `scope` and expected to
231
+ return a ctypes type.
232
+ """
233
+ if isinstance(ctype, type):
234
+ return ctype
235
+ return ctype(scope)
236
+
237
+
238
+ def _unwrap(v: Any) -> int:
239
+ """Return the integer value of `v`.
240
+
241
+ Accepts either a plain int or a ctypes scalar with a `.value`
242
+ attribute. Mixin methods sometimes have a dimension as a bare Python int
243
+ (`dims[STR_NTREES]`) and sometimes as a ctypes scalar
244
+ (`self._ntrees`). `ndptr_f64` and `ndptr_intc` factories
245
+ call through this helper so either form is accepted at the call site.
246
+ """
247
+ return v.value if hasattr(v, "value") else int(v)
248
+
249
+
250
+ def ndptr_f64(
251
+ *dim_keys: str, flags: str = STR_C_CONTIGUOUS
252
+ ) -> Callable[[Scope], type]:
253
+ """Build a factory that resolves a contiguous `float64` ndpointer.
254
+
255
+ The returned factory reads each `dim_keys` entry from the call scope
256
+ (kwargs), unwraps ctypes scalars via `_unwrap`, and returns an
257
+ `np.ctypeslib.ndpointer` subclass with the resolved shape.
258
+ """
259
+
260
+ def factory(scope: Scope) -> type:
261
+ shape = tuple(_unwrap(scope[k]) for k in dim_keys)
262
+ return np.ctypeslib.ndpointer( # type: ignore[return-value]
263
+ np.float64, shape=shape, flags=flags
264
+ )
265
+
266
+ return factory
267
+
268
+
269
+ def ndptr_intc(
270
+ *dim_keys: str, flags: str = STR_C_CONTIGUOUS
271
+ ) -> Callable[[Scope], type]:
272
+ """Build a factory that resolves a contiguous `intc` ndpointer.
273
+
274
+ See `ndptr_f64` for the shape-resolution semantics; this variant
275
+ targets C-int arrays, as used by `fvsSummary`.
276
+ """
277
+
278
+ def factory(scope: Scope) -> type:
279
+ shape = tuple(_unwrap(scope[k]) for k in dim_keys)
280
+ return np.ctypeslib.ndpointer( # type: ignore[return-value]
281
+ np.intc, shape=shape, flags=flags
282
+ )
283
+
284
+ return factory
285
+
286
+
287
+ def species_code_policy(rc: int) -> None:
288
+ """Raise `IndexError` on `fvsSpeciesCode`'s out-of-range signal.
289
+
290
+ The FVS API contract for `fvsSpeciesCode` is `0` = OK and `1` =
291
+ index is out of range. Any other value is treated as an unexpected
292
+ return code and surfaced as `RuntimeError` so the caller does
293
+ not silently proceed with a value they cannot interpret.
294
+ """
295
+ if rc == 0:
296
+ return
297
+ if rc == 1:
298
+ msg = "Species index out of range"
299
+ raise IndexError(msg)
300
+ msg = f"unrecognized fvsSpeciesCode return code: {rc}"
301
+ raise RuntimeError(msg)
302
+
303
+
304
+ def add_trees_policy(rc: int) -> None:
305
+ """Dispatch `fvsAddTrees`'s documented return-code contract.
306
+
307
+ The FVS API documents two codes for `fvsAddTrees`: `0` = OK and
308
+ `1` = there was not enough room to store the new trees. The latter
309
+ is surfaced as `ValueError` so callers can catch it alongside
310
+ the mixin's own capacity pre-check. Any other value is treated as an
311
+ unexpected return code and raised as `RuntimeError` so callers
312
+ do not silently proceed.
313
+ """
314
+ if rc == 0:
315
+ return
316
+ if rc == 1:
317
+ msg = "Not enough room to store the new trees"
318
+ raise ValueError(msg)
319
+ msg = f"unrecognized fvsAddTrees return code: {rc}"
320
+ raise RuntimeError(msg)
321
+
322
+
323
+ def add_activity_policy(rc: int) -> None:
324
+ """Dispatch `fvsAddActivity`'s rFVS-documented return-code contract.
325
+
326
+ The FVS API wiki does not document `fvsAddActivity`'s return code,
327
+ but the rFVS reference binding specifies `0` = OK and `1` = some
328
+ error (cause unspecified). The error case is surfaced as
329
+ `ValueError` so callers can catch it alongside the mixin's
330
+ own pre-call guards (keyfile loaded, simulation started, etc.). Any
331
+ other value is treated as unexpected and raised as
332
+ `RuntimeError` so callers do not silently proceed.
333
+ """
334
+ if rc == 0:
335
+ return
336
+ if rc == 1:
337
+ msg = "fvsAddActivity failed to add the activity"
338
+ raise ValueError(msg)
339
+ msg = f"unrecognized fvsAddActivity return code: {rc}"
340
+ raise RuntimeError(msg)
341
+
342
+
343
+ def attr_accessor_policy(rc: int) -> None:
344
+ """Raise if `rc` is not `FvsAttrReturnCode.OK`.
345
+
346
+ Consumed by the `rc_policy` field on `Routine` entries whose
347
+ return codes follow the canonical attr-accessor convention shared by
348
+ `fvsSpeciesAttr`, `fvsTreeAttr`, and similar routines.
349
+ `FvsAttrReturnCode.NAME_NOT_FOUND` surfaces as `NameError`
350
+ (a caller-supplied attribute name that FVS does not recognize); the
351
+ remaining documented codes surface as `RuntimeError` with the
352
+ enum's canned message. Codes outside the known set also become a
353
+ `RuntimeError`, surfaced via the generic "unrecognized" message.
354
+ """
355
+ if rc == FvsAttrReturnCode.OK:
356
+ return
357
+ try:
358
+ member = FvsAttrReturnCode(rc) # type: ignore[call-arg]
359
+ except ValueError as exc:
360
+ msg = f"unrecognized attribute-accessor return code: {rc}"
361
+ raise RuntimeError(msg) from exc
362
+ if member == FvsAttrReturnCode.NAME_NOT_FOUND:
363
+ raise NameError(member.message)
364
+ raise RuntimeError(member.message)
365
+
366
+
367
+ _RAW_ROUTINES: dict[str, Routine] = {
368
+ # Entries are added alongside the corresponding mixin migration so every
369
+ # routine ships with a matching call site. Insertion order is the
370
+ # un-mangled FVS routine name; each entry lists its params in Fortran
371
+ # declaration order.
372
+ "fvs": Routine(
373
+ params=(
374
+ Param(
375
+ name="itrncd",
376
+ ctype=ct.POINTER(ct.c_int),
377
+ intent=Intent.INOUT,
378
+ ),
379
+ ),
380
+ rc_param=None,
381
+ ),
382
+ "fvsGetICCode": Routine(
383
+ params=(
384
+ Param(
385
+ name="ic_code",
386
+ ctype=ct.POINTER(ct.c_int),
387
+ intent=Intent.OUT,
388
+ ),
389
+ ),
390
+ rc_param=None,
391
+ ),
392
+ "fvsGetRtnCode": Routine(
393
+ params=(
394
+ Param(
395
+ name="rtn_code",
396
+ ctype=ct.POINTER(ct.c_int),
397
+ intent=Intent.OUT,
398
+ ),
399
+ ),
400
+ rc_param=None,
401
+ ),
402
+ "fvsGetRestartCode": Routine(
403
+ params=(
404
+ Param(
405
+ name="restart_code",
406
+ ctype=ct.POINTER(ct.c_int),
407
+ intent=Intent.OUT,
408
+ ),
409
+ ),
410
+ rc_param=None,
411
+ ),
412
+ "fvsDimSizes": Routine(
413
+ params=(
414
+ Param(
415
+ name=STR_NTREES, ctype=ct.POINTER(ct.c_int), intent=Intent.OUT
416
+ ),
417
+ Param(
418
+ name=STR_NCYCLES, ctype=ct.POINTER(ct.c_int), intent=Intent.OUT
419
+ ),
420
+ Param(
421
+ name=STR_NPLOTS, ctype=ct.POINTER(ct.c_int), intent=Intent.OUT
422
+ ),
423
+ Param(
424
+ name=STR_MAXTREES, ctype=ct.POINTER(ct.c_int), intent=Intent.OUT
425
+ ),
426
+ Param(
427
+ name=STR_MAXSPECIES,
428
+ ctype=ct.POINTER(ct.c_int),
429
+ intent=Intent.OUT,
430
+ ),
431
+ Param(
432
+ name=STR_MAXPLOTS, ctype=ct.POINTER(ct.c_int), intent=Intent.OUT
433
+ ),
434
+ Param(
435
+ name=STR_MAXCYCLES,
436
+ ctype=ct.POINTER(ct.c_int),
437
+ intent=Intent.OUT,
438
+ ),
439
+ ),
440
+ rc_param=None,
441
+ ),
442
+ "fvsSetCmdLine": Routine(
443
+ params=(
444
+ Param(name="cmdline", ctype=ct.c_char_p),
445
+ Param(name="nch", ctype=ct.POINTER(ct.c_int)),
446
+ Param(
447
+ name="itrncd",
448
+ ctype=ct.POINTER(ct.c_int),
449
+ intent=Intent.INOUT,
450
+ ),
451
+ ),
452
+ rc_param=None,
453
+ ),
454
+ "fvsSetStoppointCodes": Routine(
455
+ params=(
456
+ Param(name="stop_point_code", ctype=ct.POINTER(ct.c_int)),
457
+ Param(name="stop_point_year", ctype=ct.POINTER(ct.c_int)),
458
+ ),
459
+ rc_param=None,
460
+ ),
461
+ "fvsStandID": Routine(
462
+ params=(
463
+ Param(name="stand_id", ctype=ct.c_char_p, intent=Intent.INOUT),
464
+ Param(name="stand_cn", ctype=ct.c_char_p, intent=Intent.INOUT),
465
+ Param(name="mgmt_id", ctype=ct.c_char_p, intent=Intent.INOUT),
466
+ Param(name="stand_id_len", ctype=ct.POINTER(ct.c_int)),
467
+ Param(name="stand_cn_len", ctype=ct.POINTER(ct.c_int)),
468
+ Param(name="mgmt_id_len", ctype=ct.POINTER(ct.c_int)),
469
+ ),
470
+ rc_param=None,
471
+ ),
472
+ "fvsSpeciesCode": Routine(
473
+ params=(
474
+ Param(name="fvs_spp", ctype=ct.c_char_p, intent=Intent.INOUT),
475
+ Param(name="fia_spp", ctype=ct.c_char_p, intent=Intent.INOUT),
476
+ Param(name="plants_spp", ctype=ct.c_char_p, intent=Intent.INOUT),
477
+ Param(name="index", ctype=ct.POINTER(ct.c_int)),
478
+ Param(name="fvs_spp_len", ctype=ct.POINTER(ct.c_int)),
479
+ Param(name="fia_spp_len", ctype=ct.POINTER(ct.c_int)),
480
+ Param(name="plants_spp_len", ctype=ct.POINTER(ct.c_int)),
481
+ Param(
482
+ name="rtncode",
483
+ ctype=ct.POINTER(ct.c_int),
484
+ intent=Intent.OUT,
485
+ ),
486
+ ),
487
+ rc_policy=species_code_policy,
488
+ ),
489
+ "fvsSpeciesAttr": Routine(
490
+ params=(
491
+ Param(name="attr_name", ctype=ct.c_char_p),
492
+ Param(name="nch", ctype=ct.POINTER(ct.c_int)),
493
+ Param(name="action", ctype=ct.c_char_p),
494
+ Param(
495
+ name="arr",
496
+ ctype=np.ctypeslib.ndpointer(
497
+ np.float64, flags=STR_C_CONTIGUOUS
498
+ ),
499
+ intent=Intent.INOUT,
500
+ ),
501
+ Param(
502
+ name="rtncode",
503
+ ctype=ct.POINTER(ct.c_int),
504
+ intent=Intent.OUT,
505
+ ),
506
+ ),
507
+ rc_policy=attr_accessor_policy,
508
+ ),
509
+ "fvsTreeAttr": Routine(
510
+ params=(
511
+ Param(name="attr_name", ctype=ct.c_char_p),
512
+ Param(name="nch", ctype=ct.POINTER(ct.c_int)),
513
+ Param(name="action", ctype=ct.c_char_p),
514
+ Param(name=STR_NTREES, ctype=ct.POINTER(ct.c_int)),
515
+ Param(
516
+ name="arr",
517
+ ctype=ndptr_f64(STR_NTREES),
518
+ intent=Intent.INOUT,
519
+ ),
520
+ Param(
521
+ name="rtncode",
522
+ ctype=ct.POINTER(ct.c_int),
523
+ intent=Intent.OUT,
524
+ ),
525
+ ),
526
+ rc_policy=attr_accessor_policy,
527
+ ),
528
+ "fvsFFEAttrs": Routine(
529
+ params=(
530
+ Param(name="attr_name", ctype=ct.c_char_p),
531
+ Param(name="nch", ctype=ct.POINTER(ct.c_int)),
532
+ Param(name="action", ctype=ct.c_char_p),
533
+ Param(name=STR_MAXSPECIES, ctype=ct.POINTER(ct.c_int)),
534
+ Param(
535
+ name="arr",
536
+ ctype=ndptr_f64(STR_MAXSPECIES),
537
+ intent=Intent.INOUT,
538
+ ),
539
+ Param(
540
+ name="rtncode",
541
+ ctype=ct.POINTER(ct.c_int),
542
+ intent=Intent.OUT,
543
+ ),
544
+ ),
545
+ rc_policy=attr_accessor_policy,
546
+ ),
547
+ "fvsSVSDimSizes": Routine(
548
+ params=(
549
+ Param(
550
+ name=STR_NSVSOBJS,
551
+ ctype=ct.POINTER(ct.c_int),
552
+ intent=Intent.OUT,
553
+ ),
554
+ Param(
555
+ name=STR_NDEADOBJS,
556
+ ctype=ct.POINTER(ct.c_int),
557
+ intent=Intent.OUT,
558
+ ),
559
+ Param(
560
+ name=STR_NCWDOBJS,
561
+ ctype=ct.POINTER(ct.c_int),
562
+ intent=Intent.OUT,
563
+ ),
564
+ Param(
565
+ name=STR_MXSVSOBJS,
566
+ ctype=ct.POINTER(ct.c_int),
567
+ intent=Intent.OUT,
568
+ ),
569
+ Param(
570
+ name=STR_MXDEADOBJS,
571
+ ctype=ct.POINTER(ct.c_int),
572
+ intent=Intent.OUT,
573
+ ),
574
+ Param(
575
+ name=STR_MXCWDOBJS,
576
+ ctype=ct.POINTER(ct.c_int),
577
+ intent=Intent.OUT,
578
+ ),
579
+ ),
580
+ rc_param=None,
581
+ ),
582
+ "fvsSVSObjData": Routine(
583
+ params=(
584
+ Param(name="attr_name", ctype=ct.c_char_p),
585
+ Param(name="nch", ctype=ct.POINTER(ct.c_int)),
586
+ Param(name="action", ctype=ct.c_char_p),
587
+ Param(name=STR_NOBJS, ctype=ct.POINTER(ct.c_int)),
588
+ Param(
589
+ name="arr",
590
+ ctype=ndptr_f64(STR_NOBJS),
591
+ intent=Intent.INOUT,
592
+ ),
593
+ Param(
594
+ name="rtncode",
595
+ ctype=ct.POINTER(ct.c_int),
596
+ intent=Intent.OUT,
597
+ ),
598
+ ),
599
+ rc_policy=attr_accessor_policy,
600
+ ),
601
+ "fvsAddTrees": Routine(
602
+ params=(
603
+ Param(
604
+ name="dbh",
605
+ ctype=ndptr_f64(STR_NTREES),
606
+ intent=Intent.INOUT,
607
+ ),
608
+ Param(
609
+ name="species",
610
+ ctype=ndptr_f64(STR_NTREES),
611
+ intent=Intent.INOUT,
612
+ ),
613
+ Param(
614
+ name="ht",
615
+ ctype=ndptr_f64(STR_NTREES),
616
+ intent=Intent.INOUT,
617
+ ),
618
+ Param(
619
+ name="cratio",
620
+ ctype=ndptr_f64(STR_NTREES),
621
+ intent=Intent.INOUT,
622
+ ),
623
+ Param(
624
+ name="plot",
625
+ ctype=ndptr_f64(STR_NTREES),
626
+ intent=Intent.INOUT,
627
+ ),
628
+ Param(
629
+ name="tpa",
630
+ ctype=ndptr_f64(STR_NTREES),
631
+ intent=Intent.INOUT,
632
+ ),
633
+ Param(name=STR_NTREES, ctype=ct.POINTER(ct.c_int)),
634
+ Param(
635
+ name="rtncode",
636
+ ctype=ct.POINTER(ct.c_int),
637
+ intent=Intent.OUT,
638
+ ),
639
+ ),
640
+ rc_policy=add_trees_policy,
641
+ ),
642
+ "fvsEvmonAttr": Routine(
643
+ params=(
644
+ Param(name="attr_name", ctype=ct.c_char_p),
645
+ Param(name="nch", ctype=ct.POINTER(ct.c_int)),
646
+ Param(name="action", ctype=ct.c_char_p),
647
+ Param(
648
+ name="arr",
649
+ ctype=np.ctypeslib.ndpointer(np.float64, shape=(1,)),
650
+ intent=Intent.INOUT,
651
+ ),
652
+ Param(
653
+ name="rtncode",
654
+ ctype=ct.POINTER(ct.c_int),
655
+ intent=Intent.OUT,
656
+ ),
657
+ ),
658
+ rc_policy=attr_accessor_policy,
659
+ ),
660
+ "fvsAddActivity": Routine(
661
+ params=(
662
+ Param(name="year", ctype=ct.POINTER(ct.c_int)),
663
+ Param(name="activity_code", ctype=ct.POINTER(ct.c_int)),
664
+ Param(name="params", ctype=ndptr_f64("nparams")),
665
+ Param(name="nparams", ctype=ct.POINTER(ct.c_int)),
666
+ Param(
667
+ name="rtncode",
668
+ ctype=ct.POINTER(ct.c_int),
669
+ intent=Intent.OUT,
670
+ ),
671
+ ),
672
+ rc_policy=add_activity_policy,
673
+ ),
674
+ "fvsSummary": Routine(
675
+ params=(
676
+ Param(
677
+ name="summary",
678
+ ctype=np.ctypeslib.ndpointer(np.intc, flags=STR_C_CONTIGUOUS),
679
+ intent=Intent.INOUT,
680
+ ),
681
+ Param(name="icycle", ctype=ct.POINTER(ct.c_int)),
682
+ Param(name="ncycles", ctype=ct.POINTER(ct.c_int)),
683
+ Param(name="maxrow", ctype=ct.POINTER(ct.c_int)),
684
+ Param(name="maxcol", ctype=ct.POINTER(ct.c_int)),
685
+ Param(
686
+ name="rtncode",
687
+ ctype=ct.POINTER(ct.c_int),
688
+ intent=Intent.OUT,
689
+ ),
690
+ ),
691
+ ),
692
+ }
693
+
694
+
695
+ FVS_ROUTINES: Mapping[str, Routine] = MappingProxyType({
696
+ k: replace(v, name=k) for k, v in _RAW_ROUTINES.items()
697
+ })
698
+ """Immutable registry of FVS routine call descriptions.
699
+
700
+ Keyed by the un-mangled FVS routine name (matching `NEEDED_ROUTINES`).
701
+ Entries are added as each mixin migrates to `FvsCore._invoke`; routines
702
+ not (yet) described here remain resolvable through `FvsCore` without
703
+ the registry applying a signature to them.
704
+ """