femic.pipeline.legacy_runtime Module

The femic.pipeline.legacy_runtime module defines the typed runtime payloads passed from modern FEMIC orchestration into the still-active legacy 00_data-prep.py / 01a_run-tsa.py / 01b_run-tsa.py surfaces. It is small, but it captures the boundary contract that keeps newer code from passing anonymous path bags and option blobs into legacy execution.

If you are debugging which arguments the legacy 01a or 01b code actually receives, why a cached artifact path was or was not present in the payload, or how parallel worker and sampling settings move across the Stage 00/01a/01b boundary, this is the first module to read. In practice it owns:

  • typed dataclasses for legacy 01a and 01b runtime payloads

  • deterministic cache-path bundling for 01a FMU/code runs through the legacy tsa seam

  • the explicit contract between modern orchestration code and legacy stage entrypoints

Start Here If…

Use this page first if you are trying to:

  • inspect what a single 01a FMU/code run receives from the Stage 00 orchestrator

  • understand the small runtime contract passed into legacy 01b post-TIPSY work

  • debug why a legacy call saw the wrong cache paths, worker count, or TIPSY output root

Typical maintenance path:

  1. Start with build_legacy_01a_runtime_config() for Stage 00 -> 01a wiring questions.

  2. Read build_legacy_01b_runtime_config() for post-TIPSY 01b contract questions.

  3. Inspect the dataclasses directly when the issue is about field semantics or test fixtures rather than builder behavior.

Typical Usage

The normal pattern is for orchestration code to build one typed payload per stage boundary instead of passing anonymous dictionaries into legacy code:

from femic.pipeline.legacy_runtime import build_legacy_01b_runtime_config

runtime_config = build_legacy_01b_runtime_config(
    tipsy_params_path_prefix="data/tipsy_params_tsa",
    tipsy_output_root="data",
    tipsy_output_filename_template="04_output-tsa{tsa}.csv",
)

How This Fits Into The Pipeline

This module sits between orchestration code and legacy stage functions:

  1. modern FEMIC orchestration resolves paths, options, and cache locations

  2. this module packages those resolved values into typed 01a or 01b runtime payloads

  3. legacy stage code consumes those payloads instead of reconstructing the runtime context itself

That means this module owns the typed handoff contract for legacy stage execution, not the higher-level path resolution or the lower-level stage logic.

Key Entry Surfaces

The highest-value entrypoints in this module are:

  • build_legacy_01a_runtime_config() Build the typed runtime payload for one 01a FMU/code run, including VDYP cache path resolution. The field names still use the legacy tsa seam for compatibility.

  • build_legacy_01b_runtime_config() Build the typed runtime payload for one 01b post-TIPSY FMU/code run.

  • Legacy01ARuntimeConfig

  • Legacy01BRuntimeConfig

Core Contracts

The most important runtime contracts in this module are:

  • 01a payloads carry resolved checkpoint paths, TIPSY export prefixes, cache paths, sampling settings, and worker-count settings

  • 01b payloads intentionally stay smaller and focus on TIPSY params and output location semantics

  • 01a cache paths are derived through femic.pipeline.vdyp.build_vdyp_cache_paths() so the naming contract stays aligned with the VDYP stage

Failure Seams To Watch

The common failure boundaries in this module are:

  • stale anonymous-parameter assumptions if callers bypass these typed builders and pass ad hoc dictionaries, runtime drift becomes much harder to debug

  • cache-path mismatch 01a behavior depends on builder-aligned cache paths matching the VDYP stage’s expectations

  • field drift across stage boundaries because the legacy stage functions are still active, mismatched field meaning here can look like a failure in lower-level notebook-era code

Cross-References

Guides and references that pair especially closely with this module:

Related API pages:

Typed runtime payloads for legacy 00/01a/01b orchestration.

class femic.pipeline.legacy_runtime.Legacy01ARuntimeConfig(resume_effective, force_run_vdyp, kwarg_overrides_for_tsa, vdyp_results_pickle_path, vdyp_input_pandl_path, vdyp_ply_feather_path, vdyp_lyr_feather_path, tipsy_params_columns, tipsy_params_path_prefix, vdyp_cache_paths, parallel_worker_count=1, vdyp_out_cache=None, curve_fit_impl=None, target_area_coverage=None, target_nstrata=None, vdyp_sampling_mode='auto', vdyp_two_pass_rebin=False, min_stands_per_si_bin=25, force_tail_blend_candidate=False, enable_late_gate_rescue=True)[source]

Bases: object

Runtime payload passed from 00_data-prep.py into 01a_run-tsa.py.

Parameters:

  • resume_effective (bool)

  • force_run_vdyp (bool)

  • kwarg_overrides_for_tsa (dict[str, dict[str, Any]] | None)

  • vdyp_results_pickle_path (str | Path)

  • vdyp_input_pandl_path (str | Path)

  • vdyp_ply_feather_path (str | Path)

  • vdyp_lyr_feather_path (str | Path)

  • tipsy_params_columns (Sequence[str])

  • tipsy_params_path_prefix (str | Path)

  • vdyp_cache_paths (Mapping[str, Path])

  • parallel_worker_count (int)

  • vdyp_out_cache (dict[str, Any] | None)

  • curve_fit_impl (Any)

  • target_area_coverage (float | None)

  • target_nstrata (int | None)

  • vdyp_sampling_mode (str | int)

  • vdyp_two_pass_rebin (bool)

  • min_stands_per_si_bin (int)

  • force_tail_blend_candidate (bool)

  • enable_late_gate_rescue (bool)

curve_fit_impl: Any = None
enable_late_gate_rescue: bool = True
force_run_vdyp: bool
force_tail_blend_candidate: bool = False
kwarg_overrides_for_tsa: dict[str, dict[str, Any]] | None
min_stands_per_si_bin: int = 25
parallel_worker_count: int = 1
resume_effective: bool
target_area_coverage: float | None = None
target_nstrata: int | None = None
tipsy_params_columns: Sequence[str]
tipsy_params_path_prefix: str | Path
vdyp_cache_paths: Mapping[str, Path]
vdyp_input_pandl_path: str | Path
vdyp_lyr_feather_path: str | Path
vdyp_out_cache: dict[str, Any] | None = None
vdyp_ply_feather_path: str | Path
vdyp_results_pickle_path: str | Path
vdyp_sampling_mode: str | int = 'auto'
vdyp_two_pass_rebin: bool = False
class femic.pipeline.legacy_runtime.Legacy01BRuntimeConfig(tipsy_params_path_prefix, tipsy_output_root, tipsy_input_filename_template='03_input-tsa{tsa}.csv', tipsy_output_filename_template='04_output-tsa{tsa}.csv')[source]

Bases: object

Runtime payload passed from 00_data-prep.py into 01b_run-tsa.py.

Parameters:

  • tipsy_params_path_prefix (str | Path)

  • tipsy_output_root (str | Path)

  • tipsy_input_filename_template (str)

  • tipsy_output_filename_template (str)

tipsy_input_filename_template: str = '03_input-tsa{tsa}.csv'
tipsy_output_filename_template: str = '04_output-tsa{tsa}.csv'
tipsy_output_root: str | Path
tipsy_params_path_prefix: str | Path
femic.pipeline.legacy_runtime.build_legacy_01a_runtime_config(*, tsa_code, resume_effective, force_run_vdyp, kwarg_overrides_for_tsa, vdyp_results_pickle_path, vdyp_input_pandl_path, vdyp_ply_feather_path, vdyp_lyr_feather_path, tipsy_params_columns, tipsy_params_path_prefix, vdyp_results_tsa_pickle_path_prefix, vdyp_curves_smooth_tsa_feather_path_prefix, parallel_worker_count=1, vdyp_out_cache=None, curve_fit_impl=None, target_area_coverage=None, target_nstrata=None, vdyp_sampling_mode='auto', vdyp_two_pass_rebin=False, min_stands_per_si_bin=25, force_tail_blend_candidate=False, enable_late_gate_rescue=True)[source]

Build typed runtime config payload for a single 01a TSA run.

Parameters:

  • tsa_code (str)

  • resume_effective (bool)

  • force_run_vdyp (bool)

  • kwarg_overrides_for_tsa (dict[str, dict[str, Any]] | None)

  • vdyp_results_pickle_path (str | Path)

  • vdyp_input_pandl_path (str | Path)

  • vdyp_ply_feather_path (str | Path)

  • vdyp_lyr_feather_path (str | Path)

  • tipsy_params_columns (Sequence[str])

  • tipsy_params_path_prefix (str | Path)

  • vdyp_results_tsa_pickle_path_prefix (str | Path)

  • vdyp_curves_smooth_tsa_feather_path_prefix (str | Path)

  • parallel_worker_count (int)

  • vdyp_out_cache (dict[str, Any] | None)

  • curve_fit_impl (Any)

  • target_area_coverage (float | None)

  • target_nstrata (int | None)

  • vdyp_sampling_mode (str | int)

  • vdyp_two_pass_rebin (bool)

  • min_stands_per_si_bin (int)

  • force_tail_blend_candidate (bool)

  • enable_late_gate_rescue (bool)

Return type:

Legacy01ARuntimeConfig

femic.pipeline.legacy_runtime.build_legacy_01b_runtime_config(*, tipsy_params_path_prefix, tipsy_output_root='data', tipsy_input_filename_template='03_input-tsa{tsa}.csv', tipsy_output_filename_template='04_output-tsa{tsa}.csv')[source]

Build typed runtime config payload for a single 01b TSA run.

Parameters:

  • tipsy_params_path_prefix (str | Path)

  • tipsy_output_root (str | Path)

  • tipsy_input_filename_template (str)

  • tipsy_output_filename_template (str)

Return type:

Legacy01BRuntimeConfig