Soil-profile application and GUI API¶
neptoon.soil_profile.application is the orchestration boundary for interactive
applications. It composes the existing preflight planner, stable sparse-profile
service, optional CRNS-constrained runner, diagnostics and parameter-estimation
contracts without changing model physics.
Use this layer when a GUI or service needs structured state instead of parsing logs or private DataFrames.
Typical workflow¶
from neptoon.soil_profile import (
ProfileInputColumns,
SoilProfileCancellationToken,
SoilProfileController,
SparseProfileRequest,
)
controller = SoilProfileController()
request = SparseProfileRequest(
latitude_deg=50.8,
sensor_columns={10.0: "sm10"},
input_columns=ProfileInputColumns(
temperature_mean="temperature",
precipitation="precipitation_mm",
),
)
session = controller.prepare(frame, request)
issues = controller.validate(session)
capabilities = controller.capabilities(session)
preview = controller.preview(session)
estimate = controller.estimate_run(session)
cancel = SoilProfileCancellationToken()
outcome = controller.run(
session,
cancellation_token=cancel,
progress_callback=lambda event: print(event.stage, event.fraction),
output_directory="outputs/run-001",
)
prepare() does not run the model. It exposes planner blockers/warnings,
capabilities and pending scientific decisions first. The default session uses
the planner-recommended physically complete window; a caller can explicitly
select the full record with session.select_window("full_record"). That choice
is recorded in the run manifest.
Stable application contracts¶
Application facade for planning, validation, execution and GUI diagnostics.
The controller never changes model physics or silently accepts diagnostic
recommendations. It composes existing public soil-profile contracts, records
planner decisions in a manifest, translates progress dictionaries into stable
events, and converts expected failures/cancellation into structured outcomes.
Unexpected :class:NeptoonInternalError instances still propagate with their
original chained traceback so application adapters do not hide programming
defects.
prepare ¶
prepare(data, request, *, execution_mode='auto', crns_options=None, planning_options=None, dwd_catalog=None, window_mode='recommended')
Prepare one run without executing the scientific reconstruction.
Planning remains non-mutating. The returned session contains structured
issues, capabilities and pending decisions suitable for GUI controls.
window_mode='recommended' selects the planner's longest physically
complete window; callers can switch to full_record explicitly before
execution and that choice is captured in the run manifest.
capabilities ¶
Return feature availability for enabling/disabling GUI controls.
estimate_run ¶
Return a cheap, explicitly lower-bound resource estimate for UI warnings.
run ¶
run(session, *, progress_callback=None, status_callback=None, cancellation_token=None, output_directory=None)
Execute one soil-profile run inside a stable user-status operation.
configuration_schema
staticmethod
¶
Return high-level request metadata suitable for generated GUI forms.
Cheap pre-run size estimate for interactive resource warnings.
raw_state_memory_mb estimates only the dense daily ensemble state array
(days × layers × ensemble members × float64). It is intentionally labelled
as a lower bound and is not a runtime or peak-memory promise.
Frontend-neutral plot-data facade over a completed profile result.
High-level optional controls for an experimental CRNS-constrained GUI run.
The application layer keeps the experimental objects opaque so importing the
stable application API does not enable or initialise experimental soil-model
access. They are passed through only when execution_mode resolves to
crns_constrained.
Progress and cancellation¶
The controller translates the model's committed-day progress dictionaries into
SoilProfileProgressEvent. It can additionally publish the same progress through
the common status_callback as operation soil_profile.reconstruction, so a GUI
can use one status contract for stationary, roving, download, and soil-profile
work. The fraction remains local to the reconstruction operation.
A broken GUI callback is logged and ignored so UI state cannot corrupt a
scientific run. Cooperative cancellation is checked before execution and after
model progress events and returns a structured CANCELLED outcome.
Cancellation is not a hard thread/process kill. It stops at model-safe callback boundaries and therefore preserves the scientific error boundary.
Run manifest¶
When output_directory is supplied, every completed, blocked, failed or
cancelled application run writes soil_profile_run_manifest.json. The manifest
contains:
- Neptoon version and application schema version;
- run ID and lifecycle timestamps;
- selected execution mode and run window;
- an SHA-256 content fingerprint plus input columns/row count, but not raw data;
- the high-level request and planner audit;
- capabilities, issues, pending decisions and automatic orchestration choices;
- compact result metadata or the structured public error.
A separate soil_profile_application_summary.json contains the latest depth,
water-balance, CRNS, parameter-estimation and diagnostic summary available from
the completed result.
GUI-generated forms¶
SoilProfileController.configuration_schema() exposes durable high-level fields
such as coordinates, profile depth, texture/bulk-density priors, adaptation
window and sensor mappings. It intentionally does not promote every private
numerical ProfileModelConfig field into a GUI compatibility promise. Expert
settings remain available through model_overrides.
Experimental CRNS runs¶
A GUI can opt into CRNS-constrained execution with
CRNSProfileApplicationOptions. Experimental modules are imported lazily only
when that execution path is actually run. The application layer does not silently
convert unsupported top-level Rosetta fraction priors; it blocks and asks the
caller to use depth-resolved hydraulic priors or a supported texture prior.