picurv_cli.core Namespace Reference

Data Structures
class	_LazyNumpyProxy
	Module-like proxy that preserves picurv.np without eager import. More...
class	CheckpointIndexWidthError
	A committed checkpoint written by a PETSc of the other index width than the driven solver's. More...
class	CommandExecutionError
	Raised when an external command exits unsuccessfully. More...
class	PlotDependencyError
	Raised when plot.gen reports a missing optional dependency. More...

Functions
	_prune_incompatible_python_site_paths (paths)
	Remove site-package paths for a different Python major/minor version.
	_drop_imported_package (str package_name)
	Remove a failed/partial import package tree from sys.modules.
	require_numpy ()
	Import NumPy only for commands that need numeric reductions.
	optional_matplotlib_pyplot ()
	Import matplotlib.pyplot lazily for study plot generation.
str	_read_release_version ()
	Read the single release version shared by every PICurv executable.
"str | None"	_git_output (*arguments)
	Run one git command in the source checkout.
dict	_source_build_identity (str release_version)
	Resolve reproducible release, commit, and dirty-tree build identity.
dict	picurv_build ()
	The conductor's own build identity, resolved on first use and kept for the process.
	_find_named_file_upwards (str start, str filename)
	Find a named file at or above an arbitrary filesystem anchor.
	find_workspace_root (*anchors)
	Locate the nearest initialized PICurv workspace for supplied anchors.
dict	load_workspace_config (str workspace_root)
	Load and validate the immutable workspace identity/configuration file.
dict	enforce_workspace_version (str workspace_root)
	Enforce an optional workspace PICurv version requirement.
dict	enforce_reproducibility_policy (str workspace_root)
	Enforce an optional workspace policy demanding a clean, released build.
str	resolve_workspace_path (str anchor_file, str candidate, *bool allow_external=False)
	Resolve a user path against its workspace and reject implicit escapes.
None	ensure_workspace_layout (str workspace_root)
	Materialize the uniform, cheap directory skeleton for one workspace.
str	initialize_workspace_root (str workspace_root, str template_name)
	Create the workspace skeleton and its identity file at one root.
None	ensure_run_layout (str run_dir)
	Materialize the uniform, cheap directory skeleton for one run.
tuple	validate_run_directory_structure (str run_dir)
	Refuse a run whose root has grown a directory the layout does not define.
None	enforce_run_directory_structure (str run_dir)
	Apply validate_run_directory_structure() as a refusal at run time.
str	case_run_label (dict case_cfg, str case_path)
	Resolve the stable human-facing portion of a generated run identifier.
str	allocate_generated_run_id (str runs_root, dict case_cfg, str case_path)
	Build the generated run identity, disambiguating a same-second collision.
bool	discard_unused_run_directory (str run_dir, *bool created, bool staged=False)
	Remove a generated run directory that never received any content.
	_file_sha256 (str path)
	Content digest of one file, or None when it cannot be read.
dict	build_software_lock ("str | None" run_dir=None)
	Capture the exact software identity a run is about to execute with.
dict	_toolchain_identity ()
	Best-effort record of the PETSc, MPI, and compiler in the shell staging the run.
str	write_software_lock (str run_dir)
	Write the run's software lock beside its asset lock.
str	workspace_artifact_root (str workspace_root, str kind)
	Return the canonical workspace-owned root for runs or studies.
	_relative_to_workspace (str path, str workspace_root)
	Return a portable workspace-relative path when possible.
dict	snapshot_run_configuration (str run_dir, dict source_paths, bool continuation=False)
	Snapshot editable YAML inputs without erasing prior continuation state.
dict	capture_continuation_records (str run_dir, str restart_dir)
	Save what a continuation's staging changes, so a refusal can undo it.
	restore_continuation_records (str run_dir, dict saved, str revision)
	Undo a refused continuation's staging: restore its records, drop its revision.
dict	load_active_run_configuration (str run_dir)
	Load the active immutable configuration revision for a run.
dict	load_run_executables (str run_dir)
	Return the executables a run is pinned to, as recorded by its active configuration.
str	run_executable_path ("str | None" run_dir, str name)
	Resolve the executable a run launches: its pinned copy, else the installation's.
dict	pin_run_executables (str run_dir, str revision)
	Copy the installation's executables into a run's configuration revision.
dict	plan_run_executable_paths (str run_dir, args, "str | None" workspace_root)
	Predict, without writing, which executables staging would give a run.
bool	resolve_executable_pinning (args, "str | None" workspace_root)
	Decide whether staging pins the installation's executables into the run.
dict	apply_run_executable_pinning (str run_dir, str revision, args, "str | None" workspace_root)
	Pin, keep, or refuse the run's executables before anything records them.
dict	archive_active_generated_configuration (str run_dir, list paths)
	Preserve generated control sidecars beside a continuation's YAML revision.
dict	_run_component_states (str run_dir, dict stages_requested)
	Report each run component's home, retention class, and lifecycle state.
dict	build_run_lineage (str parent_run_dir, int checkpoint_step, *workspace_root=None, statistics_state=None, requested_source=None)
	Record which run and which checkpoint a branched run was started from.
dict	build_run_manifest (str run_dir, str run_id, *workspace_root=None, str launch_mode="local", int num_procs=1, int post_num_procs=1, stages_requested=None, stages_completed=None, inputs=None, asset_lock=None, submission=None, lineage=None, str artifact_type="run", study_id=None, case_id=None)
	Build the authoritative run identity, topology, and lifecycle manifest.
	_recorded_run_root (str run_dir)
	Return the location a run's generated files refer to.
int	adopt_relocated_artifact (str root, str kind="run", bool dry_run=False)
	Point a moved run's or study's generated files at where it now lives.
str	_checkpoint_bundle_path (str source_dir, int step)
	Resolve a run/output root or an exact checkpoint bundle.
dict	_read_checkpoint_options (str metadata_path)
	Parse the deliberately small PETSc-options checkpoint manifest.
dict	validate_committed_checkpoint (str source_dir, int step, bool require_particles=False)
	Validate one committed bundle using the same manifest contract as C.
"set[int]"	_scan_committed_checkpoint_steps (str source_dir, bool require_particles=False)
	Return only fully validated, committed checkpoint steps.
int	parse_slurm_time_limit_to_seconds (str time_text)
	Parse a Slurm time-limit string into total seconds.
"dict | None"	resolve_walltime_guard_policy ("dict | None" cluster_cfg)
	Resolve the effective Slurm walltime-guard policy for generated solver jobs.
dict	build_walltime_guard_exports ("dict | None" cluster_cfg)
	Build shell-evaluated environment exports for the runtime walltime guard.
str	resolve_runtime_executable (str executable_name)
	Resolve solver/post executable path, preferring local sibling binaries.
"dict | None"	_parse_binary_petsc_line (str line)
	Parse the PETSc build line a native executable reports.
"dict | None"	read_binary_petsc_stamp (str executable_path)
	Read the PETSc build stamp from an executable's bytes, without running it.
"str | None"	resolved_petsc_library (str executable_path)
	The PETSc shared library the dynamic loader would give this executable when picurv launches it.
bool	petsc_library_mismatch ("dict | None" petsc, "str | None" library)
	Whether the library the loader resolves lies outside the PETSc the binary was built against.
"dict | None"	_read_binary_build_stamp (str executable_path)
	Read the build identity stamped into an executable's bytes, without running it.
dict	read_binary_build_identity (str executable_path)
	Read the build identity a native executable was compiled with.
dict	runtime_build_identities ("dict | None" source_identity=None, "str | None" run_dir=None)
	Read the build identity of every native executable a run would launch.
str	rebuild_command (str name, dict identity)
	The command that rebuilds one native executable.
list	build_identity_problems (dict identities, workspace_requirement=None, "dict | None" source_identity=None)
	Report every reason the active build identity is not internally coherent.
list	warn_on_stale_runtime_binaries (dict identities)
	Report native executables whose build identity is not the active source.
str	_sanitize_error_field (value)
	Normalize error fields into a single-line string.
	emit_structured_error (str code, str key="-", str file_path="-", str message="", str hint=None, stream=None)
	Emit one standardized error line for tooling and users.
	fail_cli_usage (str message, str hint=None)
	Emit a structured CLI usage error and exit with code 2.
	_split_error_file_and_message (str raw_error)
	Separate a validation error into its source-file and message fields when possible.
str	_extract_key_path (str message)
	Best-effort key-path extraction from free-form validation messages.
str	_classify_error_code (str message)
	Map existing validation/error messages to the standardized code set.
dict	read_yaml_file (str filepath)
	Safely reads a YAML file and returns its content.
	write_yaml_file (str filepath, dict data)
	Write YAML with stable ordering for generated study artifacts.
	write_json_file (str filepath, dict payload)
	Write JSON metadata/manifests with a stable, readable format.
str	write_runtime_execution_file (str filepath, str template_source_path=None)
	Write a default runtime execution config, copying a source template when available.
bool	_launcher_arg_contains_whitespace (token)
	Return True when a launcher arg token contains embedded whitespace and should be split.
"str | None"	resolve_runtime_execution_seed_source (str source_project_root)
	Prefer repo-local ignored runtime config, then tracked example, then built-in defaults.
dict	ensure_case_runtime_execution_config (str case_dir, str source_project_root, bool overwrite=False)
	Create case-local runtime execution config if missing, seeded from repo-local config when available.
bool	is_project_root (str candidate)
	Return True when a directory looks like the PICurv source repository root.
	_iter_parent_dirs (str start_path)
	Yield a path and all of its parents up to filesystem root.
	find_project_root_upwards (str start_path)
	Search upward from an anchor and return the first matching project root.
	discover_local_project_root (*extra_anchors)
	Best-effort source repo discovery from runtime anchors.
	find_case_origin_metadata_file (str case_dir_hint=None)
	Find the nearest case-origin metadata file from known runtime anchors.
	load_case_origin_metadata (str case_dir_hint=None)
	Load case-origin metadata if present, returning (case_dir, metadata_path, payload).
	find_runtime_execution_config_file (*anchors)
	Find the nearest optional execution config from runtime/case anchors.
dict	_normalize_execution_override_section (dict payload, str section_name, str config_path, str config_label)
	Validate one execution override section while preserving missing-vs-empty semantics.
	load_runtime_execution_config (str config_search_anchor=None, extra_search_anchors=None)
	Load optional shared execution launcher config from the nearest runtime config file.
dict	merge_execution_overrides ("dict | None" base, "dict | None" override)
	Merge execution overrides, letting explicit override values win key-by-key.
dict	resolve_runtime_execution_context (dict runtime_execution_cfg, str context)
	Resolve default plus context-specific execution overrides.
str	get_git_commit (str repo_root=None)
	Best-effort git commit lookup for run/study manifests and case metadata.
	write_case_origin_metadata (str case_dir, str source_project_root, str template_name=None, dict existing=None, template_managed_files=None)
	Create or refresh case-origin metadata for repo-aware case maintenance commands.
bool	make_args_include_explicit_goal ("list[str]" make_args)
	Return True when make args contain an explicit target rather than only options/assignments.
	resolve_case_origin_context (str case_dir_hint=None, str source_root_override=None, str template_name_override=None)
	Resolve case directory, source repo root, and optional template metadata.
	require_project_root (str candidate, str purpose)
	Validate that a source repo root was resolved and is structurally valid.
	require_existing_case_dir (str case_dir, str purpose, str source_project_root=None)
	Validate that a target case directory exists and is not the source repo root.
	resolve_template_directory (str source_project_root, str template_name)
	Resolve an example template directory inside the source repository.
	list_template_relative_files (str template_dir, excluded_rel_paths=None)
	List all files in a template directory as case-relative paths.
dict	render_template_workspace (str template_dir, str template_name, str destination)
	Render an example template into the canonical workspace layout at a new path.
list	list_rendered_template_files (str rendered_root)
	List the template-managed files of a rendered workspace, workspace-relative.
	list_source_binaries (str source_project_root)
	List binary artifacts currently available in the source repo bin directory.
	sync_case_binaries (str case_dir, str source_project_root)
	Copy current source-repo binaries into a case directory for version-pinning.
	sync_case_template_files (str case_dir, str template_dir, bool overwrite=False, bool prune=False, managed_rel_paths=None, str template_name=None)
	Sync template files into a case directory, preserving modified files unless overwrite is requested.
	compute_case_source_status (str case_dir, str source_project_root, str template_name=None, dict metadata=None)
	Compute source/case drift across commits, binaries, and template-managed files.
	print_case_source_status (dict status)
	Render human-readable source/case drift details.
	status_source_command (args)
	Report source/case drift for an initialized case directory.
str	resolve_path (str anchor_file, str candidate)
	Resolve a potentially relative path against a source YAML file path.
	_mapping_value_with_aliases (dict mapping, *keys, default=None)
	Return the first defined value from a mapping across alias keys.
	get_post_run_control_value (dict post_cfg, str canonical_key, default=None)
	Resolve post run_control values with backwards-compatible legacy aliases.
None	warn_on_grid_generator_hyphen_keys (dict generator, str case_path, list warnings)
	Warn when grid.generator uses unsupported hyphenated wrapper keys.
str	retired_destination_message (str label, str key)
	Explain why a generator may not choose its own output destination.
list	reject_generator_destination_keys (generator, str case_path, str label)
	Reject generator settings that try to choose their own output destination.
	get_post_source_data (dict post_cfg)
	Return source_data as a mapping when valid, else an empty mapping.
str	get_post_source_directory_template (dict post_cfg, str default="<solver_output_dir>")
	Resolve the source directory template from source_data with a safe default.
	get_post_input_extensions (dict post_cfg)
	Return post input_extensions, preferring io.
	get_post_statistics_task_tokens (dict post_cfg)
	Return normalized statistics pipeline tokens that will be written into post.run.
str	get_monitor_output_directory (dict monitor_cfg, str default="output")
	Resolve the solver output root from monitor.yml, preserving the default layout.
str	get_post_statistics_output_prefix (dict post_cfg, str default="Stats")
	Resolve the statistics CSV prefix, preserving legacy top-level override support.
str	resolve_post_statistics_output_prefix (dict post_cfg, monitor_cfg=None, str default="Stats")
	Resolve the runtime statistics prefix, routing bare basenames under the monitor output root.
	get_post_statistics_output_artifacts (dict post_cfg, str run_dir, monitor_cfg=None)
	Predict statistics CSV output paths relative to the postprocessor runtime cwd.
dict	resolve_scalar_transport (dict case_cfg, dict solver_cfg, bool warn=False)
	Resolve the scalar-transport parameters from case.yml or their deprecated location.
dict	normalize_post_spectra_config (dict post_cfg)
	Validate and canonicalize the spectra block of post.yml.
list	validate_post_spectra_preconditions (dict spectra_cfg, dict case_cfg, str post_path)
	Check spectra tasks against what the case can actually support.
str	_resolve_spectra_payload (dict bundle, str kind, str field, int block)
	Locate one checkpoint payload by its inventory entry rather than by path shape.
list	_spectra_mean_arguments (dict task_cfg, dict bundle, dict mean_bundle=None)
	Build the generator arguments implementing a task's fluctuation choice.
set	resolve_post_stage_selection (only)
	Resolve the --only selector into the set of post stages to execute.
dict	run_post_spectra_stage (str run_dir, dict post_cfg, dict monitor_cfg, str source_dir, steps, bool quiet=False, "dict | None" plan=None, bool recompute=False)
	Measure spectra for every requested task across a window of committed steps.
dict	normalize_post_reducers_config (dict post_cfg)
	Validate and canonicalize the reducers block of post.yml.
list	run_post_reducers_stage (str run_dir, dict post_cfg, bool quiet=False)
	Run every reducer task over the profiles the recipe has written.
list	_merge_spectra_rows (str path, tuple fieldnames, set remeasured, list new_rows)
	Combine newly measured spectra rows with those already written for other steps.
str	compute_post_spectra_signature (dict spectra_cfg)
	Reduce a normalized spectra recipe to a stable identity string.
str	resolve_post_spectra_output_dir (monitor_cfg=None)
	Resolve the run-relative directory spectra CSVs are written to.
str	resolve_recipe_spectra_output_dir (dict post_cfg, monitor_cfg=None)
	Resolve the canonical spectra directory for one versioned recipe.
list	get_post_spectra_output_artifacts (dict post_cfg, str run_dir, monitor_cfg=None)
	Predict the spectra CSV paths a recipe will write.
str	post_spectra_task_basename (dict task_cfg, str output_prefix)
	Build the file basename one normalized spectra task writes.
list	_normalize_post_statistics_ensembles (raw)
	Validate and canonicalize the ensembles a post recipe defines.
dict	normalize_post_field_statistics_config (dict post_cfg)
	Validate and canonicalize the field_statistics block of post.yml.
int	_post_window_derived_field_count (dict window_cfg, list outputs, dict eligible=None)
	Count the derived fields one window would produce for a set of outputs.
bool	_post_requests_field_statistics (dict post_cfg)
	Return whether the current post recipe derives accumulated field statistics.
	get_post_field_statistics_artifacts (dict post_cfg, str run_dir)
	Predict the per-window statistics artifacts a recipe will produce.
dict	build_post_recipe_config (dict post_cfg, monitor_cfg=None)
	Build the flat key=value mapping consumed by the C post-processor.
str	compute_post_recipe_id (dict post_cfg)
	Compute a stable human-readable identity for one post recipe.
"tuple[dict, str]"	apply_canonical_post_paths (dict post_cfg, str run_dir)
	Route every post artifact into its fixed analysis or visualization home.
dict	normalize_post_recipe_signature (dict recipe_cfg)
	Normalize post recipe settings into a stable signature mapping.
"tuple[dict, str]"	compute_post_recipe_fingerprint (dict recipe_cfg)
	Return normalized recipe signature plus SHA-256 fingerprint.
str	get_post_resume_state_path (str run_dir, dict post_cfg=None)
	Return the JSON resume metadata path for a run directory.
str	get_post_recipe_root (str run_dir, dict post_cfg)
	Return the versioned run-local control directory for one post recipe.
dict	get_post_lock_paths (str run_dir, str recipe_id=None)
	Return lock-wrapper related paths for a run directory.
str	_post_output_directory_abs (str run_dir, dict post_cfg)
	Resolve the absolute post output directory for the current recipe.
bool	_post_requests_eulerian_output (dict post_cfg)
	Return whether the current post recipe expects Eulerian VTK output artifacts.
bool	_post_requests_particle_output (dict post_cfg)
	Return whether the current post recipe expects particle VTP output artifacts.
dict	normalize_post_paraview_series_config (dict post_cfg)
	Normalize the optional ParaView collection policy in a post recipe.
str	_resolve_lineage_parent_run (str child_run_dir, dict lineage)
	Resolve and identity-check one recorded lineage parent.
list	resolve_run_lineage (str run_dir, str scope="lineage")
	Return root-to-leaf run segments, for a ParaView collection or a reducer's metrics.
dict	_existing_pvd_times (str pvd_path)
	Read step-to-time fallbacks from an existing PVD collection.
float	_checkpoint_time_for_series (str run_dir, int step, dict fallback, float time_scale=1.0)
	Read the authoritative time of one visualization frame.
None	_write_pvd_collection (str path, list entries)
	Atomically write one VTK Collection file.
int	_lineage_reset_index (list segments, str family)
	Return the first segment belonging to one continuous artifact family.
list	finalize_post_paraview_series (str run_dir, dict post_cfg)
	Build physical-time ParaView collections from current or lineage VTK output.
str	_post_finalize_python_source ()
	Return the importable serial finalizer used by generated jobs.
list	build_post_finalize_command (str run_dir, str archived_post_path, dict post_cfg, post_stages=POST_STAGE_NAMES)
	Build the serial post-success command for staged execution.
None	finalize_post_outputs (str run_dir, dict post_cfg, stages)
	Run every serial step that reads a successful field stage's output.
bool	_post_requests_statistics (dict post_cfg)
	Return whether the current post recipe expects statistics CSV artifacts.
bool	_post_needs_particle_source (dict post_cfg)
	Return whether the current post recipe requires particle source files to be present.
	_iter_post_steps (int start_step, int end_step, int step_interval)
	Yield configured post-processing steps inclusively.
"tuple[int, int, int]"	resolve_post_requested_window (dict post_cfg, dict case_cfg=None)
	Resolve post requested start/end/interval, expanding end=-1 via case.yml when available.
int	resolve_post_owned_start (str run_dir, dict post_cfg, int requested_start, int step_interval)
	Intersect a recipe's logical cadence with this run's branch.
dict	prepare_effective_post_config (dict post_cfg, str resolved_source_dir, int start_step=None, int end_step=None)
	Return a copy of post_cfg with resolved source dir and optional effective bounds.
"dict[int, str]"	_scan_post_vtk_steps (str prefix_path, str extension)
	Collect the VTK files named with a prefix, step suffix, and extension.
"set[int]"	_scan_post_statistics_csv_steps (str csv_path)
	Scan step ids from the first CSV column of a statistics artifact.
"list[tuple]"	collect_post_completion_families (str run_dir, dict post_cfg, monitor_cfg=None)
	Collect the output files each output family of the current recipe holds per step.
	_field_statistics_window_samples (str run_dir, int step)
	Read each field-statistics window's sample count from one committed checkpoint.
	post_step_outputs (str run_dir, dict post_cfg, monitor_cfg=None)
	Return a lookup of the output files one step of the current recipe holds.
	_nearest_step ("set[int]" steps, int target)
	Return the complete source step nearest to a target step.
str	_format_optional_step (step)
	Format an optional step number for user-facing diagnostics.
"tuple[set[int], dict]"	_scan_complete_source_steps (str source_dir, dict monitor_cfg, dict post_cfg)
	Scan source artifacts and return steps with every file required by the recipe.
"list[str]"	_expected_source_paths_for_step (int step, dict source_scan, dict post_cfg)
	Build required source file paths for a single post-processing step.
dict	detect_post_source_frontier (str source_dir, dict monitor_cfg, dict post_cfg, int start_step, int end_step, int step_interval)
	Detect the highest contiguous fully available source step for live post-processing.
"tuple[dict, dict]"	_read_post_records (str state_path)
	Read the per-step output records a recipe's state holds.
	persist_post_resume_state (str run_dir, dict plan, steps=None, spectra=None)
	Write a recipe's state: the window last planned and its per-step output records.
	_checkpoint_commit (str source_dir, int step)
	Identify one committed checkpoint by its commit marker.
"str | None"	classify_post_step (record, files, commit, str recipe, bool recompute=False)
	Decide whether one step's existing output is still valid.
None	warn_overlapping_post_recipes (str run_dir, dict post_cfg, dict plan, post_stages)
	Warn when another recipe in this run already produced outputs this one repeats.
str	_build_post_lock_wrapper_source ()
	Return the Python wrapper that runs one post job under an exclusive lock.
str	ensure_post_lock_wrapper (str run_dir)
	Ensure the lock wrapper exists for a run directory and return its path.
"tuple[list, dict]"	build_post_locked_command (str run_dir, str recipe_fingerprint, list wrapped_command, bool create_wrapper=True, "list | None" success_command=None, "str | None" post_recipe=None, "str | None" postprocessor=None, bool recompute=False)
	Wrap a postprocessor command behind the run-dir-scoped lock wrapper.
None	run_post_finalize_locked (str run_dir, str recipe_fingerprint, list finalize_command)
	Refresh a collection-only result under the ordinary post writer lock.
dict	build_post_execution_plan (str run_dir, str run_id, dict case_cfg, dict monitor_cfg, dict post_cfg, bool recompute=False, bool allow_source_frontier_scan=True, "str | None" postprocessor_sha=None)
	Decide which steps of a recipe's window one invocation processes.
None	report_post_plan (dict plan)
	Print which steps a post plan processes, keeps, and waits for.
str	get_post_step_list_path (str run_dir, dict post_cfg)
	Return the file naming the steps a launched post job processes.
"tuple[dict, dict, dict]"	_load_post_job_configs (str run_dir, str post_recipe_path)
	Load the configuration a post job needs from the run it runs in.
int	prepare_post_job (str run_dir, str post_recipe_path, str postprocessor, bool recompute=False)
	Decide, as a post job starts, which steps it processes.
int	finish_post_job (str run_dir, str post_recipe_path, bool exited_cleanly=False)
	Record, after a post job ends, which steps it produced.
bool	needs_restart_source (dict case_cfg, dict solver_cfg)
	Return True when the solver requires restart data from disk.
str	resolve_run_output_dir (str run_dir, dict monitor_cfg)
	Resolve the output data directory within a run directory.
str	resolve_run_restart_dir (str run_dir, dict monitor_cfg)
	Resolve the restart staging directory within a run directory.
str	compute_physical_case_identity (dict case_cfg)
	Compute the hidden identity used to guard in-place continuation.
None	validate_continue_case_identity (str run_dir, dict case_cfg)
	Reject in-place continuation when the physical case has changed.
	populate_restart_directory (str source_output, str target_restart, int start_step, dict monitor_cfg, "int | None" end_step=None, bool materialize=True)
	Atomically materialize an immutable checkpoint interval into a run.
	validate_eulerian_checkpoint (str source_dir, int step, dict monitor_cfg)
	Validate the mandatory Eulerian field set required by ReadSimulationFields().
	detect_last_checkpoint_step (str output_dir)
	Scan output directory for the highest step number available.
dict	detect_case_completion_status (str run_dir, dict monitor_cfg, int target_final_step)
	Determine whether a study case is complete, partially complete, or empty.
	validate_load_mode_step_range (str source_output, int start_step, int total_steps, dict monitor_cfg)
	Validate that all required eulerian step files exist for "load" mode.
	validate_particle_checkpoint (str source_dir, int start_step, dict monitor_cfg)
	Validate that particle checkpoint files exist for the given step.
dict	read_monitor_from_run (str run_dir)
	Read the monitor.yml from a run directory's config/ subdirectory.
str	resolve_latest_restart_run (dict case_cfg, str case_path, int start_step)
	Select the newest local workspace run compatible with a requested restart.
	resolve_restart_source (args, dict case_cfg, dict solver_cfg, dict monitor_cfg, str run_dir, bool materialize=True)
	Resolve the restart source directory based on –restart-from or –continue CLI flags.
	absolutize_case_external_paths (dict case_cfg, str case_anchor_path)
	Convert external grid/generator paths in case config to absolute paths.
	prepare_case_for_continuation (str run_dir, str case_id, int last_step, int target_final_step, dict cluster_cfg)
	Set up a partially-completed study case for continuation in-place.
bool	is_valid_email (str email)
	Lightweight email validation for scheduler notifications.
str	normalize_statistics_task (str task_name)
	Normalizes user-facing statistics task names to C pipeline keywords.
	_iter_nonempty_noncomment_lines (file_obj)
	Yield (lineno, stripped_line) for non-empty, non-comment lines.
str	format_picgrid_coordinate (float value)
	Format a coordinate with round-trip-safe binary64 precision.
dict	validate_and_nondimensionalize_picgrid (str source_grid, str dest_grid, float L_ref, int expected_nblk=None)
	Validates PICGRID payload and writes a non-dimensionalized copy.
list	read_picgrid_header_dimensions (str source_grid, int expected_nblk=None)
	Read only the canonical PICGRID header dimensions.
dict	validate_and_nondimensionalize_picslice (str source_slice, str dest_slice, float U_ref, tuple expected_dims=None)
	Validate a canonical PICSLICE payload and write a solver-scale copy.
str	_face_artifact_token (str face)
	Convert a BC face token into a filesystem-friendly artifact token.
str	_resolve_run_artifact_path (str run_dir, str configured_path, str default_path, bool default_to_config_dir=False)
	Resolve a run artifact path with run-dir-relative defaults.
str	_resolve_generator_script (str configured_script, str case_path, str default_name)
	Resolve an optional generator script override or repository default.
dict	_normalize_square_duct_poiseuille_params (params, str field_name)
	Validate square-duct Poiseuille generator parameters.
dict	_normalize_field_slice_source (source, str field_name)
	Validate a prescribed_flow field_slice source block.
dict	_normalize_field_slice_selector (slice_cfg, str field_name)
	Validate the field_slice slice selector.
dict	generate_square_duct_poiseuille_picslice (str output_path, tuple dims, dict params, str target_grid=None, int target_block=0, str target_face=None, str script=None, str case_path=None)
	Generate a dimensional canonical PICSLICE for square-duct Poiseuille flow.
dict	generate_field_slice_picslice (str output_path, tuple expected_dims, dict source, str target_grid, str target_face, int target_block, str case_path)
	Invoke profile.gen to extract a field_slice PICSLICE artifact.
str	_resolve_case_relative_path (str path_value, str case_dir)
	Resolve a path relative to the current case directory.
float	_resolve_field_slice_velocity_scale (dict source, str case_dir)
	Resolve field_slice dimensional velocity scale.
str	resolve_target_grid_for_field_slice (dict case_cfg, str case_path, str run_dir)
	Resolve the target canonical PICGRID path needed for field_slice normals.
str	resolve_target_grid_for_generated_profile (dict case_cfg, str case_path, str run_dir)
	Resolve the target canonical PICGRID for generated profile sampling.
str	write_profile_info (str config_dir, list summaries)
	Write a profile.info summary for generated inlet profiles.
list	validate_grid_generator_cli_args (cli_args, str case_path)
	Check closed-choice values inside the generator's opaque token list.
str	run_grid_generator (str case_path, str run_dir, dict grid_cfg, dict case_cfg=None)
	Runs generators/grid.gen to produce a PICGRID file for this run.
dict	_normalize_prescribed_flow_source (source, str field_name)
	Validate the structured source block for prescribed_flow BCs.
tuple	_bc_profile_expected_dims (str face, tuple block_dims)
	Return expected PICSLICE dimensions for a face and block node dimensions.
list	resolve_grid_block_dimensions_for_profiles (dict case_cfg, str case_path, str run_dir=None)
	Resolve per-block node dimensions for prescribed inlet profile validation.
list	materialize_generated_prescribed_flow_profiles (str run_dir, dict case_cfg, str case_path, list profile_grid_dims=None)
	Generate dimensional PICSLICE artifacts for generated/field_slice prescribed_flow sources.
float	_to_float (value, str field_name)
	Convert a YAML scalar to float with a clear error message.
float	_to_finite_float (value, str field_name)
	Convert a non-boolean YAML scalar to a finite float.
bool	_to_bool (value, str field_name)
	Convert a YAML scalar/string to bool with a clear error message.
	normalize_boundary_conditions_layout (all_blocks_bcs, int num_blocks)
	Normalize boundary_conditions to list-of-lists form and validate block count.
set	_les_periodic_axes (dict case_cfg)
	Reports which logical axes a case declares periodic on both faces.
	validate_wall_model_pairing (dict case_cfg, les_cfg, wall_cfg, str case_path, list errors, list warnings)
	Rejects wall-model selections that no turbulence treatment can support.
	_case_reynolds_number (dict case_cfg)
	Reynolds number implied by a case's scaling and fluid properties.
	validate_les_configuration (dict case_cfg, dict les_cfg, str case_path, list errors, list warnings)
	Checks the structured LES block for values the closure cannot honour.
	validate_and_prepare_boundary_conditions (dict case_cfg)
	Validate BC entries against currently supported C-side handlers/types and.
str	_schema_path_text (tuple path)
	Render an internal schema path tuple as a user-facing YAML path.
	_lookup_allowed_schema_keys (dict schema, tuple path)
	Return allowed keys for a path, honoring '*' dynamic mapping entries.
str	_schema_key_hint (dict schema, tuple path, str key, set allowed)
	Build a concise typo or hierarchy hint for an unsupported YAML key.
None	_validate_yaml_schema_keys (cfg, dict schema, str file_path, list errors, tuple path=())
	Reject unsupported YAML keys before they can be silently ignored by staging.
dict	_ensemble_source_fields (str source)
	Return the field table an ensemble of one source names its fields from.
tuple	input_quantity (tuple path)
	Return the (dimension, conversion site) recorded for one configuration input.
float	reference_scale (tuple dimension, dict scales)
	Return the factor that turns a physical quantity of this dimension into solver units.
float	input_reference_scale (tuple path, dict scales)
	Return the reference scale of one recorded input, for converting a whole payload.
	quantity_to_solver_units (value, tuple quantity, dict scales, str label)
	Convert a physical value, or a list of them, by one recorded quantity entry.
	to_solver_units (value, tuple path, dict scales)
	Convert one physical configuration value, or a list of them, to solver units.
dict	resolve_reference_scales (dict case_cfg)
	Resolve the reference length and velocity (and density, when given) of a case.
str	directory_value_charset_problem (str value)
	Describe why a directory value cannot be written to a PETSc options line.
str	classify_run_directory_value (value)
	Classify a configured run directory value.
str	normalized_run_directory (str value)
	Normalized, comparable form of a contained run directory value.
bool	paths_overlap (str first, str second)
	Whether two run-relative directories are the same or nested in one another.
tuple	resolve_unsafe_paths_override (dict dirs, str monitor_path)
	Resolve the unsafe-paths override, requiring a real YAML boolean.
tuple	evaluate_run_directories (dict values, bool override, set explicit=None)
	Apply every run-directory safety rule to a set of effective directory values.
list	classify_physical_containment (str run_dir, dict values)
	Classify where each run-owned directory physically lands.
list	check_physical_containment (str run_dir, dict values)
	Human-readable physical containment violations.
dict	effective_run_directories (dict configured)
	Fill in defaults for run-owned directories that were not configured.
tuple	validate_run_directory_containment (dict monitor_cfg, str monitor_path)
	Classify legacy directory values as defense-in-depth during validation.
list	validate_reserved_directory_flags (dict config, str config_path, str label)
	Reject raw PETSc passthrough options that set run-owned directories.
list	physical_units_transition_notices (dict case_cfg, dict solver_cfg, dict monitor_cfg)
	Name the inputs whose meaning changed when every input became physical.
	validate_simulation_configs (dict case_cfg, dict solver_cfg, dict monitor_cfg, str case_path, str solver_path, str monitor_path, bool restart_source_given=False)
	Validates every configuration a simulation run consumes, before any work is done.
"tuple[list, list]"	check_post_checkpoint_cadence_alignment (dict post_cfg, dict monitor_cfg, str post_path, str monitor_path="monitor.yml")
	Report post step selections that cannot land on a committed checkpoint.
	validate_post_config (dict post_cfg, str post_path, dict monitor_cfg=None, dict case_cfg=None)
	Validates the post-processing config before running the post-processor.
	validate_cluster_config (dict cluster_cfg, str cluster_path)
	Validate Slurm scheduler configuration from cluster.yml.
	validate_study_config (dict study_cfg, str study_path, bool skip_base_file_check=False)
	Validate sweep/study specification from study.yml.
	_deep_set (dict container, str dotted_path, value)
	Set nested dictionary value, creating intermediate maps when needed.
list	expand_parameter_matrix (dict parameters)
	Expand study parameter lists into cartesian-product combinations.
list	expand_study_parameter_combinations (dict study_cfg)
	Expand either cartesian-study parameters or explicit parameter sets.
dict	flatten_study_parameters (dict parameters)
	Flatten grouped study overrides into scalar dotted-path columns.
list	get_study_parameter_keys (dict study_cfg)
	Collect ordered parameter keys from either cross-product parameter expansions or explicit parameter sets.
int	get_cluster_total_tasks (dict cluster_cfg)
	Return cluster total tasks.
str	normalize_extension (str ext)
	Canonicalize a user-supplied filename extension by trimming whitespace and leading dots.
list	resolve_conductor_entry_point ()
	Resolve how to invoke this conductor again from a batch script.
list	build_spectra_follow_command (str run_dir, str post_path, dict post_cfg, bool recompute=False)
	Build the batch-script step that measures spectra after the field stage.
"str | None"	executable_petsc_library_dir (str executable_path)
	The lib/ directory of the PETSc an executable was built against, from its stamp.
list	petsc_library_path_lines ("str | None" library_dir)
	Shell lines putting one PETSc's lib/ first on LD_LIBRARY_PATH, after module setup.
list	executable_identity_check_lines (str executable, "str | None" expected_version_line, bool pinned=False)
	Shell lines that compare an executable's reported identity with the staged one.
	render_slurm_script (str script_path, str job_name, dict cluster_cfg, list command, str workdir, str stdout_path, str stderr_path=None, dict env_vars=None, dict shell_env_vars=None, str array_spec=None, list follow_commands=None, "tuple | None" identity_check=None)
	Render a Slurm batch script for a single command.
"tuple[str | None, list[str]]"	split_launcher_tokens ("str | None" launcher, "list | None" launcher_args=None, str label="launcher")
	Canonicalize launcher config into executable token plus argv-style flags.
"tuple[str | None, list[str]]"	normalize_cluster_launcher (dict execution)
	Canonicalize cluster launcher config into executable token plus argv-style flags.
"list[str]"	strip_launcher_size_flags (str launcher_name, "list[str]" launcher_args)
	Remove explicit MPI task-count flags from known launchers.
list	build_local_launch_command (str executable, list executable_args, int num_procs, str config_search_anchor=None, bool allow_single_rank_launcher_override=False, "int | None" force_num_procs=None)
	Build local launcher command, allowing env or shared config overrides for login-node MPI quirks.
dict	restart_grid_inputs (str run_dir, dict case_cfg)
	The inputs a run's geometry is derived from, to compare across a restart.
	warn_on_restart_grid_change (dict source_inputs, dict branch_inputs)
	Warn at staging when a restart's grid inputs differ from its source run's.
	check_restart_continuation (str solver_exe, list solver_args, str run_dir, str config_search_anchor=None)
	Ask the simulator whether a staged restart's carried statistics windows can continue.
dict	resolve_cluster_execution (dict cluster_cfg, str config_search_anchor=None, extra_search_anchors=None)
	Resolve cluster execution launcher settings from shared runtime config plus cluster.yml overrides.
list	build_cluster_launch_command (dict cluster_cfg, str executable, list executable_args, str config_search_anchor=None, extra_search_anchors=None, "int | None" force_num_procs=None)
	Build scheduler launcher command from cluster config plus optional shared execution defaults.
str	parse_slurm_job_id (str sbatch_output)
	Extract numeric job id from standard sbatch output.
"tuple[str, str | None]"	slurm_job_end_state (str job_id)
	Whether a recorded Slurm job (or array) is still queued, and how it ended if not.
dict	submit_sbatch (str script_path, str dependency=None, str dependency_type="afterok")
	Submit sbatch script and return submission metadata.
	_print_validation_errors (list errors)
	Prints validation errors and exits.
str	generate_header (str run_id, dict source_files)
	Creates a standard header block for all generated files.
str	generate_simple_list_file (str run_dir, str run_id, dict cfg, str section, str key, str filename, dict header_sources, str config_dir=None)
	Generic function to create a file containing a simple list of strings.
list	normalize_monitor_function_names (list names, str field_name)
	Translate renamed solver functions in a monitor.yml function list.
bool	has_explicit_monitor_whitelist (dict monitor_cfg)
	Return True when logging.enabled_functions contains at least one entry.
dict	resolve_profiling_config (dict monitor_cfg)
	Resolve profiling reporting config from monitor.yml.
dict	_diagnostic_info (value)
	Validate PETSc info logging configuration.
	_diagnostic_bool_or_path (value, str key)
	Validate a diagnostics value that can be false, true, or a path/viewer string.
bool	_diagnostic_bool (value, str key)
	Validate a diagnostics boolean value.
	_diagnostic_bool_or_all (value, str key)
	Validate a diagnostics value that can be false, true, or "all".
str	_diagnostic_default_file (str run_dir, str filename)
	Return an absolute run-local diagnostics file path.
	_diagnostic_resolve_path_or_default (value, str run_dir, str default_filename)
	Resolve true/string diagnostics values to a concrete file path.
dict	resolve_diagnostics_config (dict monitor_cfg, "str | None" run_dir=None, str stage_label="Solver")
	Resolve monitor diagnostics config and default run-local log paths.
list	build_petsc_diagnostics_args (dict monitor_cfg, str run_dir, str stage_label)
	Build PETSc diagnostics command-line arguments for a run stage.
bool	_statistics_subsystem_available (dict case_cfg, requirement)
	Report whether the subsystem a statistics field depends on is active.
dict	normalize_field_statistics_config (dict monitor_cfg, dict case_cfg=None)
	Validate and canonicalize the field-statistics block of monitor.yml.
	_normalize_statistics_requests (str label, fields_raw, covariances_raw, dict eligible, case_cfg=None)
	Validate and canonicalize the fields and covariances one window or ensemble requests.
list	resolve_field_statistics_flags (dict monitor_cfg, dict case_cfg=None)
	Serialize field-statistics configuration into control-file option lines.
"int | None"	resolve_statistics_console_output_frequency (dict io_cfg)
	Resolve the statistics console cadence, mirroring the particle one.
dict	normalize_solution_monitoring_config (dict monitor_cfg)
	Validate and canonicalize physical-solution convergence monitoring.
dict	resolve_solution_monitoring_flags (dict monitor_cfg)
	Translate solution-monitoring YAML into the existing C convergence flags.
dict	prepare_monitor_files (str run_dir, str run_id, dict monitor_cfg, dict source_files, str config_dir=None)
	Generate monitor sidecar files and resolve profiling reporting behavior.
list	generate_multi_block_bcs (str run_dir, str run_id, dict case_cfg, dict source_files, str config_dir=None)
	Parses multi-block BCs from YAML, generates a .run file for each block, and returns a list of their absolute paths.
	format_flag_value (value)
	Converts Python types to C-style command-line flag values.
dict	translate_programmatic_grid_settings (dict grid_settings)
	Return programmatic-grid settings translated to the C node-count contract.
None	validate_programmatic_bridge_grid_settings (dict raw_settings)
	Validate the scalar programmatic grid settings the bridge PICGRID is built from.
dict	generate_picgrid_from_programmatic_settings (dict raw_settings, str dest_path, float L_ref)
	Generate a canonical PICGRID file from programmatic Cartesian grid settings.
dict	resolve_grid_da_processor_layout (dict grid_cfg)
	Resolve optional global DMDA layout, preferring grid-level keys over legacy nested keys.
"list | None"	resolve_grid_node_dims (dict case_cfg, str case_path, "str | None" staged_grid=None)
	Per-block (IM, JM, KM) node counts the solver will read, without building the grid.
bool	case_declares_periodic_axis (dict case_cfg)
	Whether any face of any block is PERIODIC, which sets the DMDA stencil width.
list	da_processor_layout_problems (dict grid_cfg, "int | None" num_procs, "list | None" block_dims=None, "dict | None" solver_cfg=None, bool any_periodic=False, "str | None" source=None)
	Problems with a user-set DMDA layout that would abort grid setup.
None	normalize_decomposition_args (args)
	Resolve -n and the optional --ni/--nj/--nk of picurv run into one rank count.
dict	_decomposition_layout (layout)
	Express an (ni, nj, nk) tuple as the da_processors mapping the layout checks read.
	choose_decomposition (int num_procs, list block_dims, "dict | None" solver_cfg, bool any_periodic)
	Choose the MPI decomposition of a structured grid for a rank count.
dict	resolve_decomposition (int num_procs, dict grid_cfg, "list | None" block_dims, "dict | None" solver_cfg, bool any_periodic, explicit=None, "dict | None" cluster_cfg=None)
	Resolve the MPI decomposition a stage launches with.
"dict | None"	_decomposition_record ("dict | None" resolved)
	The JSON-serializable record of a resolved decomposition for run metadata.
str	describe_decomposition (dict resolved, int num_procs)
	One line stating the decomposition a stage launches with.
dict	append_grid_da_processor_layout (list control_lines, dict grid_cfg, int num_procs, "list | None" block_dims=None, "dict | None" solver_cfg=None, bool any_periodic=False, explicit=None, "dict | None" cluster_cfg=None)
	Resolve the solver's MPI decomposition, report it, and append its flags.
str	normalize_momentum_solver_type (str value)
	Maps canonical user-facing momentum solver names to C-enum CLI values.
dict	validate_newton_krylov_config (dict cfg)
	Validate and normalize the structured Newton–Krylov solver block.
str	normalize_solution_convergence_mode (str value)
	Normalizes the solution-convergence mode selector to the C-side canonical string.
int	normalize_field_init_mode (str value)
	Maps canonical field init mode names to C enum/int codes (-finit).
"tuple[str, int]"	normalize_initial_condition_field (str value)
	Normalize a file IC field selector to its staged basename and C enum value.
dict	resolve_ic_payload_provenance (dict ic, int field_code)
	Resolve which scales a file-backed initial condition was written in.
float	ic_payload_divisor (dict resolved_ic, str case_dir)
	Return the factor a file-backed initial condition is divided by when staged.
bool	is_generated_ic_provider (dict resolved_ic)
	Return whether a resolved IC is backed by a registered file generator.
dict	resolve_fluid_scaling (dict case_cfg)
	Resolve the shared physical and nondimensional fluid scaling contract.
	load_generator_module (str script_name, str module_name)
	Load one of the extensionless scripts under generators/ as a module.
	load_ic_generator_module ()
	Load generators/ic.gen, which owns the expression language and the IC providers.
list	normalize_particle_fields (fields_cfg)
	Validate models.physics.particles.fields and lower each value to expressions.
dict	ic_provider_params_to_solver_units (str generator, dict params, dict scales)
	Convert a provider's validated physical parameters to solver units.
dict	resolve_resampled_velocity_params (dict params, prepared_blocks, dict scales, provider_context=None)
	Validate resampled_velocity parameters and convert them to the provider contract.
	normalize_ic_initial_spectra (requested, excluded_axes, generator, required)
	Validate the spectra a structured IC provider measures on its own output.
dict	resolve_initial_condition_config (dict ic, prepared_blocks, dict scales, provider_context=None)
	Resolve legacy and structured initial-condition YAML into one launcher contract.
int	runtime_petsc_index_bytes ()
	Bytes of a PetscInt in the PETSc the solver this conductor drives was built on.
"int | None"	requested_petsc_index_bytes (args=None)
	The index width a command was told to use: --petsc-index-bits, else PICURV_PETSC_INDEX_BITS.
"tuple[int, str]"	required_petsc_index_bytes (dict case_cfg, str case_path, "dict | None" monitor_cfg, "str | None" staged_grid=None)
	The PetscInt width a new run needs, from its particle count and grid size.
"int | None"	checkpoint_source_petsc_index_bytes (str source_dir)
	PetscInt width the committed checkpoints under a run output root were written with.
int	select_petsc_index_bytes (int index_bytes, str reason)
	Make the current command drive the build of one PetscInt width.
int	select_run_petsc_index_bytes (args, dict case_cfg, str case_path, "dict | None" monitor_cfg, "str | None" restart_source_dir=None)
	Choose and select the PetscInt width a run's solve stage needs.
int	select_existing_run_petsc_index_bytes (str run_dir, args=None)
	Select the PetscInt width an existing run was staged with, for its later stages.
None	record_run_petsc_index_bytes (str run_dir)
	Record in config/active.json the PetscInt width the current command selected.
int	payload_petsc_index_bytes (str path)
	PetscInt width of a PETSc payload: as its checkpoint recorded it, else the driven solver's.
list	petsc_index_arguments (int index_bytes)
	Generator arguments naming a PetscInt width; none for PETSc's default 32-bit.
dict	validate_petsc_vec_binary (str path, "int | None" index_bytes=None)
	Validate the basic PETSc binary VecView envelope used by ReadFieldData.
dict	write_scaled_petsc_vec_binary (str source, str destination, float divisor)
	Copy a PETSc binary Vec, dividing every scalar by one factor.
	initial_condition_diagnostic_paths (run_dir, resolved_ic)
	Resolve spectral IC artifacts through the canonical run layout, also for dry runs.
str	run_initial_spectrum_generator (str field_path, str staged_grid, str spectrum_path, str case_dir, task_cfg=None)
	Measure the shell-averaged spectrum of a staged initial condition.
str	run_initial_condition_generator (str case_path, str run_dir, dict resolved_ic)
	Run the repository IC generator.
None	_check_file_ic_matches_grid (dict payload, str staged_grid, dict resolved_ic)
	Refuse a mode: file payload sized for another grid, and say what imports one.
dict	stage_initial_condition_file (str run_dir, str case_path, dict resolved_ic)
	Materialize and stage one file-backed IC in ReadFieldData's expected layout.
int	normalize_flow_direction_token (str value)
	Maps a face-token flow direction string to the C FlowDirection enum integer.
bool	_ic_has_inlet (prepared_blocks)
	Return True if any prepared BC block contains an INLET face.
dict	resolve_ic_cli_params (dict ic, int finit_code, prepared_blocks, dict scales)
	Resolve all IC parameters and return a dict of PETSc option values.
str	normalize_eulerian_field_source (str value)
	Normalizes the Eulerian field source selector to the C-side canonical string.
bool	initial_condition_is_authoritative (dict case_cfg, dict solver_cfg)
	Whether the configured initial condition is the field the solver starts from.
tuple	unused_asset_kinds (dict case_cfg, dict solver_cfg)
	Asset kinds a run with these configurations would build but never read.
str	normalize_analytical_type (str value)
	Normalizes the analytical solution selector to the C-side canonical string.
"tuple[float, float, float]"	parse_initial_velocity_components (dict initial_conditions, int finit_code, *bool require_explicit)
	Parse initial-condition velocity components with mode-aware defaults.
"str | None"	infer_unique_inlet_axis_from_prepared_bcs (list prepared_blocks)
	Infer the unique inlet axis across all blocks using C-side "primary inlet" ordering.
int	normalize_particle_init_mode (str value)
	Maps canonical particle init mode names to C enum/int codes (-pinit).
int	normalize_interpolation_method (str value)
	Maps interpolation method names to C enum/int codes (-interpolation_method).
int	normalize_les_model (value)
	Maps LES model selectors to C enum/int codes (-les).
int	normalize_les_test_filter (value)
	Maps LES test-filter kernel names to the C -les_test_filter_kernel flag.
int	normalize_les_filter_width (value)
	Maps LES grid-filter-width model names to the C -les_filter_width flag.
int	normalize_les_averaging_mode (value)
	Maps LES coefficient-averaging mode names to the C -les_averaging_mode flag.
int	normalize_les_clip_mode (value)
	Maps LES coefficient-limiting mode names to the C -les_clip_mode flag.
str	normalize_les_averaging_directions (value)
	Maps a list of homogeneous logical directions to the C flag's string form.
int	normalize_wall_function_model (value)
	Maps wall-function model selectors to the C -wallfunction flag.
bool	resolve_enabled_flag (dict cfg, str path, bool default=True)
	Resolves a structured enabled flag and rejects non-boolean values.
	append_les_parameter_flags (dict les_cfg, list control_lines)
	Appends the LES closure parameter flags from a structured les block.
"dict | None"	resolve_les_diagnostics (dict case_cfg, dict monitor_cfg, bool warn=False)
	Resolve the LES diagnostic log settings from monitor.yml or their deprecated location.
	append_les_diagnostics_flags ("dict | None" diagnostics, list control_lines)
	Append the LES diagnostic log flags resolved by resolve_les_diagnostics().
	append_turbulence_flags (dict models, list control_lines, dict scales=None)
	Appends turbulence model flags from legacy or structured case.yml blocks.
	control_value (value, str context)
	Guard a value that is written verbatim into the generated control file.
	append_passthrough_flags (list control_lines, dict options)
	Appends raw CLI flags to the control list from a {flag: value} dict.
dict	resolve_solver_monitoring_flags (dict monitor_cfg)
	Resolve human-readable solver monitoring YAML to raw control flags.
list	resolve_traced_particle_ids (dict monitor_cfg)
	Return the sorted, distinct particle IDs of logging.trace_particles.
"int | None"	resolve_particle_console_output_frequency (dict io_cfg)
	Return the effective particle-console snapshot cadence from monitor.yml.
	parse_and_add_model_flags (dict case_cfg, list control_lines)
	Parses the 'models' section of case.yml and adds corresponding C-solver flags.
dict	parse_solver_config (dict solver_cfg, dict scales=None, dict case_cfg=None)
	Parses the structured solver.yml into a flat dictionary of {flag: value}.
	generate_solver_control_file (run_dir, run_id, configs, num_procs, monitor_files, restart_source_dir=None, continue_mode=False, str config_dir=None)
	Generates the main .control file for the C-solver.
dict	resolve_post_decomposition (str run_dir, int num_procs, explicit=None, "dict | None" cluster_cfg=None)
	Resolve the postprocessor's MPI decomposition from the run's staged configuration.
str	generate_post_recipe_file (str run_dir, str run_id, dict post_cfg, dict source_files, monitor_cfg=None, "dict | None" decomposition=None)
	Generates a key=value config file (post.run) for the C post-processor.
	execute_command (list command, str run_dir, str log_filename, dict monitor_cfg=None)
	Executes a command, streaming its output to the console and a log file.
str	format_command_for_display (list command)
	Render a shell-safe command string for console and log output.
str	resolve_command_log_path (str run_dir, str log_filename)
	Resolve a command log filename relative to the run directory.
subprocess.CompletedProcess	_run_captured_command (list command, str run_dir)
	Run a command and capture combined stdout/stderr details for later inspection.
	_require_successful_command (list command, subprocess.CompletedProcess result)
	Raise CommandExecutionError when a captured command failed.
str	_capture_command_stdout (list command, str run_dir)
	Run a command, require success, and return stripped stdout text.
	_stream_command_to_console_and_log (list command, str run_dir, log_file)
	Stream command output to stdout and an already-open log file.
dict	_get_git_head_state (str run_dir)
	Capture the current git HEAD branch name and commit hash.
"list[tuple[str, str | None]]"	_get_local_branches_with_upstreams (str run_dir)
	Return local branch names plus their configured upstreams.
bool	_working_tree_has_tracked_changes (str run_dir)
	Return True when the repository has staged or unstaged tracked changes.
	_attempt_pull_cleanup (str run_dir, bool rebase, log_file)
	Best-effort cleanup after a failed git pull so the original branch can be restored.
	_restore_git_head (str run_dir, dict original_head, log_file)
	Restore the repository back to the branch or detached commit it started on.
None	_refuse_detached_source_checkout (str source_project_root, str action)
	Refuse a branch pull when the source checkout is pinned to a detached commit.
	pull_all_source_branches (str run_dir, str log_filename, bool rebase=True)
	Refresh every local tracking branch in the source repository, then restore the starting branch.
	auto_identify_run_inputs (str config_dir)
	Auto-detect case.yml, monitor.yml, and *.control in a run config directory.
str	resolve_post_source_directory (str run_dir, dict monitor_cfg, dict post_cfg, bool strict=True)
	Resolve post source directory token and optionally enforce existence.
	render_slurm_array_stage_script (str script_path, str job_name, dict cluster_cfg, str array_spec, str case_index_tsv, str stage, str solver_exe, str post_exe, str stdout_path, str stderr_path, "str | None" expected_version_line=None)
	Render array script that maps SLURM_ARRAY_TASK_ID to per-case run artifacts.
	render_metrics_aggregate_script (str script_path, str job_name, dict cluster_cfg, str study_dir, str picurv_path)
	Generate a single-node sbatch script that runs metrics aggregation.
	reduce_metric_values (values, str reduction)
	Reduce a metric series to one scalar according to the requested reducer.
	extract_metric_from_csv (str case_dir, dict spec)
	Extract a scalar metric from a CSV source.
	extract_metric_from_log (str case_dir, dict spec)
	Extract a scalar metric from a log file using regex.
	normalize_metric_spec (metric)
	Normalize study metric definitions to a common dictionary form.
dict	_read_previous_metric_rows (str results_dir)
	Read the metrics table an earlier aggregation wrote, keyed by case id.
str	aggregate_study_metrics (dict study_cfg, list cases, str results_dir)
	Collect metric values from generated case directories into one CSV.
str	_study_parameter_label (str key)
	Return a concise report label for a study parameter path.
str	_study_metric_label (dict study_cfg, str metric)
	Resolve an optional configured metric label or humanize its name.
"list | None"	_numeric_study_column (list rows, str key)
	Parse one complete, finite numeric study-table column.
"dict | None"	_infer_study_plot_axis (dict study_cfg, list rows)
	Infer the scientifically meaningful independent variable of a study.
	infer_plot_x_axis (dict study_cfg, list rows)
	Infer x-axis key/values for study plots.
str	_format_study_group_value (value)
	Format a secondary study parameter compactly for a legend.
list	_study_plot_groups (dict study_cfg, list rows, dict axis, str metric)
	Group metric points by any secondary varied study parameters.
bool	_study_use_log_scale (list values, bool semantic_hint=False)
	Use log scaling only for positive data spanning a meaningful range.
"tuple[float, float] | None"	_study_linear_y_limits (list values)
	Build padded linear limits that include zero for non-negative metrics.
	generate_study_plots (dict study_cfg, str metrics_csv, str plots_dir)
	Generate metric-vs-parameter plots for completed studies.
str	_command_to_string (list command_tokens)
	Render a command list as a shell-safe display string.
str	_resolve_post_source_directory_preview (str run_dir, dict monitor_cfg, dict post_cfg)
	Resolve post source directory without side effects or stdout/stderr output.
dict	build_run_dry_plan (args)
	Build a no-write execution plan for run --dry-run.
None	add_planned_grid_artifacts (dict plan, dict case_cfg, str run_dir)
	Add grid-mode-specific staged artifacts to a dry-run plan.
None	add_planned_profile_artifacts (dict plan, dict case_cfg, str run_dir)
	Add generated prescribed-flow profile artifacts to a dry-run plan.
None	add_planned_initial_condition_artifacts (dict plan, dict case_cfg, dict solver_cfg, str run_dir)
	Add authoritative file-backed initial-condition artifacts to a dry-run plan.
	render_run_dry_plan (dict plan, str output_format="text")
	Render dry-run plan in human or JSON format.
	validate_workflow (args)
	Implements picurv validate without launching solver/post workflows.
str	_asset_file_sha256 (str path)
	Hash an asset source or payload without loading it into memory.
str	_stable_mapping_sha256 (payload)
	Hash a JSON-compatible value with deterministic serialization.
dict	_provider_source_fingerprints (value, str case_path, str key="")
	Hash every existing file explicitly referenced by an asset provider.
dict	build_case_asset_graph (dict case_cfg, str case_path)
	Classify case inputs into precomputable or simulator-runtime providers.
list	_asset_selection (dict graph, requested=None, *bool precomputable_only=False)
	Resolve requested asset kinds plus dependency closure.
list	_asset_payload_files (str build_root, str kind)
	Enumerate canonical files belonging to one asset kind in a build tree.
dict	_build_selected_asset_payloads (str build_root, dict case_cfg, str case_path, list selected)
	Execute existing generators into one isolated run-like build tree.
dict	_picgrid_geometry_summary (str path)
	Read a canonical PICGRID and summarize what a user would want to check.
bool	_write_structured_grid_preview (str picgrid_path, str destination, dims)
	Write a single-block ASCII VTS preview of a staged PICGRID.
dict	_build_asset_inspection (str kind, str build_root, dict provider, list payload_files)
	Produce the inspection material published beside an asset's payload.
dict	_publish_asset_object (str workspace_root, str build_root, dict provider, list payload_files)
	Publish one immutable content-addressed asset object atomically.
str	_workspace_asset_set_name (str workspace_root, str case_path)
	Return a collision-free, readable mutable asset-set name.
str	_write_workspace_asset_set (str workspace_root, str case_path, dict graph, dict references)
	Atomically update the named asset set and workspace asset catalog.
dict	precompute_case_assets (str workspace_root, dict case_cfg, str case_path, requested=None, bool precomputable_only=False)
	Build and publish a selected deterministic asset dependency closure.
str	_workspace_asset_set_path (str workspace_root, str case_path)
	Return the mutable asset-set pointer associated with a case config name.
	_find_stored_asset (str workspace_root, dict provider)
	Find a published object built from exactly this provider's inputs.
dict	plan_run_assets (dict case_cfg, str case_path, skip_kinds=())
	Plan reuse/build/runtime actions for all configured run providers.
str	_materialize_asset_file (str source, str destination)
	Expose one immutable shared-asset file through reflink, hardlink, or copy.
dict	materialize_run_assets (str run_dir, dict case_cfg, str case_path, bool require_precomputed=False, bool fetch_missing=False, skip_kinds=())
	Resolve/build workspace assets and write the exact run input lock.
	precompute_workflow (args)
	Resolve, preflight, and atomically publish reusable workspace assets.
	run_workflow (args)
	Main orchestrator for the 'run' command (local and Slurm modes).
list	parse_case_index_tsv (str tsv_path)
	Parse a case_index.tsv file back into a list of case entry dicts.
dict	resolve_sweep_stage_executables (list run_dirs)
	Choose the executables an array stage launches for every member of a study.
	sweep_workflow (args)
	Study/sweep orchestration using Slurm job arrays.
	sweep_continue_workflow (args)
	Continue a partially-completed Slurm parameter sweep study.
	sweep_reaggregate_workflow (args)
	Re-run metrics aggregation and plot generation for an existing study.
	_read_yaml_if_exists (str filepath)
	Read YAML when present, otherwise return None.
	_read_json_if_exists (str filepath)
	Read JSON when present, otherwise return None.
	_parse_int_loose (value)
	Best-effort integer parsing for summary extraction.
	_parse_float_loose (value)
	Best-effort float parsing for summary extraction.
	_extract_numeric_tuple (str text)
	Extract a numeric tuple from a string like '(1, 2, 3)'.
dict	_build_summary_context (str run_dir)
	Resolve run-local config and artifact paths for summarize.
dict	_require_summary_config (dict context, str name)
	Return one explicitly requested copied config or fail with a structured error.
dict	_build_run_overview (dict context)
	Build timestep-independent run metadata for summarize.
dict	_summarize_turbulence (dict turbulence_cfg)
	Build compact turbulence and wall-model selections.
dict	_build_case_overview (dict context)
	Build a curated case.yml summary with useful derived quantities.
dict	_summary_scalar_transport (dict context, dict solver_cfg)
	Scalar-transport parameters as the run resolves them, wherever they are set.
dict	_build_solver_overview (dict context)
	Build a curated solver.yml summary with normalized selections.
dict	_build_monitor_overview (dict context)
	Build a curated monitor.yml summary with resolved defaults.
"tuple[dict, list[int]]"	_parse_continuity_metrics_log (str log_dir)
	Read the continuity record into rows by step (one per block) plus observed order.
"tuple[dict, list[int]]"	_parse_particle_metrics_log (str log_dir, str metrics_dir)
	Read the per-step particle record into rows by step plus observed order.
"tuple[dict, dict, list[int]]"	_parse_momentum_convergence_logs (str log_dir)
	Read the per-block momentum records (Picard history, Newton summary) into rows by step.
"tuple[dict, dict, list[int]]"	_parse_poisson_convergence_logs (str log_dir)
	Read the per-block Poisson histories into each step's last iteration.
"tuple[dict, list[int]]"	_parse_profiling_timestep_csv (str filepath)
	Parse profiling timestep CSV into latest rows by step plus observed order.
"tuple[dict, list[int], dict]"	_parse_runtime_memory_log (str filepath)
	Read the runtime memory record into rows by step and its final status.
"tuple[dict, list[int]]"	_parse_solution_convergence_log (str log_dir)
	Read the solution-convergence record into rows by step plus observed order.
"list[str]"	_find_solver_stream_log_candidates (str run_dir, str log_dir)
	Return plausible solver stream logs for local and Slurm runs.
dict	_parse_particle_snapshot_file (str filepath)
	Parse sampled particle snapshots from a solver stream log.
"int | None"	_find_previous_snapshot_step ("list[int]" snapshot_steps, int step)
	Return the nearest earlier snapshot step when available.
dict	_compute_particle_snapshot_delta ("list[dict]" current_rows, "list[dict]" previous_rows)
	Compute sampled deltas between two particle snapshot samples.
dict	_build_particle_snapshot_summary (str source, int step, "list[dict]" rows, int preview_rows, particle_console_output_freq, particle_log_interval, "int | None" previous_step=None, "list[dict] | None" previous_rows=None)
	Build sampled diagnostics for one particle console snapshot.
dict	_find_particle_snapshot_for_step (str run_dir, str log_dir, int step, int preview_rows, particle_console_output_freq, particle_log_interval)
	Locate and summarize a particle console snapshot for one step.
	_resolve_summary_step (requested_step, continuity_rows, particle_rows, momentum_rows, poisson_rows, profiling_rows, memory_rows=None, convergence_rows=None, step_orders=None, str selection_mode="latest")
	Select a step to summarize from available metric artifacts.
str	_format_summary_float (value, str spec=".6e", str missing="n/a")
	Format optional numeric values for summary text output.
float	_summary_source_mtime (paths)
	Return the newest modification time among one or more summary sources.
"list[list[int]]"	_order_summary_step_orders ("list[tuple[list[int], object]]" sources)
	Order observed step sequences by the recency of their source files.
dict	build_run_summary_payload (str run_dir, "int | None" step=None, int snapshot_rows=5, str selection_mode="latest")
	Build a read-only run-step summary from existing PICurv artifacts.
	render_run_summary (dict payload, str output_format="text")
	Render a run-step summary in human or JSON form.
str	_summary_display_value (value)
	Format one configuration-summary value for compact text output.
	_print_config_header (str title, "str | None" subtitle=None)
	Print a strong dashboard-style configuration summary header.
	_print_config_group (str title, list rows)
	Print an aligned configuration-summary field group.
list	_flatten_summary_mapping (dict mapping, str prefix="")
	Flatten nested summary mappings into readable dotted field rows.
	_render_run_overview_text (dict summary)
	Render run metadata as a compact dashboard.
	_render_case_summary_text (dict summary)
	Render the case summary as a glanceable simulation dashboard.
	_render_solver_summary_text (dict summary)
	Render the solver summary as a glanceable numerical-method dashboard.
	_render_monitor_summary_text (dict summary)
	Render the monitor summary as a glanceable observability dashboard.
	render_selected_summary (dict payload, str output_format="text")
	Render selected timestep-independent config views and optional health.
str	_humanize_plot_identifier (str value)
	Convert one machine-oriented identifier into a readable plot label.
str	_summary_field_label (str field)
	Return the report-facing label for one logged scalar field.
"float | None"	_summary_physical_time (dict context, dict record)
	Resolve a record's physical time from its artifact or copied case configuration.
	_read_runtime_diagnostics_csv (path)
	Yields (segment, row) for each data line of one of the solver's CSV records.
"str | None"	_log_family_path (str log_dir, str base)
	Return a solver record's CSV, or the text log an older run wrote instead.
"list[tuple[int, str]]"	_block_family_paths (str log_dir, *str bases)
	Return (block, path) for each per-block solver record, CSV preferred per block.
"tuple[str | None, list]"	_continuity_rows (str log_dir)
	Return the continuity record's path and its (segment, row) pairs.
"tuple[str | None, list]"	_particle_step_rows (str log_dir, str metrics_dir)
	Return the per-step particle record's path and its (segment, row) pairs.
"list[tuple[int, str, list]]"	_picard_history_rows (str log_dir)
	Return (block, path, [(segment, row)]) for each Picard momentum history.
"list[tuple[int, str, list]]"	_newton_history_rows (str log_dir)
	Return (block, path, [(segment, row)]) for each Newton iteration history.
"list[tuple[int, str, list]]"	_newton_summary_rows (str log_dir)
	Return (block, path, [(segment, row)]) for each Newton per-step summary.
"list[tuple[int, str, list]]"	_poisson_history_rows (str log_dir)
	Return (block, path, [(segment, row)]) for each Poisson iteration history.
list	_runtime_memory_rows (str path)
	Return the runtime memory record's (segment, row) pairs (CSV, or an older run's text log).
	_typed_csv_value (str text)
	Return a CSV cell as a float (written with a point or exponent), an int, or the text.
"tuple[str | None, list]"	_solution_convergence_rows (str log_dir)
	Return the solution-convergence record's path and its (segment, row) pairs.
	_append_summary_plot_record (list records, str source, step, str line, dict values, str source_path, int segment=0, dict coordinates=None)
	Append one numeric append-ordered record for summarize plotting.
bool	_is_summary_plot_continuation_marker (str line)
	Return whether a log line starts a new continuation segment.
list	_collect_summary_plot_records (dict context)
	Collect append-ordered numeric records from summarize-supported scalar logs.
list	_collect_spectra_plot_records (dict context)
	Collect the per-step scalar histories written by the spectra post stage.
list	_collect_profile_plot_records (dict context)
	Collect the profile histories the profile_series reducer wrote.
list	_build_summary_plot_catalog (list records)
	Build available qualified-series metadata from plot records.
list	_representative_indices (int count, int maximum=6)
	Select evenly distributed indices while always retaining both endpoints.
dict	_build_spectrum_plot_request (dict context, str task, bool reference, bool linear_y, "str | None" output_path)
	Build a plot.gen request drawing representative measured spectra.
dict	_build_summary_plot_request (dict context, list records, str series, "int | None" last_n, bool linear_y, "str | None" output_path)
	Build one normalized plot.gen request from collected summarize records.
	_render_summary_plot_catalog (list catalog, str output_format)
	Render available summarize plot-series metadata.
str	_summary_table_path (dict context, str name)
	Resolve a summarize --table name to the CSV it prints.
	_list_summary_tables (dict context, str output_format)
	Print the summarize --table names whose CSV this run has, with row counts.
	_render_summary_table (dict context, str name, last_n, columns, str output_format)
	Print the last rows of one of the run's CSV records as aligned columns (or JSON).
	_invoke_plot_gen (dict request)
	Invoke standalone plot.gen with one normalized request over stdin.
	summarize_workflow (args)
	Build and render a read-only health summary for a run step.
dict	_resolve_submission_target (str run_dir=None, str study_dir=None)
	Resolve a run/study submission target from explicit directory flags.
dict	_get_submission_stage_metadata (dict target_context, str stage_name)
	Return stored metadata for one staged submission target.
list	_get_recorded_submission_stages (dict target_context)
	Return stage names explicitly recorded in scheduler submission metadata.
str	_build_submit_missing_stage_hint (dict target_context, str requested_stage, list selected_stages)
	Build an actionable hint for requested submit stages missing from metadata.
	_set_submission_stage_metadata (dict target_context, str stage_name, dict stage_meta)
	Persist one stage's metadata back into the submission payload.
	_write_submission_target_metadata (dict target_context)
	Write updated submission metadata back to disk.
tuple	staged_control_directories (str control_path)
	Read run-owned directory values from a staged control file.
list	preflight_config_directories (str root_dir)
	Every config directory under a run or study root that may hold a control file.
tuple	preflight_staged_run_directories (str root_dir)
	Re-check run-directory safety against an already-staged run or study.
list	read_text_file_lines (str path)
	Read a text file into a list of lines.
	submit_staged_jobs (args)
	Submit previously staged Slurm artifacts from an existing run/study directory.
	submit_staged_local_run (args, dict target_context, list selected_stages)
	Execute previously staged local run commands from scheduler/submission.json.
	cancel_run_jobs (args)
	Cancel Slurm-submitted jobs for an existing run directory.
	_workspace_yaml_role (str path)
	Infer the owned workspace role of one copied YAML file.
	_rewrite_workspace_path_values (value, dict replacements)
	Rewrite copied template path scalars to workspace-root-relative homes.
	_choose_primary_workspace_role (list candidates, str role, str template_name)
	Select the canonical role file from a template that may carry variants.
dict	organize_initialized_workspace (str workspace_root, str template_name, str source_template_root=None)
	Convert a copied example into the canonical editable workspace layout.
dict	import_workspace_input (str workspace_root, str kind, str source, str name=None, str mode="copy")
	Explicitly import or register one workspace input.
	inputs_workflow (args)
	Handle explicit workspace input management.
	version_workflow (args)
	Report, and for the status action validate, the shared build identity.
None	_print_petsc_build (dict identity)
	Print the PETSc an executable was built against and the library it would load.
None	_require_clean_source_checkout (str action)
	Refuse version-changing Git operations in a dirty source checkout.
subprocess.CompletedProcess	_git_source_command (list arguments)
	Run a checked Git command against the active PICurv source checkout.
	source_workflow (args)
	Fetch source history without silently changing the active code.
	_workspace_requested_version (str workspace_root)
	Resolve an exact version requested by an initialized workspace.
	versions_workflow (args)
	List or activate a release using the existing source/build owners.
str	_resolve_version_ref (str version)
	Resolve a user-named version to a Git ref that exists in the source checkout.
	init_case (args)
	Implements the 'init' command.
	sync_case_config_command (args)
	Refresh template-managed config/docs files in a case directory.
	pull_source_repo (args)
	Refresh source branches in the repository resolved from a case directory.
	build_project (args)
	Implements the 'build' command.
None	run_project_make (str source_project_root, "list[str]" make_args)
	Run the project Makefile with caller-supplied arguments, defaulting to all.

Variables
	_package_parent = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
	_storage_module = importlib.import_module("picurv_cli.storage")
	StorageError = _storage_module.StorageError
	cold_study_members = _storage_module.cold_study_members
	restore_cold_study_members = _storage_module.restore_cold_study_members
	is_artifact_cold = _storage_module.is_artifact_cold
	read_artifact_identity = _storage_module.read_artifact_identity
	STORAGE_LOCK_FILENAME = _storage_module.STORAGE_LOCK_FILENAME
	STORAGE_STATE_FILENAME = _storage_module.STORAGE_STATE_FILENAME
	require_storage_payload_local = _storage_module.require_storage_payload_local
	runtime_stage_lock = _storage_module.runtime_stage_lock
	storage_state_summary = _storage_module.storage_state_summary
	_rebase_restored_text_paths = _storage_module._rebase_restored_text_paths
	_NUMPY_MODULE = None
	_MATPLOTLIB_PYPLOT = None
	np = _LazyNumpyProxy()
	PACKAGE_PATH = os.path.dirname(os.path.realpath(__file__))
	PACKAGE_PROJECT_ROOT = os.path.dirname(PACKAGE_PATH)
	INVOKED_SCRIPT_DIR
	SCRIPT_PATH
	PROJECT_ROOT = os.path.dirname(SCRIPT_PATH)
	GENERATORS_PATH = os.path.join(PACKAGE_PROJECT_ROOT, "generators")
	DEFAULT_BIN_DIR = SCRIPT_PATH
	VERSION_FILE = os.path.join(PACKAGE_PROJECT_ROOT, "VERSION")
str	PICURV_RELEASE_VERSION = _read_release_version()
str	CASE_ORIGIN_METADATA_FILENAME = ".picurv-origin.json"
str	WORKSPACE_CONFIG_FILENAME = ".picurv-workspace.yml"
int	WORKSPACE_SCHEMA_VERSION = 1
int	RUN_MANIFEST_SCHEMA_VERSION = 3
int	ASSET_MANIFEST_SCHEMA_VERSION = 1
int	ASSET_LOCK_SCHEMA_VERSION = 1
str	RUNTIME_EXECUTION_CONFIG_FILENAME = ".picurv-execution.yml"
str	LEGACY_LOCAL_RUNTIME_CONFIG_FILENAME = ".picurv-local.yml"
str	RUNTIME_EXECUTION_EXAMPLE_FILENAME = "execution.example.yml"
tuple	RUNTIME_EXECUTION_CONFIG_FILENAMES
str	DEFAULT_RUNTIME_EXECUTION_CONFIG_TEMPLATE
str	CLUSTER_TEMPLATE_PLACEHOLDER_ACCOUNT = "my_project_account"
str	CLUSTER_TEMPLATE_PLACEHOLDER_MAIL = "user@example.edu"
dict	DEFAULT_WALLTIME_GUARD_POLICY
str	WALLTIME_GUARD_ENV_JOB_START_EPOCH = "PICURV_JOB_START_EPOCH"
str	WALLTIME_GUARD_ENV_LIMIT_SECONDS = "PICURV_WALLTIME_LIMIT_SECONDS"
str	POST_RESUME_STATE_FILENAME = "post.resume.json"
str	POST_LOCK_FILENAME = "post.lock"
str	POST_LOCK_METADATA_FILENAME = "post.lock.json"
str	POST_LOCK_WRAPPER_FILENAME = "post_lock_wrapper.py"
int	POST_RESUME_SCHEMA_VERSION = 2
dict	POST_RECIPE_SIGNATURE_EXCLUDED_KEYS = {"startTime", "endTime", "timeStep", "source_directory"}
str	CHECKPOINT_FORMAT = "picurv-checkpoint"
int	CHECKPOINT_VERSION = 1
int	CHECKPOINT_STEP_WIDTH = 12
dict	CHECKPOINT_REQUIRED_EULERIAN_FIELDS = {"Ucat", "Ucont", "Ucont_rm1", "P", "Nvert"}
tuple	WORKSPACE_DIRECTORY_LAYOUT
tuple	RUN_DIRECTORY_LAYOUT
dict	CANONICAL_RUN_PATHS
	INITIAL_CONDITION_SPECTRUM_RELPATH
dict	_WORKSPACE_ARTIFACT_ROOT_VALUES = {"runs", "studies"}
dict	_ASSET_SOURCE_REFERENCE_KEYS
dict	_PYTHON_INITIAL_CONDITION_PROVIDERS
tuple	SPECTRAL_IC_PROVIDERS
tuple	SHELL_SPECTRUM_IC_PROVIDERS = ("spectral_random_velocity", "resampled_velocity")
	SPECTRAL_RANDOM_VELOCITY_PARAMS
	RESAMPLED_VELOCITY_PARAMS
tuple	RESAMPLED_VELOCITY_FASTEST_AXES = ("x", "z")
tuple	RESAMPLED_VELOCITY_COMPONENT_LAYOUTS = ("interleaved", "separate")
tuple	RESAMPLED_VELOCITY_RAW_DTYPES = ("float32", "float64")
tuple	RESAMPLED_VELOCITY_BYTE_ORDERS = ("little", "big", "native")
tuple	RESAMPLED_VELOCITY_PROJECTIONS = ("picurv_discrete", "continuum", "none")
dict	RESAMPLED_VELOCITY_LAYOUT_KEYS
dict	_FILE_BACKED_GRID_VALUES = {"file", "grid_gen"}
dict	_WORKSPACE_MANAGED_PATHS = {"assets", "inputs", "runs", "studies"}
dict	_VENDORABLE_CONFIG_REFERENCE_KEYS = {"config_file", "script"}
dict	_PLAIN_FILENAME_SENTINELS = {"", ".", ".."}
dict	_VERSION_BUILD_ACTIONS = {"install", "activate"}
	RUN_DIRECTORY_ROOTS
	RUN_ROOT_ALLOWED_FILES = frozenset({"manifest.json"})
tuple	CONTINUATION_STAGED_RECORDS
tuple	RUN_EXECUTABLE_NAMES = ("simulator", "postprocessor")
	STORAGE_OFFLOADED_STATES = frozenset({"COLD", "PARTIAL"})
tuple	RUN_COMPONENT_STATES
tuple	RUN_COMPONENT_LAYOUT
	_SELECTED_PETSC_INDEX_BYTES = None
	_BINARY_VERSION_PATTERN
	_BINARY_PETSC_PATTERN
dict	PETSC_INDEX_BYTES = {"int32": 4, "int64": 8}
str	_BINARY_PETSC_STAMP_MARKER = b"PICURV_PETSC_BUILD:"
str	_BINARY_BUILD_STAMP_MARKER = b"PICURV_BUILD:"
str	ERROR_CODE_CLI_USAGE_INVALID = "CLI_USAGE_INVALID"
str	ERROR_CODE_CFG_MISSING_SECTION = "CFG_MISSING_SECTION"
str	ERROR_CODE_CFG_MISSING_KEY = "CFG_MISSING_KEY"
str	ERROR_CODE_CFG_INVALID_TYPE = "CFG_INVALID_TYPE"
str	ERROR_CODE_CFG_INVALID_VALUE = "CFG_INVALID_VALUE"
str	ERROR_CODE_CFG_FILE_NOT_FOUND = "CFG_FILE_NOT_FOUND"
str	ERROR_CODE_CFG_GRID_PARSE = "CFG_GRID_PARSE"
str	ERROR_CODE_CFG_INCONSISTENT_COMBO = "CFG_INCONSISTENT_COMBO"
str	ERROR_CODE_DEPENDENCY_MISSING = "DEPENDENCY_MISSING"
tuple	RESTART_RUN_DIR_REQUIRED_MESSAGE
dict	_ERROR_HINTS
tuple	_RESTART_HINT
tuple	_STORAGE_RESTORE_HINT
str	_STUDY_DIR_HINT = "Pass a study directory that 'picurv sweep' created (studies/<study_id>)."
	_MAKE_ASSIGNMENT_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*[:+?]?=.*$")
dict	POST_RUN_CONTROL_ALIASES
dict	GRID_GENERATOR_HYPHEN_KEY_HINTS
tuple	RETIRED_GENERATOR_DESTINATION_KEYS
tuple	RETIRED_INITIAL_CONDITION_DESTINATION_KEYS = ("output_file", "summary_json", "spectrum_csv")
dict	POST_SPECTRA_TASKS
tuple	POST_SPECTRA_SYMBOLS = ("continuum", "discrete")
tuple	POST_SPECTRA_MEAN_MODES = ("none", "domain", "sample")
tuple	POST_FIELD_STATISTICS_OUTPUTS = ("mean", "reynolds_stress", "rms", "tke", "flux", "point_variance")
tuple	POST_FIELD_STATISTICS_DEFAULT_OUTPUTS = POST_FIELD_STATISTICS_OUTPUTS[:-1]
tuple	POST_FIELD_STATISTICS_FORMATS = ("vtk", "csv")
tuple	GRID_MODES = ("file", "programmatic_c", "grid_gen")
tuple	DOMAIN_DIMENSIONALITY_MODES = ("3D", "2D")
tuple	GRID_GENERATOR_TYPES = ("box", "sweep")
tuple	GRID_CROSS_SECTION_KINDS = ("rectangle", "circle")
tuple	GRID_WALL_SEGMENT_KINDS = ("flat", "step", "ramp", "arc", "sine", "gaussian", "hill")
tuple	GRID_PATH_SEGMENT_KINDS = ("straight", "arc")
tuple	GRID_TRANSFORM_KINDS = ("anchor", "translate", "scale", "rotate", "mirror", "permute", "reverse")
tuple	PARTICLE_RESTART_MODES = ("init", "load")
tuple	POST_EULERIAN_PIPELINE_TASKS = ("q_criterion", "normalize_field", "nodal_average")
tuple	POST_LAGRANGIAN_PIPELINE_TASKS = ("specific_ke",)
tuple	STUDY_TYPES = ("grid_independence", "timestep_independence", "sensitivity")
tuple	NEWTON_KRYLOV_PRECONDITIONER_MODELS = ("none", "frozen_momentum_jacobian")
tuple	NEWTON_KRYLOV_PRECONDITIONER_STRUCTURES = ("none", "point_block")
tuple	POISSON_PRECONDITIONER_TYPES = ("multigrid",)
dict	POISSON_PRECONDITIONER_SPELLINGS = {"mg": "multigrid", "pcmg": "multigrid"}
tuple	PRESCRIBED_FLOW_SOURCE_TYPES = ("file", "generated", "field_slice")
tuple	VERIFICATION_SCALAR_PROFILES = ("CONSTANT", "LINEAR_X", "SIN_PRODUCT")
dict	SCALAR_TRANSPORT_FLAGS
dict	SCALAR_TRANSPORT_CASE_PATHS
tuple	STUDY_PLOT_FORMATS = ("png", "pdf", "svg")
tuple	PROFILING_TIMESTEP_MODES = ("off", "selected", "all")
dict	RENAMED_MONITOR_FUNCTIONS
tuple	REMOVED_MONITOR_FUNCTIONS
tuple	GMRES_RESTART_METHODS = ("gmres", "fgmres", "lgmres")
dict	POISSON_KSP_METHODS
dict	POISSON_KSP_REFUSED
tuple	ANALYTICAL_SOLUTION_TYPES = ("TGV3D", "ZERO_FLOW", "UNIFORM_FLOW")
tuple	LEGACY_FIELD_INIT_SPELLINGS = ("Zero", "Constant", "Poiseuille")
tuple	PROJECTION_OPERATORS = ("continuum", "picurv_discrete")
tuple	METRIC_SOURCE_KINDS = ("statistics_csv", "csv", "log_regex", "log")
tuple	LAUNCH_MODES = ("local", "cluster")
tuple	POST_SPECTRA_SCALAR_COLUMNS
tuple	POST_STAGE_NAMES = ("fields", "spectra", "reducers")
dict	POST_REDUCER_TASKS
dict	POST_REDUCER_FRICTION_SOURCES
dict	_REDUCER_AXIS_TOKENS = {"i": "Xi", "j": "Eta", "k": "Zeta"}
dict	POST_PARAVIEW_SERIES_SCOPES = {"run", "lineage"}
dict	POST_PROCESS_REASON_LABELS
str	PICGRID_FLOAT_FORMAT = ".17e"
dict	GENERATED_PROFILE_GENERATORS = {"square_duct_poiseuille"}
dict	GRID_GENERATOR_CHOICE_FLAGS
dict	GRID_GENERATOR_SPEC_FLAGS
dict	BC_FACE_MAP
dict	BC_TYPE_MAP
tuple	PARTICLE_BOUNDARY_POLICIES = ("reflect", "remove", "wrap")
dict	BC_HANDLER_SPECS
dict	_NUMERIC_BC_PARAMS = {"vx", "vy", "vz", "v_max", "target_flux"}
dict	_BOOL_BC_PARAMS = {"enforce_seam_flux", "apply_trim"}
dict	_DEPRECATED_BC_PARAM_ALIASES = {"apply_trim": "enforce_seam_flux"}
tuple	RANS_PLANNED_REFUSAL
dict	_CASE_SCHEMA
dict	_SOLVER_SCHEMA
dict	_MONITOR_SCHEMA
dict	STATISTICS_ELIGIBLE_FIELDS
dict	STATISTICS_PARTICLE_FIELDS
tuple	POST_STATISTICS_ENSEMBLE_SOURCES = ("particles", "eulerian")
tuple	STATISTICS_MOMENT_NAMES = ("first", "second")
tuple	STATISTICS_WEIGHTING_MODES = ("sample", "physical_time")
dict	_POST_SCHEMA
dict	_CLUSTER_SCHEMA
dict	_STUDY_SCHEMA
dict	_WORKSPACE_SCHEMA
tuple	DIMENSIONLESS = (0, 0, 0)
tuple	LENGTH = (1, 0, 0)
tuple	VELOCITY = (0, 1, 0)
tuple	TIME = (1, -1, 0)
tuple	WAVENUMBER = (-1, 0, 0)
tuple	VOLUME_FLUX = (2, 1, 0)
tuple	DIFFUSIVITY = (1, 1, 0)
tuple	PRESSURE = (0, 2, 1)
tuple	DENSITY = (0, 0, 1)
tuple	DYNAMIC_VISCOSITY = (1, 1, 1)
tuple	INPUT_CONVERSION_SITES = ("cli", "c", "staging", "provider", "evaluator", "reference", "passthrough", "")
tuple	NOT_A_QUANTITY = (None, "")
tuple	UNITLESS = (DIMENSIONLESS, "")
dict	INPUT_QUANTITIES
dict	BC_PARAM_QUANTITIES
dict	IC_PARAM_QUANTITIES
tuple	RUN_OWNED_DIRECTORY_KEYS = ("log", "output")
str	UNSAFE_PATHS_OVERRIDE_KEY = "allow_unsafe_paths"
tuple	RESERVED_RUN_DIRECTORY_NAMES = ("config", "scheduler", "checkpoints", "visualization")
dict	RUN_DIRECTORY_DEFAULTS = {"log": "logs", "output": "output"}
tuple	RESERVED_DIRECTORY_FLAGS
tuple	RESERVED_INDIRECTION_FLAGS = ("-options_file", "-options_file_yaml", "-alias")
tuple	UNSAFE_DIRECTORY_CHARACTERS = ('"', "'", "#", "\n", "\r", "\t")
str	PHYSICAL_VERDICT_CONTAINED = "contained"
str	PHYSICAL_VERDICT_RUN_ROOT = "run_root"
str	PHYSICAL_VERDICT_ANCESTOR = "ancestor"
str	PHYSICAL_VERDICT_RELATIVE_ESCAPE = "relative_escape"
str	PHYSICAL_VERDICT_EXTERNAL_ABSOLUTE = "external_absolute"
	WAIVABLE_PHYSICAL_VERDICTS = frozenset({PHYSICAL_VERDICT_EXTERNAL_ABSOLUTE})
dict	_SLURM_FAILED_END_STATES
str	RUNTIME_MEMORY_FILE = "Runtime_Memory.csv"
str	PROFILING_TIMESTEP_FILE = "Profiling_Timestep_Summary.csv"
dict	DIAGNOSTICS_PETSC_KEYS
tuple	PROGRAMMATIC_BRIDGE_GRID_KEYS
tuple	GRID_DA_PROCESSOR_KEYS = ("da_processors_x", "da_processors_y", "da_processors_z")
dict	IC_PAYLOAD_DIMENSIONS = {0: VELOCITY, 1: VOLUME_FLUX}
dict	GENERATED_IC_PROVIDERS
dict	PARTICLE_SETTABLE_FIELDS = {"Psi": 1}
tuple	PETSC_INDEX_BITS_CHOICES = ("32", "64")
int	PETSC_MAX_INT_32BIT = 2**31 - 1
int	PARTICLE_FIELD_MAX_COMPONENTS = 3
int	GRID_FIELD_MAX_COMPONENTS = 3
int	STATISTICS_FIELD_COMPONENTS = 6
dict	LES_MODEL_NAMES = {1: "constant_smagorinsky", 2: "dynamic_smagorinsky", 3: "vreman", 4: "wale"}
dict	LES_MODEL_OWNED_KEYS
dict	LES_MODEL_KEY_OWNER_DESCRIPTIONS
tuple	LES_AVERAGING_DIRECTION_AXES = ("i", "j", "k")
dict	SOLVER_MONITORING_POISSON_FLAG_MAP
dict	SOLVER_MONITORING_MOMENTUM_FLAG_MAP
int	MAX_TRACED_PARTICLES = 64
dict	KRYLOV_KSP_TYPES
tuple	_STUDY_REPORT_COLORS
dict	ASSET_KIND_DIRECTORIES
int	ASSET_PREVIEW_NODE_LIMIT = 2_000_000
	_SUMMARY_NUMERIC_RE = re.compile(r"[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?")
int	_CONFIG_SUMMARY_WIDTH = 78
dict	_SUMMARY_PLOT_LOG_SCALE_FIELDS
dict	_SUMMARY_PLOT_FIELD_LABELS
dict	_SUMMARY_PLOT_SOURCE_TITLES
dict	_SUMMARY_ITERATION_HISTORY_FIELDS
dict	_SUMMARY_COUNT_FIELDS
	_LEGACY_PICARD_REGEX
	_LEGACY_NEWTON_HISTORY_REGEX
	_LEGACY_NEWTON_SUMMARY_REGEX
	_LEGACY_POISSON_REGEX
tuple	_PLOT_ROW_IDENTITY_KEYS = ("step", "block")
dict	SUMMARY_TABLES
dict	WORKSPACE_INPUT_DIRECTORIES

Function Documentation

_prune_incompatible_python_site_paths()

picurv_cli.core._prune_incompatible_python_site_paths (   paths )

protected

Remove site-package paths for a different Python major/minor version.

Parameters

[in]

paths

Candidate sys.path entries.

Returns

Filtered path list.

Definition at line 101 of file core.py.

def _prune_incompatible_python_site_paths(paths):
    """!
    @brief Remove site-package paths for a different Python major/minor version.
    @param[in] paths Candidate sys.path entries.
    @return Filtered path list.
    """
    current = (sys.version_info[0], sys.version_info[1])
    pattern = re.compile(r"python(?:-)?(\d+)\.(\d+)", re.IGNORECASE)
    filtered = []
    for path in paths:
        text = str(path)
        match = pattern.search(text)
        if match:
            path_version = (int(match.group(1)), int(match.group(2)))
            if path_version != current and ("site-packages" in text or "dist-packages" in text):
                continue
        filtered.append(path)
    return filtered
 
 

Here is the caller graph for this function:

_drop_imported_package()

picurv_cli.core._drop_imported_package ( str  package_name )

protected

Remove a failed/partial import package tree from sys.modules.

Parameters

[in]

package_name

Top-level package name.

Definition at line 121 of file core.py.

def _drop_imported_package(package_name: str):
    """!
    @brief Remove a failed/partial import package tree from sys.modules.
    @param[in] package_name Top-level package name.
    """
    prefix = package_name + "."
    for module_name in list(sys.modules):
        if module_name == package_name or module_name.startswith(prefix):
            sys.modules.pop(module_name, None)
 
 

Here is the caller graph for this function:

require_numpy()

picurv_cli.core.require_numpy

(

)

Import NumPy only for commands that need numeric reductions.

Returns

Imported NumPy module.

Definition at line 132 of file core.py.

def require_numpy():
    """!
    @brief Import NumPy only for commands that need numeric reductions.
    @return Imported NumPy module.
    """
    global _NUMPY_MODULE
    if _NUMPY_MODULE is not None:
        return _NUMPY_MODULE
    try:
        import numpy
    except Exception as exc:
        first_error = exc
        original_path = list(sys.path)
        try:
            _drop_imported_package("numpy")
            sys.path = _prune_incompatible_python_site_paths(original_path)
            import numpy
        except Exception as retry_exc:
            raise RuntimeError(
                "NumPy is required for this operation, but no compatible NumPy "
                "could be imported for this Python interpreter. PICurv ignored "
                "site-packages paths for other Python versions and retried. "
                f"First error: {first_error}. Retry error: {retry_exc}"
            ) from retry_exc
        finally:
            sys.path = original_path
    _NUMPY_MODULE = numpy
    return _NUMPY_MODULE
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

optional_matplotlib_pyplot()

picurv_cli.core.optional_matplotlib_pyplot

(

)

Import matplotlib.pyplot lazily for study plot generation.

Returns

matplotlib.pyplot when available, otherwise None.

Definition at line 162 of file core.py.

def optional_matplotlib_pyplot():
    """!
    @brief Import matplotlib.pyplot lazily for study plot generation.
    @return matplotlib.pyplot when available, otherwise None.
    """
    global _MATPLOTLIB_PYPLOT
    if _MATPLOTLIB_PYPLOT is not None:
        return _MATPLOTLIB_PYPLOT
    original_path = list(sys.path)
    try:
        import matplotlib.pyplot as pyplot
    except Exception:
        try:
            _drop_imported_package("matplotlib")
            sys.path = _prune_incompatible_python_site_paths(original_path)
            import matplotlib.pyplot as pyplot
        except Exception:
            return None
        finally:
            sys.path = original_path
    _MATPLOTLIB_PYPLOT = pyplot
    return _MATPLOTLIB_PYPLOT
 
# --- Global Path Definitions ---
# The implementation package and source-tree entrypoint live in picurv_cli/,
# while generators/ owns standalone generators.

Here is the call graph for this function:

Here is the caller graph for this function:

_read_release_version()

str picurv_cli.core._read_release_version ( )

protected

Read the single release version shared by every PICurv executable.

Returns

Release version from VERSION, or a safe development fallback.

Definition at line 208 of file core.py.

def _read_release_version() -> str:
    """!
    @brief Read the single release version shared by every PICurv executable.
    @return Release version from VERSION, or a safe development fallback.
    """
    configured = os.environ.get("PICURV_RELEASE_VERSION")
    if configured:
        return configured.strip()
    try:
        with open(VERSION_FILE, "r", encoding="utf-8") as stream:
            value = stream.read().strip()
    except OSError:
        value = "0.0.0"
    return value or "0.0.0"
 
 

Here is the caller graph for this function:

_git_output()

"str | None" picurv_cli.core._git_output ( *  arguments )

protected

Run one git command in the source checkout.

Parameters

[in]

arguments

Git arguments.

Returns

Stripped standard output, or None when git is unavailable or the command fails.

Definition at line 224 of file core.py.

def _git_output(*arguments) -> "str | None":
    """!
    @brief Run one git command in the source checkout.
    @param[in] arguments Git arguments.
    @return Stripped standard output, or None when git is unavailable or the command fails.
    """
    try:
        result = subprocess.run(["git", *arguments], cwd=PACKAGE_PROJECT_ROOT,
                                text=True, capture_output=True, check=False)
    except OSError:
        return None
    return result.stdout.strip() if result.returncode == 0 else None
 
 

Here is the caller graph for this function:

_source_build_identity()

dict picurv_cli.core._source_build_identity ( str  release_version )

protected

Resolve reproducible release, commit, and dirty-tree build identity.

One git describe --long --dirty gives the commit, its distance from the release tag, and whether tracked files differ from it (untracked files are ignored, as git status --untracked-files=no did). Only when the tag is missing does it fall back to the commit, a dirty check, and the commit count. On a cold network filesystem each git call costs seconds, which is why this is reached lazily through picurv_build() rather than at import.

Parameters

[in]

release_version

Release version read from VERSION.

Returns

Mapping suitable for manifests and user-facing status output.

Definition at line 238 of file core.py.

def _source_build_identity(release_version: str) -> dict:
    """!
    @brief Resolve reproducible release, commit, and dirty-tree build identity.
    @details One `git describe --long --dirty` gives the commit, its distance from the
             release tag, and whether tracked files differ from it (untracked files are
             ignored, as `git status --untracked-files=no` did). Only when the tag is
             missing does it fall back to the commit, a dirty check, and the commit count.
             On a cold network filesystem each git call costs seconds, which is why this is
             reached lazily through picurv_build() rather than at import.
    @param[in] release_version Release version read from VERSION.
    @return Mapping suitable for manifests and user-facing status output.
    """
    identity = {
        "release_version": release_version,
        "version": release_version,
        "git_commit": None,
        "git_short_commit": None,
        "dirty": None,
        "build_id": release_version,
        "dev_distance": None,
        "released": False,
    }
    described = _git_output("describe", "--tags", "--long", "--dirty", "--abbrev=40",
                            "--match", f"v{release_version}")
    match = re.match(r"^v.+-(\d+)-g([0-9a-f]{40})(-dirty)?$", described or "")
    if match:
        identity["dev_distance"] = int(match.group(1))
        identity["git_commit"] = match.group(2)
        identity["dirty"] = bool(match.group(3))
    else:
        # No tag for this release yet: every commit is development toward it.
        identity["git_commit"] = _git_output("rev-parse", "HEAD")
        status = _git_output("status", "--porcelain", "--untracked-files=no")
        identity["dirty"] = None if status is None else bool(status)
        count = _git_output("rev-list", "--count", "HEAD")
        if count is not None and count.isdigit():
            identity["dev_distance"] = int(count)
    if identity["git_commit"]:
        identity["git_short_commit"] = identity["git_commit"][:12]
    # Commits since the release tag, so a development build is visibly ahead of the
    # release it names rather than claiming to be that release.
    identity["released"] = identity["dev_distance"] == 0 and not identity["dirty"]
    if identity["git_short_commit"]:
        development = "" if identity["dev_distance"] in (0, None) else f".dev{identity['dev_distance']}"
        suffix = f"{development}+g{identity['git_short_commit']}"
        if identity["dirty"]:
            suffix += ".dirty"
        identity["build_id"] = release_version + suffix
        identity["version"] = identity["build_id"]
    return identity
 
 
@functools.lru_cache(maxsize=None)

Here is the call graph for this function:

Here is the caller graph for this function:

picurv_build()

dict picurv_cli.core.picurv_build

(

)

The conductor's own build identity, resolved on first use and kept for the process.

Commands that only parse, validate, or scaffold never touch git; manifests, locks, and picurv version do, once. Callers that store it copy it.

Returns

The cached identity mapping from _source_build_identity().

Definition at line 291 of file core.py.

def picurv_build() -> dict:
    """!
    @brief The conductor's own build identity, resolved on first use and kept for the process.
    @details Commands that only parse, validate, or scaffold never touch git; manifests,
             locks, and `picurv version` do, once. Callers that store it copy it.
    @return The cached identity mapping from _source_build_identity().
    """
    return _source_build_identity(PICURV_RELEASE_VERSION)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_find_named_file_upwards()

picurv_cli.core._find_named_file_upwards ( str  start, str  filename  )

protected

Find a named file at or above an arbitrary filesystem anchor.

Parameters

[in]	start	File or directory from which to search.
[in]	filename	Basename to locate.

Returns

Absolute path when found, otherwise None.

Definition at line 467 of file core.py.

def _find_named_file_upwards(start: str, filename: str):
    """!
    @brief Find a named file at or above an arbitrary filesystem anchor.
    @param[in] start File or directory from which to search.
    @param[in] filename Basename to locate.
    @return Absolute path when found, otherwise None.
    """
    current = os.path.abspath(start or os.getcwd())
    if os.path.isfile(current):
        current = os.path.dirname(current)
    while True:
        candidate = os.path.join(current, filename)
        if os.path.isfile(candidate):
            return candidate
        parent = os.path.dirname(current)
        if parent == current:
            return None
        current = parent
 
 

Here is the caller graph for this function:

find_workspace_root()

picurv_cli.core.find_workspace_root

(

*

anchors

)

Locate the nearest initialized PICurv workspace for supplied anchors.

Parameters

[in]

anchors

Candidate config, run, study, or current-working-directory paths.

Returns

Workspace root path when found, otherwise None.

Definition at line 487 of file core.py.

def find_workspace_root(*anchors):
    """!
    @brief Locate the nearest initialized PICurv workspace for supplied anchors.
    @param[in] anchors Candidate config, run, study, or current-working-directory paths.
    @return Workspace root path when found, otherwise None.
    """
    for anchor in anchors or (os.getcwd(),):
        if not anchor:
            continue
        found = _find_named_file_upwards(str(anchor), WORKSPACE_CONFIG_FILENAME)
        if found:
            return os.path.dirname(found)
    return None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

load_workspace_config()

dict picurv_cli.core.load_workspace_config

(

str

workspace_root

)

Load and validate the immutable workspace identity/configuration file.

Parameters

[in]

workspace_root

Initialized workspace directory.

Returns

Parsed workspace configuration mapping.

Definition at line 502 of file core.py.

def load_workspace_config(workspace_root: str) -> dict:
    """!
    @brief Load and validate the immutable workspace identity/configuration file.
    @param[in] workspace_root Initialized workspace directory.
    @return Parsed workspace configuration mapping.
    """
    path = os.path.join(os.path.abspath(workspace_root), WORKSPACE_CONFIG_FILENAME)
    payload = read_yaml_file(path)
    if payload.get("schema_version") != WORKSPACE_SCHEMA_VERSION:
        raise ValueError(
            f"{path}: unsupported workspace schema_version "
            f"{payload.get('schema_version')!r}; expected {WORKSPACE_SCHEMA_VERSION}."
        )
    errors: list = []
    _validate_yaml_schema_keys(payload, _WORKSPACE_SCHEMA, path, errors)
    if errors:
        raise ValueError("\n".join(errors))
    return payload
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

enforce_workspace_version()

dict picurv_cli.core.enforce_workspace_version

(

str

workspace_root

)

Enforce an optional workspace PICurv version requirement.

Parameters

[in]

workspace_root

Initialized workspace directory.

Returns

Current build identity after successful validation.

Definition at line 522 of file core.py.

def enforce_workspace_version(workspace_root: str) -> dict:
    """!
    @brief Enforce an optional workspace PICurv version requirement.
    @param[in] workspace_root Initialized workspace directory.
    @return Current build identity after successful validation.
    """
    payload = load_workspace_config(workspace_root)
    software = payload.get("software") or {}
    requirement = software.get("picurv") if isinstance(software, dict) else None
    if requirement in (None, ""):
        return dict(picurv_build())
    try:
        from packaging.specifiers import SpecifierSet
        from packaging.version import Version
        requirement_text = str(requirement).strip()
        if not any(token in requirement_text for token in "<>=!~"):
            requirement_text = "==" + requirement_text
        matches = Version(PICURV_RELEASE_VERSION) in SpecifierSet(requirement_text)
    except Exception as exc:
        raise ValueError(
            f"{WORKSPACE_CONFIG_FILENAME}: software.picurv={requirement!r} is not a valid "
            "version or version range."
        ) from exc
    if not matches:
        raise ValueError(
            f"Workspace requires PICurv {requirement!r}, but the active release is "
            f"{PICURV_RELEASE_VERSION} (build {picurv_build()['build_id']}).\n"
            f"Activate a matching installation with 'picurv versions activate <version>' "
            "and retry.\n"
            f"Note: {PACKAGE_PROJECT_ROOT} is a single shared installation. Activating "
            "re-points every workspace and every unpinned job that resolves executables "
            "from it, so two workspaces pinned to different releases cannot both be "
            "satisfied at once. A run staged with --pin-executables keeps its own copy and "
            "survives an activation."
        )
    return dict(picurv_build())
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

enforce_reproducibility_policy()

dict picurv_cli.core.enforce_reproducibility_policy

(

str

workspace_root

)

Enforce an optional workspace policy demanding a clean, released build.

Exploratory work should stay frictionless, so this is opt-in: a workspace running a campaign that will be published sets it once, and PICurv then refuses to stage from a modified or untagged tree instead of recording the compromise in a manifest nobody reads until later.

Parameters

[in]

workspace_root

Initialized workspace directory, or None.

Returns

The resolved policy mapping, empty when none is configured.

Exceptions

ValueError

when the active build does not satisfy the configured policy.

Definition at line 560 of file core.py.

def enforce_reproducibility_policy(workspace_root: str) -> dict:
    """!
    @brief Enforce an optional workspace policy demanding a clean, released build.
 
    @details Exploratory work should stay frictionless, so this is opt-in: a workspace
             running a campaign that will be published sets it once, and PICurv then
             refuses to stage from a modified or untagged tree instead of recording the
             compromise in a manifest nobody reads until later.
    @param[in] workspace_root Initialized workspace directory, or None.
    @return The resolved policy mapping, empty when none is configured.
    @throws ValueError when the active build does not satisfy the configured policy.
    """
    if not workspace_root:
        return {}
    payload = load_workspace_config(workspace_root)
    policy = payload.get("reproducibility") or {}
    if not isinstance(policy, dict) or not policy:
        return {}
    if policy.get("require_clean_release"):
        problems = []
        if picurv_build().get("dirty"):
            problems.append("the source tree has uncommitted changes")
        if picurv_build().get("dev_distance"):
            problems.append(
                f"HEAD is {picurv_build()['dev_distance']} commit(s) past the "
                f"v{PICURV_RELEASE_VERSION} release tag"
            )
        elif picurv_build().get("dev_distance") is None:
            problems.append("the release tag could not be resolved from this checkout")
        if problems:
            raise ValueError(
                f"{WORKSPACE_CONFIG_FILENAME} sets reproducibility.require_clean_release, "
                f"but this build is {picurv_build()['build_id']}: " + "; ".join(problems) + ".\n"
                "Commit and tag the release, or clear the policy for exploratory work."
            )
    if policy.get("pin_executables"):
        identities = runtime_build_identities()
        stale = [
            name for name, identity in sorted(identities.items())
            if identity.get("available") and not identity.get("matches_source")
        ]
        unavailable = [
            name for name, identity in sorted(identities.items())
            if not identity.get("available")
        ]
        if stale or unavailable:
            detail = []
            if stale:
                detail.append("built from another revision: " + ", ".join(stale))
            if unavailable:
                detail.append("no build identity available: " + ", ".join(unavailable))
            commands = sorted({rebuild_command(name, identities[name]) for name in stale + unavailable})
            raise ValueError(
                f"{WORKSPACE_CONFIG_FILENAME} sets reproducibility.pin_executables, but "
                "the executables do not match the active source (" + "; ".join(detail) + ").\n"
                "Rebuild with " + " and ".join(f"'{command}'" for command in commands)
                + " so the run records the build that produced it."
            )
    return dict(policy)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_workspace_path()

str picurv_cli.core.resolve_workspace_path	(	str	anchor_file,
		str	candidate,
		*bool	allow_external = False
	)

Resolve a user path against its workspace and reject implicit escapes.

Parameters

[in]	anchor_file	Config file whose workspace owns the reference.
[in]	candidate	Workspace-relative path text.
[in]	allow_external	Whether an explicit import/reference operation permits an absolute path.

Returns

Absolute resolved path.

Definition at line 621 of file core.py.

def resolve_workspace_path(anchor_file: str, candidate: str, *, allow_external: bool = False) -> str:
    """!
    @brief Resolve a user path against its workspace and reject implicit escapes.
    @param[in] anchor_file Config file whose workspace owns the reference.
    @param[in] candidate Workspace-relative path text.
    @param[in] allow_external Whether an explicit import/reference operation permits an absolute path.
    @return Absolute resolved path.
    """
    if not isinstance(candidate, str) or not candidate.strip():
        raise ValueError("Referenced path must be a non-empty string.")
    text = os.path.expanduser(candidate.strip())
    workspace_root = find_workspace_root(anchor_file)
    if not workspace_root:
        return os.path.abspath(text if os.path.isabs(text) else os.path.join(os.path.dirname(os.path.abspath(anchor_file)), text))
    if os.path.isabs(text):
        if allow_external:
            return os.path.abspath(text)
        raise ValueError(
            f"{anchor_file}: absolute path {candidate!r} is not allowed in workspace configuration; "
            "import it with 'picurv inputs import' or use an explicit reference-mode import."
        )
    resolved = os.path.abspath(os.path.join(workspace_root, text))
    if os.path.commonpath([workspace_root, resolved]) != os.path.abspath(workspace_root):
        raise ValueError(
            f"{anchor_file}: path {candidate!r} escapes the workspace; parent traversal is not allowed."
        )
    if resolved.endswith(".reference.yml") and os.path.isfile(resolved):
        pointer = read_yaml_file(resolved)
        external = pointer.get("picurv_external_reference") if isinstance(pointer, dict) else None
        if not isinstance(external, str) or not os.path.isabs(external):
            raise ValueError(f"Invalid external-reference descriptor: {resolved}")
        if not os.path.isfile(external):
            raise ValueError(f"Registered external input is unavailable: {external}")
        return external
    return resolved
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

ensure_workspace_layout()

None picurv_cli.core.ensure_workspace_layout

(

str

workspace_root

)

Materialize the uniform, cheap directory skeleton for one workspace.

Parameters

[in]

workspace_root

Workspace root to initialize.

Definition at line 658 of file core.py.

def ensure_workspace_layout(workspace_root: str) -> None:
    """!
    @brief Materialize the uniform, cheap directory skeleton for one workspace.
    @param[in] workspace_root Workspace root to initialize.
    """
    for relative in WORKSPACE_DIRECTORY_LAYOUT:
        os.makedirs(os.path.join(workspace_root, *relative.split("/")), exist_ok=True)
 
 

Here is the caller graph for this function:

initialize_workspace_root()

str picurv_cli.core.initialize_workspace_root	(	str	workspace_root,
		str	template_name
	)

Create the workspace skeleton and its identity file at one root.

Parameters

[in]	workspace_root	Workspace root to initialize.
[in]	template_name	Example template the workspace was created from.

Returns

Path to the written workspace configuration file.

Definition at line 667 of file core.py.

def initialize_workspace_root(workspace_root: str, template_name: str) -> str:
    """!
    @brief Create the workspace skeleton and its identity file at one root.
    @param[in] workspace_root Workspace root to initialize.
    @param[in] template_name Example template the workspace was created from.
    @return Path to the written workspace configuration file.
    """
    workspace_root = os.path.abspath(workspace_root)
    ensure_workspace_layout(workspace_root)
    config_path = os.path.join(workspace_root, WORKSPACE_CONFIG_FILENAME)
    write_yaml_file(config_path, {
        "schema_version": WORKSPACE_SCHEMA_VERSION,
        "workspace": {
            "id": os.path.basename(workspace_root),
            "template": template_name,
            "created_at": datetime.now().astimezone().isoformat(),
        },
        "software": {},
        "paths": {
            "config": "config",
            "inputs": "inputs",
            "assets": "assets",
            "runs": "runs",
            "studies": "studies",
        },
    })
    return config_path
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

ensure_run_layout()

None picurv_cli.core.ensure_run_layout

(

str

run_dir

)

Materialize the uniform, cheap directory skeleton for one run.

Parameters

[in]

run_dir

Run root to initialize.

Definition at line 696 of file core.py.

def ensure_run_layout(run_dir: str) -> None:
    """!
    @brief Materialize the uniform, cheap directory skeleton for one run.
    @param[in] run_dir Run root to initialize.
    """
    for relative in RUN_DIRECTORY_LAYOUT:
        os.makedirs(os.path.join(run_dir, *relative.split("/")), exist_ok=True)
 
 
#: Top-level directory names a run owns. Anything else beside them is a peer PICurv
#: does not route, cannot classify for storage, and will not prune.

Here is the caller graph for this function:

validate_run_directory_structure()

tuple picurv_cli.core.validate_run_directory_structure

(

str

run_dir

)

Refuse a run whose root has grown a directory the layout does not define.

The run topology is a contract: manifest.json publishes it, the solver's reserved-directory guard defends it, and storage classifies against it. A directory beside output/ breaks all three at once - it is routed by nothing, classified as unclassified, and therefore archived forever and pruned never. Catching it when the run is staged or resumed is the only point where the answer is still "move it", rather than "it is already in every archive of this run".

Unexpected files are reported and allowed. A stray note at a run root costs nothing and refusing to resume a long campaign over one would be a worse failure than the one being prevented.

Parameters

[in]

run_dir

Run root to check.

Returns

Tuple of (errors, warnings) as human-readable message lists.

Definition at line 716 of file core.py.

def validate_run_directory_structure(run_dir: str) -> tuple:
    """!
    @brief Refuse a run whose root has grown a directory the layout does not define.
 
    @details The run topology is a contract: `manifest.json` publishes it, the solver's
             reserved-directory guard defends it, and storage classifies against it. A
             directory beside `output/` breaks all three at once - it is routed by
             nothing, classified as `unclassified`, and therefore archived forever and
             pruned never. Catching it when the run is staged or resumed is the only
             point where the answer is still "move it", rather than "it is already in
             every archive of this run".
 
             Unexpected *files* are reported and allowed. A stray note at a run root
             costs nothing and refusing to resume a long campaign over one would be a
             worse failure than the one being prevented.
    @param[in] run_dir Run root to check.
    @return Tuple of (errors, warnings) as human-readable message lists.
    """
    root = os.path.abspath(run_dir)
    if not os.path.isdir(root):
        return [], []
    allowed_files = set(RUN_ROOT_ALLOWED_FILES) | {
        STORAGE_STATE_FILENAME, STORAGE_LOCK_FILENAME,
    }
    errors, warnings = [], []
    for name in sorted(os.listdir(root)):
        path = os.path.join(root, name)
        if os.path.isdir(path) and not os.path.islink(path):
            if name not in RUN_DIRECTORY_ROOTS:
                errors.append(
                    f"{run_dir}: '{name}/' is not part of the run layout. Scientific "
                    f"output belongs under {CANONICAL_RUN_PATHS['checkpoints']}, "
                    f"{CANONICAL_RUN_PATHS['analysis']}, or "
                    f"{CANONICAL_RUN_PATHS['visualization']}; move or remove '{name}/' "
                    f"before running. Run-owned roots are: "
                    + ", ".join(sorted(RUN_DIRECTORY_ROOTS)) + "."
                )
        elif name not in allowed_files:
            warnings.append(
                f"{run_dir}: unexpected file '{name}' at the run root. It is archived "
                "as unclassified and never pruned."
            )
    return errors, warnings
 
 

Here is the caller graph for this function:

enforce_run_directory_structure()

None picurv_cli.core.enforce_run_directory_structure

(

str

run_dir

)

Apply validate_run_directory_structure() as a refusal at run time.

Parameters

[in]

run_dir

Run root to check.

Returns

None. Exits non-zero when the run root carries a directory outside the layout.

Definition at line 761 of file core.py.

def enforce_run_directory_structure(run_dir: str) -> None:
    """!
    @brief Apply `validate_run_directory_structure()` as a refusal at run time.
    @param[in] run_dir Run root to check.
    @return None. Exits non-zero when the run root carries a directory outside the layout.
    """
    errors, warnings = validate_run_directory_structure(run_dir)
    for message in warnings:
        print(f"[WARNING] {message}", file=sys.stderr)
    if not errors:
        return
    for message in errors:
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="run_layout",
            file_path=os.path.abspath(run_dir),
            message=message,
            hint="Move the directory under output/ or out of the run, then retry.",
        )
    sys.exit(1)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

case_run_label()

str picurv_cli.core.case_run_label	(	dict	case_cfg,
		str	case_path
	)

Resolve the stable human-facing portion of a generated run identifier.

Parameters

[in]	case_cfg	Parsed case configuration.
[in]	case_path	Source case YAML path.

Returns

Filesystem-safe case title, name, or source stem.

Definition at line 783 of file core.py.

def case_run_label(case_cfg: dict, case_path: str) -> str:
    """!
    @brief Resolve the stable human-facing portion of a generated run identifier.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Source case YAML path.
    @return Filesystem-safe case title, name, or source stem.
    """
    metadata = case_cfg.get("metadata") or {}
    candidate = (
        case_cfg.get("title")
        or (metadata.get("title") if isinstance(metadata, dict) else None)
        or (metadata.get("name") if isinstance(metadata, dict) else None)
        or Path(case_path).stem
    )
    label = re.sub(r"[^A-Za-z0-9_.-]+", "-", str(candidate).strip()).strip("-.")
    return label or "case"
 
 

Here is the caller graph for this function:

allocate_generated_run_id()

str picurv_cli.core.allocate_generated_run_id	(	str	runs_root,
		dict	case_cfg,
		str	case_path
	)

Build the generated run identity, disambiguating a same-second collision.

The identity is <run label>_<timestamp> at one-second resolution, so two runs of the same case launched back to back - a script, or a smoke sequence - would otherwise name the same directory. Creating a run never writes into an existing one, so the identity is advanced instead of the launch being refused for a clock artifact.

Parameters

[in]	runs_root	Directory generated runs are created beneath.
[in]	case_cfg	Parsed case configuration supplying the run label.
[in]	case_path	Case path, for the label's fallback.

Returns

Run identity that does not currently exist under runs_root.

Definition at line 801 of file core.py.

def allocate_generated_run_id(runs_root: str, case_cfg: dict, case_path: str) -> str:
    """!
    @brief Build the generated run identity, disambiguating a same-second collision.
 
    @details The identity is `<run label>_<timestamp>` at one-second resolution, so two
             runs of the same case launched back to back - a script, or a smoke
             sequence - would otherwise name the same directory. Creating a run never
             writes into an existing one, so the identity is advanced instead of the
             launch being refused for a clock artifact.
    @param[in] runs_root Directory generated runs are created beneath.
    @param[in] case_cfg Parsed case configuration supplying the run label.
    @param[in] case_path Case path, for the label's fallback.
    @return Run identity that does not currently exist under `runs_root`.
    """
    base = f"{case_run_label(case_cfg, case_path)}_{datetime.now().strftime('%Y%m%d-%H%M%S')}"
    run_id, suffix = base, 1
    while os.path.exists(os.path.join(runs_root, run_id)):
        suffix += 1
        run_id = f"{base}-{suffix}"
    return run_id
 
 

Here is the caller graph for this function:

discard_unused_run_directory()

bool picurv_cli.core.discard_unused_run_directory	(	str	run_dir,
		*bool	created,
		bool	staged = False
	)

Remove a generated run directory that never received any content.

Only a directory this invocation created, and which still holds no files, is removed: an existing run, or one that already produced output, is never touched by a staging failure. With staged the directory may hold the files this invocation staged, for a refusal after staging but before any launch.

Parameters

[in]	run_dir	Run directory that was about to be staged.
[in]	created	Whether this invocation created the directory.
[in]	staged	Whether files this invocation staged, and nothing else, may be present.

Returns

True when the directory was removed.

Definition at line 823 of file core.py.

def discard_unused_run_directory(run_dir: str, *, created: bool, staged: bool = False) -> bool:
    """!
    @brief Remove a generated run directory that never received any content.
 
    @details Only a directory this invocation created, and which still holds no files,
             is removed: an existing run, or one that already produced output, is never
             touched by a staging failure. With @p staged the directory may hold the files
             this invocation staged, for a refusal after staging but before any launch.
    @param[in] run_dir Run directory that was about to be staged.
    @param[in] created Whether this invocation created the directory.
    @param[in] staged Whether files this invocation staged, and nothing else, may be present.
    @return True when the directory was removed.
    """
    if not created or not os.path.isdir(run_dir):
        return False
    for _root, _dirs, files in os.walk(run_dir):
        if files and not staged:
            return False
    shutil.rmtree(run_dir, ignore_errors=True)
    return True
 
 

Here is the caller graph for this function:

_file_sha256()

picurv_cli.core._file_sha256 ( str  path )

protected

Content digest of one file, or None when it cannot be read.

Parameters

[in]

path

File to digest.

Returns

Hex digest, or None.

Definition at line 845 of file core.py.

def _file_sha256(path: str):
    """!
    @brief Content digest of one file, or None when it cannot be read.
    @param[in] path File to digest.
    @return Hex digest, or None.
    """
    digest = hashlib.sha256()
    try:
        with open(path, "rb") as stream:
            for block in iter(lambda: stream.read(1024 * 1024), b""):
                digest.update(block)
    except OSError:
        return None
    return digest.hexdigest()
 
 

Here is the caller graph for this function:

build_software_lock()

dict picurv_cli.core.build_software_lock

(

"str | None"

run_dir = None

)

Capture the exact software identity a run is about to execute with.

The release and commit say which source is checked out; they do not say which bytes ran. Hashing the executables and the generators pins that, so a queued job rebuilt out from under it is detectable afterwards rather than merely suspected.

Parameters

[in]

run_dir

Run whose pinned executables are hashed; the installation's when None.

Returns

Software lock mapping.

Definition at line 861 of file core.py.

def build_software_lock(run_dir: "str | None" = None) -> dict:
    """!
    @brief Capture the exact software identity a run is about to execute with.
 
    @details The release and commit say which source is checked out; they do not say
             which bytes ran. Hashing the executables and the generators pins that, so
             a queued job rebuilt out from under it is detectable afterwards rather
             than merely suspected.
    @param[in] run_dir Run whose pinned executables are hashed; the installation's when None.
    @return Software lock mapping.
    """
    lock = {
        "schema_version": 1,
        "picurv_version": PICURV_RELEASE_VERSION,
        "build_id": picurv_build().get("build_id"),
        "git_commit": picurv_build().get("git_commit"),
        "git_dirty": picurv_build().get("dirty"),
        "captured_at": datetime.now().astimezone().isoformat(),
        "executables": {},
        "generators": {},
        "environment": _toolchain_identity(),
    }
    for name in RUN_EXECUTABLE_NAMES:
        path = run_executable_path(run_dir, name)
        identity = read_binary_build_identity(path)
        lock["executables"][name] = {
            "path": path,
            "sha256": _file_sha256(path),
            "build_id": identity.get("build_id"),
            "matches_source": identity.get("matches_source"),
            "petsc": identity.get("petsc"),
        }
    conductor = os.path.join(PACKAGE_PROJECT_ROOT, "picurv_cli", "core.py")
    lock["python_conductor_sha256"] = _file_sha256(conductor)
    if os.path.isdir(GENERATORS_PATH):
        for entry in sorted(os.listdir(GENERATORS_PATH)):
            candidate = os.path.join(GENERATORS_PATH, entry)
            if os.path.isfile(candidate):
                lock["generators"][entry] = _file_sha256(candidate)
    return lock
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_toolchain_identity()

dict picurv_cli.core._toolchain_identity ( )

protected

Best-effort record of the PETSc, MPI, and compiler in the shell staging the run.

This is the staging environment, which need not be what the binaries were built against; each executable's own PETSc is recorded from its build stamp.

Returns

Mapping of what could be determined; absent keys mean it could not be read.

Definition at line 903 of file core.py.

def _toolchain_identity() -> dict:
    """!
    @brief Best-effort record of the PETSc, MPI, and compiler in the shell staging the run.
    @details This is the staging environment, which need not be what the binaries were
             built against; each executable's own PETSc is recorded from its build stamp.
    @return Mapping of what could be determined; absent keys mean it could not be read.
    """
    identity = {}
    petsc_dir = os.environ.get("PETSC_DIR")
    if petsc_dir:
        identity["petsc_dir"] = petsc_dir
        version_header = os.path.join(petsc_dir, "include", "petscversion.h")
        try:
            with open(version_header, "r", encoding="utf-8", errors="replace") as stream:
                numbers = {}
                for line in stream:
                    match = re.match(
                        r"#define\s+PETSC_VERSION_(MAJOR|MINOR|SUBMINOR)\s+(\d+)", line
                    )
                    if match:
                        numbers[match.group(1)] = match.group(2)
                if len(numbers) == 3:
                    identity["petsc_version"] = (
                        f"{numbers['MAJOR']}.{numbers['MINOR']}.{numbers['SUBMINOR']}"
                    )
        except OSError:
            pass
    if os.environ.get("PETSC_ARCH"):
        identity["petsc_arch"] = os.environ["PETSC_ARCH"]
    for tool, key in (("mpiexec", "mpi"), ("mpicc", "compiler")):
        executable = shutil.which(tool)
        if not executable:
            continue
        try:
            result = subprocess.run(
                [executable, "--version"], text=True, capture_output=True, timeout=20, check=False
            )
        except (OSError, subprocess.SubprocessError):
            continue
        first = (result.stdout or result.stderr or "").strip().splitlines()
        if first:
            identity[key] = first[0][:200]
    return identity
 
 

Here is the caller graph for this function:

write_software_lock()

str picurv_cli.core.write_software_lock

(

str

run_dir

)

Write the run's software lock beside its asset lock.

Parameters

[in]

run_dir

Run directory receiving the lock.

Returns

Path to the written lock.

Definition at line 948 of file core.py.

def write_software_lock(run_dir: str) -> str:
    """!
    @brief Write the run's software lock beside its asset lock.
    @param[in] run_dir Run directory receiving the lock.
    @return Path to the written lock.
    """
    path = os.path.join(run_dir, CANONICAL_RUN_PATHS["inputs"], "software.lock.json")
    os.makedirs(os.path.dirname(path), exist_ok=True)
    write_json_file(path, build_software_lock(run_dir))
    return path
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

workspace_artifact_root()

str picurv_cli.core.workspace_artifact_root	(	str	workspace_root,
		str	kind
	)

Return the canonical workspace-owned root for runs or studies.

Parameters

[in]	workspace_root	Initialized workspace, or None for standalone mode.
[in]	kind	Either runs or studies.

Returns

Absolute artifact root.

Definition at line 960 of file core.py.

def workspace_artifact_root(workspace_root: str, kind: str) -> str:
    """!
    @brief Return the canonical workspace-owned root for runs or studies.
    @param[in] workspace_root Initialized workspace, or None for standalone mode.
    @param[in] kind Either runs or studies.
    @return Absolute artifact root.
    """
    if kind not in _WORKSPACE_ARTIFACT_ROOT_VALUES:
        raise ValueError(f"Unsupported workspace artifact kind: {kind}")
    if workspace_root:
        return os.path.join(os.path.abspath(workspace_root), kind)
    return os.path.abspath(kind)
 
 

Here is the caller graph for this function:

_relative_to_workspace()

picurv_cli.core._relative_to_workspace ( str  path, str  workspace_root  )

protected

Return a portable workspace-relative path when possible.

Parameters

[in]	path	Path to normalize.
[in]	workspace_root	Optional initialized workspace root.

Returns

Workspace-relative POSIX path, absolute path, or None.

Definition at line 974 of file core.py.

def _relative_to_workspace(path: str, workspace_root: str):
    """!
    @brief Return a portable workspace-relative path when possible.
    @param[in] path Path to normalize.
    @param[in] workspace_root Optional initialized workspace root.
    @return Workspace-relative POSIX path, absolute path, or None.
    """
    if not path:
        return None
    absolute = os.path.abspath(path)
    if workspace_root and os.path.commonpath([absolute, workspace_root]) == os.path.abspath(workspace_root):
        return os.path.relpath(absolute, workspace_root).replace(os.sep, "/")
    return absolute
 
 

Here is the caller graph for this function:

snapshot_run_configuration()

dict picurv_cli.core.snapshot_run_configuration	(	str	run_dir,
		dict	source_paths,
		bool	continuation = False
	)

Snapshot editable YAML inputs without erasing prior continuation state.

Parameters

[in]	run_dir	Owning run directory.
[in]	source_paths	Role-to-source-path mapping.
[in]	continuation	Whether this is a continuation configuration revision.

Returns

Active snapshot metadata.

Definition at line 989 of file core.py.

                               continuation: bool = False) -> dict:
    """!
    @brief Snapshot editable YAML inputs without erasing prior continuation state.
    @param[in] run_dir Owning run directory.
    @param[in] source_paths Role-to-source-path mapping.
    @param[in] continuation Whether this is a continuation configuration revision.
    @return Active snapshot metadata.
    """
    config_root = os.path.join(run_dir, "config")
    os.makedirs(config_root, exist_ok=True)
    previous = _read_json_if_exists(os.path.join(config_root, "active.json")) or {}
    revision = None
    destination_root = config_root
    if continuation:
        revision = datetime.now().strftime("%Y%m%d-%H%M%S-%f")
        destination_root = os.path.join(config_root, "history", revision)
        os.makedirs(destination_root, exist_ok=False)
    snapshots = {}
    for role, source in source_paths.items():
        if not source:
            continue
        source = os.path.abspath(source)
        suffix = os.path.splitext(source)[1] or ".yml"
        name = f"{role}{suffix}" if role != "cluster" else "cluster.yml"
        destination = os.path.join(destination_root, name)
        shutil.copy2(source, destination)
        snapshots[role] = os.path.relpath(destination, run_dir).replace(os.sep, "/")
    active = {
        "schema_version": 1,
        "revision": revision or "initial",
        "updated_at": datetime.now().astimezone().isoformat(),
        "files": snapshots,
    }
    if continuation and isinstance(previous.get("executables"), dict):
        # A continuation changes what is configured, not which build runs it. The pin
        # moves only when the caller re-pins, which records a new executables entry.
        active["executables"] = previous["executables"]
    write_json_file(os.path.join(config_root, "active.json"), active)
    return active
 
 
#: Run records a continuation's staging rewrites in place, relative to the run directory.

Here is the call graph for this function:

Here is the caller graph for this function:

capture_continuation_records()

dict picurv_cli.core.capture_continuation_records	(	str	run_dir,
		str	restart_dir
	)

Save what a continuation's staging changes, so a refusal can undo it.

Staging rewrites the records in CONTINUATION_STAGED_RECORDS and materializes the restart checkpoint into the run's restart input, so both are captured before restart resolution runs.

Parameters

[in]	run_dir	Existing run directory.
[in]	restart_dir	The run's restart input directory.

Returns

Saved state for restore_continuation_records().

Definition at line 1036 of file core.py.

def capture_continuation_records(run_dir: str, restart_dir: str) -> dict:
    """!
    @brief Save what a continuation's staging changes, so a refusal can undo it.
    @details Staging rewrites the records in CONTINUATION_STAGED_RECORDS and materializes
             the restart checkpoint into the run's restart input, so both are captured
             before restart resolution runs.
    @param[in] run_dir Existing run directory.
    @param[in] restart_dir The run's restart input directory.
    @return Saved state for restore_continuation_records().
    """
    records = {}
    for relative in CONTINUATION_STAGED_RECORDS:
        path = os.path.join(run_dir, *relative.split("/"))
        records[relative] = open(path, "rb").read() if os.path.isfile(path) else None
    checkpoints = os.path.join(restart_dir, "checkpoints")
    return {"records": records, "checkpoints": checkpoints,
            "checkpoint_entries": set(os.listdir(checkpoints)) if os.path.isdir(checkpoints) else None}
 
 

Here is the caller graph for this function:

restore_continuation_records()

picurv_cli.core.restore_continuation_records	(	str	run_dir,
		dict	saved,
		str	revision
	)

Undo a refused continuation's staging: restore its records, drop its revision.

Removes the restart checkpoints staging materialized; everything else a continuation stages, including pinned executables, lives in the revision directory, so removing it leaves the run as it was.

Parameters

[in]	run_dir	Existing run directory.
[in]	saved	State returned by capture_continuation_records().
[in]	revision	Configuration revision the refused staging created.

Definition at line 1055 of file core.py.

def restore_continuation_records(run_dir: str, saved: dict, revision: str):
    """!
    @brief Undo a refused continuation's staging: restore its records, drop its revision.
    @details Removes the restart checkpoints staging materialized; everything else a
             continuation stages, including pinned executables, lives in the revision
             directory, so removing it leaves the run as it was.
    @param[in] run_dir Existing run directory.
    @param[in] saved State returned by capture_continuation_records().
    @param[in] revision Configuration revision the refused staging created.
    """
    checkpoints, before = saved["checkpoints"], saved["checkpoint_entries"]
    if os.path.isdir(checkpoints):
        for entry in set(os.listdir(checkpoints)) - (before or set()):
            shutil.rmtree(os.path.join(checkpoints, entry), ignore_errors=True)
        if before is None and not os.listdir(checkpoints):
            os.rmdir(checkpoints)
    for relative, content in saved["records"].items():
        path = os.path.join(run_dir, *relative.split("/"))
        if content is None:
            if os.path.isfile(path):
                os.remove(path)
        else:
            with open(path, "wb") as stream:
                stream.write(content)
    shutil.rmtree(os.path.join(run_dir, "config", "history", revision), ignore_errors=True)
 
 

Here is the caller graph for this function:

load_active_run_configuration()

dict picurv_cli.core.load_active_run_configuration

(

str

run_dir

)

Load the active immutable configuration revision for a run.

Parameters

[in]

run_dir

Run directory.

Returns

Role-to-absolute-path mapping.

Definition at line 1082 of file core.py.

def load_active_run_configuration(run_dir: str) -> dict:
    """!
    @brief Load the active immutable configuration revision for a run.
    @param[in] run_dir Run directory.
    @return Role-to-absolute-path mapping.
    """
    config_root = os.path.join(os.path.abspath(run_dir), "config")
    active = _read_json_if_exists(os.path.join(config_root, "active.json"))
    if isinstance(active, dict) and isinstance(active.get("files"), dict):
        return {
            role: os.path.join(run_dir, *relative.split("/"))
            for role, relative in active["files"].items()
            if isinstance(relative, str)
        }
    return {
        role: os.path.join(config_root, f"{role}.yml")
        for role in ("case", "solver", "monitor", "cluster")
        if os.path.isfile(os.path.join(config_root, f"{role}.yml"))
    }
 
 
#: Native executables a run launches, and therefore the ones a run pins.

Here is the call graph for this function:

Here is the caller graph for this function:

load_run_executables()

dict picurv_cli.core.load_run_executables

(

str

run_dir

)

Return the executables a run is pinned to, as recorded by its active configuration.

Parameters

[in]

run_dir

Run directory.

Returns

Mapping of executable name to its recorded entry, with path made absolute; empty when the run launches the installation's executables.

Definition at line 1107 of file core.py.

def load_run_executables(run_dir: str) -> dict:
    """!
    @brief Return the executables a run is pinned to, as recorded by its active configuration.
    @param[in] run_dir Run directory.
    @return Mapping of executable name to its recorded entry, with `path` made absolute;
            empty when the run launches the installation's executables.
    """
    active = _read_json_if_exists(os.path.join(os.path.abspath(run_dir), "config", "active.json"))
    recorded = active.get("executables") if isinstance(active, dict) else None
    if not isinstance(recorded, dict):
        return {}
    pinned = {}
    for name, entry in recorded.items():
        if isinstance(entry, dict) and isinstance(entry.get("path"), str):
            pinned[name] = dict(entry, path=os.path.join(os.path.abspath(run_dir), *entry["path"].split("/")))
    return pinned
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

run_executable_path()

str picurv_cli.core.run_executable_path	(	"str | None"	run_dir,
		str	name
	)

Resolve the executable a run launches: its pinned copy, else the installation's.

Parameters

[in]	run_dir	Run directory, or None when no run exists yet.
[in]	name	simulator or postprocessor.

Returns

Absolute executable path.

Exceptions

ValueError

when the run records a pinned copy that is no longer on disk.

Definition at line 1125 of file core.py.

def run_executable_path(run_dir: "str | None", name: str) -> str:
    """!
    @brief Resolve the executable a run launches: its pinned copy, else the installation's.
    @param[in] run_dir Run directory, or None when no run exists yet.
    @param[in] name `simulator` or `postprocessor`.
    @return Absolute executable path.
    @throws ValueError when the run records a pinned copy that is no longer on disk.
    """
    pinned = load_run_executables(run_dir).get(name) if run_dir else None
    if not pinned:
        return resolve_runtime_executable(name)
    if not os.path.isfile(pinned["path"]):
        raise ValueError(
            f"{run_dir} is pinned to {pinned['path']}, which no longer exists. Restore it "
            "from the run's archive, or re-pin with --pin-executables to run the current build."
        )
    return pinned["path"]
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

pin_run_executables()

dict picurv_cli.core.pin_run_executables	(	str	run_dir,
		str	revision
	)

Copy the installation's executables into a run's configuration revision.

The installation's bin/ is rebuilt in place, so a job that resolves its executable there when it starts runs whatever was built last, not what was staged. The copy lives under config/, which storage retains as essential and the solver refuses to write into, and active.json records it so every later stage of the run - continuation, post-processing - launches the same build. Each copy is written beside its destination and renamed into place.

Parameters

[in]	run_dir	Run directory.
[in]	revision	Active configuration revision (initial or a continuation id).

Returns

Recorded executables mapping, keyed by executable name; an executable that has not been built is left unpinned with a warning, as staging treats it today.

Definition at line 1144 of file core.py.

def pin_run_executables(run_dir: str, revision: str) -> dict:
    """!
    @brief Copy the installation's executables into a run's configuration revision.
 
    @details The installation's `bin/` is rebuilt in place, so a job that resolves its
             executable there when it starts runs whatever was built last, not what was
             staged. The copy lives under `config/`, which storage retains as essential
             and the solver refuses to write into, and `active.json` records it so every
             later stage of the run - continuation, post-processing - launches the same
             build. Each copy is written beside its destination and renamed into place.
    @param[in] run_dir Run directory.
    @param[in] revision Active configuration revision (`initial` or a continuation id).
    @return Recorded executables mapping, keyed by executable name; an executable that
            has not been built is left unpinned with a warning, as staging treats it today.
    """
    run_root = os.path.abspath(run_dir)
    config_root = os.path.join(run_root, "config")
    target = (os.path.join(config_root, "bin") if revision == "initial"
              else os.path.join(config_root, "history", revision, "bin"))
    recorded = {}
    for name in RUN_EXECUTABLE_NAMES:
        source = resolve_runtime_executable(name)
        if not os.path.isfile(source):
            print(f"[WARNING] {name} is not built at {source}, so it is not pinned; a stage that "
                  "launches it will use whatever is there when it starts.", file=sys.stderr)
            continue
        os.makedirs(target, exist_ok=True)
        destination = os.path.join(target, name)
        partial = destination + ".partial"
        shutil.copy2(source, partial)
        os.replace(partial, destination)
        identity = read_binary_build_identity(destination)
        recorded[name] = {
            "path": os.path.relpath(destination, run_root).replace(os.sep, "/"),
            "pinned_from": source,
            "sha256": _file_sha256(destination),
            "build_id": identity.get("build_id"),
            "version_line": identity.get("version_line"),
            "identity_reason": None if identity.get("available") else identity.get("reason"),
        }
    if not recorded:
        return {}
    active_path = os.path.join(config_root, "active.json")
    active = _read_json_if_exists(active_path) or {"schema_version": 1, "revision": revision, "files": {}}
    active["executables"] = recorded
    active["updated_at"] = datetime.now().astimezone().isoformat()
    write_json_file(active_path, active)
    return recorded
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

plan_run_executable_paths()

dict picurv_cli.core.plan_run_executable_paths	(	str	run_dir,
			args,
		"str | None"	workspace_root
	)

Predict, without writing, which executables staging would give a run.

Mirrors apply_run_executable_pinning() for run --dry-run: an existing pin is kept unless re-pinned, a new pin lands in the configuration revision staging would create, and otherwise the installation's executables run.

Parameters

[in]	run_dir	Run directory the plan targets.
[in]	args	Parsed command arguments.
[in]	workspace_root	Owning workspace, or None.

Returns

Mapping with pinning (kept, new, or none) and per-executable paths.

Definition at line 1194 of file core.py.

def plan_run_executable_paths(run_dir: str, args, workspace_root: "str | None") -> dict:
    """!
    @brief Predict, without writing, which executables staging would give a run.
    @details Mirrors `apply_run_executable_pinning()` for `run --dry-run`: an existing
             pin is kept unless re-pinned, a new pin lands in the configuration revision
             staging would create, and otherwise the installation's executables run.
    @param[in] run_dir Run directory the plan targets.
    @param[in] args Parsed command arguments.
    @param[in] workspace_root Owning workspace, or None.
    @return Mapping with `pinning` (`kept`, `new`, or `none`) and per-executable `paths`.
    """
    existing = load_run_executables(run_dir) if os.path.isdir(run_dir) else {}
    if existing and getattr(args, "pin_executables", None) is not True:
        return {"pinning": "kept", "paths": {name: entry["path"] for name, entry in existing.items()}}
    if resolve_executable_pinning(args, workspace_root):
        revision_root = (os.path.join(run_dir, "config") if not existing
                         and not getattr(args, "continue_run", False)
                         else os.path.join(run_dir, "config", "history", "<new-revision>"))
        return {"pinning": "new",
                "paths": {name: os.path.join(revision_root, "bin", name) for name in RUN_EXECUTABLE_NAMES}}
    return {"pinning": "none",
            "paths": {name: resolve_runtime_executable(name) for name in RUN_EXECUTABLE_NAMES}}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_executable_pinning()

bool picurv_cli.core.resolve_executable_pinning	(		args,
		"str | None"	workspace_root
	)

Decide whether staging pins the installation's executables into the run.

Pinning is opt-in: an explicit --pin-executables/--no-pin-executables wins, then the workspace's reproducibility.pin_executables. Unpinned jobs are still protected by the job-start identity check, which stops a job whose executable was rebuilt after staging instead of running the new build.

Parameters

[in]	args	Parsed command arguments.
[in]	workspace_root	Owning workspace, or None.

Returns

True to pin, False not to.

Definition at line 1218 of file core.py.

def resolve_executable_pinning(args, workspace_root: "str | None") -> bool:
    """!
    @brief Decide whether staging pins the installation's executables into the run.
    @details Pinning is opt-in: an explicit `--pin-executables`/`--no-pin-executables`
             wins, then the workspace's `reproducibility.pin_executables`. Unpinned jobs
             are still protected by the job-start identity check, which stops a job whose
             executable was rebuilt after staging instead of running the new build.
    @param[in] args Parsed command arguments.
    @param[in] workspace_root Owning workspace, or None.
    @return True to pin, False not to.
    """
    explicit = getattr(args, "pin_executables", None)
    if explicit is not None:
        return bool(explicit)
    if workspace_root:
        policy = load_workspace_config(workspace_root).get("reproducibility") or {}
        if isinstance(policy, dict):
            return bool(policy.get("pin_executables"))
    return False
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

apply_run_executable_pinning()

dict picurv_cli.core.apply_run_executable_pinning	(	str	run_dir,
		str	revision,
			args,
		"str | None"	workspace_root
	)

Pin, keep, or refuse the run's executables before anything records them.

A run already pinned keeps its build unless the caller explicitly re-pins, so a continuation or post-processing pass cannot silently switch builds. Refusing --no-pin-executables on a pinned run keeps the run's records describing one build rather than a pin nobody launched.

Parameters

[in]	run_dir	Run directory.
[in]	revision	Active configuration revision.
[in]	args	Parsed command arguments.
[in]	workspace_root	Owning workspace, or None.

Returns

The run's pinned executables; empty when it launches the installation's.

Exceptions

ValueError

when --no-pin-executables is given for a pinned run.

Definition at line 1239 of file core.py.

                                 workspace_root: "str | None") -> dict:
    """!
    @brief Pin, keep, or refuse the run's executables before anything records them.
    @details A run already pinned keeps its build unless the caller explicitly re-pins,
             so a continuation or post-processing pass cannot silently switch builds.
             Refusing `--no-pin-executables` on a pinned run keeps the run's records
             describing one build rather than a pin nobody launched.
    @param[in] run_dir Run directory.
    @param[in] revision Active configuration revision.
    @param[in] args Parsed command arguments.
    @param[in] workspace_root Owning workspace, or None.
    @return The run's pinned executables; empty when it launches the installation's.
    @throws ValueError when `--no-pin-executables` is given for a pinned run.
    """
    explicit = getattr(args, "pin_executables", None)
    existing = load_run_executables(run_dir)
    if existing and explicit is not True:
        if explicit is False:
            build = existing.get("simulator", {}).get("build_id") or "a pinned build"
            raise ValueError(
                f"{run_dir} is pinned to {build}. --no-pin-executables would launch the "
                "installation's build instead while the run still records the pin; re-pin "
                "with --pin-executables to move this run to the current build."
            )
        build = existing.get("simulator", {}).get("build_id") or "unknown build"
        print(f"[INFO] Launching the run's pinned executables ({build}).")
        return existing
    if not resolve_executable_pinning(args, workspace_root):
        return {}
    recorded = pin_run_executables(run_dir, revision)
    if not recorded:
        return {}
    first = next(iter(recorded.values()))
    build = first.get("build_id") or "build identity unavailable"
    print(f"[INFO] Pinned {', '.join(sorted(recorded))} into "
          f"{os.path.dirname(first['path'])}/ ({build}).")
    return load_run_executables(run_dir)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

archive_active_generated_configuration()

dict picurv_cli.core.archive_active_generated_configuration	(	str	run_dir,
		list	paths
	)

Preserve generated control sidecars beside a continuation's YAML revision.

Parameters

[in]	run_dir	Owning run.
[in]	paths	Generated control and sidecar paths.

Returns

Updated active configuration record.

Definition at line 1279 of file core.py.

def archive_active_generated_configuration(run_dir: str, paths: list) -> dict:
    """!
    @brief Preserve generated control sidecars beside a continuation's YAML revision.
    @param[in] run_dir Owning run.
    @param[in] paths Generated control and sidecar paths.
    @return Updated active configuration record.
    """
    config_root = os.path.join(os.path.abspath(run_dir), "config")
    active_path = os.path.join(config_root, "active.json")
    active = _read_json_if_exists(active_path) or {"schema_version": 1, "revision": "initial", "files": {}}
    revision = active.get("revision", "initial")
    target_root = config_root if revision == "initial" else os.path.join(config_root, "history", revision)
    os.makedirs(target_root, exist_ok=True)
    files = active.setdefault("files", {})
    for source in paths:
        if not source or not os.path.isfile(source):
            continue
        source = os.path.abspath(source)
        destination = os.path.join(target_root, os.path.basename(source))
        if source != destination:
            shutil.copy2(source, destination)
        relative = os.path.relpath(destination, run_dir).replace(os.sep, "/")
        if destination.endswith(".control"):
            files["control"] = relative
        else:
            files.setdefault("generated", []).append(relative)
    active["updated_at"] = datetime.now().astimezone().isoformat()
    write_json_file(active_path, active)
    return active
 
 
#: Storage states in which a run's heavy payload is no longer wholly local. A component
#: absent under one of these was archived, not skipped.

Here is the call graph for this function:

Here is the caller graph for this function:

_run_component_states()

dict picurv_cli.core._run_component_states ( str  run_dir, dict  stages_requested  )

protected

Report each run component's home, retention class, and lifecycle state.

The skeleton is created whole, so an empty directory says nothing about whether its contents were requested. This is where that question is answered, and it is answered for every component whether or not it ran.

Parameters

[in]	run_dir	Run directory being described.
[in]	stages_requested	Mapping of requested stage names to booleans.

Returns

Component name to {path, retention, state} mapping.

Definition at line 1333 of file core.py.

def _run_component_states(run_dir: str, stages_requested: dict) -> dict:
    """!
    @brief Report each run component's home, retention class, and lifecycle state.
 
    @details The skeleton is created whole, so an empty directory says nothing about
             whether its contents were requested. This is where that question is
             answered, and it is answered for every component whether or not it ran.
    @param[in] run_dir Run directory being described.
    @param[in] stages_requested Mapping of requested stage names to booleans.
    @return Component name to `{path, retention, state}` mapping.
    """
    marker = storage_state_summary(run_dir) if os.path.isdir(run_dir) else {"state": "LOCAL"}
    offloaded = marker.get("state") in STORAGE_OFFLOADED_STATES
    solve_requested = bool(stages_requested.get("solve"))
    post_requested = bool(stages_requested.get("post_process"))
    requested = {
        "configuration": True,
        "inputs": True,
        "logs": True,
        "scheduler": True,
        "checkpoints": solve_requested,
        "analysis": post_requested,
        "field_statistics": post_requested,
        "spectra": post_requested,
        "visualization": post_requested,
    }
    components = {}
    for name, relative, retention in RUN_COMPONENT_LAYOUT:
        path = os.path.join(run_dir, *relative.split("/"))
        populated = False
        if os.path.isdir(path):
            populated = any(files for _root, _dirs, files in os.walk(path))
        if populated:
            state = "offloaded" if offloaded and retention != "essential" else "complete"
        elif not requested.get(name, False):
            state = "not_requested"
        elif offloaded:
            state = "offloaded"
        else:
            state = "planned"
        components[name] = {"path": relative, "retention": retention, "state": state}
    return components
 
 

Here is the caller graph for this function:

build_run_lineage()

dict picurv_cli.core.build_run_lineage	(	str	parent_run_dir,
		int	checkpoint_step,
		*	workspace_root = None,
			statistics_state = None,
			requested_source = None
	)

Record which run and which checkpoint a branched run was started from.

Without this a branch is indistinguishable from a fresh run: the copied bundle under inputs/restart/ carries the parent's geometry and software identity but never says which run produced it, so the trajectory a result belongs to cannot be reconstructed after the fact.

The parent's own manifest is asked for its identity rather than its directory name, so a parent that was renamed or restored under another name is still named correctly here.

Parameters

[in]	parent_run_dir	Absolute path to the run being branched from.
[in]	checkpoint_step	Checkpoint step the branch starts from.
[in]	workspace_root	Optional workspace root, to record a portable path.
[in]	statistics_state	Resolved field-statistics decision for the branch.
[in]	requested_source	What the user asked for, e.g. "latest" or a path.

Returns

JSON-serializable lineage record.

Definition at line 1377 of file core.py.

                      statistics_state=None, requested_source=None) -> dict:
    """!
    @brief Record which run and which checkpoint a branched run was started from.
 
    @details Without this a branch is indistinguishable from a fresh run: the copied
             bundle under `inputs/restart/` carries the parent's geometry and software
             identity but never says which run produced it, so the trajectory a result
             belongs to cannot be reconstructed after the fact.
 
             The parent's own manifest is asked for its identity rather than its
             directory name, so a parent that was renamed or restored under another
             name is still named correctly here.
    @param[in] parent_run_dir Absolute path to the run being branched from.
    @param[in] checkpoint_step Checkpoint step the branch starts from.
    @param[in] workspace_root Optional workspace root, to record a portable path.
    @param[in] statistics_state Resolved field-statistics decision for the branch.
    @param[in] requested_source What the user asked for, e.g. "latest" or a path.
    @return JSON-serializable lineage record.
    """
    parent_identity = read_artifact_identity(parent_run_dir)
    return {
        "relationship": "branch",
        "parent_run_id": parent_identity["run_id"],
        "parent_study_id": parent_identity["study_id"] if parent_identity["case_id"] else None,
        "parent_case_id": parent_identity["case_id"],
        "parent_identity_source": parent_identity["identity_source"],
        "parent_path": _relative_to_workspace(parent_run_dir, workspace_root),
        "checkpoint_step": int(checkpoint_step),
        "statistics_state": statistics_state,
        "requested_source": requested_source,
        "recorded_at": datetime.now().astimezone().isoformat(),
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

build_run_manifest()

dict picurv_cli.core.build_run_manifest	(	str	run_dir,
		str	run_id,
		*	workspace_root = None,
		str	launch_mode = "local",
		int	num_procs = 1,
		int	post_num_procs = 1,
			stages_requested = None,
			stages_completed = None,
			inputs = None,
			asset_lock = None,
			submission = None,
			lineage = None,
		str	artifact_type = "run",
			study_id = None,
			case_id = None
	)

Build the authoritative run identity, topology, and lifecycle manifest.

Parameters

[in]	run_dir	Owning run directory.
[in]	run_id	Stable run identity.
[in]	workspace_root	Optional initialized workspace root.
[in]	launch_mode	Local or scheduler-backed launch mode.
[in]	num_procs	Effective solver process count.
[in]	post_num_procs	Effective post-process count.
[in]	stages_requested	Requested stage mapping.
[in]	stages_completed	Completed or submitted stage names.
[in]	inputs	Active configuration identities.
[in]	asset_lock	Resolved run asset lock.
[in]	submission	Scheduler submission metadata.
[in]	lineage	Where this run's initial state came from; see build_run_lineage().
[in]	artifact_type	"run" for a standalone run, "study-case" for a study member.
[in]	study_id	Owning study identity, for a study member.
[in]	case_id	Member identity within its study.

Returns

JSON-serializable run manifest.

Definition at line 1412 of file core.py.

                       study_id=None, case_id=None) -> dict:
    """!
    @brief Build the authoritative run identity, topology, and lifecycle manifest.
    @param[in] run_dir Owning run directory.
    @param[in] run_id Stable run identity.
    @param[in] workspace_root Optional initialized workspace root.
    @param[in] launch_mode Local or scheduler-backed launch mode.
    @param[in] num_procs Effective solver process count.
    @param[in] post_num_procs Effective post-process count.
    @param[in] stages_requested Requested stage mapping.
    @param[in] stages_completed Completed or submitted stage names.
    @param[in] inputs Active configuration identities.
    @param[in] asset_lock Resolved run asset lock.
    @param[in] submission Scheduler submission metadata.
    @param[in] lineage Where this run's initial state came from; see `build_run_lineage()`.
    @param[in] artifact_type "run" for a standalone run, "study-case" for a study member.
    @param[in] study_id Owning study identity, for a study member.
    @param[in] case_id Member identity within its study.
    @return JSON-serializable run manifest.
    """
    existing = _read_json_if_exists(os.path.join(run_dir, "manifest.json")) or {}
    created_at = existing.get("created_at") or datetime.now().astimezone().isoformat()
    # The manifest describes the run, not the latest invocation: a post-only pass over a
    # solved run keeps the solve it records, and each stage keeps the rank count it ran on.
    requested_now = dict(stages_requested or {})
    stages_requested = {stage: bool(requested_now.get(stage) or (existing.get("stages_requested") or {}).get(stage))
                        for stage in {**(existing.get("stages_requested") or {}), **requested_now}}
    stages_completed = list(dict.fromkeys(
        list(existing.get("stages_completed_or_submitted") or []) + list(stages_completed or [])))
    if not requested_now.get("solve") and "solver_num_procs" in existing:
        num_procs = existing["solver_num_procs"]
    if not requested_now.get("post_process") and "post_num_procs" in existing:
        post_num_procs = existing["post_num_procs"]
    payload = {
        "schema_version": RUN_MANIFEST_SCHEMA_VERSION,
        "artifact_type": artifact_type,
        "run_id": run_id,
        "study_id": study_id,
        "case_id": case_id,
        "created_at": created_at,
        "updated_at": datetime.now().astimezone().isoformat(),
        "workspace": (
            (load_workspace_config(workspace_root).get("workspace") or {})
            if workspace_root else None
        ),
        "software": dict(picurv_build()),
        # The conductor's identity says which source staged the run; the binaries'
        # says which build produced its checkpoints. They can differ - an edited C
        # tree that was never rebuilt - so provenance records both.
        "binaries": runtime_build_identities(run_dir=run_dir),
        "launch_mode": launch_mode,
        "num_procs": num_procs,
        "solver_num_procs": num_procs,
        "post_num_procs": post_num_procs,
        "stages_requested": stages_requested or {},
        "stages_completed_or_submitted": stages_completed or [],
        "inputs": inputs or {},
        "paths": dict(CANONICAL_RUN_PATHS),
        # Where the run lived when its files were generated; adopt_relocated_artifact()
        # compares it with where the run is now.
        "root_path": os.path.abspath(run_dir),
        # Fixed schema, every component present whatever happened, so a reader never
        # has to distinguish "absent because it was not asked for" from "absent because
        # it failed" by looking for empty directories.
        "components": _run_component_states(run_dir, stages_requested or {}),
        "assets": (asset_lock or {}).get("assets", {}),
        "runtime_providers": (asset_lock or {}).get("runtime_providers", {}),
        # Always present, so a reader distinguishes "this run began from nothing" from
        # "this manifest predates lineage" by the value rather than by the key's absence.
        # A re-staged continuation keeps the lineage recorded when the run was created:
        # what a run branched from does not change because it was resumed.
        "lineage": lineage or existing.get("lineage") or {"relationship": "root"},
        "submission": submission or {},
    }
    return payload
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_recorded_run_root()

picurv_cli.core._recorded_run_root ( str  run_dir )

protected

Return the location a run's generated files refer to.

Runs staged before the manifest recorded root_path are read from the active control file, whose generated input paths all start at the run root.

Parameters

[in]

run_dir

Current run directory.

Returns

Recorded absolute root, or None when it cannot be determined.

Definition at line 1494 of file core.py.

def _recorded_run_root(run_dir: str):
    """!
    @brief Return the location a run's generated files refer to.
    @details Runs staged before the manifest recorded `root_path` are read from the
             active control file, whose generated input paths all start at the run root.
    @param[in] run_dir Current run directory.
    @return Recorded absolute root, or None when it cannot be determined.
    """
    manifest = _read_json_if_exists(os.path.join(run_dir, "manifest.json")) or {}
    if manifest.get("root_path"):
        return manifest["root_path"]
    control = auto_identify_run_inputs(os.path.join(run_dir, CANONICAL_RUN_PATHS["config"]))[2]
    if not (control and os.path.isfile(control)):
        return None
    markers = tuple(f"/{CANONICAL_RUN_PATHS[key]}/" for key in ("config", "inputs"))
    with open(control, "r", encoding="utf-8", errors="replace") as stream:
        for line in stream:
            for token in line.split()[1:]:
                for marker in markers:
                    if not (token.startswith("/") and marker in token):
                        continue
                    candidate, rest = token.split(marker, 1)
                    # Only a path that names a file of this run identifies its old root;
                    # an external input that merely contains the same segment does not.
                    if os.path.exists(os.path.join(run_dir, marker.strip("/"), rest)):
                        return candidate
    return None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

adopt_relocated_artifact()

int picurv_cli.core.adopt_relocated_artifact	(	str	root,
		str	kind = "run",
		bool	dry_run = False
	)

Point a moved run's or study's generated files at where it now lives.

Generated control files, recipes, scheduler scripts, and case indexes hold absolute paths, so a run or study moved or copied to another directory would otherwise launch against its old location. The rewrite is the one a relocated storage restore applies, after which the recorded root is updated.

Parameters

[in]	root	Current run or study directory.
[in]	kind	"run" or "study".
[in]	dry_run	Report the relocation without rewriting anything.

Returns

Number of files rewritten (0 when the artifact has not moved).

Definition at line 1523 of file core.py.

def adopt_relocated_artifact(root: str, kind: str = "run", dry_run: bool = False) -> int:
    """!
    @brief Point a moved run's or study's generated files at where it now lives.
    @details Generated control files, recipes, scheduler scripts, and case indexes hold
             absolute paths, so a run or study moved or copied to another directory would
             otherwise launch against its old location. The rewrite is the one a
             relocated storage restore applies, after which the recorded root is updated.
    @param[in] root Current run or study directory.
    @param[in] kind "run" or "study".
    @param[in] dry_run Report the relocation without rewriting anything.
    @return Number of files rewritten (0 when the artifact has not moved).
    """
    root = os.path.abspath(root)
    if kind == "study":
        manifest_path = os.path.join(root, "study_manifest.json")
        recorded = ((_read_json_if_exists(manifest_path) or {}).get("paths") or {}).get("study_dir")
    else:
        manifest_path = os.path.join(root, "manifest.json")
        recorded = _recorded_run_root(root)
    if not recorded or os.path.realpath(recorded) == os.path.realpath(root) or recorded == root:
        return 0
    if dry_run:
        print(f"[WARNING] This {kind} was moved from {recorded}; a real invocation first updates "
              "its generated files to the new location.", file=sys.stderr)
        return 0
    changed = _rebase_restored_text_paths(root, [(recorded, root)])
    manifest = _read_json_if_exists(manifest_path)
    if isinstance(manifest, dict):
        if kind == "study":
            manifest.setdefault("paths", {})["study_dir"] = root
        else:
            manifest["root_path"] = root
        write_json_file(manifest_path, manifest)
    print(f"[INFO] This {kind} was moved from {recorded}; updated {len(changed)} generated "
          "file(s) to its new location.")
    return len(changed)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_checkpoint_bundle_path()

str picurv_cli.core._checkpoint_bundle_path ( str  source_dir, int  step  )

protected

Resolve a run/output root or an exact checkpoint bundle.

Parameters

[in]	source_dir	Run/output root or exact bundle path.
[in]	step	Checkpoint step to resolve.

Returns

Absolute path to the checkpoint bundle.

Definition at line 1561 of file core.py.

def _checkpoint_bundle_path(source_dir: str, step: int) -> str:
    """!
    @brief Resolve a run/output root or an exact checkpoint bundle.
    @param[in] source_dir Run/output root or exact bundle path.
    @param[in] step Checkpoint step to resolve.
    @return Absolute path to the checkpoint bundle.
    """
    source_dir = os.path.abspath(source_dir)
    if os.path.isfile(os.path.join(source_dir, "checkpoint.meta")):
        return source_dir
    return os.path.join(source_dir, "checkpoints", f"step_{step:0{CHECKPOINT_STEP_WIDTH}d}")
 
 

Here is the caller graph for this function:

_read_checkpoint_options()

dict picurv_cli.core._read_checkpoint_options ( str  metadata_path )

protected

Parse the deliberately small PETSc-options checkpoint manifest.

Parameters

[in]

metadata_path

Path to checkpoint.meta.

Returns

Mapping of option names to scalar text values.

Definition at line 1574 of file core.py.

def _read_checkpoint_options(metadata_path: str) -> dict:
    """!
    @brief Parse the deliberately small PETSc-options checkpoint manifest.
    @param[in] metadata_path Path to checkpoint.meta.
    @return Mapping of option names to scalar text values.
    """
    options = {}
    with open(metadata_path, "r", encoding="utf-8") as stream:
        for line_number, raw_line in enumerate(stream, start=1):
            tokens = shlex.split(raw_line, comments=True, posix=True)
            if not tokens:
                continue
            if len(tokens) != 2 or not tokens[0].startswith("-"):
                raise ValueError(
                    f"Invalid checkpoint metadata line {line_number} in {metadata_path}."
                )
            key = tokens[0][1:]
            if key in options:
                raise ValueError(f"Duplicate checkpoint metadata key '-{key}' in {metadata_path}.")
            options[key] = tokens[1]
    return options
 
 

Here is the caller graph for this function:

validate_committed_checkpoint()

dict picurv_cli.core.validate_committed_checkpoint	(	str	source_dir,
		int	step,
		bool	require_particles = False
	)

Validate one committed bundle using the same manifest contract as C.

Parameters

[in]	source_dir	Run/output root or exact bundle path.
[in]	step	Expected checkpoint step.
[in]	require_particles	Whether particle restart payloads are required.

Returns

Validated bundle path, metadata, and payload inventory.

Definition at line 1605 of file core.py.

def validate_committed_checkpoint(source_dir: str, step: int, require_particles: bool = False) -> dict:
    """!
    @brief Validate one committed bundle using the same manifest contract as C.
    @param[in] source_dir Run/output root or exact bundle path.
    @param[in] step Expected checkpoint step.
    @param[in] require_particles Whether particle restart payloads are required.
    @return Validated bundle path, metadata, and payload inventory.
    """
    bundle = _checkpoint_bundle_path(source_dir, step)
    metadata_path = os.path.join(bundle, "checkpoint.meta")
    commit_path = os.path.join(bundle, "COMMITTED")
    if not os.path.isfile(metadata_path) or not os.path.isfile(commit_path):
        raise ValueError(f"No committed checkpoint for step {step}: {bundle}")
 
    with open(commit_path, "r", encoding="ascii") as stream:
        expected_digest = stream.read().strip()
    if not re.fullmatch(r"[0-9a-fA-F]{64}", expected_digest):
        raise ValueError(f"Invalid checkpoint commit marker: {commit_path}")
    with open(metadata_path, "rb") as stream:
        actual_digest = hashlib.sha256(stream.read()).hexdigest()
    if actual_digest.lower() != expected_digest.lower():
        raise ValueError(f"Checkpoint metadata hash mismatch: {bundle}")
 
    options = _read_checkpoint_options(metadata_path)
    try:
        saved_version = int(options.get("checkpoint_version", "-1"))
        saved_step = int(options.get("checkpoint_step", "-1"))
        payload_count = int(options.get("checkpoint_payload_count", "-1"))
        particle_count = int(options.get("checkpoint_particle_count", "-1"))
        block_count = int(options.get("checkpoint_block_count", "-1"))
        float(options["checkpoint_time"])
    except (KeyError, TypeError, ValueError) as exc:
        raise ValueError(f"Checkpoint metadata is incomplete or malformed: {metadata_path}") from exc
    if options.get("checkpoint_format") != CHECKPOINT_FORMAT or saved_version != CHECKPOINT_VERSION:
        raise ValueError(f"Unsupported checkpoint format/version: {metadata_path}")
    if saved_step != step:
        raise ValueError(f"Checkpoint records step {saved_step}, expected {step}: {bundle}")
    # Checked once the command has selected its build; restart resolution validates before
    # selecting, and selection then takes this checkpoint's width, so the two agree.
    saved_index_bytes = int(options.get("checkpoint_petsc_index_bytes", "4"))
    solver_index_bytes = _SELECTED_PETSC_INDEX_BYTES or saved_index_bytes
    if saved_index_bytes != solver_index_bytes:
        raise CheckpointIndexWidthError(
            f"Checkpoint {bundle} was written by a PETSc with {8 * saved_index_bytes}-bit indices, but this "
            f"picurv drives a {8 * solver_index_bytes}-bit-index build ({resolve_runtime_executable('simulator')}). "
            f"Restart or post-process it with the PICurv built on a {8 * saved_index_bytes}-bit-index PETSc.")
    if payload_count <= 0 or particle_count < 0 or block_count <= 0:
        raise ValueError(f"Checkpoint inventory counts are invalid: {metadata_path}")
 
    payloads = []
    for index in range(payload_count):
        prefix = f"checkpoint_payload_{index}_"
        relative_path = options.get(prefix + "path")
        try:
            expected_bytes = int(options[prefix + "bytes"])
        except (KeyError, TypeError, ValueError) as exc:
            raise ValueError(f"Checkpoint payload {index} has invalid metadata: {metadata_path}") from exc
        if not relative_path or os.path.isabs(relative_path) or ".." in relative_path.split("/"):
            raise ValueError(f"Checkpoint payload {index} has an unsafe path: {relative_path!r}")
        payload_path = os.path.join(bundle, *relative_path.split("/"))
        if not os.path.isfile(payload_path) or os.path.getsize(payload_path) != expected_bytes:
            raise ValueError(f"Checkpoint payload is missing or truncated: {payload_path}")
        payloads.append({
            "path": relative_path,
            "kind": options.get(prefix + "kind"),
            "field": options.get(prefix + "field"),
            "block": options.get(prefix + "block"),
        })
 
    for block in range(block_count):
        fields = {
            item["field"] for item in payloads
            if item["kind"] == "eulerian" and item["block"] == str(block)
        }
        missing = CHECKPOINT_REQUIRED_EULERIAN_FIELDS - fields
        if missing:
            raise ValueError(
                f"Checkpoint block {block} is missing required Eulerian field(s): "
                f"{', '.join(sorted(missing))}."
            )
    particle_payloads = [item for item in payloads if item["kind"] == "particle"]
    has_particles = options.get("checkpoint_particles", "false").lower() == "true"
    if (not has_particles and particle_count != 0) or (has_particles and not particle_payloads):
        raise ValueError(f"Checkpoint particle inventory is inconsistent: {metadata_path}")
    if require_particles and not has_particles:
        raise ValueError(f"Checkpoint step {step} does not contain particle state: {bundle}")
 
    return {
        "bundle": bundle,
        "metadata": options,
        "payloads": payloads,
        "has_particles": has_particles,
        "particle_count": particle_count,
    }
 
 

Here is the caller graph for this function:

_scan_committed_checkpoint_steps()

"set[int]" picurv_cli.core._scan_committed_checkpoint_steps ( str  source_dir, bool   require_particles = False  )

protected

Return only fully validated, committed checkpoint steps.

Parameters

[in]	source_dir	Run/output root containing checkpoints.
[in]	require_particles	Whether particle restart payloads are required.

Returns

Set of valid committed step numbers.

Definition at line 1701 of file core.py.

def _scan_committed_checkpoint_steps(source_dir: str, require_particles: bool = False) -> "set[int]":
    """!
    @brief Return only fully validated, committed checkpoint steps.
    @param[in] source_dir Run/output root containing checkpoints.
    @param[in] require_particles Whether particle restart payloads are required.
    @return Set of valid committed step numbers.
    """
    checkpoints_dir = os.path.join(os.path.abspath(source_dir), "checkpoints")
    if not os.path.isdir(checkpoints_dir):
        return set()
    pattern = re.compile(rf"^step_(\d{{{CHECKPOINT_STEP_WIDTH}}})$")
    steps = set()
    for name in os.listdir(checkpoints_dir):
        match = pattern.fullmatch(name)
        if not match:
            continue
        step = int(match.group(1))
        try:
            validate_committed_checkpoint(source_dir, step, require_particles=require_particles)
        except CheckpointIndexWidthError:
            raise
        except ValueError:
            continue
        steps.add(step)
    return steps
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

parse_slurm_time_limit_to_seconds()

int picurv_cli.core.parse_slurm_time_limit_to_seconds

(

str

time_text

)

Parse a Slurm time-limit string into total seconds.

Parameters

[in]

time_text

Argument passed to parse_slurm_time_limit_to_seconds().

Returns

Value returned by parse_slurm_time_limit_to_seconds().

Definition at line 1728 of file core.py.

def parse_slurm_time_limit_to_seconds(time_text: str) -> int:
    """!
    @brief Parse a Slurm time-limit string into total seconds.
    @param[in] time_text Argument passed to `parse_slurm_time_limit_to_seconds()`.
    @return Value returned by `parse_slurm_time_limit_to_seconds()`.
    """
    text = str(time_text).strip()
    if not text:
        raise ValueError("time limit cannot be empty")
 
    days = 0
    clock_text = text
    if "-" in text:
        day_text, clock_text = text.split("-", 1)
        if not day_text.isdigit():
            raise ValueError(f"invalid day field '{day_text}'")
        days = int(day_text)
        if not clock_text:
            raise ValueError("missing time portion after day field")
 
    parts = clock_text.split(":")
    if len(parts) > 3:
        raise ValueError(f"unsupported time format '{time_text}'")
    if any(part == "" for part in parts):
        raise ValueError(f"malformed time field '{time_text}'")
    if any(not part.isdigit() for part in parts):
        raise ValueError(f"non-numeric time field '{time_text}'")
 
    nums = [int(part) for part in parts]
    if days > 0:
        if len(nums) == 1:
            hours, minutes, seconds = nums[0], 0, 0
        elif len(nums) == 2:
            hours, minutes = nums
            seconds = 0
        else:
            hours, minutes, seconds = nums
    else:
        if len(nums) == 1:
            hours, minutes, seconds = 0, nums[0], 0
        elif len(nums) == 2:
            hours = 0
            minutes, seconds = nums
        else:
            hours, minutes, seconds = nums
 
    if minutes >= 60 or seconds >= 60:
        raise ValueError(f"minutes and seconds must be < 60 in '{time_text}'")
    if days == 0 and len(nums) == 3 and hours < 0:
        raise ValueError(f"hours must be non-negative in '{time_text}'")
 
    total_seconds = (((days * 24) + hours) * 60 + minutes) * 60 + seconds
    if total_seconds <= 0:
        raise ValueError("time limit must be positive")
    return total_seconds
 
 

Here is the caller graph for this function:

resolve_walltime_guard_policy()

"dict | None" picurv_cli.core.resolve_walltime_guard_policy

(

"dict | None"

cluster_cfg

)

Resolve the effective Slurm walltime-guard policy for generated solver jobs.

Parameters

[in]

cluster_cfg

Argument passed to resolve_walltime_guard_policy().

Returns

Value returned by resolve_walltime_guard_policy().

Definition at line 1785 of file core.py.

def resolve_walltime_guard_policy(cluster_cfg: "dict | None") -> "dict | None":
    """!
    @brief Resolve the effective Slurm walltime-guard policy for generated solver jobs.
    @param[in] cluster_cfg Argument passed to `resolve_walltime_guard_policy()`.
    @return Value returned by `resolve_walltime_guard_policy()`.
    """
    if not isinstance(cluster_cfg, dict):
        return None
 
    scheduler = cluster_cfg.get("scheduler", {}) or {}
    if str(scheduler.get("type", "slurm")).lower() != "slurm":
        return None
 
    execution = cluster_cfg.get("execution", {}) or {}
    guard_cfg = execution.get("walltime_guard")
    if guard_cfg is None:
        guard_cfg = {}
    elif not isinstance(guard_cfg, dict):
        raise ValueError("execution.walltime_guard must be a mapping when provided")
 
    policy = copy.deepcopy(DEFAULT_WALLTIME_GUARD_POLICY)
    policy.update(guard_cfg)
    policy["enabled"] = bool(policy["enabled"])
    policy["warmup_steps"] = int(policy["warmup_steps"])
    policy["multiplier"] = float(policy["multiplier"])
    policy["min_seconds"] = float(policy["min_seconds"])
    policy["estimator_alpha"] = float(policy["estimator_alpha"])
    return policy
 
 

Here is the caller graph for this function:

build_walltime_guard_exports()

dict picurv_cli.core.build_walltime_guard_exports

(

"dict | None"

cluster_cfg

)

Build shell-evaluated environment exports for the runtime walltime guard.

Parameters

[in]

cluster_cfg

Argument passed to build_walltime_guard_exports().

Returns

Value returned by build_walltime_guard_exports().

Definition at line 1815 of file core.py.

def build_walltime_guard_exports(cluster_cfg: "dict | None") -> dict:
    """!
    @brief Build shell-evaluated environment exports for the runtime walltime guard.
    @param[in] cluster_cfg Argument passed to `build_walltime_guard_exports()`.
    @return Value returned by `build_walltime_guard_exports()`.
    """
    policy = resolve_walltime_guard_policy(cluster_cfg)
    if not policy or not policy.get("enabled", False):
        return {}
    walltime_limit_seconds = parse_slurm_time_limit_to_seconds(cluster_cfg.get("resources", {}).get("time", ""))
    return {
        WALLTIME_GUARD_ENV_JOB_START_EPOCH: "$(date +%s)",
        WALLTIME_GUARD_ENV_LIMIT_SECONDS: str(walltime_limit_seconds),
    }
 
#: PetscInt width of the build the current command drives, chosen once per command by
#: `select_petsc_index_bytes()`; None keeps the default 32-bit `simulator`/`postprocessor`.

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_runtime_executable()

str picurv_cli.core.resolve_runtime_executable

(

str

executable_name

)

Resolve solver/post executable path, preferring local sibling binaries.

A command that selected the 64-bit-index build resolves simulator64 and postprocessor64, which make INDEX_BITS=64 installs beside the 32-bit pair.

Parameters

[in]

executable_name

simulator or postprocessor.

Returns

Absolute executable path.

Definition at line 1835 of file core.py.

def resolve_runtime_executable(executable_name: str) -> str:
    """!
    @brief Resolve solver/post executable path, preferring local sibling binaries.
    @details A command that selected the 64-bit-index build resolves `simulator64` and
             `postprocessor64`, which `make INDEX_BITS=64` installs beside the 32-bit pair.
    @param[in] executable_name `simulator` or `postprocessor`.
    @return Absolute executable path.
    """
    if _SELECTED_PETSC_INDEX_BYTES == 8 and executable_name in RUN_EXECUTABLE_NAMES:
        executable_name += "64"
    local_candidate = os.path.join(INVOKED_SCRIPT_DIR, executable_name)
    if os.path.isfile(local_candidate):
        return os.path.abspath(local_candidate)
    return os.path.join(DEFAULT_BIN_DIR, executable_name)
 
 
#: Identity a native executable prints for `--version`:
#: `<name> <release>[.dev<N>]+g<commit>[.dirty]`; executables built before the `.dev<N>` stamp omit it.

Here is the caller graph for this function:

_parse_binary_petsc_line()

"dict | None" picurv_cli.core._parse_binary_petsc_line ( str  line )

protected

Parse the PETSc build line a native executable reports.

Parameters

[in]

line

petsc <version> <debug|optimized> [int32|int64] <arch> <dir>.

Returns

Mapping with version, mode, indices, arch, and dir, or None when the line is not one. A binary built before the index width was stamped is 32-bit; indices_stamped records whether the line named it, so the line can be rebuilt exactly.

Definition at line 1868 of file core.py.

def _parse_binary_petsc_line(line: str) -> "dict | None":
    """!
    @brief Parse the PETSc build line a native executable reports.
    @param[in] line `petsc <version> <debug|optimized> [int32|int64] <arch> <dir>`.
    @return Mapping with version, mode, indices, arch, and dir, or None when the line is not
            one. A binary built before the index width was stamped is 32-bit; `indices_stamped`
            records whether the line named it, so the line can be rebuilt exactly.
    """
    match = _BINARY_PETSC_PATTERN.match((line or "").strip())
    if not match:
        return None
    parsed = {key: match.group(key) for key in ("version", "mode", "arch", "dir")}
    parsed["indices_stamped"] = match.group("indices") is not None
    parsed["indices"] = match.group("indices") or "int32"
    return parsed
 
 

Here is the caller graph for this function:

read_binary_petsc_stamp()

"dict | None" picurv_cli.core.read_binary_petsc_stamp

(

str

executable_path

)

Read the PETSc build stamp from an executable's bytes, without running it.

A binary built against one PETSc and started against another cannot run --version at all, which is exactly when knowing its PETSc matters.

Parameters

[in]

executable_path

Path to simulator or postprocessor.

Returns

The parsed stamp, or None when the file carries none (built before it existed).

Definition at line 1885 of file core.py.

def read_binary_petsc_stamp(executable_path: str) -> "dict | None":
    """!
    @brief Read the PETSc build stamp from an executable's bytes, without running it.
    @details A binary built against one PETSc and started against another cannot run
             `--version` at all, which is exactly when knowing its PETSc matters.
    @param[in] executable_path Path to `simulator` or `postprocessor`.
    @return The parsed stamp, or None when the file carries none (built before it existed).
    """
    try:
        with open(executable_path, "rb") as stream:
            data = stream.read()
    except OSError:
        return None
    start = data.find(_BINARY_PETSC_STAMP_MARKER)
    if start < 0:
        return None
    start += len(_BINARY_PETSC_STAMP_MARKER)
    text = data[start:start + 4096].split(b"\0", 1)[0].split(b"\n", 1)[0]
    return _parse_binary_petsc_line(text.decode("utf-8", errors="replace"))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolved_petsc_library()

"str | None" picurv_cli.core.resolved_petsc_library

(

str

executable_path

)

The PETSc shared library the dynamic loader would give this executable when picurv launches it.

Uses ldd on the current shell's library path with the executable's own PETSc lib/ first, as launches and job scripts put it; returns None where ldd is unavailable or the executable links PETSc statically.

Parameters

[in]

executable_path

Path to simulator or postprocessor.

Returns

Absolute library path, not found, or None.

Definition at line 1906 of file core.py.

def resolved_petsc_library(executable_path: str) -> "str | None":
    """!
    @brief The PETSc shared library the dynamic loader would give this executable when picurv launches it.
    @details Uses `ldd` on the current shell's library path with the executable's own PETSc
             lib/ first, as launches and job scripts put it; returns None where `ldd` is
             unavailable or the executable links PETSc statically.
    @param[in] executable_path Path to `simulator` or `postprocessor`.
    @return Absolute library path, `not found`, or None.
    """
    ldd = shutil.which("ldd")
    if not ldd:
        return None
    env = dict(os.environ)
    library_dir = executable_petsc_library_dir(executable_path)
    if library_dir:
        env["LD_LIBRARY_PATH"] = os.pathsep.join(filter(None, (library_dir, env.get("LD_LIBRARY_PATH"))))
    try:
        result = subprocess.run([ldd, executable_path], text=True, capture_output=True,
                                timeout=20, check=False, env=env)
    except (OSError, subprocess.SubprocessError):
        return None
    for line in (result.stdout or "").splitlines():
        name, _, target = line.strip().partition("=>")
        if not name.strip().startswith("libpetsc"):
            continue
        target = target.strip()
        if target.startswith("not found"):
            return "not found"
        return target.split(" (")[0].strip() or None
    return None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

petsc_library_mismatch()

bool picurv_cli.core.petsc_library_mismatch	(	"dict | None"	petsc,
		"str | None"	library
	)

Whether the library the loader resolves lies outside the PETSc the binary was built against.

Parameters

[in]	petsc	Stamp from read_binary_petsc_stamp() or the --version line.
[in]	library	Path from resolved_petsc_library().

Returns

True only when both are known and the library is not under the build's tree.

Definition at line 1938 of file core.py.

def petsc_library_mismatch(petsc: "dict | None", library: "str | None") -> bool:
    """!
    @brief Whether the library the loader resolves lies outside the PETSc the binary was built against.
    @param[in] petsc Stamp from `read_binary_petsc_stamp()` or the `--version` line.
    @param[in] library Path from `resolved_petsc_library()`.
    @return True only when both are known and the library is not under the build's tree.
    """
    if not petsc or not petsc.get("dir") or not library:
        return False
    if library == "not found":
        return True
    build_root = os.path.realpath(os.path.join(petsc["dir"], petsc.get("arch") or ""))
    return not os.path.realpath(library).startswith(build_root.rstrip(os.sep) + os.sep)
 
 

Here is the caller graph for this function:

_read_binary_build_stamp()

"dict | None" picurv_cli.core._read_binary_build_stamp ( str  executable_path )

protected

Read the build identity stamped into an executable's bytes, without running it.

src/setup.c stores PICURV_BUILD:<version> <commit> <dirty> beside the PETSc stamp. Running --version on a login node starts the dynamic loader against a cold filesystem, tens of seconds; reading the file costs one read.

Parameters

[in]

executable_path

Path to simulator or postprocessor.

Returns

The identity mapping read_binary_build_identity() returns, or None for a binary built before the stamp existed.

Definition at line 1953 of file core.py.

def _read_binary_build_stamp(executable_path: str) -> "dict | None":
    """!
    @brief Read the build identity stamped into an executable's bytes, without running it.
    @details src/setup.c stores `PICURV_BUILD:<version> <commit> <dirty>` beside the PETSc
             stamp. Running `--version` on a login node starts the dynamic loader against a
             cold filesystem, tens of seconds; reading the file costs one read.
    @param[in] executable_path Path to `simulator` or `postprocessor`.
    @return The identity mapping `read_binary_build_identity()` returns, or None for a binary
            built before the stamp existed.
    """
    try:
        with open(executable_path, "rb") as stream:
            data = stream.read()
    except OSError:
        return None
    start = data.find(_BINARY_BUILD_STAMP_MARKER)
    if start < 0:
        return None
    fields = data[start + len(_BINARY_BUILD_STAMP_MARKER):start + 512].split(b"\0", 1)[0].decode(
        "utf-8", errors="replace").split()
    if len(fields) != 3 or not re.fullmatch(r"[0-9a-f]+", fields[1]) or fields[2] not in ("true", "false"):
        return None
    version, commit, dirty = fields[0], fields[1][:12], fields[2] == "true"
    release = re.sub(r"\.dev\d+$", "", version)
    petsc = read_binary_petsc_stamp(executable_path)
    if petsc is None:
        return None
    # Exactly what `--version` prints (src/setup.c), which the job-start check compares with.
    name = os.path.basename(executable_path)
    version_line = (f"{name} {version}+g{commit}{'.dirty' if dirty else ''}\n"
                    f"petsc {petsc['version']} {petsc['mode']}"
                    f"{' ' + petsc['indices'] if petsc.get('indices_stamped') else ''} {petsc['arch']} {petsc['dir']}")
    return {
        "available": True,
        "path": executable_path,
        "version_line": version_line,
        "release_version": release,
        "git_commit": commit,
        "dirty": dirty,
        "build_id": f"{version}+g{commit}{'.dirty' if dirty else ''}",
        "petsc": petsc,
        "identity_source": "stamp",
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

read_binary_build_identity()

dict picurv_cli.core.read_binary_build_identity

(

str

executable_path

)

Read the build identity a native executable was compiled with.

The Makefile stamps the release, commit, and dirty state into the binaries, and they are written into every checkpoint manifest. Reading it back is what makes the run manifest's provenance a statement about the binary that ran rather than about whatever source happens to be checked out when the conductor is invoked.

Parameters

[in]

executable_path

Path to simulator or postprocessor.

Returns

Identity mapping, or an available: False mapping when it cannot be read.

Definition at line 1998 of file core.py.

def read_binary_build_identity(executable_path: str) -> dict:
    """!
    @brief Read the build identity a native executable was compiled with.
 
    @details The Makefile stamps the release, commit, and dirty state into the
             binaries, and they are written into every checkpoint manifest. Reading it
             back is what makes the run manifest's provenance a statement about the
             binary that ran rather than about whatever source happens to be checked
             out when the conductor is invoked.
    @param[in] executable_path Path to `simulator` or `postprocessor`.
    @return Identity mapping, or an `available: False` mapping when it cannot be read.
    """
    if not os.path.isfile(executable_path) or not os.access(executable_path, os.X_OK):
        return {"available": False, "reason": "not built", "path": executable_path}
    stamped = _read_binary_build_stamp(executable_path)
    if stamped is not None:
        return stamped
    try:
        result = subprocess.run(
            [executable_path, "--version"], text=True, capture_output=True, timeout=30,
        )
    except (OSError, subprocess.SubprocessError) as exc:
        return {"available": False, "reason": str(exc), "path": executable_path}
    if result.returncode != 0:
        # A binary that cannot start - typically its shared libraries are not loadable
        # in this shell - is not the same failure as one that predates the identity
        # flag, and recording it as such hides a broken staging environment.
        detail = (result.stderr or result.stdout or "").strip().splitlines()
        return {"available": False,
                "reason": f"--version exited {result.returncode}"
                          + (f": {detail[0]}" if detail else ""),
                "path": executable_path,
                "petsc": read_binary_petsc_stamp(executable_path)}
    lines = (result.stdout or "").strip().splitlines()
    match = _BINARY_VERSION_PATTERN.match(lines[0] if lines else "")
    if not match:
        # A binary from before the identity flag existed, or a wrapper that prints
        # something else. Recorded as unavailable rather than guessed at.
        return {"available": False, "reason": "no build identity reported",
                "path": executable_path}
    return {
        "available": True,
        "path": executable_path,
        "version_line": (result.stdout or "").strip(),
        "release_version": match.group("release"),
        "git_commit": match.group("commit"),
        "dirty": bool(match.group("dirty")),
        "build_id": (
            f"{match.group('version')}+g{match.group('commit')}"
            f"{'.dirty' if match.group('dirty') else ''}"
        ),
        "petsc": _parse_binary_petsc_line(lines[1]) if len(lines) > 1 else None,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

runtime_build_identities()

dict picurv_cli.core.runtime_build_identities	(	"dict | None"	source_identity = None,
		"str | None"	run_dir = None
	)

Read the build identity of every native executable a run would launch.

Parameters

[in]	source_identity	Source identity to compare against; defaults to the identity this process computed at startup.
[in]	run_dir	Run whose pinned executables are read; the installation's when None, which also lists the 64-bit-index pair (simulator64, postprocessor64) when it is built.

Returns

Mapping of executable name to its identity, each carrying matches_source.

Definition at line 2053 of file core.py.

                             run_dir: "str | None" = None) -> dict:
    """!
    @brief Read the build identity of every native executable a run would launch.
    @param[in] source_identity Source identity to compare against; defaults to the
                               identity this process computed at startup.
    @param[in] run_dir Run whose pinned executables are read; the installation's when None,
                       which also lists the 64-bit-index pair (`simulator64`,
                       `postprocessor64`) when it is built.
    @return Mapping of executable name to its identity, each carrying `matches_source`.
    """
    source_identity = source_identity or picurv_build()
    identities = {}
    source_commit = str(source_identity.get("git_commit") or "")
    paths = {name: run_executable_path(run_dir, name) for name in RUN_EXECUTABLE_NAMES}
    if run_dir is None and _SELECTED_PETSC_INDEX_BYTES is None:
        for name in RUN_EXECUTABLE_NAMES:
            wide = os.path.join(os.path.dirname(paths[name]), name + "64")
            if os.path.isfile(wide):
                paths[name + "64"] = wide
    for name, path in paths.items():
        identity = read_binary_build_identity(path)
        if identity.get("available"):
            # The stamped commit is abbreviated, so compare on the prefix it carries.
            identity["matches_source"] = bool(
                source_commit
                and source_commit.startswith(identity["git_commit"])
                and identity["dirty"] == bool(source_identity.get("dirty"))
            )
        identities[name] = identity
    return identities
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

rebuild_command()

str picurv_cli.core.rebuild_command	(	str	name,
		dict	identity
	)

The command that rebuilds one native executable.

The 64-bit-index pair needs INDEX_BITS=64 and its own PETSc, named from the executable's PETSc stamp when it has one; a plain build makes the 32-bit pair.

Parameters

[in]	name	Executable name, such as simulator64.
[in]	identity	Identity mapping from read_binary_build_identity().

Returns

Shell command text.

Definition at line 2086 of file core.py.

def rebuild_command(name: str, identity: dict) -> str:
    """!
    @brief The command that rebuilds one native executable.
    @details The 64-bit-index pair needs `INDEX_BITS=64` and its own PETSc, named from the
             executable's PETSc stamp when it has one; a plain build makes the 32-bit pair.
    @param[in] name Executable name, such as `simulator64`.
    @param[in] identity Identity mapping from `read_binary_build_identity()`.
    @return Shell command text.
    """
    if not name.endswith("64"):
        return "picurv build"
    petsc = identity.get("petsc") or {}
    command = f"picurv build INDEX_BITS=64 PETSC_DIR={petsc.get('dir') or '<64-bit PETSc>'}"
    return command + (f" PETSC_ARCH={petsc['arch']}" if petsc.get("arch") else "")
 
 

Here is the caller graph for this function:

build_identity_problems()

list picurv_cli.core.build_identity_problems	(	dict	identities,
			workspace_requirement = None,
		"dict | None"	source_identity = None
	)

Report every reason the active build identity is not internally coherent.

The conductor, the simulator, and the postprocessor are three artifacts that must agree before a run's provenance means anything. This states the disagreements rather than printing them, so version status can exit on them while ordinary staging only warns.

Parameters

[in]	identities	Mapping returned by runtime_build_identities().
[in]	workspace_requirement	Optional software.picurv constraint to check.
[in]	source_identity	Source identity the executables must match; defaults to the identity this process computed at startup.

Returns

Human-readable problem descriptions; empty when the build is coherent.

Definition at line 2102 of file core.py.

                            source_identity: "dict | None" = None) -> list:
    """!
    @brief Report every reason the active build identity is not internally coherent.
 
    @details The conductor, the simulator, and the postprocessor are three artifacts
             that must agree before a run's provenance means anything. This states the
             disagreements rather than printing them, so `version status` can exit on
             them while ordinary staging only warns.
    @param[in] identities Mapping returned by `runtime_build_identities()`.
    @param[in] workspace_requirement Optional `software.picurv` constraint to check.
    @param[in] source_identity Source identity the executables must match; defaults to
                               the identity this process computed at startup.
    @return Human-readable problem descriptions; empty when the build is coherent.
    """
    source_identity = source_identity or picurv_build()
    problems = []
    for name, identity in sorted(identities.items()):
        if not identity.get("available"):
            problems.append(
                f"{name}: no build identity available ({identity.get('reason', 'unknown')}); "
                f"rebuild with '{rebuild_command(name, identity)}'."
            )
        elif not identity.get("matches_source"):
            problems.append(
                f"{name}: built from {identity['build_id']}, but the active source is "
                f"{source_identity['build_id']}; rebuild with '{rebuild_command(name, identity)}'."
            )
    if workspace_requirement not in (None, ""):
        try:
            from packaging.specifiers import SpecifierSet
            from packaging.version import Version
            requirement_text = str(workspace_requirement).strip()
            if not any(token in requirement_text for token in "<>=!~"):
                requirement_text = "==" + requirement_text
            satisfied = Version(PICURV_RELEASE_VERSION) in SpecifierSet(requirement_text)
        except Exception:
            problems.append(
                f"workspace: software.picurv={workspace_requirement!r} is not a valid "
                "version or version range."
            )
        else:
            if not satisfied:
                problems.append(
                    f"workspace: requires PICurv {workspace_requirement!r}, but the active "
                    f"release is {PICURV_RELEASE_VERSION}."
                )
    return problems
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

warn_on_stale_runtime_binaries()

list picurv_cli.core.warn_on_stale_runtime_binaries

(

dict

identities

)

Report native executables whose build identity is not the active source.

An executable whose identity cannot be read is reported too: the manifest would otherwise record "unavailable" for a run with no word at staging.

Parameters

[in]

identities

Mapping returned by runtime_build_identities().

Returns

Names of executables that disagree with the active source identity.

Definition at line 2152 of file core.py.

def warn_on_stale_runtime_binaries(identities: dict) -> list:
    """!
    @brief Report native executables whose build identity is not the active source.
    @details An executable whose identity cannot be read is reported too: the manifest
             would otherwise record "unavailable" for a run with no word at staging.
    @param[in] identities Mapping returned by `runtime_build_identities()`.
    @return Names of executables that disagree with the active source identity.
    """
    stale = [name for name, identity in sorted(identities.items())
             if identity.get("available") and not identity.get("matches_source")]
    for name in stale:
        print(
            f"[WARNING] {name} was built from {identities[name]['build_id']}, but the active "
            f"source is {picurv_build()['build_id']}. Checkpoints will record the binary's "
            f"identity, not the source's. Rebuild with '{rebuild_command(name, identities[name])}'.",
            file=sys.stderr,
        )
    for name, identity in sorted(identities.items()):
        if identity.get("available"):
            continue
        print(
            f"[WARNING] The build identity of {name} could not be read "
            f"({identity.get('reason', 'unknown')}); this run's manifest will not record "
            f"which build it used. Path: {identity.get('path')}",
            file=sys.stderr,
        )
    return stale
 
# Standardized error codes used for CLI/validation reporting.

Here is the caller graph for this function:

_sanitize_error_field()

str picurv_cli.core._sanitize_error_field (   value )

protected

Normalize error fields into a single-line string.

Parameters

[in]

value

Argument passed to _sanitize_error_field().

Returns

Value returned by _sanitize_error_field().

Definition at line 2218 of file core.py.

def _sanitize_error_field(value) -> str:
    """!
    @brief Normalize error fields into a single-line string.
    @param[in] value Argument passed to `_sanitize_error_field()`.
    @return Value returned by `_sanitize_error_field()`.
    """
    if value is None:
        return "-"
    text = str(value).strip()
    if not text:
        return "-"
    return " ".join(text.splitlines())
 
 

emit_structured_error()

picurv_cli.core.emit_structured_error	(	str	code,
		str	key = "-",
		str	file_path = "-",
		str	message = "",
		str	hint = None,
			stream = None
	)

Emit one standardized error line for tooling and users.

Parameters

[in]	code	Argument passed to emit_structured_error().
[in]	key	Argument passed to emit_structured_error().
[in]	file_path	Argument passed to emit_structured_error().
[in]	message	Argument passed to emit_structured_error().
[in]	hint	Argument passed to emit_structured_error().
[in]	stream	Argument passed to emit_structured_error().

Definition at line 2232 of file core.py.

                          message: str = "", hint: str = None, stream=None):
    """!
    @brief Emit one standardized error line for tooling and users.
    @param[in] code Argument passed to `emit_structured_error()`.
    @param[in] key Argument passed to `emit_structured_error()`.
    @param[in] file_path Argument passed to `emit_structured_error()`.
    @param[in] message Argument passed to `emit_structured_error()`.
    @param[in] hint Argument passed to `emit_structured_error()`.
    @param[in] stream Argument passed to `emit_structured_error()`.
    """
    if stream is None:
        stream = sys.stderr
    resolved_hint = hint if hint is not None else _ERROR_HINTS.get(code, "-")
    print(
        f"ERROR {_sanitize_error_field(code)} | "
        f"key={_sanitize_error_field(key)} | "
        f"file={_sanitize_error_field(file_path)} | "
        f"message={_sanitize_error_field(message)} | "
        f"hint={_sanitize_error_field(resolved_hint)}",
        file=stream,
    )
 
 

Here is the caller graph for this function:

fail_cli_usage()

picurv_cli.core.fail_cli_usage	(	str	message,
		str	hint = None
	)

Emit a structured CLI usage error and exit with code 2.

Without a hint, the default names the command the user ran.

Parameters

[in]	message	Argument passed to fail_cli_usage().
[in]	hint	Argument passed to fail_cli_usage().

Definition at line 2256 of file core.py.

def fail_cli_usage(message: str, hint: str = None):
    """!
    @brief Emit a structured CLI usage error and exit with code 2.
    @details Without a @p hint, the default names the command the user ran.
    @param[in] message Argument passed to `fail_cli_usage()`.
    @param[in] hint Argument passed to `fail_cli_usage()`.
    """
    command = next((token for token in sys.argv[1:] if not token.startswith("-")), "")
    emit_structured_error(
        ERROR_CODE_CLI_USAGE_INVALID,
        key="-",
        file_path="-",
        message=message,
        hint=hint or _ERROR_HINTS[ERROR_CODE_CLI_USAGE_INVALID].replace(
            "<command>", command if re.fullmatch(r"[a-z][a-z-]*", command) else "<command>"),
    )
    sys.exit(2)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_split_error_file_and_message()

picurv_cli.core._split_error_file_and_message ( str  raw_error )

protected

Separate a validation error into its source-file and message fields when possible.

Parameters

[in]

raw_error

Validation error text, optionally beginning with a file path and colon.

Returns

A pair containing the detected file path (or -) and the message text.

Definition at line 2275 of file core.py.

def _split_error_file_and_message(raw_error: str):
    """!
    @brief Separate a validation error into its source-file and message fields when possible.
    @param[in] raw_error Validation error text, optionally beginning with a file path and colon.
    @return A pair containing the detected file path (or ``-``) and the message text.
    """
    text = str(raw_error).strip()
    match = re.match(r"^(?P<file>[^:]+):\s*(?P<msg>.+)$", text)
    if not match:
        return "-", text
    file_candidate = match.group("file").strip()
    msg = match.group("msg").strip()
    known_suffixes = (".yml", ".yaml", ".cfg", ".picgrid", ".control", ".run", ".txt")
    if "/" in file_candidate or file_candidate.endswith(known_suffixes):
        return file_candidate, msg
    return "-", text
 
 

Here is the caller graph for this function:

_extract_key_path()

str picurv_cli.core._extract_key_path ( str  message )

protected

Best-effort key-path extraction from free-form validation messages.

Parameters

[in]

message

Argument passed to _extract_key_path().

Returns

Value returned by _extract_key_path().

Definition at line 2293 of file core.py.

def _extract_key_path(message: str) -> str:
    """!
    @brief Best-effort key-path extraction from free-form validation messages.
    @param[in] message Argument passed to `_extract_key_path()`.
    @return Value returned by `_extract_key_path()`.
    """
    dotted = re.search(r"\b([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z0-9_\[\]-]+)+)\b", message)
    if dotted:
        return dotted.group(1)
 
    bracketed = re.search(r"\b([A-Za-z_][A-Za-z0-9_]*\[[^\]]+\](?:\[[^\]]+\])*)\b", message)
    if bracketed:
        return bracketed.group(1)
 
    quoted = re.findall(r"'([A-Za-z0-9_.\[\]-]+)'", message)
    for token in quoted:
        if "." in token or "[" in token or token.isidentifier():
            return token
    return "-"
 
 

Here is the caller graph for this function:

_classify_error_code()

str picurv_cli.core._classify_error_code ( str  message )

protected

Map existing validation/error messages to the standardized code set.

Parameters

[in]

message

Argument passed to _classify_error_code().

Returns

Value returned by _classify_error_code().

Definition at line 2314 of file core.py.

def _classify_error_code(message: str) -> str:
    """!
    @brief Map existing validation/error messages to the standardized code set.
    @param[in] message Argument passed to `_classify_error_code()`.
    @return Value returned by `_classify_error_code()`.
    """
    msg = message.lower()
    if "missing required section" in msg:
        return ERROR_CODE_CFG_MISSING_SECTION
    if "missing required key" in msg or "missing key" in msg:
        return ERROR_CODE_CFG_MISSING_KEY
    if "not found" in msg or "does not exist" in msg:
        return ERROR_CODE_CFG_FILE_NOT_FOUND
    if "invalid dimensions line" in msg or "invalid coordinate row" in msg or "grid file" in msg:
        return ERROR_CODE_CFG_GRID_PARSE
    if (
        "must both be periodic" in msg
        or "inconsistent periodicity" in msg
        or "mismatch" in msg
        or "requires --" in msg
        or "must be 1 (auto) or exactly" in msg
    ):
        return ERROR_CODE_CFG_INCONSISTENT_COMBO
    if (
        "must be a mapping" in msg
        or "must be a list" in msg
        or "must be a string" in msg
        or "must be a boolean" in msg
        or "must be either" in msg
    ):
        return ERROR_CODE_CFG_INVALID_TYPE
    if "unsupported key" in msg or "unsupported top-level section" in msg:
        return ERROR_CODE_CFG_INVALID_VALUE
    return ERROR_CODE_CFG_INVALID_VALUE
 
# ==============================================================================
# HELPER FUNCTIONS
# ==============================================================================
 

Here is the caller graph for this function:

read_yaml_file()

dict picurv_cli.core.read_yaml_file

(

str

filepath

)

Safely reads a YAML file and returns its content.

Parameters

[in]

filepath

Path to the YAML file.

Returns

A dictionary containing the parsed YAML content.

Exceptions

SystemExit

if the file is not found or cannot be parsed.

Definition at line 2353 of file core.py.

def read_yaml_file(filepath: str) -> dict:
    """!
    @brief Safely reads a YAML file and returns its content.
    @param[in] filepath Path to the YAML file.
    @return A dictionary containing the parsed YAML content.
    @throws SystemExit if the file is not found or cannot be parsed.
    """
    if not os.path.exists(filepath):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="-",
            file_path=filepath,
            message="Configuration file not found.",
        )
        sys.exit(1)
    try:
        with open(filepath, 'r') as f:
            return yaml.safe_load(f)
    except yaml.YAMLError as e:
        emit_structured_error(
            ERROR_CODE_CFG_INVALID_VALUE,
            key="-",
            file_path=filepath,
            message=f"YAML parse error: {e}",
            hint="Fix YAML syntax/indentation and retry validation.",
        )
        sys.exit(1)
 

Here is the call graph for this function:

Here is the caller graph for this function:

write_yaml_file()

picurv_cli.core.write_yaml_file	(	str	filepath,
		dict	data
	)

Write YAML with stable ordering for generated study artifacts.

Parameters

[in]	filepath	Argument passed to write_yaml_file().
[in]	data	Argument passed to write_yaml_file().

Definition at line 2381 of file core.py.

def write_yaml_file(filepath: str, data: dict):
    """!
    @brief Write YAML with stable ordering for generated study artifacts.
    @param[in] filepath Argument passed to `write_yaml_file()`.
    @param[in] data Argument passed to `write_yaml_file()`.
    """
    path = os.path.abspath(filepath)
    os.makedirs(os.path.dirname(path), exist_ok=True)
    temporary = f"{path}.tmp.{os.getpid()}"
    with open(temporary, "w") as f:
        yaml.safe_dump(data, f, sort_keys=False)
        f.flush()
        os.fsync(f.fileno())
    os.replace(temporary, path)
 

Here is the caller graph for this function:

write_json_file()

picurv_cli.core.write_json_file	(	str	filepath,
		dict	payload
	)

Write JSON metadata/manifests with a stable, readable format.

Parameters

[in]	filepath	Argument passed to write_json_file().
[in]	payload	Argument passed to write_json_file().

Definition at line 2396 of file core.py.

def write_json_file(filepath: str, payload: dict):
    """!
    @brief Write JSON metadata/manifests with a stable, readable format.
    @param[in] filepath Argument passed to `write_json_file()`.
    @param[in] payload Argument passed to `write_json_file()`.
    """
    path = os.path.abspath(filepath)
    os.makedirs(os.path.dirname(path), exist_ok=True)
    temporary = f"{path}.tmp.{os.getpid()}"
    with open(temporary, "w") as f:
        json.dump(payload, f, indent=2, sort_keys=True)
        f.write("\n")
        f.flush()
        os.fsync(f.fileno())
    os.replace(temporary, path)
 
 

Here is the caller graph for this function:

write_runtime_execution_file()

str picurv_cli.core.write_runtime_execution_file	(	str	filepath,
		str	template_source_path = None
	)

Write a default runtime execution config, copying a source template when available.

Parameters

[in]	filepath	Argument passed to write_runtime_execution_file().
[in]	template_source_path	Argument passed to write_runtime_execution_file().

Returns

Value returned by write_runtime_execution_file().

Definition at line 2413 of file core.py.

def write_runtime_execution_file(filepath: str, template_source_path: str = None) -> str:
    """!
    @brief Write a default runtime execution config, copying a source template when available.
    @param[in] filepath Argument passed to `write_runtime_execution_file()`.
    @param[in] template_source_path Argument passed to `write_runtime_execution_file()`.
    @return Value returned by `write_runtime_execution_file()`.
    """
    os.makedirs(os.path.dirname(filepath), exist_ok=True)
 
    if template_source_path and os.path.isfile(template_source_path):
        shutil.copy2(template_source_path, filepath)
        return filepath
 
    with open(filepath, "w", encoding="utf-8") as f:
        f.write(DEFAULT_RUNTIME_EXECUTION_CONFIG_TEMPLATE)
    return filepath
 
 

Here is the caller graph for this function:

_launcher_arg_contains_whitespace()

bool picurv_cli.core._launcher_arg_contains_whitespace (   token )

protected

Return True when a launcher arg token contains embedded whitespace and should be split.

Parameters

[in]

token

Argument passed to _launcher_arg_contains_whitespace().

Returns

Value returned by _launcher_arg_contains_whitespace().

Definition at line 2431 of file core.py.

def _launcher_arg_contains_whitespace(token) -> bool:
    """!
    @brief Return True when a launcher arg token contains embedded whitespace and should be split.
    @param[in] token Argument passed to `_launcher_arg_contains_whitespace()`.
    @return Value returned by `_launcher_arg_contains_whitespace()`.
    """
    return isinstance(token, str) and any(ch.isspace() for ch in token.strip())
 
 

Here is the caller graph for this function:

resolve_runtime_execution_seed_source()

"str | None" picurv_cli.core.resolve_runtime_execution_seed_source

(

str

source_project_root

)

Prefer repo-local ignored runtime config, then tracked example, then built-in defaults.

Parameters

[in]

source_project_root

Argument passed to resolve_runtime_execution_seed_source().

Returns

Value returned by resolve_runtime_execution_seed_source().

Definition at line 2440 of file core.py.

def resolve_runtime_execution_seed_source(source_project_root: str) -> "str | None":
    """!
    @brief Prefer repo-local ignored runtime config, then tracked example, then built-in defaults.
    @param[in] source_project_root Argument passed to `resolve_runtime_execution_seed_source()`.
    @return Value returned by `resolve_runtime_execution_seed_source()`.
    """
    source_root_abs = os.path.abspath(source_project_root)
    repo_local_runtime = os.path.join(source_root_abs, RUNTIME_EXECUTION_CONFIG_FILENAME)
    if os.path.isfile(repo_local_runtime):
        return repo_local_runtime
 
    tracked_example = os.path.join(
        source_root_abs,
        "config",
        "runtime",
        RUNTIME_EXECUTION_EXAMPLE_FILENAME,
    )
    if os.path.isfile(tracked_example):
        return tracked_example
    return None
 
 

Here is the caller graph for this function:

ensure_case_runtime_execution_config()

dict picurv_cli.core.ensure_case_runtime_execution_config	(	str	case_dir,
		str	source_project_root,
		bool	overwrite = False
	)

Create case-local runtime execution config if missing, seeded from repo-local config when available.

Parameters

[in]	case_dir	Argument passed to ensure_case_runtime_execution_config().
[in]	source_project_root	Argument passed to ensure_case_runtime_execution_config().
[in]	overwrite	Argument passed to ensure_case_runtime_execution_config().

Returns

Value returned by ensure_case_runtime_execution_config().

Definition at line 2462 of file core.py.

def ensure_case_runtime_execution_config(case_dir: str, source_project_root: str, overwrite: bool = False) -> dict:
    """!
    @brief Create case-local runtime execution config if missing, seeded from repo-local config when available.
    @param[in] case_dir Argument passed to `ensure_case_runtime_execution_config()`.
    @param[in] source_project_root Argument passed to `ensure_case_runtime_execution_config()`.
    @param[in] overwrite Argument passed to `ensure_case_runtime_execution_config()`.
    @return Value returned by `ensure_case_runtime_execution_config()`.
    """
    case_dir_abs = os.path.abspath(case_dir)
    dest_path = os.path.join(case_dir_abs, RUNTIME_EXECUTION_CONFIG_FILENAME)
    if os.path.exists(dest_path) and not overwrite:
        return {
            "path": dest_path,
            "created": False,
            "seed_source": None,
        }
 
    seed_source = resolve_runtime_execution_seed_source(source_project_root)
    write_runtime_execution_file(dest_path, seed_source)
    return {
        "path": dest_path,
        "created": True,
        "seed_source": seed_source,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

is_project_root()

bool picurv_cli.core.is_project_root

(

str

candidate

)

Return True when a directory looks like the PICurv source repository root.

Parameters

[in]

candidate

Argument passed to is_project_root().

Returns

Value returned by is_project_root().

Definition at line 2488 of file core.py.

def is_project_root(candidate: str) -> bool:
    """!
    @brief Return True when a directory looks like the PICurv source repository root.
    @param[in] candidate Argument passed to `is_project_root()`.
    @return Value returned by `is_project_root()`.
    """
    if not candidate:
        return False
    candidate_abs = os.path.abspath(candidate)
    return (
        os.path.isfile(os.path.join(candidate_abs, "Makefile"))
        and os.path.isdir(os.path.join(candidate_abs, "src"))
        and os.path.isdir(os.path.join(candidate_abs, "include"))
        and os.path.isdir(os.path.join(candidate_abs, "picurv_cli"))
    )
 
 

Here is the caller graph for this function:

_iter_parent_dirs()

picurv_cli.core._iter_parent_dirs ( str  start_path )

protected

Yield a path and all of its parents up to filesystem root.

Parameters

[in]

start_path

Argument passed to _iter_parent_dirs().

Definition at line 2505 of file core.py.

def _iter_parent_dirs(start_path: str):
    """!
    @brief Yield a path and all of its parents up to filesystem root.
    @param[in] start_path Argument passed to `_iter_parent_dirs()`.
    """
    current = os.path.abspath(start_path)
    if os.path.isfile(current):
        current = os.path.dirname(current)
    while True:
        yield current
        parent = os.path.dirname(current)
        if parent == current:
            break
        current = parent
 
 

Here is the caller graph for this function:

find_project_root_upwards()

picurv_cli.core.find_project_root_upwards

(

str

start_path

)

Search upward from an anchor and return the first matching project root.

Parameters

[in]

start_path

Argument passed to find_project_root_upwards().

Returns

Value returned by find_project_root_upwards().

Definition at line 2521 of file core.py.

def find_project_root_upwards(start_path: str):
    """!
    @brief Search upward from an anchor and return the first matching project root.
    @param[in] start_path Argument passed to `find_project_root_upwards()`.
    @return Value returned by `find_project_root_upwards()`.
    """
    if not start_path:
        return None
    for directory in _iter_parent_dirs(start_path):
        if is_project_root(directory):
            return directory
    return None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

discover_local_project_root()

picurv_cli.core.discover_local_project_root

(

*

extra_anchors

)

Best-effort source repo discovery from runtime anchors.

Parameters

[in]

extra_anchors

Argument passed to discover_local_project_root().

Returns

Value returned by discover_local_project_root().

Definition at line 2535 of file core.py.

def discover_local_project_root(*extra_anchors):
    """!
    @brief Best-effort source repo discovery from runtime anchors.
    @param[in] extra_anchors Argument passed to `discover_local_project_root()`.
    @return Value returned by `discover_local_project_root()`.
    """
    anchors = list(extra_anchors) + [os.getcwd(), INVOKED_SCRIPT_DIR, SCRIPT_PATH, PROJECT_ROOT]
    seen = set()
    for anchor in anchors:
        if not anchor:
            continue
        anchor_abs = os.path.abspath(anchor)
        if anchor_abs in seen:
            continue
        seen.add(anchor_abs)
        project_root = find_project_root_upwards(anchor_abs)
        if project_root:
            return project_root
    return None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

find_case_origin_metadata_file()

picurv_cli.core.find_case_origin_metadata_file

(

str

case_dir_hint = None

)

Find the nearest case-origin metadata file from known runtime anchors.

An explicit case directory is the only anchor searched, so a wrong one cannot fall back to the case in the working directory.

Parameters

[in]

case_dir_hint

Argument passed to find_case_origin_metadata_file().

Returns

Value returned by find_case_origin_metadata_file().

Exceptions

ValueError

when case_dir_hint is given but is not a directory.

Definition at line 2556 of file core.py.

def find_case_origin_metadata_file(case_dir_hint: str = None):
    """!
    @brief Find the nearest case-origin metadata file from known runtime anchors.
    @details An explicit case directory is the only anchor searched, so a wrong one cannot
             fall back to the case in the working directory.
    @param[in] case_dir_hint Argument passed to `find_case_origin_metadata_file()`.
    @return Value returned by `find_case_origin_metadata_file()`.
    @throws ValueError when @p case_dir_hint is given but is not a directory.
    """
    if case_dir_hint and not os.path.isdir(case_dir_hint):
        raise ValueError(f"Case directory does not exist: {os.path.abspath(case_dir_hint)}")
    search_roots = []
    for candidate in (case_dir_hint,) if case_dir_hint else (os.getcwd(), INVOKED_SCRIPT_DIR):
        if not candidate:
            continue
        abs_candidate = os.path.abspath(candidate)
        if abs_candidate not in search_roots:
            search_roots.append(abs_candidate)
 
    for root in search_roots:
        for directory in _iter_parent_dirs(root):
            metadata_path = os.path.join(directory, CASE_ORIGIN_METADATA_FILENAME)
            if os.path.isfile(metadata_path):
                return metadata_path
    return None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

load_case_origin_metadata()

picurv_cli.core.load_case_origin_metadata

(

str

case_dir_hint = None

)

Load case-origin metadata if present, returning (case_dir, metadata_path, payload).

Parameters

[in]

case_dir_hint

Argument passed to load_case_origin_metadata().

Returns

Value returned by load_case_origin_metadata().

Definition at line 2583 of file core.py.

def load_case_origin_metadata(case_dir_hint: str = None):
    """!
    @brief Load case-origin metadata if present, returning (case_dir, metadata_path, payload).
    @param[in] case_dir_hint Argument passed to `load_case_origin_metadata()`.
    @return Value returned by `load_case_origin_metadata()`.
    """
    metadata_path = find_case_origin_metadata_file(case_dir_hint)
    if not metadata_path:
        return None, None, None
    try:
        with open(metadata_path, "r", encoding="utf-8") as f:
            payload = json.load(f)
        if not isinstance(payload, dict):
            raise ValueError("Case origin metadata must be a JSON object.")
    except Exception as exc:
        raise ValueError(f"Failed to read case origin metadata at {metadata_path}: {exc}") from exc
    return os.path.dirname(metadata_path), metadata_path, payload
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

find_runtime_execution_config_file()

picurv_cli.core.find_runtime_execution_config_file

(

*

anchors

)

Find the nearest optional execution config from runtime/case anchors.

Parameters

[in]

anchors

Argument passed to find_runtime_execution_config_file().

Returns

Value returned by find_runtime_execution_config_file().

Definition at line 2602 of file core.py.

def find_runtime_execution_config_file(*anchors):
    """!
    @brief Find the nearest optional execution config from runtime/case anchors.
    @param[in] anchors Argument passed to `find_runtime_execution_config_file()`.
    @return Value returned by `find_runtime_execution_config_file()`.
    """
    seen = set()
    search_roots = []
    for candidate in list(anchors) + [os.getcwd(), INVOKED_SCRIPT_DIR]:
        if not candidate:
            continue
        current = os.path.abspath(candidate)
        if os.path.isfile(current):
            current = os.path.dirname(current)
        if current in seen:
            continue
        seen.add(current)
        search_roots.append(current)
 
    seen_dirs = set()
    for root in search_roots:
        for directory in _iter_parent_dirs(root):
            if directory in seen_dirs:
                continue
            seen_dirs.add(directory)
            for filename in RUNTIME_EXECUTION_CONFIG_FILENAMES:
                config_path = os.path.join(directory, filename)
                if os.path.isfile(config_path):
                    return config_path
    return None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_normalize_execution_override_section()

dict picurv_cli.core._normalize_execution_override_section ( dict  payload, str  section_name, str  config_path, str  config_label  )

protected

Validate one execution override section while preserving missing-vs-empty semantics.

Parameters

[in]	payload	Argument passed to _normalize_execution_override_section().
[in]	section_name	Argument passed to _normalize_execution_override_section().
[in]	config_path	Argument passed to _normalize_execution_override_section().
[in]	config_label	Argument passed to _normalize_execution_override_section().

Returns

Value returned by _normalize_execution_override_section().

Definition at line 2634 of file core.py.

def _normalize_execution_override_section(payload: dict, section_name: str, config_path: str, config_label: str) -> dict:
    """!
    @brief Validate one execution override section while preserving missing-vs-empty semantics.
    @param[in] payload Argument passed to `_normalize_execution_override_section()`.
    @param[in] section_name Argument passed to `_normalize_execution_override_section()`.
    @param[in] config_path Argument passed to `_normalize_execution_override_section()`.
    @param[in] config_label Argument passed to `_normalize_execution_override_section()`.
    @return Value returned by `_normalize_execution_override_section()`.
    """
    section = payload.get(section_name)
    if section is None:
        return {"launcher": None, "launcher_args": None}
    if not isinstance(section, dict):
        raise ValueError(f"{config_label} at {config_path}: {section_name} must be a mapping.")
 
    launcher = section.get("launcher")
    if launcher is not None and not isinstance(launcher, str):
        raise ValueError(f"{config_label} at {config_path}: {section_name}.launcher must be a string.")
 
    launcher_args = None
    if "launcher_args" in section:
        launcher_args = section.get("launcher_args", [])
        if launcher_args is None:
            launcher_args = []
        if not isinstance(launcher_args, list):
            raise ValueError(f"{config_label} at {config_path}: {section_name}.launcher_args must be a list.")
        for i, token in enumerate(launcher_args):
            if not isinstance(token, (str, int, float)):
                raise ValueError(
                    f"{config_label} at {config_path}: {section_name}.launcher_args[{i}] "
                    "must be a scalar CLI token."
                )
            if _launcher_arg_contains_whitespace(token):
                raise ValueError(
                    f"{config_label} at {config_path}: {section_name}.launcher_args[{i}] "
                    "must be a single CLI token; split whitespace-separated arguments into separate list items."
                )
        launcher_args = [str(x) for x in launcher_args]
 
    return {
        "launcher": launcher,
        "launcher_args": launcher_args,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

load_runtime_execution_config()

picurv_cli.core.load_runtime_execution_config	(	str	config_search_anchor = None,
			extra_search_anchors = None
	)

Load optional shared execution launcher config from the nearest runtime config file.

Parameters

[in]	config_search_anchor	Argument passed to load_runtime_execution_config().
[in]	extra_search_anchors	Argument passed to load_runtime_execution_config().

Returns

Value returned by load_runtime_execution_config().

Definition at line 2679 of file core.py.

def load_runtime_execution_config(config_search_anchor: str = None, extra_search_anchors=None):
    """!
    @brief Load optional shared execution launcher config from the nearest runtime config file.
    @param[in] config_search_anchor Argument passed to `load_runtime_execution_config()`.
    @param[in] extra_search_anchors Argument passed to `load_runtime_execution_config()`.
    @return Value returned by `load_runtime_execution_config()`.
    """
    anchors = []
    if config_search_anchor is not None:
        anchors.append(config_search_anchor)
    if extra_search_anchors:
        anchors.extend(extra_search_anchors)
 
    config_path = find_runtime_execution_config_file(*anchors)
    if not config_path:
        return None, {}
 
    try:
        with open(config_path, "r", encoding="utf-8") as f:
            payload = yaml.safe_load(f) or {}
    except yaml.YAMLError as exc:
        raise ValueError(f"{os.path.basename(config_path)} YAML parse error at {config_path}: {exc}") from exc
 
    if not isinstance(payload, dict):
        raise ValueError(f"{os.path.basename(config_path)} at {config_path} must be a YAML mapping.")
 
    return config_path, {
        "default_execution": _normalize_execution_override_section(
            payload,
            "default_execution",
            config_path,
            os.path.basename(config_path),
        ),
        "local_execution": _normalize_execution_override_section(
            payload,
            "local_execution",
            config_path,
            os.path.basename(config_path),
        ),
        "cluster_execution": _normalize_execution_override_section(
            payload,
            "cluster_execution",
            config_path,
            os.path.basename(config_path),
        ),
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

merge_execution_overrides()

dict picurv_cli.core.merge_execution_overrides	(	"dict | None"	base,
		"dict | None"	override
	)

Merge execution overrides, letting explicit override values win key-by-key.

Parameters

[in]	base	Argument passed to merge_execution_overrides().
[in]	override	Argument passed to merge_execution_overrides().

Returns

Value returned by merge_execution_overrides().

Definition at line 2727 of file core.py.

def merge_execution_overrides(base: "dict | None", override: "dict | None") -> dict:
    """!
    @brief Merge execution overrides, letting explicit override values win key-by-key.
    @param[in] base Argument passed to `merge_execution_overrides()`.
    @param[in] override Argument passed to `merge_execution_overrides()`.
    @return Value returned by `merge_execution_overrides()`.
    """
    base = base or {}
    override = override or {}
 
    launcher = override.get("launcher")
    if launcher is None:
        launcher = base.get("launcher")
 
    launcher_args = override.get("launcher_args")
    if launcher_args is None:
        launcher_args = base.get("launcher_args")
 
    return {
        "launcher": launcher,
        "launcher_args": None if launcher_args is None else [str(x) for x in launcher_args],
    }
 
 

Here is the caller graph for this function:

resolve_runtime_execution_context()

dict picurv_cli.core.resolve_runtime_execution_context	(	dict	runtime_execution_cfg,
		str	context
	)

Resolve default plus context-specific execution overrides.

Parameters

[in]	runtime_execution_cfg	Argument passed to resolve_runtime_execution_context().
[in]	context	Argument passed to resolve_runtime_execution_context().

Returns

Value returned by resolve_runtime_execution_context().

Definition at line 2751 of file core.py.

def resolve_runtime_execution_context(runtime_execution_cfg: dict, context: str) -> dict:
    """!
    @brief Resolve default plus context-specific execution overrides.
    @param[in] runtime_execution_cfg Argument passed to `resolve_runtime_execution_context()`.
    @param[in] context Argument passed to `resolve_runtime_execution_context()`.
    @return Value returned by `resolve_runtime_execution_context()`.
    """
    if context not in LAUNCH_MODES:
        raise ValueError(f"Unsupported execution context '{context}'.")
    return merge_execution_overrides(
        runtime_execution_cfg.get("default_execution"),
        runtime_execution_cfg.get(f"{context}_execution"),
    )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

get_git_commit()

str picurv_cli.core.get_git_commit

(

str

repo_root = None

)

Best-effort git commit lookup for run/study manifests and case metadata.

Parameters

[in]

repo_root

Argument passed to get_git_commit().

Returns

Value returned by get_git_commit().

Definition at line 2766 of file core.py.

def get_git_commit(repo_root: str = None) -> str:
    """!
    @brief Best-effort git commit lookup for run/study manifests and case metadata.
    @param[in] repo_root Argument passed to `get_git_commit()`.
    @return Value returned by `get_git_commit()`.
    """
    cwd = repo_root or PROJECT_ROOT
    try:
        result = subprocess.run(
            ["git", "rev-parse", "HEAD"],
            cwd=cwd,
            text=True,
            capture_output=True,
            check=False
        )
        if result.returncode == 0:
            return result.stdout.strip()
    except Exception:
        pass
    return None
 
 

Here is the caller graph for this function:

write_case_origin_metadata()

picurv_cli.core.write_case_origin_metadata	(	str	case_dir,
		str	source_project_root,
		str	template_name = None,
		dict	existing = None,
			template_managed_files = None
	)

Create or refresh case-origin metadata for repo-aware case maintenance commands.

Parameters

[in]	case_dir	Argument passed to write_case_origin_metadata().
[in]	source_project_root	Argument passed to write_case_origin_metadata().
[in]	template_name	Argument passed to write_case_origin_metadata().
[in]	existing	Argument passed to write_case_origin_metadata().
[in]	template_managed_files	Argument passed to write_case_origin_metadata().

Returns

Value returned by write_case_origin_metadata().

Definition at line 2788 of file core.py.

                               existing: dict = None, template_managed_files=None):
    """!
    @brief Create or refresh case-origin metadata for repo-aware case maintenance commands.
    @param[in] case_dir Argument passed to `write_case_origin_metadata()`.
    @param[in] source_project_root Argument passed to `write_case_origin_metadata()`.
    @param[in] template_name Argument passed to `write_case_origin_metadata()`.
    @param[in] existing Argument passed to `write_case_origin_metadata()`.
    @param[in] template_managed_files Argument passed to `write_case_origin_metadata()`.
    @return Value returned by `write_case_origin_metadata()`.
    """
    payload = dict(existing or {})
    if "initialized_at" not in payload:
        payload["initialized_at"] = datetime.now().isoformat()
    payload["source_repo_root"] = os.path.abspath(source_project_root)
    if template_name:
        payload["template_name"] = template_name
    if template_managed_files is not None:
        payload["template_managed_files"] = sorted(set(str(p) for p in template_managed_files))
    payload["last_known_source_git_commit"] = get_git_commit(source_project_root)
    metadata_path = os.path.join(os.path.abspath(case_dir), CASE_ORIGIN_METADATA_FILENAME)
    write_json_file(metadata_path, payload)
    return metadata_path, payload
 
 
#: A `make` variable assignment such as `SYSTEM=cluster` or `CFLAGS+=-g`.

Here is the call graph for this function:

Here is the caller graph for this function:

make_args_include_explicit_goal()

bool picurv_cli.core.make_args_include_explicit_goal

(

"list[str]"

make_args

)

Return True when make args contain an explicit target rather than only options/assignments.

Parameters

[in]

make_args

Argument passed to make_args_include_explicit_goal().

Returns

Value returned by make_args_include_explicit_goal().

Definition at line 2817 of file core.py.

def make_args_include_explicit_goal(make_args: "list[str]") -> bool:
    """!
    @brief Return True when make args contain an explicit target rather than only options/assignments.
    @param[in] make_args Argument passed to `make_args_include_explicit_goal()`.
    @return Value returned by `make_args_include_explicit_goal()`.
    """
    if not make_args:
        return False
 
    options_with_value = {
        "-C", "-f", "-I", "-j", "-l", "-o", "-W",
        "--directory", "--file", "--makefile", "--include-dir", "--jobs",
        "--load-average", "--max-load", "--old-file", "--assume-old",
        "--what-if", "--new-file", "--assume-new",
    }
 
    skip_next = False
    for token in make_args:
        if skip_next:
            skip_next = False
            continue
        if token in options_with_value:
            skip_next = True
            continue
        if token.startswith("-"):
            continue
        if _MAKE_ASSIGNMENT_PATTERN.match(token):
            continue
        return True
    return False
 
 

Here is the caller graph for this function:

resolve_case_origin_context()

picurv_cli.core.resolve_case_origin_context	(	str	case_dir_hint = None,
		str	source_root_override = None,
		str	template_name_override = None
	)

Resolve case directory, source repo root, and optional template metadata.

Parameters

[in]	case_dir_hint	Argument passed to resolve_case_origin_context().
[in]	source_root_override	Argument passed to resolve_case_origin_context().
[in]	template_name_override	Argument passed to resolve_case_origin_context().

Returns

Value returned by resolve_case_origin_context().

Definition at line 2849 of file core.py.

def resolve_case_origin_context(case_dir_hint: str = None, source_root_override: str = None, template_name_override: str = None):
    """!
    @brief Resolve case directory, source repo root, and optional template metadata.
    @param[in] case_dir_hint Argument passed to `resolve_case_origin_context()`.
    @param[in] source_root_override Argument passed to `resolve_case_origin_context()`.
    @param[in] template_name_override Argument passed to `resolve_case_origin_context()`.
    @return Value returned by `resolve_case_origin_context()`.
    """
    metadata_case_dir, metadata_path, metadata = load_case_origin_metadata(case_dir_hint)
 
    if metadata_case_dir:
        case_dir = metadata_case_dir
    else:
        case_dir = os.path.abspath(case_dir_hint or os.getcwd())
 
    source_project_root = source_root_override
    if source_project_root:
        source_project_root = os.path.abspath(source_project_root)
    elif isinstance(metadata, dict) and isinstance(metadata.get("source_repo_root"), str):
        source_project_root = os.path.abspath(metadata["source_repo_root"])
    else:
        source_project_root = discover_local_project_root(case_dir)
 
    template_name = template_name_override
    if not template_name and isinstance(metadata, dict):
        template_name = metadata.get("template_name")
 
    return {
        "case_dir": case_dir,
        "metadata_path": metadata_path,
        "metadata": metadata or {},
        "source_project_root": source_project_root,
        "template_name": template_name,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

require_project_root()

picurv_cli.core.require_project_root	(	str	candidate,
		str	purpose
	)

Validate that a source repo root was resolved and is structurally valid.

Parameters

[in]	candidate	Argument passed to require_project_root().
[in]	purpose	Argument passed to require_project_root().

Returns

Value returned by require_project_root().

Definition at line 2885 of file core.py.

def require_project_root(candidate: str, purpose: str):
    """!
    @brief Validate that a source repo root was resolved and is structurally valid.
    @param[in] candidate Argument passed to `require_project_root()`.
    @param[in] purpose Argument passed to `require_project_root()`.
    @return Value returned by `require_project_root()`.
    """
    if not candidate:
        raise ValueError(
            f"Could not determine the PICurv source repository for {purpose}. "
            "Run this command from an initialized case directory or pass --source-root."
        )
    candidate_abs = os.path.abspath(candidate)
    if not is_project_root(candidate_abs):
        raise ValueError(
            f"Resolved source repository for {purpose} is not a valid PICurv root: {candidate_abs}"
        )
    return candidate_abs
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

require_existing_case_dir()

picurv_cli.core.require_existing_case_dir	(	str	case_dir,
		str	purpose,
		str	source_project_root = None
	)

Validate that a target case directory exists and is not the source repo root.

Parameters

[in]	case_dir	Argument passed to require_existing_case_dir().
[in]	purpose	Argument passed to require_existing_case_dir().
[in]	source_project_root	Argument passed to require_existing_case_dir().

Returns

Value returned by require_existing_case_dir().

Definition at line 2905 of file core.py.

def require_existing_case_dir(case_dir: str, purpose: str, source_project_root: str = None):
    """!
    @brief Validate that a target case directory exists and is not the source repo root.
    @param[in] case_dir Argument passed to `require_existing_case_dir()`.
    @param[in] purpose Argument passed to `require_existing_case_dir()`.
    @param[in] source_project_root Argument passed to `require_existing_case_dir()`.
    @return Value returned by `require_existing_case_dir()`.
    """
    if not case_dir:
        raise ValueError(f"Could not determine the case directory for {purpose}. Pass --case-dir.")
    case_dir_abs = os.path.abspath(case_dir)
    if not os.path.isdir(case_dir_abs):
        raise ValueError(f"Case directory for {purpose} does not exist: {case_dir_abs}")
    if source_project_root and os.path.abspath(source_project_root) == case_dir_abs:
        raise ValueError(
            f"Refusing to run {purpose} against the source repository root itself: {case_dir_abs}"
        )
    return case_dir_abs
 
 

Here is the caller graph for this function:

resolve_template_directory()

picurv_cli.core.resolve_template_directory	(	str	source_project_root,
		str	template_name
	)

Resolve an example template directory inside the source repository.

Parameters

[in]	source_project_root	Argument passed to resolve_template_directory().
[in]	template_name	Argument passed to resolve_template_directory().

Returns

Value returned by resolve_template_directory().

Definition at line 2925 of file core.py.

def resolve_template_directory(source_project_root: str, template_name: str):
    """!
    @brief Resolve an example template directory inside the source repository.
    @param[in] source_project_root Argument passed to `resolve_template_directory()`.
    @param[in] template_name Argument passed to `resolve_template_directory()`.
    @return Value returned by `resolve_template_directory()`.
    """
    if not template_name:
        raise ValueError(
            "Template name is required for config sync. Re-run with --template-name or from a case initialized by current picurv."
        )
    template_dir = os.path.join(source_project_root, "examples", template_name)
    if not os.path.isdir(template_dir):
        raise ValueError(f"Case template '{template_name}' not found at '{template_dir}'")
    return template_dir
 
 

Here is the caller graph for this function:

list_template_relative_files()

picurv_cli.core.list_template_relative_files	(	str	template_dir,
			excluded_rel_paths = None
	)

List all files in a template directory as case-relative paths.

Parameters

[in]	template_dir	Argument passed to list_template_relative_files().
[in]	excluded_rel_paths	Argument passed to list_template_relative_files().

Returns

Value returned by list_template_relative_files().

Definition at line 2942 of file core.py.

def list_template_relative_files(template_dir: str, excluded_rel_paths=None):
    """!
    @brief List all files in a template directory as case-relative paths.
    @param[in] template_dir Argument passed to `list_template_relative_files()`.
    @param[in] excluded_rel_paths Argument passed to `list_template_relative_files()`.
    @return Value returned by `list_template_relative_files()`.
    """
    template_dir_abs = os.path.abspath(template_dir)
    if not os.path.isdir(template_dir_abs):
        raise ValueError(f"Template directory not found: {template_dir_abs}")
    excluded = set(excluded_rel_paths or [])
    relative_paths = []
    for root, _, files in os.walk(template_dir_abs):
        rel_root = os.path.relpath(root, template_dir_abs)
        for filename in sorted(files):
            rel_path = filename if rel_root == "." else os.path.join(rel_root, filename)
            if rel_path in excluded:
                continue
            relative_paths.append(rel_path)
    return relative_paths
 
 

Here is the caller graph for this function:

render_template_workspace()

dict picurv_cli.core.render_template_workspace	(	str	template_dir,
		str	template_name,
		str	destination
	)

Render an example template into the canonical workspace layout at a new path.

This is the one transformation init applies to a template: copy it, drop the execution example, then relocate and rewrite its files through organize_initialized_workspace(). sync-config and status-source render the current template the same way, so all three agree on where each file lives and what it contains.

Parameters

[in]	template_dir	Example template directory to render.
[in]	template_name	Example template identity.
[in]	destination	Path to render into; it must not exist.

Returns

The layout mapping returned by organize_initialized_workspace().

Definition at line 2964 of file core.py.

def render_template_workspace(template_dir: str, template_name: str, destination: str) -> dict:
    """!
    @brief Render an example template into the canonical workspace layout at a new path.
    @details This is the one transformation `init` applies to a template: copy it, drop the
             execution example, then relocate and rewrite its files through
             organize_initialized_workspace(). `sync-config` and `status-source` render the
             current template the same way, so all three agree on where each file lives and
             what it contains.
    @param[in] template_dir Example template directory to render.
    @param[in] template_name Example template identity.
    @param[in] destination Path to render into; it must not exist.
    @return The layout mapping returned by organize_initialized_workspace().
    """
    shutil.copytree(template_dir, destination)
    copied_runtime_example = os.path.join(destination, RUNTIME_EXECUTION_EXAMPLE_FILENAME)
    if os.path.isfile(copied_runtime_example):
        os.remove(copied_runtime_example)
    return organize_initialized_workspace(destination, template_name, source_template_root=template_dir)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

list_rendered_template_files()

list picurv_cli.core.list_rendered_template_files

(

str

rendered_root

)

List the template-managed files of a rendered workspace, workspace-relative.

The workspace identity file is excluded: it records when and where the workspace was created, which is the workspace's own state, not the template's.

Parameters

[in]

rendered_root

Root produced by render_template_workspace().

Returns

Sorted workspace-relative paths.

Definition at line 2984 of file core.py.

def list_rendered_template_files(rendered_root: str) -> list:
    """!
    @brief List the template-managed files of a rendered workspace, workspace-relative.
    @details The workspace identity file is excluded: it records when and where the
             workspace was created, which is the workspace's own state, not the template's.
    @param[in] rendered_root Root produced by render_template_workspace().
    @return Sorted workspace-relative paths.
    """
    return sorted(
        rel for rel in list_template_relative_files(rendered_root)
        if rel != WORKSPACE_CONFIG_FILENAME
    )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

list_source_binaries()

picurv_cli.core.list_source_binaries

(

str

source_project_root

)

List binary artifacts currently available in the source repo bin directory.

Parameters

[in]

source_project_root

Argument passed to list_source_binaries().

Returns

Value returned by list_source_binaries().

Definition at line 2998 of file core.py.

def list_source_binaries(source_project_root: str):
    """!
    @brief List binary artifacts currently available in the source repo bin directory.
    @param[in] source_project_root Argument passed to `list_source_binaries()`.
    @return Value returned by `list_source_binaries()`.
    """
    source_bin_dir = os.path.join(os.path.abspath(source_project_root), "bin")
    if not os.path.isdir(source_bin_dir):
        raise ValueError(f"Source bin directory not found: {source_bin_dir}. Run 'picurv build' first.")
    binaries = sorted(
        f for f in os.listdir(source_bin_dir)
        if os.path.isfile(os.path.join(source_bin_dir, f)) and f != "picurv"
    )
    if not binaries:
        raise ValueError(f"Source bin directory contains no files: {source_bin_dir}")
    return source_bin_dir, binaries
 
 

Here is the caller graph for this function:

sync_case_binaries()

picurv_cli.core.sync_case_binaries	(	str	case_dir,
		str	source_project_root
	)

Copy current source-repo binaries into a case directory for version-pinning.

Parameters

[in]	case_dir	Argument passed to sync_case_binaries().
[in]	source_project_root	Argument passed to sync_case_binaries().

Returns

Value returned by sync_case_binaries().

Definition at line 3016 of file core.py.

def sync_case_binaries(case_dir: str, source_project_root: str):
    """!
    @brief Copy current source-repo binaries into a case directory for version-pinning.
    @param[in] case_dir Argument passed to `sync_case_binaries()`.
    @param[in] source_project_root Argument passed to `sync_case_binaries()`.
    @return Value returned by `sync_case_binaries()`.
    """
    case_dir_abs = os.path.abspath(case_dir)
    os.makedirs(case_dir_abs, exist_ok=True)
    source_bin_dir, binaries = list_source_binaries(source_project_root)
    copied = []
    for binary_name in binaries:
        source_path = os.path.join(source_bin_dir, binary_name)
        dest_path = os.path.join(case_dir_abs, binary_name)
        shutil.copy2(source_path, dest_path)
        copied.append(dest_path)
    return copied
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

sync_case_template_files()

picurv_cli.core.sync_case_template_files	(	str	case_dir,
		str	template_dir,
		bool	overwrite = False,
		bool	prune = False,
			managed_rel_paths = None,
		str	template_name = None
	)

Sync template files into a case directory, preserving modified files unless overwrite is requested.

Parameters

[in]	case_dir	Argument passed to sync_case_template_files().
[in]	template_dir	Argument passed to sync_case_template_files().
[in]	overwrite	Argument passed to sync_case_template_files().
[in]	prune	Argument passed to sync_case_template_files().
[in]	managed_rel_paths	Argument passed to sync_case_template_files().
[in]	template_name	Template identity; defaults to the template directory name.

Returns

Value returned by sync_case_template_files().

Files are compared with a fresh rendering of the template in the workspace layout init creates, so a case file is matched with the template file it was made from, under its workspace name and rewritten contents.

Definition at line 3035 of file core.py.

                             prune: bool = False, managed_rel_paths=None, template_name: str = None):
    """!
    @brief Sync template files into a case directory, preserving modified files unless overwrite is requested.
    @param[in] case_dir Argument passed to `sync_case_template_files()`.
    @param[in] template_dir Argument passed to `sync_case_template_files()`.
    @param[in] overwrite Argument passed to `sync_case_template_files()`.
    @param[in] prune Argument passed to `sync_case_template_files()`.
    @param[in] managed_rel_paths Argument passed to `sync_case_template_files()`.
    @param[in] template_name Template identity; defaults to the template directory name.
    @return Value returned by `sync_case_template_files()`.
    @details Files are compared with a fresh rendering of the template in the workspace
             layout `init` creates, so a case file is matched with the template file it
             was made from, under its workspace name and rewritten contents.
    """
    case_dir_abs = os.path.abspath(case_dir)
    template_dir_abs = os.path.abspath(template_dir)
    if not os.path.isdir(template_dir_abs):
        raise ValueError(f"Template directory not found: {template_dir_abs}")
    template_name = template_name or os.path.basename(template_dir_abs)
 
    summary = {
        "copied": [],
        "overwritten": [],
        "skipped_modified": [],
        "unchanged": [],
        "pruned": [],
        "prune_requested_without_tracking": False,
    }
    with tempfile.TemporaryDirectory(prefix="picurv-template-") as scratch:
        rendered_root = os.path.join(scratch, os.path.basename(case_dir_abs) or "workspace")
        render_template_workspace(template_dir_abs, template_name, rendered_root)
        current_template_files = list_rendered_template_files(rendered_root)
        for rel_path in current_template_files:
            src_path = os.path.join(rendered_root, rel_path)
            dest_path = os.path.join(case_dir_abs, rel_path)
            os.makedirs(os.path.dirname(dest_path), exist_ok=True)
 
            if not os.path.exists(dest_path):
                shutil.copy2(src_path, dest_path)
                summary["copied"].append(dest_path)
                continue
 
            if filecmp.cmp(src_path, dest_path, shallow=False):
                summary["unchanged"].append(dest_path)
                continue
 
            if overwrite:
                shutil.copy2(src_path, dest_path)
                summary["overwritten"].append(dest_path)
            else:
                summary["skipped_modified"].append(dest_path)
    current_template_set = set(current_template_files)
 
    managed_set = set(managed_rel_paths or [])
    if prune:
        if not managed_set:
            summary["prune_requested_without_tracking"] = True
        for rel_path in sorted(managed_set - current_template_set):
            dest_path = os.path.join(case_dir_abs, rel_path)
            if os.path.isfile(dest_path):
                os.remove(dest_path)
                summary["pruned"].append(dest_path)
 
    summary["template_managed_files"] = current_template_files
    return summary
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

compute_case_source_status()

picurv_cli.core.compute_case_source_status	(	str	case_dir,
		str	source_project_root,
		str	template_name = None,
		dict	metadata = None
	)

Compute source/case drift across commits, binaries, and template-managed files.

Parameters

[in]	case_dir	Argument passed to compute_case_source_status().
[in]	source_project_root	Argument passed to compute_case_source_status().
[in]	template_name	Argument passed to compute_case_source_status().
[in]	metadata	Argument passed to compute_case_source_status().

Returns

Value returned by compute_case_source_status().

Definition at line 3103 of file core.py.

def compute_case_source_status(case_dir: str, source_project_root: str, template_name: str = None, metadata: dict = None):
    """!
    @brief Compute source/case drift across commits, binaries, and template-managed files.
    @param[in] case_dir Argument passed to `compute_case_source_status()`.
    @param[in] source_project_root Argument passed to `compute_case_source_status()`.
    @param[in] template_name Argument passed to `compute_case_source_status()`.
    @param[in] metadata Argument passed to `compute_case_source_status()`.
    @return Value returned by `compute_case_source_status()`.
    """
    case_dir_abs = os.path.abspath(case_dir)
    source_root_abs = os.path.abspath(source_project_root)
    metadata = metadata or {}
    status = {
        "case_dir": case_dir_abs,
        "source_repo_root": source_root_abs,
        "metadata_present": bool(metadata),
        "template_name": template_name,
        "last_known_source_git_commit": metadata.get("last_known_source_git_commit"),
        "current_source_git_commit": get_git_commit(source_root_abs),
    }
    status["source_commit_changed"] = (
        bool(status["last_known_source_git_commit"])
        and bool(status["current_source_git_commit"])
        and status["last_known_source_git_commit"] != status["current_source_git_commit"]
    )
 
    binary_status = {
        "source_bin_present": False,
        "source_bin_missing": [],
        "case_bin_missing": [],
        "case_bin_different": [],
        "case_bin_current": [],
    }
    try:
        source_bin_dir, binaries = list_source_binaries(source_root_abs)
        binary_status["source_bin_present"] = True
        for binary_name in binaries:
            source_path = os.path.join(source_bin_dir, binary_name)
            case_path = os.path.join(case_dir_abs, binary_name)
            if not os.path.isfile(case_path):
                binary_status["case_bin_missing"].append(binary_name)
            elif filecmp.cmp(source_path, case_path, shallow=False):
                binary_status["case_bin_current"].append(binary_name)
            else:
                binary_status["case_bin_different"].append(binary_name)
    except ValueError as exc:
        binary_status["source_bin_missing"].append(str(exc))
    status["binaries"] = binary_status
 
    config_status = {
        "template_available": False,
        "template_files": [],
        "case_missing_files": [],
        "case_modified_files": [],
        "case_current_files": [],
        "template_removed_since_last_sync": [],
        "tracking_available": isinstance(metadata.get("template_managed_files"), list),
    }
    if template_name:
        try:
            template_dir = resolve_template_directory(source_root_abs, template_name)
            with tempfile.TemporaryDirectory(prefix="picurv-template-") as scratch:
                rendered_root = os.path.join(scratch, os.path.basename(case_dir_abs) or "workspace")
                render_template_workspace(template_dir, template_name, rendered_root)
                template_files = list_rendered_template_files(rendered_root)
                config_status["template_available"] = True
                config_status["template_files"] = template_files
                for rel_path in template_files:
                    src_path = os.path.join(rendered_root, rel_path)
                    case_path = os.path.join(case_dir_abs, rel_path)
                    if not os.path.isfile(case_path):
                        config_status["case_missing_files"].append(rel_path)
                    elif filecmp.cmp(src_path, case_path, shallow=False):
                        config_status["case_current_files"].append(rel_path)
                    else:
                        config_status["case_modified_files"].append(rel_path)
            managed_files = metadata.get("template_managed_files")
            if isinstance(managed_files, list):
                config_status["template_removed_since_last_sync"] = sorted(set(managed_files) - set(template_files))
        except ValueError:
            pass
    status["config"] = config_status
 
    case_runtime_cfg = os.path.join(case_dir_abs, RUNTIME_EXECUTION_CONFIG_FILENAME)
    repo_runtime_seed = os.path.join(source_root_abs, RUNTIME_EXECUTION_CONFIG_FILENAME)
    runtime_status = {
        "case_config_present": os.path.isfile(case_runtime_cfg),
        "repo_seed_present": os.path.isfile(repo_runtime_seed),
        "case_matches_repo_seed": False,
    }
    if runtime_status["case_config_present"] and runtime_status["repo_seed_present"]:
        runtime_status["case_matches_repo_seed"] = filecmp.cmp(
            case_runtime_cfg,
            repo_runtime_seed,
            shallow=False,
        )
    status["runtime_execution"] = runtime_status
    return status
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

print_case_source_status()

picurv_cli.core.print_case_source_status

(

dict

status

)

Render human-readable source/case drift details.

Parameters

[in]

status

Argument passed to print_case_source_status().

Definition at line 3203 of file core.py.

def print_case_source_status(status: dict):
    """!
    @brief Render human-readable source/case drift details.
    @param[in] status Argument passed to `print_case_source_status()`.
    """
    print(f"[INFO] Case directory     : {status['case_dir']}")
    print(f"[INFO] Source repo        : {status['source_repo_root']}")
    print(f"[INFO] Template           : {status.get('template_name') or '(unknown)'}")
    if status.get("last_known_source_git_commit"):
        print(f"[INFO] Last synced commit : {status['last_known_source_git_commit']}")
    if status.get("current_source_git_commit"):
        print(f"[INFO] Current src commit : {status['current_source_git_commit']}")
    print(f"[INFO] Source changed     : {'yes' if status.get('source_commit_changed') else 'no'}")
 
    binaries = status["binaries"]
    if binaries["source_bin_present"] and not (binaries["case_bin_current"] or binaries["case_bin_different"]):
        print("[INFO] Binaries           : not pinned (the installation's executables are used)")
    elif binaries["source_bin_present"]:
        print(
            f"[INFO] Binaries           : current={len(binaries['case_bin_current'])} "
            f"changed={len(binaries['case_bin_different'])} missing={len(binaries['case_bin_missing'])}"
        )
    else:
        print("[INFO] Binaries           : source bin/ unavailable")
 
    config = status["config"]
    if config["template_available"]:
        print(
            f"[INFO] Template files     : current={len(config['case_current_files'])} "
            f"modified={len(config['case_modified_files'])} missing={len(config['case_missing_files'])}"
        )
        if config["tracking_available"]:
            print(f"[INFO] Prune candidates   : {len(config['template_removed_since_last_sync'])}")
        else:
            print("[INFO] Prune candidates   : tracking unavailable")
    elif status.get("template_name"):
        print("[INFO] Template files     : template unavailable in source repo")
 
    runtime_cfg = status.get("runtime_execution", {})
    print(
        f"[INFO] Runtime config     : case={'yes' if runtime_cfg.get('case_config_present') else 'no'} "
        f"repo-seed={'yes' if runtime_cfg.get('repo_seed_present') else 'no'} "
        f"matches-repo-seed={'yes' if runtime_cfg.get('case_matches_repo_seed') else 'no'}"
    )
 
 

Here is the caller graph for this function:

status_source_command()

picurv_cli.core.status_source_command

(

args

)

Report source/case drift for an initialized case directory.

Parameters

[in]

args

Command-line style argument list supplied to the function.

Definition at line 3249 of file core.py.

def status_source_command(args):
    """!
    @brief Report source/case drift for an initialized case directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    try:
        context = resolve_case_origin_context(
            case_dir_hint=getattr(args, "case_dir", None),
            source_root_override=getattr(args, "source_root", None),
            template_name_override=getattr(args, "template_name", None),
        )
        source_project_root = require_project_root(context["source_project_root"], "status-source")
        case_dir = require_existing_case_dir(context["case_dir"], "status-source", source_project_root)
        status = compute_case_source_status(
            case_dir,
            source_project_root,
            template_name=context.get("template_name"),
            metadata=context.get("metadata"),
        )
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    if getattr(args, "output_format", "text") == "json":
        print(json.dumps(status, indent=2, sort_keys=True))
        return
    print_case_source_status(status)
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_path()

str picurv_cli.core.resolve_path	(	str	anchor_file,
		str	candidate
	)

Resolve a potentially relative path against a source YAML file path.

Parameters

[in]	anchor_file	Argument passed to resolve_path().
[in]	candidate	Argument passed to resolve_path().

Returns

Value returned by resolve_path().

Definition at line 3277 of file core.py.

def resolve_path(anchor_file: str, candidate: str) -> str:
    """!
    @brief Resolve a potentially relative path against a source YAML file path.
    @param[in] anchor_file Argument passed to `resolve_path()`.
    @param[in] candidate Argument passed to `resolve_path()`.
    @return Value returned by `resolve_path()`.
    """
    if candidate is None:
        return None
    return resolve_workspace_path(anchor_file, candidate)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_mapping_value_with_aliases()

picurv_cli.core._mapping_value_with_aliases ( dict  mapping, *  keys,   default = None  )

protected

Return the first defined value from a mapping across alias keys.

Parameters

[in]	mapping	Argument passed to _mapping_value_with_aliases().
[in]	default	Argument passed to _mapping_value_with_aliases().
[in]	keys	Argument passed to _mapping_value_with_aliases().

Returns

Value returned by _mapping_value_with_aliases().

Definition at line 3309 of file core.py.

def _mapping_value_with_aliases(mapping: dict, *keys, default=None):
    """!
    @brief Return the first defined value from a mapping across alias keys.
    @param[in] mapping Argument passed to `_mapping_value_with_aliases()`.
    @param[in] default Argument passed to `_mapping_value_with_aliases()`.
    @param[in] keys Argument passed to `_mapping_value_with_aliases()`.
    @return Value returned by `_mapping_value_with_aliases()`.
    """
    if not isinstance(mapping, dict):
        return default
    for key in keys:
        if key in mapping:
            return mapping.get(key)
    return default
 
 

Here is the caller graph for this function:

get_post_run_control_value()

picurv_cli.core.get_post_run_control_value	(	dict	post_cfg,
		str	canonical_key,
			default = None
	)

Resolve post run_control values with backwards-compatible legacy aliases.

Parameters

[in]	post_cfg	Argument passed to get_post_run_control_value().
[in]	canonical_key	Argument passed to get_post_run_control_value().
[in]	default	Argument passed to get_post_run_control_value().

Returns

Value returned by get_post_run_control_value().

Definition at line 3325 of file core.py.

def get_post_run_control_value(post_cfg: dict, canonical_key: str, default=None):
    """!
    @brief Resolve post run_control values with backwards-compatible legacy aliases.
    @param[in] post_cfg Argument passed to `get_post_run_control_value()`.
    @param[in] canonical_key Argument passed to `get_post_run_control_value()`.
    @param[in] default Argument passed to `get_post_run_control_value()`.
    @return Value returned by `get_post_run_control_value()`.
    """
    aliases = POST_RUN_CONTROL_ALIASES.get(canonical_key, (canonical_key,))
    rc = post_cfg.get("run_control", {})
    return _mapping_value_with_aliases(rc, *aliases, default=default)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

warn_on_grid_generator_hyphen_keys()

None picurv_cli.core.warn_on_grid_generator_hyphen_keys	(	dict	generator,
		str	case_path,
		list	warnings
	)

Warn when grid.generator uses unsupported hyphenated wrapper keys.

Parameters

[in]	generator	grid.generator mapping from case.yml.
[in]	case_path	Case file path for diagnostics.
[in,out]	warnings	Warning list to append to.

Definition at line 3338 of file core.py.

def warn_on_grid_generator_hyphen_keys(generator: dict, case_path: str, warnings: list) -> None:
    """!
    @brief Warn when grid.generator uses unsupported hyphenated wrapper keys.
    @param[in] generator grid.generator mapping from case.yml.
    @param[in] case_path Case file path for diagnostics.
    @param[in,out] warnings Warning list to append to.
    """
    if not isinstance(generator, dict):
        return
    for bad_key, expected_key in GRID_GENERATOR_HYPHEN_KEY_HINTS.items():
        if bad_key in generator and bad_key != expected_key:
            warnings.append(
                f"{case_path}: grid.generator.{bad_key} is ignored; use grid.generator.{expected_key}."
            )
 
 
#: Destination keys a generated initial condition once accepted. Its payload, summary and
#: spectrum always land at fixed paths in the asset store, so these were read and ignored.

Here is the caller graph for this function:

retired_destination_message()

str picurv_cli.core.retired_destination_message	(	str	label,
		str	key
	)

Explain why a generator may not choose its own output destination.

Parameters

[in]	label	Dotted configuration path of the mapping carrying the key.
[in]	key	The refused destination key.

Returns

The refusal message, shared by every generator that once took one.

Definition at line 3359 of file core.py.

def retired_destination_message(label: str, key: str) -> str:
    """!
    @brief Explain why a generator may not choose its own output destination.
    @param[in] label Dotted configuration path of the mapping carrying the key.
    @param[in] key The refused destination key.
    @return The refusal message, shared by every generator that once took one.
    """
    return (
        f"'{label}.{key}' is no longer accepted. PICurv chooses where generated artifacts "
        "go; the published asset carries the payload, its preview, and its validation record."
    )
 
 

Here is the caller graph for this function:

reject_generator_destination_keys()

list picurv_cli.core.reject_generator_destination_keys	(		generator,
		str	case_path,
		str	label
	)

Reject generator settings that try to choose their own output destination.

Parameters

[in]	generator	Generator mapping from the case configuration.
[in]	case_path	Case file path for diagnostics.
[in]	label	Dotted configuration path being checked, for the message.

Returns

List of error strings.

Definition at line 3372 of file core.py.

def reject_generator_destination_keys(generator, case_path: str, label: str) -> list:
    """!
    @brief Reject generator settings that try to choose their own output destination.
    @param[in] generator Generator mapping from the case configuration.
    @param[in] case_path Case file path for diagnostics.
    @param[in] label Dotted configuration path being checked, for the message.
    @return List of error strings.
    """
    if not isinstance(generator, dict):
        return []
    return [
        f"  {case_path}: {retired_destination_message(label, key)}"
        for key in RETIRED_GENERATOR_DESTINATION_KEYS if key in generator
    ]
 
 

Here is the caller graph for this function:

get_post_source_data()

picurv_cli.core.get_post_source_data

(

dict

post_cfg

)

Return source_data as a mapping when valid, else an empty mapping.

Parameters

[in]

post_cfg

Argument passed to get_post_source_data().

Returns

Value returned by get_post_source_data().

Definition at line 3388 of file core.py.

def get_post_source_data(post_cfg: dict):
    """!
    @brief Return source_data as a mapping when valid, else an empty mapping.
    @param[in] post_cfg Argument passed to `get_post_source_data()`.
    @return Value returned by `get_post_source_data()`.
    """
    source_cfg = post_cfg.get("source_data", {})
    if isinstance(source_cfg, dict):
        return source_cfg
    return {}
 
 

Here is the caller graph for this function:

get_post_source_directory_template()

str picurv_cli.core.get_post_source_directory_template	(	dict	post_cfg,
		str	default = "<solver_output_dir>"
	)

Resolve the source directory template from source_data with a safe default.

Parameters

[in]	post_cfg	Argument passed to get_post_source_directory_template().
[in]	default	Argument passed to get_post_source_directory_template().

Returns

Value returned by get_post_source_directory_template().

Definition at line 3400 of file core.py.

def get_post_source_directory_template(post_cfg: dict, default: str = "<solver_output_dir>") -> str:
    """!
    @brief Resolve the source directory template from source_data with a safe default.
    @param[in] post_cfg Argument passed to `get_post_source_directory_template()`.
    @param[in] default Argument passed to `get_post_source_directory_template()`.
    @return Value returned by `get_post_source_directory_template()`.
    """
    return get_post_source_data(post_cfg).get("directory", default)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

get_post_input_extensions()

picurv_cli.core.get_post_input_extensions

(

dict

post_cfg

)

Return post input_extensions, preferring io.

• and tolerating legacy source_data.* placement.

  Parameters

  [in]

  post_cfg

  Argument passed to get_post_input_extensions().

  Returns

  Value returned by get_post_input_extensions().

Definition at line 3410 of file core.py.

def get_post_input_extensions(post_cfg: dict):
    """!
    @brief Return post input_extensions, preferring io.* and tolerating legacy source_data.* placement.
    @param[in] post_cfg Argument passed to `get_post_input_extensions()`.
    @return Value returned by `get_post_input_extensions()`.
    """
    io_cfg = post_cfg.get("io", {})
    io_ext = io_cfg.get("input_extensions") if isinstance(io_cfg, dict) else None
    if isinstance(io_ext, dict):
        return io_ext
 
    source_ext = get_post_source_data(post_cfg).get("input_extensions")
    if isinstance(source_ext, dict):
        return source_ext
 
    return {}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

get_post_statistics_task_tokens()

picurv_cli.core.get_post_statistics_task_tokens

(

dict

post_cfg

)

Return normalized statistics pipeline tokens that will be written into post.run.

Parameters

[in]

post_cfg

Argument passed to get_post_statistics_task_tokens().

Returns

Value returned by get_post_statistics_task_tokens().

Definition at line 3428 of file core.py.

def get_post_statistics_task_tokens(post_cfg: dict):
    """!
    @brief Return normalized statistics pipeline tokens that will be written into post.run.
    @param[in] post_cfg Argument passed to `get_post_statistics_task_tokens()`.
    @return Value returned by `get_post_statistics_task_tokens()`.
    """
    stats_cfg = post_cfg.get("statistics_pipeline")
    stats_entries = []
    if isinstance(stats_cfg, list):
        stats_entries = stats_cfg
    elif isinstance(stats_cfg, dict):
        stats_entries = stats_cfg.get("tasks", [])
 
    tokens = []
    for entry in stats_entries:
        if isinstance(entry, str):
            task_name = entry
        elif isinstance(entry, dict):
            task_name = entry.get("task")
        else:
            continue
        try:
            tokens.append(normalize_statistics_task(task_name))
        except ValueError:
            continue
    return tokens
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

get_monitor_output_directory()

str picurv_cli.core.get_monitor_output_directory	(	dict	monitor_cfg,
		str	default = "output"
	)

Resolve the solver output root from monitor.yml, preserving the default layout.

Parameters

[in]	monitor_cfg	Argument passed to get_monitor_output_directory().
[in]	default	Argument passed to get_monitor_output_directory().

Returns

Value returned by get_monitor_output_directory().

Definition at line 3456 of file core.py.

def get_monitor_output_directory(monitor_cfg: dict, default: str = "output") -> str:
    """!
    @brief Resolve the solver output root from monitor.yml, preserving the default layout.
    @param[in] monitor_cfg Argument passed to `get_monitor_output_directory()`.
    @param[in] default Argument passed to `get_monitor_output_directory()`.
    @return Value returned by `get_monitor_output_directory()`.
    """
    del monitor_cfg, default
    return CANONICAL_RUN_PATHS["output"]
 
 

get_post_statistics_output_prefix()

str picurv_cli.core.get_post_statistics_output_prefix	(	dict	post_cfg,
		str	default = "Stats"
	)

Resolve the statistics CSV prefix, preserving legacy top-level override support.

Parameters

[in]	post_cfg	Argument passed to get_post_statistics_output_prefix().
[in]	default	Argument passed to get_post_statistics_output_prefix().

Returns

Value returned by get_post_statistics_output_prefix().

Definition at line 3467 of file core.py.

def get_post_statistics_output_prefix(post_cfg: dict, default: str = "Stats") -> str:
    """!
    @brief Resolve the statistics CSV prefix, preserving legacy top-level override support.
    @param[in] post_cfg Argument passed to `get_post_statistics_output_prefix()`.
    @param[in] default Argument passed to `get_post_statistics_output_prefix()`.
    @return Value returned by `get_post_statistics_output_prefix()`.
    """
    stats_cfg = post_cfg.get("statistics_pipeline")
    if isinstance(stats_cfg, dict):
        prefix = stats_cfg.get("output_prefix")
        if isinstance(prefix, str) and prefix.strip():
            return prefix.strip()
 
    legacy_prefix = post_cfg.get("statistics_output_prefix")
    if isinstance(legacy_prefix, str) and legacy_prefix.strip():
        return legacy_prefix.strip()
 
    return default
 
 

Here is the caller graph for this function:

resolve_post_statistics_output_prefix()

str picurv_cli.core.resolve_post_statistics_output_prefix	(	dict	post_cfg,
			monitor_cfg = None,
		str	default = "Stats"
	)

Resolve the runtime statistics prefix, routing bare basenames under the monitor output root.

Parameters

[in]	post_cfg	Argument passed to resolve_post_statistics_output_prefix().
[in]	monitor_cfg	Optional monitor configuration used to anchor the default statistics home.
[in]	default	Argument passed to resolve_post_statistics_output_prefix().

Returns

Value returned by resolve_post_statistics_output_prefix().

Definition at line 3487 of file core.py.

def resolve_post_statistics_output_prefix(post_cfg: dict, monitor_cfg=None, default: str = "Stats") -> str:
    """!
    @brief Resolve the runtime statistics prefix, routing bare basenames under the monitor output root.
    @param[in] post_cfg Argument passed to `resolve_post_statistics_output_prefix()`.
    @param[in] monitor_cfg Optional monitor configuration used to anchor the default statistics home.
    @param[in] default Argument passed to `resolve_post_statistics_output_prefix()`.
    @return Value returned by `resolve_post_statistics_output_prefix()`.
    """
    prefix = get_post_statistics_output_prefix(post_cfg, default=default).strip()
    if os.path.isabs(prefix):
        return prefix
 
    if os.path.dirname(prefix):
        return prefix
 
    del monitor_cfg
    return os.path.join(CANONICAL_RUN_PATHS["statistics"], prefix)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

get_post_statistics_output_artifacts()

picurv_cli.core.get_post_statistics_output_artifacts	(	dict	post_cfg,
		str	run_dir,
			monitor_cfg = None
	)

Predict statistics CSV output paths relative to the postprocessor runtime cwd.

Parameters

[in]	post_cfg	Argument passed to get_post_statistics_output_artifacts().
[in]	run_dir	Argument passed to get_post_statistics_output_artifacts().
[in]	monitor_cfg	Optional monitor configuration used to anchor the default statistics home.

Returns

Value returned by get_post_statistics_output_artifacts().

Definition at line 3506 of file core.py.

def get_post_statistics_output_artifacts(post_cfg: dict, run_dir: str, monitor_cfg=None):
    """!
    @brief Predict statistics CSV output paths relative to the postprocessor runtime cwd.
    @param[in] post_cfg Argument passed to `get_post_statistics_output_artifacts()`.
    @param[in] run_dir Argument passed to `get_post_statistics_output_artifacts()`.
    @param[in] monitor_cfg Optional monitor configuration used to anchor the default statistics home.
    @return Value returned by `get_post_statistics_output_artifacts()`.
    """
    if not isinstance((post_cfg or {}).get("_picurv_paths"), dict):
        post_cfg, _ = apply_canonical_post_paths(post_cfg, run_dir)
    token_to_suffix = {
        "ComputeMSD": "_msd.csv",
    }
    prefix = resolve_post_statistics_output_prefix(post_cfg, monitor_cfg)
    if os.path.isabs(prefix):
        base_path = os.path.abspath(prefix)
    else:
        base_path = os.path.abspath(os.path.join(run_dir, prefix))
 
    output_paths = []
    for token in get_post_statistics_task_tokens(post_cfg):
        suffix = token_to_suffix.get(token)
        if suffix:
            output_paths.append(base_path + suffix)
 
    return list(dict.fromkeys(output_paths))
 
 
#: Spectra tasks a post recipe may request, with the preconditions each needs.
#:
#: `requires_uniform_cartesian` is checked against the staged PICGRID and
#: `requires_periodic_geometric` against the resolved boundary conditions, both
#: before any field is read. A task whose preconditions the case cannot meet is
#: refused at validation rather than producing a curve with no meaning: a spectrum
#: needs the transform direction to be uniformly spaced, periodic, and statistically
#: homogeneous. Wall-bounded Cartesian cases may transform only their periodic axes.

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_scalar_transport()

dict picurv_cli.core.resolve_scalar_transport	(	dict	case_cfg,
		dict	solver_cfg,
		bool	warn = False
	)

Resolve the scalar-transport parameters from case.yml or their deprecated location.

Each parameter is read from its case.yml location (SCALAR_TRANSPORT_CASE_PATHS) or, as a deprecated alias, from solver.yml scalar_transport. Setting one in both places is refused rather than resolved by precedence.

Parameters

[in]	case_cfg	Parsed case configuration.
[in]	solver_cfg	Parsed solver configuration.
[in]	warn	Print a deprecation warning for each parameter read from solver.yml.

Returns

Mapping of parameter name to validated value, for the parameters that are set.

Exceptions

ValueError

for a malformed, duplicated, or out-of-range parameter.

Definition at line 3662 of file core.py.

def resolve_scalar_transport(case_cfg: dict, solver_cfg: dict, warn: bool = False) -> dict:
    """!
    @brief Resolve the scalar-transport parameters from case.yml or their deprecated location.
    @details Each parameter is read from its case.yml location (SCALAR_TRANSPORT_CASE_PATHS)
             or, as a deprecated alias, from solver.yml `scalar_transport`. Setting one in both
             places is refused rather than resolved by precedence.
    @param[in] case_cfg Parsed case configuration.
    @param[in] solver_cfg Parsed solver configuration.
    @param[in] warn Print a deprecation warning for each parameter read from solver.yml.
    @return Mapping of parameter name to validated value, for the parameters that are set.
    @throws ValueError for a malformed, duplicated, or out-of-range parameter.
    """
    legacy = (solver_cfg or {}).get("scalar_transport") or {}
    if not isinstance(legacy, dict):
        raise ValueError("solver.yml scalar_transport must be a mapping when provided.")
    unknown = sorted(set(legacy) - set(SCALAR_TRANSPORT_FLAGS))
    if unknown:
        raise ValueError(f"solver.yml scalar_transport has unsupported key(s): {unknown}. "
                         f"Use one of {sorted(SCALAR_TRANSPORT_FLAGS)}, in case.yml.")
    values = {}
    for key, path in SCALAR_TRANSPORT_CASE_PATHS.items():
        node = case_cfg or {}
        for part in path:
            node = node.get(part) if isinstance(node, dict) else None
        case_label = ".".join(path + (key,))
        in_case = isinstance(node, dict) and key in node
        if in_case and key in legacy:
            raise ValueError(f"{key} is set in case.yml ({case_label}) and in its deprecated "
                             f"solver.yml location (scalar_transport.{key}); keep only the case.yml one.")
        if not in_case and key not in legacy:
            continue
        raw, label = (node[key], f"case.yml {case_label}") if in_case else \
                     (legacy[key], f"solver.yml scalar_transport.{key}")
        try:
            value = _to_finite_float(raw, label) if key == "iem_constant" else float(raw)
        except (TypeError, ValueError) as exc:
            raise ValueError(f"{label} must be numeric.") from exc
        # iem_constant = 0 switches micromixing off; the Schmidt numbers divide.
        if value < 0.0 or (value == 0.0 and key != "iem_constant"):
            raise ValueError(f"{label} must be {'non-negative' if key == 'iem_constant' else 'positive'}.")
        if not in_case and warn:
            print(f"[WARNING] solver.yml scalar_transport.{key} is deprecated; set it in case.yml "
                  f"as {case_label}.", file=sys.stderr)
        values[key] = value
    return values
 
#: Image formats `picurv sweep` can render study plots in.

Here is the call graph for this function:

Here is the caller graph for this function:

normalize_post_spectra_config()

dict picurv_cli.core.normalize_post_spectra_config

(

dict

post_cfg

)

Validate and canonicalize the spectra block of post.yml.

The recipe chooses what to measure; whether the case can support that measurement is a separate question answered by validate_post_spectra_preconditions(), which needs the grid and the boundary conditions. Keeping the two apart means a recipe stays valid on its own terms even when it is read without a case beside it.

Parameters

[in]

post_cfg

Parsed post-processing configuration.

Returns

Normalized mapping with an output prefix and a list of tasks.

Exceptions

ValueError

on a malformed or inconsistent recipe.

Definition at line 3770 of file core.py.

def normalize_post_spectra_config(post_cfg: dict) -> dict:
    """!
    @brief Validate and canonicalize the spectra block of post.yml.
 
    @details The recipe chooses what to measure; whether the case *can* support that
             measurement is a separate question answered by
             `validate_post_spectra_preconditions()`, which needs the grid and the
             boundary conditions. Keeping the two apart means a recipe stays valid on
             its own terms even when it is read without a case beside it.
 
    @param[in] post_cfg Parsed post-processing configuration.
    @return Normalized mapping with an output prefix and a list of tasks.
    @throws ValueError on a malformed or inconsistent recipe.
    """
    raw = (post_cfg or {}).get("spectra")
    if raw is None:
        return {"output_prefix": "Spectrum", "tasks": []}
    if not isinstance(raw, dict):
        raise ValueError("'spectra' must be a mapping.")
 
    prefix = raw.get("output_prefix", "Spectrum")
    if not isinstance(prefix, str) or not prefix.strip():
        raise ValueError("'spectra.output_prefix' must be a non-empty string.")
 
    tasks = raw.get("tasks")
    if not isinstance(tasks, list) or not tasks:
        raise ValueError("'spectra.tasks' must be a non-empty list.")
 
    cleaned = []
    seen = []
    for position, entry in enumerate(tasks):
        if not isinstance(entry, dict):
            raise ValueError(f"spectra task {position}: each task must be a mapping.")
        name = entry.get("task")
        if not isinstance(name, str) or name not in POST_SPECTRA_TASKS:
            raise ValueError(
                f"spectra task {position}: unknown task {name!r}. "
                f"Available tasks: {sorted(POST_SPECTRA_TASKS)}."
            )
        spec = POST_SPECTRA_TASKS[name]
 
        field = entry.get("field", spec["fields"][0])
        if field not in spec["fields"]:
            raise ValueError(
                f"spectra task '{name}': field {field!r} is not supported. "
                f"Supported fields: {list(spec['fields'])}."
            )
 
        block = entry.get("block", 0)
        if not isinstance(block, int) or isinstance(block, bool) or block < 0:
            raise ValueError(f"spectra task '{name}': 'block' must be a non-negative integer.")
 
        symbol = entry.get("symbol", "continuum")
        if symbol not in POST_SPECTRA_SYMBOLS:
            raise ValueError(
                f"spectra task '{name}': unknown symbol {symbol!r}. "
                f"Available symbols: {list(POST_SPECTRA_SYMBOLS)}."
            )
 
        subtract_mean = entry.get("subtract_mean", "none")
        if not isinstance(subtract_mean, str) or not subtract_mean.strip():
            raise ValueError(f"spectra task '{name}': 'subtract_mean' must be a string.")
        subtract_mean = subtract_mean.strip()
        if subtract_mean.startswith("window:"):
            window_name = subtract_mean.split(":", 1)[1].strip()
            if not window_name:
                raise ValueError(
                    f"spectra task '{name}': 'subtract_mean: window:<name>' needs a window name."
                )
        elif subtract_mean not in POST_SPECTRA_MEAN_MODES:
            raise ValueError(
                f"spectra task '{name}': unknown subtract_mean {subtract_mean!r}. "
                f"Use one of {list(POST_SPECTRA_MEAN_MODES)} or 'window:<name>'."
            )
 
        # A window mean is only worth subtracting once the window has converged, so the
        # bundle the mean is read from is chosen separately from the step being
        # transformed. Left unset, each step uses its own bundle, whose running mean is
        # undefined at the moment the window activates.
        mean_source_step = entry.get("mean_source_step")
        if mean_source_step is not None:
            if (not isinstance(mean_source_step, int) or isinstance(mean_source_step, bool)
                    or mean_source_step < 0):
                raise ValueError(
                    f"spectra task '{name}': 'mean_source_step' must be a non-negative integer."
                )
            if not subtract_mean.startswith("window:"):
                raise ValueError(
                    f"spectra task '{name}': 'mean_source_step' only applies to "
                    f"'subtract_mean: window:<name>'."
                )
 
        reference = entry.get("reference")
        if reference is not None and (not isinstance(reference, str) or not reference.strip()):
            raise ValueError(f"spectra task '{name}': 'reference' must be a non-empty string.")
 
        selection = {}
        if name != "shell_spectrum":
            axes = entry.get("axes")
            fixed = entry.get("fixed_indices")
            count = 2 if name == "plane_spectrum" else 1
            if (not isinstance(axes, list) or len(axes) != count or any(a not in ("i", "j", "k") for a in axes)
                    or len(set(axes)) != count or not isinstance(fixed, dict)
                    or set(fixed) != set("ijk")-set(axes)
                    or any(isinstance(i, bool) or not isinstance(i, int) or i < 0 for i in fixed.values())):
                raise ValueError(f"{name} requires {count} distinct axes and zero-based fixed_indices on all remaining axes.")
            if symbol != "continuum":
                raise ValueError("plane/line spectra require symbol: continuum.")
            selection = {"axes": sorted(axes), "fixed_indices": dict(sorted(fixed.items()))}
        elif subtract_mean == "sample" or "axes" in entry or "fixed_indices" in entry:
            raise ValueError("shell_spectrum does not accept sample subtraction or plane/line selections.")
        # Each task writes its own file, so a repeat would overwrite its own output.
        identity = (name, field, block, symbol, json.dumps(selection, sort_keys=True))
        if identity in seen:
            raise ValueError(
                f"spectra recipe lists task '{name}' for field {field} on block {block} "
                f"with symbol '{symbol}' more than once."
            )
        seen.append(identity)
        cleaned.append({
            "task": name,
            **selection,
            "field": field,
            "block": block,
            "symbol": symbol,
            "subtract_mean": subtract_mean,
            "mean_source_step": mean_source_step,
            "reference": reference.strip() if isinstance(reference, str) else None,
        })
 
    return {"output_prefix": prefix.strip(), "tasks": cleaned}
 
 

Here is the caller graph for this function:

validate_post_spectra_preconditions()

list picurv_cli.core.validate_post_spectra_preconditions	(	dict	spectra_cfg,
		dict	case_cfg,
		str	post_path
	)

Check spectra tasks against what the case can actually support.

Runs before any field is read, so a case with no homogeneous direction is refused rather than yielding a curve that means nothing. Only the checks the case file can answer are made here: periodicity and block count. Grid uniformity is enforced by generators/spectra.gen, which reads the staged PICGRID and is the only place the real node coordinates are known.

Parameters

[in]	spectra_cfg	Normalized spectra recipe.
[in]	case_cfg	Parsed case configuration.
[in]	post_path	Post recipe path, for error messages.

Returns

List of formatted error strings; empty when every task is supportable.

Definition at line 3903 of file core.py.

def validate_post_spectra_preconditions(spectra_cfg: dict, case_cfg: dict, post_path: str) -> list:
    """!
    @brief Check spectra tasks against what the case can actually support.
 
    @details Runs before any field is read, so a case with no homogeneous direction is
             refused rather than yielding a curve that means nothing. Only the checks
             the case file can answer are made here: periodicity and block count. Grid
             uniformity is enforced by `generators/spectra.gen`, which reads the staged
             PICGRID and is the only place the real node coordinates are known.
 
    @param[in] spectra_cfg Normalized spectra recipe.
    @param[in] case_cfg Parsed case configuration.
    @param[in] post_path Post recipe path, for error messages.
    @return List of formatted error strings; empty when every task is supportable.
    """
    errors = []
    if not spectra_cfg.get("tasks"):
        return errors
 
    try:
        prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    except ValueError:
        # The case file reports its own boundary-condition errors; do not repeat them.
        return errors
 
    block_count = int((case_cfg.get("models", {}) or {}).get("domain", {}).get("blocks", 1))
    periodic_faces = {}
    for block_index, block_bcs in enumerate(prepared_blocks):
        faces = {entry.get("face") for entry in block_bcs if entry.get("type") == "PERIODIC"}
        periodic_faces[block_index] = faces
 
    # run_post_spectra_stage reads the staged PICGRID, which only file and grid_gen
    # grids provide; refuse here rather than after the solve has run.
    grid_mode = str((case_cfg.get("grid", {}) or {}).get("mode", "")).strip()
    if grid_mode == "programmatic_c":
        errors.append(
            f"  {post_path}: spectra need a staged PICGRID, which grid.mode 'programmatic_c' "
            "does not provide. Use grid.mode 'grid_gen' or 'file' for a case whose spectra "
            "are measured."
        )
        return errors
 
    all_faces = {"-Xi", "+Xi", "-Eta", "+Eta", "-Zeta", "+Zeta"}
    for task_cfg in spectra_cfg["tasks"]:
        spec = POST_SPECTRA_TASKS[task_cfg["task"]]
        label = f"spectra task '{task_cfg['task']}'"
 
        if spec.get("requires_single_block") and block_count != 1:
            errors.append(
                f"  {post_path}: {label} requires a single-block domain; this case has "
                f"{block_count} blocks."
            )
 
        block = task_cfg["block"]
        if block >= block_count:
            errors.append(
                f"  {post_path}: {label} targets block {block}, but the case defines "
                f"{block_count} block(s)."
            )
            continue
 
        if task_cfg["task"] != "shell_spectrum":
            if (case_cfg.get("models", {}).get("physics", {}).get("fsi", {}) or {}).get("immersed", False):
                errors.append(f"  {post_path}: {label} does not support immersed masks.")
            names = {"i": "Xi", "j": "Eta", "k": "Zeta"}
            needed = {sign+names[a] for a in task_cfg["axes"] for sign in ("-", "+")}
            if not needed <= periodic_faces.get(block, set()):
                errors.append(f"  {post_path}: {label} requires PERIODIC boundaries on its transform axes.")
        if spec.get("requires_periodic_geometric"):
            missing = sorted(all_faces - periodic_faces.get(block, set()))
            if missing:
                errors.append(
                    f"  {post_path}: {label} requires every face of block {block} to be "
                    f"PERIODIC, because a shell-averaged spectrum is only defined for a "
                    f"triply periodic homogeneous box. Non-periodic faces: {missing}."
                )
    return errors
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_resolve_spectra_payload()

str picurv_cli.core._resolve_spectra_payload ( dict  bundle, str  kind, str  field, int  block  )

protected

Locate one checkpoint payload by its inventory entry rather than by path shape.

Parameters

[in]	bundle	Validated checkpoint bundle mapping.
[in]	kind	Payload kind recorded in the inventory.
[in]	field	Payload field name recorded in the inventory.
[in]	block	Block index the payload belongs to.

Returns

Absolute path to the payload file.

Exceptions

ValueError

when the bundle carries no such payload.

Definition at line 3982 of file core.py.

def _resolve_spectra_payload(bundle: dict, kind: str, field: str, block: int) -> str:
    """!
    @brief Locate one checkpoint payload by its inventory entry rather than by path shape.
    @param[in] bundle Validated checkpoint bundle mapping.
    @param[in] kind Payload kind recorded in the inventory.
    @param[in] field Payload field name recorded in the inventory.
    @param[in] block Block index the payload belongs to.
    @return Absolute path to the payload file.
    @throws ValueError when the bundle carries no such payload.
    """
    for payload in bundle["payloads"]:
        if (payload["kind"] == kind and payload["field"] == field
                and payload["block"] == str(block)):
            return os.path.join(bundle["bundle"], *payload["path"].split("/"))
    raise ValueError(
        f"checkpoint {os.path.basename(bundle['bundle'])} carries no {kind} payload "
        f"'{field}' for block {block}."
    )
 
 

Here is the caller graph for this function:

_spectra_mean_arguments()

list picurv_cli.core._spectra_mean_arguments ( dict  task_cfg, dict  bundle, dict   mean_bundle = None  )

protected

Build the generator arguments implementing a task's fluctuation choice.

Parameters

[in]	task_cfg	Normalized spectra task.
[in]	bundle	Validated checkpoint bundle for the step being transformed.
[in]	mean_bundle	Bundle supplying the window mean; defaults to bundle.

Returns

Argument list to append to the generator command.

Exceptions

ValueError

when a named window is absent from the bundle.

Definition at line 4002 of file core.py.

def _spectra_mean_arguments(task_cfg: dict, bundle: dict, mean_bundle: dict = None) -> list:
    """!
    @brief Build the generator arguments implementing a task's fluctuation choice.
    @param[in] task_cfg Normalized spectra task.
    @param[in] bundle Validated checkpoint bundle for the step being transformed.
    @param[in] mean_bundle Bundle supplying the window mean; defaults to @p bundle.
    @return Argument list to append to the generator command.
    @throws ValueError when a named window is absent from the bundle.
    """
    mode = task_cfg["subtract_mean"]
    if not mode.startswith("window:"):
        return ["--subtract-mean", mode]
    window = mode.split(":", 1)[1].strip()
    block = task_cfg["block"]
    source = mean_bundle or bundle
    mean_path = _resolve_spectra_payload(source, "mean", f"{window}/{task_cfg['field']}_mean", block)
    count_path = _resolve_spectra_payload(source, "occupancy", f"{window}/count", block)
    return ["--subtract-mean", "field", "--mean-file", mean_path, "--count-file", count_path]
 
 
#: Scalar columns the spectra stage records once per processed step.

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_post_stage_selection()

set picurv_cli.core.resolve_post_stage_selection

(

only

)

Resolve the --only selector into the set of post stages to execute.

Parameters

[in]

only

Comma-separated selector text, or None for every stage.

Returns

Set of stage names.

Exceptions

ValueError

when the selector names an unknown or empty stage.

Definition at line 4034 of file core.py.

def resolve_post_stage_selection(only) -> set:
    """!
    @brief Resolve the `--only` selector into the set of post stages to execute.
    @param[in] only Comma-separated selector text, or None for every stage.
    @return Set of stage names.
    @throws ValueError when the selector names an unknown or empty stage.
    """
    if not only:
        return set(POST_STAGE_NAMES)
    requested = [token.strip() for token in str(only).split(",")]
    if not all(requested):
        raise ValueError("--only must not contain an empty stage name.")
    unknown = sorted({token for token in requested if token not in POST_STAGE_NAMES})
    if unknown:
        raise ValueError(
            f"--only names unknown post stage(s) {unknown}. "
            f"Available stages: {list(POST_STAGE_NAMES)}."
        )
    return set(requested)
 
 

Here is the caller graph for this function:

run_post_spectra_stage()

dict picurv_cli.core.run_post_spectra_stage	(	str	run_dir,
		dict	post_cfg,
		dict	monitor_cfg,
		str	source_dir,
			steps,
		bool	quiet = False,
		"dict | None"	plan = None,
		bool	recompute = False
	)

Measure spectra for every requested task across a window of committed steps.

One spectrum per step per task, because a spectrum is a property of one state: averaging across steps would be wrong for a decaying flow, where every step is a different statistical state. Results are written in long form so a family of curves stays one file, alongside a scalar history that plots through the ordinary series machinery.

Parameters

[in]	run_dir	Run directory receiving the output.
[in]	post_cfg	Parsed post-processing configuration.
[in]	monitor_cfg	Parsed monitor configuration anchoring the output root.
[in]	source_dir	Directory holding the committed checkpoints.
[in]	steps	Iterable of checkpoint steps to process, in order.
[in]	quiet	Suppress progress reporting.
[in]	plan	Post plan whose recipe state records each measured step; with it, a step whose rows are still valid (classify_post_step()) is not measured again. None measures every committed step given.
[in]	recompute	Measure every committed step even when its rows are valid.

Returns

Summary with the written paths and the steps actually processed.

Exceptions

ValueError

when the generator fails or a requested payload is absent.

Definition at line 4055 of file core.py.

                           plan: "dict | None" = None, recompute: bool = False) -> dict:
    """!
    @brief Measure spectra for every requested task across a window of committed steps.
 
    @details One spectrum per step per task, because a spectrum is a property of one
             state: averaging across steps would be wrong for a decaying flow, where
             every step is a different statistical state. Results are written in long
             form so a family of curves stays one file, alongside a scalar history that
             plots through the ordinary series machinery.
 
    @param[in] run_dir Run directory receiving the output.
    @param[in] post_cfg Parsed post-processing configuration.
    @param[in] monitor_cfg Parsed monitor configuration anchoring the output root.
    @param[in] source_dir Directory holding the committed checkpoints.
    @param[in] steps Iterable of checkpoint steps to process, in order.
    @param[in] quiet Suppress progress reporting.
    @param[in] plan Post plan whose recipe state records each measured step; with it, a
                    step whose rows are still valid (classify_post_step()) is not
                    measured again. None measures every committed step given.
    @param[in] recompute Measure every committed step even when its rows are valid.
    @return Summary with the written paths and the steps actually processed.
    @throws ValueError when the generator fails or a requested payload is absent.
    """
    spectra = normalize_post_spectra_config(post_cfg)
    if not spectra["tasks"]:
        return {"tasks": [], "steps": [], "artifacts": []}
 
    script = os.path.join(GENERATORS_PATH, "spectra.gen")
    if not os.path.isfile(script):
        raise ValueError(f"spectra.gen script not found: {script}")
    staged_grid = os.path.join(run_dir, "inputs", "grid", "grid.run")
    if not os.path.isfile(staged_grid):
        raise ValueError(f"spectra require a staged PICGRID at {staged_grid}.")
 
    output_dir = os.path.join(
        os.path.abspath(run_dir), resolve_recipe_spectra_output_dir(post_cfg, monitor_cfg)
    )
    os.makedirs(output_dir, exist_ok=True)
 
    # Spectra are computed from the staged non-dimensional field on the staged
    # non-dimensional grid, so physical units are the generator's to apply. The run's
    # own configuration snapshot is the authority for the scales it used.
    scale_arguments = []
    # Checkpoint times are solver time; a dimensionalized result reports physical time.
    time_scale = 1.0
    if bool((post_cfg.get("global_operations") or {}).get("dimensionalize", False)):
        active_case = load_active_run_configuration(run_dir).get("case")
        case_path = os.path.join(run_dir, active_case) if active_case else None
        if case_path and os.path.isfile(case_path):
            scaling = resolve_fluid_scaling(read_yaml_file(case_path))
            scale_arguments = [
                "--velocity-ref", repr(float(scaling["velocity_ref"])),
                "--length-ref", repr(float(scaling["length_ref"])),
            ]
            time_scale = reference_scale(TIME, scaling)
        elif not quiet:
            print("[WARNING] Spectra: dimensionalize was requested but this run carries no "
                  "readable case snapshot; results stay non-dimensional.", file=sys.stderr)
 
    requested = sorted(set(int(step) for step in steps))
    signature = compute_post_spectra_signature(spectra)
    records = {}
    if plan is not None:
        # Steps whose rows are still valid are not measured again; unrecorded rows are
        # adopted on the same terms as field output (classify_post_step()).
        existing = _read_post_records(plan['resume_state_path'])[1]
        # Each task writes a spectrum and a history file; a step is measured only when
        # both of every task's files hold it.
        spectra_files = [
            os.path.join(output_dir, f"{post_spectra_task_basename(task, spectra['output_prefix'])}{suffix}.csv")
            for task in spectra["tasks"] for suffix in ("", "_history")
        ]
        measured = set.intersection(*(_scan_post_statistics_csv_steps(path) for path in spectra_files))
        pending = []
        for step in requested:
            record = existing.get(str(step))
            commit = _checkpoint_commit(source_dir, step)
            reason = classify_post_step(record, spectra_files if step in measured else None,
                                        commit, signature, recompute)
            if reason is not None:
                pending.append(step)
            elif record is None:
                records[step] = {"recipe": signature, "checkpoint": commit[0] if commit else None}
        if not quiet and len(pending) != len(requested):
            print(f"[INFO] Spectra: {len(requested) - len(pending)} requested step(s) are up to date.")
        try:
            require_storage_payload_local(run_dir, "spectra", checkpoints=pending)
        except StorageError as exc:
            raise ValueError(str(exc)) from exc
        requested = pending
        if not requested:
            persist_post_resume_state(run_dir, plan, spectra=records)
            return {"tasks": [], "steps": [], "artifacts": []}
    # The requested window is what the recipe asks for, not what exists. Like the field
    # stage, only committed checkpoints are measured: a window reaching past the last
    # committed checkpoint is normal while a solve is still running, and is not an error.
    available = _scan_committed_checkpoint_steps(source_dir)
    ordered_steps = [step for step in requested if step in available]
    if not ordered_steps:
        if not quiet:
            print("[INFO] Spectra: no step needing measurement has a committed checkpoint "
                  "yet; nothing measured.")
        if plan is not None:
            persist_post_resume_state(run_dir, plan, spectra=records)
        return {"tasks": [], "steps": [], "artifacts": []}
    if not quiet and len(ordered_steps) != len(requested):
        print(f"[INFO] Spectra: {len(ordered_steps)} of {len(requested)} step(s) needing "
              f"measurement are committed; measuring those.")
    artifacts = []
    for task_cfg in spectra["tasks"]:
        basename = post_spectra_task_basename(task_cfg, spectra["output_prefix"])
        spectrum_path = os.path.join(output_dir, f"{basename}.csv")
        scalar_path = os.path.join(output_dir, f"{basename}_history.csv")
        spectrum_rows = []
        scalar_rows = []
        mean_bundle = None
        if task_cfg["mean_source_step"] is not None:
            mean_bundle = validate_committed_checkpoint(source_dir, task_cfg["mean_source_step"])
 
        for step in ordered_steps:
            bundle = validate_committed_checkpoint(source_dir, step)
            time = float(bundle["metadata"]["checkpoint_time"]) * time_scale
            field_path = _resolve_spectra_payload(
                bundle, "eulerian", task_cfg["field"], task_cfg["block"]
            )
            cmd = [sys.executable, script, task_cfg["task"].replace("_", "-"),
                   "--field-file", field_path, "--source-grid", staged_grid,
                   "--block", str(task_cfg["block"]), "--symbol", task_cfg["symbol"]]
            if task_cfg["task"] != "shell_spectrum":
                cmd.extend(["--axes", *task_cfg["axes"], "--fixed-indices", json.dumps(task_cfg["fixed_indices"])])
            cmd.extend(_spectra_mean_arguments(task_cfg, bundle, mean_bundle))
            cmd.extend(scale_arguments)
            cmd.extend(petsc_index_arguments(int(bundle["metadata"].get("checkpoint_petsc_index_bytes", "4"))))
            result = subprocess.run(cmd, text=True, capture_output=True)
            if result.returncode != 0:
                details = (result.stderr or result.stdout or "").strip()
                raise ValueError(
                    f"spectra task '{task_cfg['task']}' failed at step {step} with exit code "
                    f"{result.returncode}. Details:\n{details}"
                )
            summary = json.loads(result.stdout)
            for row in summary.get("sampled_spectrum", summary.get("shell_spectrum")):
                spectrum_rows.append({"step": step, "time": time, **row})
            scalar_columns = (POST_SPECTRA_SCALAR_COLUMNS if task_cfg["task"] == "shell_spectrum"
                              else ("resolved_kinetic_energy", "parseval_residual"))
            scalar_rows.append({"step": step, "time": time,
                                **{name: summary[name] for name in scalar_columns}})
 
        spectrum_fields = ("step", "time", *summary.get("spectrum_columns", ("k", "energy")))
        scalar_fields = ("step", "time") + scalar_columns
        # Only the steps that were missing or stale are measured; keep the rows already
        # written for every other step, replacing only those re-measured now.
        remeasured = set(ordered_steps)
        spectrum_rows = _merge_spectra_rows(spectrum_path, spectrum_fields, remeasured, spectrum_rows)
        scalar_rows = _merge_spectra_rows(scalar_path, scalar_fields, remeasured, scalar_rows)
        with open(spectrum_path, "w", newline="", encoding="utf-8") as stream:
            writer = csv.DictWriter(stream, fieldnames=spectrum_fields)
            writer.writeheader()
            writer.writerows(spectrum_rows)
        with open(scalar_path, "w", newline="", encoding="utf-8") as stream:
            writer = csv.DictWriter(stream, fieldnames=scalar_fields)
            writer.writeheader()
            writer.writerows(scalar_rows)
        artifacts.extend([spectrum_path, scalar_path])
        if not quiet:
            print(f"[INFO] Spectra: measured {len(ordered_steps)} step(s) for task "
                  f"'{task_cfg['task']}'; {os.path.relpath(spectrum_path, run_dir)} now holds "
                  f"{len(scalar_rows)} step(s)")
 
    if plan is not None:
        for step in ordered_steps:
            commit = _checkpoint_commit(source_dir, step)
            records[step] = {"recipe": signature, "checkpoint": commit[0] if commit else None}
        persist_post_resume_state(run_dir, plan, spectra=records)
    return {
        "tasks": [entry["task"] for entry in spectra["tasks"]],
        "steps": ordered_steps,
        "artifacts": artifacts,
    }
 
 
#: Reducer tasks a post recipe may request. Each runs a `generators/reduce.gen`
#: subcommand over the field-statistics profiles of one window or ensemble.
#: `retains` is how many directions the profile must keep, and `axis_key` the task key
#: naming the one it keeps (`wall_axis`) or the one it merged (`stream_axis`).

Here is the call graph for this function:

Here is the caller graph for this function:

normalize_post_reducers_config()

dict picurv_cli.core.normalize_post_reducers_config

(

dict

post_cfg

)

Validate and canonicalize the reducers block of post.yml.

A reducer reads the profiles field_statistics writes, so each task names a window or ensemble of the same recipe, and the recipe's homogeneous must leave the directions the task needs.

Parameters

[in]

post_cfg

Parsed post-processing configuration.

Returns

Mapping with the canonical task list.

Definition at line 4263 of file core.py.

def normalize_post_reducers_config(post_cfg: dict) -> dict:
    """!
    @brief Validate and canonicalize the reducers block of post.yml.
    @details A reducer reads the profiles `field_statistics` writes, so each task names a
             window or ensemble of the same recipe, and the recipe's `homogeneous` must
             leave the directions the task needs.
    @param[in] post_cfg Parsed post-processing configuration.
    @return Mapping with the canonical task list.
    """
    raw = (post_cfg or {}).get("reducers")
    if raw is None:
        return {"tasks": []}
    if not isinstance(raw, dict) or not isinstance(raw.get("tasks"), list) or not raw["tasks"]:
        raise ValueError("'reducers' must be a mapping with a non-empty 'tasks' list.")
    statistics = normalize_post_field_statistics_config(post_cfg)
    windows = set(statistics["windows"])
    owners = windows | {ensemble["name"] for ensemble in statistics["ensembles"]}
    retained = [axis for axis in ("i", "j", "k") if axis not in statistics["homogeneous"]]
    tasks = []
    for index, entry in enumerate(raw["tasks"]):
        if not isinstance(entry, dict):
            raise ValueError(f"'reducers.tasks[{index}]' must be a mapping.")
        name = entry.get("task")
        if not isinstance(name, str) or name not in POST_REDUCER_TASKS:
            raise ValueError(f"reducer task {name!r} is unknown. Available tasks: {sorted(POST_REDUCER_TASKS)}.")
        spec = POST_REDUCER_TASKS[name]
        label = f"reducer '{name}'"
        source = entry.get("source")
        if not isinstance(source, str) or source not in owners:
            raise ValueError(f"{label}: 'source' must name a field_statistics window or ensemble of this "
                             f"recipe (got {source!r}; available: {sorted(owners)}).")
        if "csv" not in statistics["formats"] or len(retained) != spec["retains"]:
            raise ValueError(f"{label} reads a profile keeping {spec['retains']} direction(s), so "
                             f"field_statistics needs 'csv' in formats and 'homogeneous' leaving that "
                             f"many (it leaves {retained}).")
        task = {"task": name, "source": source}
        if spec["axis_key"]:
            axis = entry.get(spec["axis_key"], spec["default_axis"])
            if axis not in _REDUCER_AXIS_TOKENS:
                raise ValueError(f"{label}: '{spec['axis_key']}' must be one of i, j, k (got {axis!r}).")
            kept = axis in retained
            if kept != (spec["axis_key"] == "wall_axis"):
                raise ValueError(f"{label}: the profile {'must keep' if not kept else 'must merge over'} "
                                 f"'{axis}', but 'homogeneous' is {statistics['homogeneous']}.")
            task[spec["axis_key"]] = axis
            stream = entry.get("stream_axis", "k")
            if stream not in _REDUCER_AXIS_TOKENS or stream == task.get("wall_axis"):
                raise ValueError(f"{label}: 'stream_axis' must be i, j or k and differ from the wall axis.")
            task["stream_axis"] = stream
            friction = entry.get("friction_velocity", "first_cell")
            if friction not in POST_REDUCER_FRICTION_SOURCES or (name == "cross_section" and friction == "wall_model"):
                raise ValueError(f"{label}: 'friction_velocity' must be one of "
                                 f"{[f for f in POST_REDUCER_FRICTION_SOURCES if name != 'cross_section' or f != 'wall_model']} "
                                 f"(got {friction!r}).")
            needs = POST_REDUCER_FRICTION_SOURCES.get(friction, {}).get("needs")
            if needs == "window" and source not in windows:
                raise ValueError(f"{label}: friction_velocity '{friction}' averages over a run window's time "
                                 f"bounds, so 'source' must be a run window, not an ensemble.")
            task["friction_velocity"] = friction
            if needs == "value":
                value = entry.get("value")
                if not isinstance(value, (int, float)) or isinstance(value, bool) or value <= 0:
                    raise ValueError(f"{label}: friction_velocity '{friction}' needs a positive 'value'.")
                task["value"] = float(value)
            if name == "cross_section":
                task["fold"] = bool(entry.get("fold", True))
            if name == "wall_profile" and entry.get("half_height") is not None:
                task["half_height"] = float(entry["half_height"])
        tasks.append(task)
    return {"tasks": tasks}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

run_post_reducers_stage()

list picurv_cli.core.run_post_reducers_stage	(	str	run_dir,
		dict	post_cfg,
		bool	quiet = False
	)

Run every reducer task over the profiles the recipe has written.

Reducers read only small CSVs, so every profile present is reduced again on each invocation rather than tracked step by step. Inputs come from the run: the viscosity and reference scales from its case snapshot, the grid it was staged with, a window's effective bounds from each step's checkpoint.meta, and the runtime metrics CSVs.

Parameters

[in]	run_dir	Run directory.
[in]	post_cfg	Post recipe with canonical paths applied.
[in]	quiet	Suppress progress reporting.

Returns

Absolute paths written.

Exceptions

ValueError

when a reducer fails.

Definition at line 4335 of file core.py.

def run_post_reducers_stage(run_dir: str, post_cfg: dict, quiet: bool = False) -> list:
    """!
    @brief Run every reducer task over the profiles the recipe has written.
    @details Reducers read only small CSVs, so every profile present is reduced again on
             each invocation rather than tracked step by step. Inputs come from the run:
             the viscosity and reference scales from its case snapshot, the grid it was
             staged with, a window's effective bounds from each step's `checkpoint.meta`,
             and the runtime metrics CSVs.
    @param[in] run_dir Run directory.
    @param[in] post_cfg Post recipe with canonical paths applied.
    @param[in] quiet Suppress progress reporting.
    @return Absolute paths written.
    @throws ValueError when a reducer fails.
    """
    tasks = normalize_post_reducers_config(post_cfg)["tasks"]
    if not tasks:
        return []
    run_dir = os.path.abspath(run_dir)
    if not isinstance((post_cfg or {}).get("_picurv_paths"), dict):
        post_cfg, _ = apply_canonical_post_paths(post_cfg, run_dir)
    script = os.path.join(GENERATORS_PATH, "reduce.gen")
    grid = os.path.join(run_dir, "inputs", "grid", "grid.run")
    case_path = load_active_run_configuration(run_dir).get("case")
    case_cfg = read_yaml_file(case_path) if case_path and os.path.isfile(case_path) else {}
    scaling = resolve_fluid_scaling(case_cfg)
    dimensional = bool((post_cfg.get("global_operations") or {}).get("dimensionalize", False))
    velocity_scale = scaling["velocity_ref"] if dimensional else 1.0
    dt_physical = float((case_cfg.get("run_control") or {}).get("dt_physical", 0.0) or 0.0)
    step_time = dt_physical if dimensional else dt_physical / reference_scale(TIME, scaling)
    prefix = os.path.join(run_dir, post_cfg["_picurv_paths"]["field_statistics_prefix"])
    output_root = os.path.join(run_dir, CANONICAL_RUN_PATHS["output"])
    lineage = resolve_run_lineage(run_dir)
    written = []
 
    def lineage_metrics(name):
        """!
        @brief List a metrics CSV across the restart lineage, root to leaf.
        @details A window carried into a branched run spans its ancestors' time, whose
                 metrics rows are in their own files. Each ancestor's file is limited to
                 the steps up to the checkpoint its child branched from.
        @param[in] name Metrics CSV basename.
        @return `path` or `path@last_step` entries for every segment holding the file.
        """
        entries = []
        for index, segment in enumerate(lineage):
            path = os.path.join(segment["run_dir"], CANONICAL_RUN_PATHS["metrics"], name)
            if not os.path.isfile(path):
                continue
            child = lineage[index + 1] if index + 1 < len(lineage) else None
            entries.append(f"{path}@{child['fork_step']}" if child else path)
        return entries or [os.path.join(run_dir, CANONICAL_RUN_PATHS["metrics"], name)]
 
    def run(arguments, label):
        """!
        @brief Run one reduce.gen subcommand, failing with its own diagnostics.
        @param[in] arguments Subcommand and its arguments.
        @param[in] label Reducer and step named in a failure.
        """
        result = subprocess.run([sys.executable, script, *arguments], text=True, capture_output=True)
        if result.returncode != 0:
            raise ValueError(f"reducer {label} failed with exit code {result.returncode}:\n"
                             f"{(result.stderr or result.stdout).strip()}")
 
    for task in tasks:
        family = f"{prefix}_profile_{task['source']}"
        if task["task"] == "profile_series":
            output = f"{family}_history.csv"
            if _scan_post_vtk_steps(family, "csv"):
                run(["profile-series", "--profile-prefix", family, "--dt", repr(step_time),
                     "--output", output], f"profile_series of '{task['source']}'")
                written.append(output)
            continue
        friction = {"first_cell": [], "body_force": ["--body-force", repr(task.get("value"))],
                    "u_tau": ["--u-tau", repr(task.get("value"))],
                    "driven_flow": ["--driven-flow-csv", *lineage_metrics("driven_flow.csv")],
                    "wall_model": ["--wall-model-csv", *lineage_metrics("wall_model.csv")]}[task["friction_velocity"]]
        for step, path in sorted(_scan_post_vtk_steps(family, "csv").items()):
            arguments = [POST_REDUCER_TASKS[task["task"]]["command"], "--profile", path, "--grid", grid,
                         "--window", task["source"], "--viscosity",
                         repr(scaling["nondimensional_kinematic_viscosity"]),
                         "--velocity-scale", repr(velocity_scale),
                         "--stream-axis", _REDUCER_AXIS_TOKENS[task["stream_axis"]], *friction]
            metadata = os.path.join(_checkpoint_bundle_path(output_root, step), "checkpoint.meta")
            options = _read_checkpoint_options(metadata) if os.path.isfile(metadata) else {}
            for index in range(int(options.get("checkpoint_statistics_window_count", 0) or 0)):
                key = f"checkpoint_statistics_window_{index}_"
                if options.get(key + "name") == task["source"]:
                    arguments += ["--window-start", options[key + "effective_start"],
                                  "--window-end", options[key + "effective_end"],
                                  "--window-note", f"{options.get(key + 'state')}, "
                                                   f"{options.get(key + 'sample_count')} samples"]
            if task["task"] == "wall_profile":
                output = f"{prefix}_wall_profile_{task['source']}_{step}.csv"
                arguments += ["--wall-axis", _REDUCER_AXIS_TOKENS[task["wall_axis"]], "--output", output]
                if "half_height" in task:
                    arguments += ["--half-height", repr(task["half_height"])]
                written.append(output)
            else:
                output = f"{prefix}_cross_section_{task['source']}_{step}"
                arguments += ["--output-prefix", output] + ([] if task["fold"] else ["--no-fold"])
                written.append(output + "_cross_section.csv")
            run(arguments, f"{task['task']} of '{task['source']}' at step {step}")
    if not quiet:
        for path in written:
            print(f"[INFO] Reducer output: {os.path.relpath(path)}")
    return written
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_merge_spectra_rows()

list picurv_cli.core._merge_spectra_rows ( str  path, tuple  fieldnames, set  remeasured, list  new_rows  )

protected

Combine newly measured spectra rows with those already written for other steps.

The file belongs to one recipe, whose identity covers the spectra settings, so its existing rows come from the same measurement. Rows for a re-measured step are replaced; rows for every other step are kept. A file whose columns differ is not merged: it was written by another format and is rewritten whole.

Parameters

[in]	path	Existing CSV path, which may be absent.
[in]	fieldnames	Columns the new rows carry.
[in]	remeasured	Steps measured in this invocation.
[in]	new_rows	Rows measured in this invocation.

Returns

All rows, ordered by step with each step's rows in their measured order.

Definition at line 4443 of file core.py.

def _merge_spectra_rows(path: str, fieldnames: tuple, remeasured: set, new_rows: list) -> list:
    """!
    @brief Combine newly measured spectra rows with those already written for other steps.
    @details The file belongs to one recipe, whose identity covers the spectra settings, so
             its existing rows come from the same measurement. Rows for a re-measured step
             are replaced; rows for every other step are kept. A file whose columns differ
             is not merged: it was written by another format and is rewritten whole.
    @param[in] path Existing CSV path, which may be absent.
    @param[in] fieldnames Columns the new rows carry.
    @param[in] remeasured Steps measured in this invocation.
    @param[in] new_rows Rows measured in this invocation.
    @return All rows, ordered by step with each step's rows in their measured order.
    """
    kept = []
    try:
        with open(path, newline="", encoding="utf-8") as stream:
            reader = csv.DictReader(stream)
            if tuple(reader.fieldnames or ()) == tuple(fieldnames):
                kept = [row for row in reader if int(row["step"]) not in remeasured]
    except FileNotFoundError:
        pass
    return sorted(kept + list(new_rows), key=lambda row: int(row["step"]))
 
 

Here is the caller graph for this function:

compute_post_spectra_signature()

str picurv_cli.core.compute_post_spectra_signature

(

dict

spectra_cfg

)

Reduce a normalized spectra recipe to a stable identity string.

Parameters

[in]

spectra_cfg

Normalized spectra recipe.

Returns

Hex digest covering every choice that changes the produced spectra.

Definition at line 4467 of file core.py.

def compute_post_spectra_signature(spectra_cfg: dict) -> str:
    """!
    @brief Reduce a normalized spectra recipe to a stable identity string.
    @param[in] spectra_cfg Normalized spectra recipe.
    @return Hex digest covering every choice that changes the produced spectra.
    """
    payload = json.dumps(spectra_cfg, sort_keys=True, separators=(",", ":")).encode("utf-8")
    return hashlib.sha256(payload).hexdigest()[:16]
 
 

Here is the caller graph for this function:

resolve_post_spectra_output_dir()

str picurv_cli.core.resolve_post_spectra_output_dir

(

monitor_cfg = None

)

Resolve the run-relative directory spectra CSVs are written to.

Parameters

[in]

monitor_cfg

Optional monitor configuration anchoring the output root.

Returns

Run-relative directory path.

Definition at line 4477 of file core.py.

def resolve_post_spectra_output_dir(monitor_cfg=None) -> str:
    """!
    @brief Resolve the run-relative directory spectra CSVs are written to.
    @param[in] monitor_cfg Optional monitor configuration anchoring the output root.
    @return Run-relative directory path.
    """
    del monitor_cfg
    return CANONICAL_RUN_PATHS["spectra"]
 
 

Here is the caller graph for this function:

resolve_recipe_spectra_output_dir()

str picurv_cli.core.resolve_recipe_spectra_output_dir	(	dict	post_cfg,
			monitor_cfg = None
	)

Resolve the canonical spectra directory for one versioned recipe.

Parameters

[in]	post_cfg	Parsed runtime post config.
[in]	monitor_cfg	Optional monitor config for standalone compatibility.

Returns

Run-relative spectra directory.

Definition at line 4487 of file core.py.

def resolve_recipe_spectra_output_dir(post_cfg: dict, monitor_cfg=None) -> str:
    """!
    @brief Resolve the canonical spectra directory for one versioned recipe.
    @param[in] post_cfg Parsed runtime post config.
    @param[in] monitor_cfg Optional monitor config for standalone compatibility.
    @return Run-relative spectra directory.
    """
    internal = (post_cfg or {}).get("_picurv_paths", {}) or {}
    return internal.get("spectra") or resolve_post_spectra_output_dir(monitor_cfg)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

get_post_spectra_output_artifacts()

list picurv_cli.core.get_post_spectra_output_artifacts	(	dict	post_cfg,
		str	run_dir,
			monitor_cfg = None
	)

Predict the spectra CSV paths a recipe will write.

Parameters

[in]	post_cfg	Parsed post-processing configuration.
[in]	run_dir	Run directory the recipe operates on.
[in]	monitor_cfg	Optional monitor configuration anchoring the output root.

Returns

Absolute CSV paths, one per task, in recipe order.

Definition at line 4498 of file core.py.

def get_post_spectra_output_artifacts(post_cfg: dict, run_dir: str, monitor_cfg=None) -> list:
    """!
    @brief Predict the spectra CSV paths a recipe will write.
    @param[in] post_cfg Parsed post-processing configuration.
    @param[in] run_dir Run directory the recipe operates on.
    @param[in] monitor_cfg Optional monitor configuration anchoring the output root.
    @return Absolute CSV paths, one per task, in recipe order.
    """
    try:
        spectra = normalize_post_spectra_config(post_cfg)
    except ValueError:
        # The recipe reports its own errors during validation; predict nothing here.
        return []
    if not spectra["tasks"]:
        return []
    base = os.path.join(os.path.abspath(run_dir), resolve_recipe_spectra_output_dir(post_cfg, monitor_cfg))
    paths = []
    for task_cfg in spectra["tasks"]:
        name = post_spectra_task_basename(task_cfg, spectra["output_prefix"])
        paths.append(os.path.join(base, f"{name}.csv"))
    return list(dict.fromkeys(paths))
 
 

Here is the call graph for this function:

post_spectra_task_basename()

str picurv_cli.core.post_spectra_task_basename	(	dict	task_cfg,
		str	output_prefix
	)

Build the file basename one normalized spectra task writes.

Parameters

[in]	task_cfg	Normalized task mapping.
[in]	output_prefix	Recipe output prefix.

Returns

Basename without directory or extension.

Definition at line 4521 of file core.py.

def post_spectra_task_basename(task_cfg: dict, output_prefix: str) -> str:
    """!
    @brief Build the file basename one normalized spectra task writes.
    @param[in] task_cfg Normalized task mapping.
    @param[in] output_prefix Recipe output prefix.
    @return Basename without directory or extension.
    """
    parts = [output_prefix, task_cfg["task"], task_cfg["field"],
             f"block{task_cfg['block']:04d}", task_cfg["symbol"]]
    if task_cfg["task"] != "shell_spectrum":
        parts.extend(["".join(task_cfg["axes"]), *[f"{a}{i}" for a,i in task_cfg["fixed_indices"].items()]])
    return "_".join(parts)
 
 

Here is the caller graph for this function:

_normalize_post_statistics_ensembles()

list picurv_cli.core._normalize_post_statistics_ensembles (   raw )

protected

Validate and canonicalize the ensembles a post recipe defines.

An ensemble is a window over one instant: its samples are the particles in each cell, or each cell's own state, at the step being processed. It is defined in the recipe rather than the run, because it needs no state accumulated during the solve.

Parameters

[in]

raw

The recipe's field_statistics.ensembles list, or None.

Returns

List of ensembles with name, source, fields and covariances.

Definition at line 4535 of file core.py.

def _normalize_post_statistics_ensembles(raw) -> list:
    """!
    @brief Validate and canonicalize the ensembles a post recipe defines.
    @details An ensemble is a window over one instant: its samples are the particles in
             each cell, or each cell's own state, at the step being processed. It is
             defined in the recipe rather than the run, because it needs no state
             accumulated during the solve.
    @param[in] raw The recipe's `field_statistics.ensembles` list, or None.
    @return List of ensembles with name, source, fields and covariances.
    """
    if raw is None:
        return []
    if not isinstance(raw, list):
        raise ValueError("'field_statistics.ensembles' must be a list.")
    ensembles = []
    for index, entry in enumerate(raw):
        if not isinstance(entry, dict):
            raise ValueError(f"'field_statistics.ensembles[{index}]' must be a mapping.")
        name = entry.get("name")
        if not isinstance(name, str) or not name.strip():
            raise ValueError(f"'field_statistics.ensembles[{index}]' needs a non-empty 'name'.")
        name = name.strip()
        if any(existing["name"] == name for existing in ensembles):
            raise ValueError(f"field statistics ensemble '{name}' is defined more than once.")
        source = entry.get("source")
        if source not in POST_STATISTICS_ENSEMBLE_SOURCES:
            raise ValueError(
                f"field statistics ensemble '{name}': 'source' must be one of "
                f"{list(POST_STATISTICS_ENSEMBLE_SOURCES)} (got {source!r})."
            )
        fields, covariances = _normalize_statistics_requests(
            f"field statistics ensemble '{name}'", entry.get("fields"), entry.get("covariances"),
            _ensemble_source_fields(source))
        ensembles.append({"name": name, "source": source, "fields": fields, "covariances": covariances})
    return ensembles
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

normalize_post_field_statistics_config()

dict picurv_cli.core.normalize_post_field_statistics_config

(

dict

post_cfg

)

Validate and canonicalize the field_statistics block of post.yml.

The recipe names windows rather than redescribing them, because the window definitions already reach the post-processor through the run's solver control. Validation therefore covers the recipe's own choices only; a name no window matches is caught in C against the resolved list, which is the only place the real set is known.

Parameters

[in]

post_cfg

Parsed post-processing configuration.

Returns

Value returned by normalize_post_field_statistics_config().

Definition at line 4572 of file core.py.

def normalize_post_field_statistics_config(post_cfg: dict) -> dict:
    """!
    @brief Validate and canonicalize the field_statistics block of post.yml.
 
    @details The recipe names windows rather than redescribing them, because the
             window definitions already reach the post-processor through the run's
             solver control. Validation therefore covers the recipe's own choices
             only; a name no window matches is caught in C against the resolved list,
             which is the only place the real set is known.
 
    @param[in] post_cfg Parsed post-processing configuration.
    @return Value returned by `normalize_post_field_statistics_config()`.
    """
    raw = (post_cfg or {}).get("field_statistics")
    if raw is None:
        return {"windows": [], "ensembles": [], "homogeneous": [], "source_step": None,
                "outputs": [], "formats": []}
    if not isinstance(raw, dict):
        raise ValueError("'field_statistics' must be a mapping.")
 
    ensembles = _normalize_post_statistics_ensembles(raw.get("ensembles"))
    windows = raw.get("windows", [] if ensembles else None)
    if not isinstance(windows, list) or not (windows or ensembles):
        raise ValueError("'field_statistics.windows' must be a non-empty list of window names "
                         "unless 'ensembles' defines what to derive.")
    cleaned = []
    for entry in windows:
        if not isinstance(entry, str) or not entry.strip():
            raise ValueError("'field_statistics.windows' entries must be non-empty window names.")
        name = entry.strip()
        # Each window writes its own file, so a repeat would overwrite its own output.
        if name in cleaned:
            raise ValueError(f"field statistics recipe lists window '{name}' more than once.")
        cleaned.append(name)
    for ensemble in ensembles:
        if ensemble["name"] in cleaned:
            raise ValueError(f"field statistics ensemble '{ensemble['name']}' has the name of a "
                             "requested window; both would write the same files.")
 
    label = ", ".join(cleaned + [ensemble["name"] for ensemble in ensembles])
    source_step = raw.get("source_step")
    if source_step is not None:
        if not isinstance(source_step, int) or isinstance(source_step, bool) or source_step < 0:
            raise ValueError(
                f"field statistics recipe for [{label}]: 'source_step' must be a non-negative "
                f"integer (got {source_step!r})."
            )
 
    outputs = raw.get("outputs", list(POST_FIELD_STATISTICS_DEFAULT_OUTPUTS))
    if not isinstance(outputs, list) or not outputs:
        raise ValueError(f"field statistics recipe for [{label}]: 'outputs' must be a non-empty list.")
    unknown = [item for item in outputs if item not in POST_FIELD_STATISTICS_OUTPUTS]
    if unknown:
        raise ValueError(
            f"field statistics recipe for [{label}]: unknown outputs {unknown}. "
            f"Available outputs: {list(POST_FIELD_STATISTICS_OUTPUTS)}."
        )
    if len(set(outputs)) != len(outputs):
        raise ValueError(f"field statistics recipe for [{label}]: 'outputs' lists a duplicate.")
 
    formats = raw.get("formats", ["vtk"])
    if not isinstance(formats, list) or not formats:
        raise ValueError(f"field statistics recipe for [{label}]: 'formats' must be a non-empty list.")
    unknown = [item for item in formats if item not in POST_FIELD_STATISTICS_FORMATS]
    if unknown:
        raise ValueError(
            f"field statistics recipe for [{label}]: unknown formats {unknown}. "
            f"Available formats: {list(POST_FIELD_STATISTICS_FORMATS)}."
        )
    if len(set(formats)) != len(formats):
        raise ValueError(f"field statistics recipe for [{label}]: 'formats' lists a duplicate.")
 
    homogeneous = raw.get("homogeneous", [])
    if (not isinstance(homogeneous, list) or any(axis not in ("i", "j", "k") for axis in homogeneous)
            or len(set(homogeneous)) != len(homogeneous)):
        raise ValueError(
            f"field statistics recipe for [{label}]: 'homogeneous' must list distinct axes from "
            f"['i', 'j', 'k'] (got {homogeneous!r})."
        )
    # An ensemble has no convergence history, so its CSV output is the profile alone.
    if ensembles and "csv" in formats and not homogeneous:
        raise ValueError(
            f"field statistics recipe for [{label}]: an ensemble writes CSV only as a profile, "
            "so 'csv' needs 'homogeneous' to name the directions to merge over."
        )
 
    return {
        "windows": cleaned,
        "ensembles": ensembles,
        "homogeneous": [axis for axis in ("i", "j", "k") if axis in homogeneous],
        "source_step": source_step,
        "outputs": list(outputs),
        "formats": list(formats),
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_post_window_derived_field_count()

int picurv_cli.core._post_window_derived_field_count ( dict  window_cfg, list  outputs, dict   eligible = None  )

protected

Count the derived fields one window would produce for a set of outputs.

Mirrors the resolution the C derivation performs, so a recipe that would produce an empty file is refused before the run rather than after it. Each output resolves against what the window accumulated: a window keeping only first moments has no stresses, RMS, or turbulent kinetic energy to give.

Parameters

[in]	window_cfg	Normalized window definition from monitor.yml.
[in]	outputs	Requested output kinds.
[in]	eligible	Field table the window's fields are named from; the Eulerian table when None.

Returns

Value returned by _post_window_derived_field_count().

Definition at line 4668 of file core.py.

def _post_window_derived_field_count(window_cfg: dict, outputs: list, eligible: dict = None) -> int:
    """!
    @brief Count the derived fields one window would produce for a set of outputs.
 
    @details Mirrors the resolution the C derivation performs, so a recipe that would
             produce an empty file is refused before the run rather than after it. Each
             output resolves against what the window accumulated: a window keeping only
             first moments has no stresses, RMS, or turbulent kinetic energy to give.
 
    @param[in] window_cfg Normalized window definition from monitor.yml.
    @param[in] outputs Requested output kinds.
    @param[in] eligible Field table the window's fields are named from; the Eulerian
                        table when None.
    @return Value returned by `_post_window_derived_field_count()`.
    """
    eligible = STATISTICS_ELIGIBLE_FIELDS if eligible is None else eligible
    fields = window_cfg.get("fields", []) or []
    covariances = window_cfg.get("covariances", []) or []
    with_second = [f for f in fields if "second" in (f.get("moments") or [])]
    total = 0
    for kind in outputs:
        if kind == "mean":
            total += len(fields)
        elif kind == "reynolds_stress":
            for entry in with_second:
                dof = eligible[entry["field"]]["components"]
                total += 6 if dof == 3 else 1
        elif kind == "rms":
            for entry in with_second:
                total += eligible[entry["field"]]["components"]
        elif kind == "tke":
            total += sum(1 for entry in with_second
                         if eligible[entry["field"]]["components"] == 3)
        elif kind == "flux":
            total += len(covariances)
    return total
 
 

Here is the caller graph for this function:

_post_requests_field_statistics()

bool picurv_cli.core._post_requests_field_statistics ( dict  post_cfg )

protected

Return whether the current post recipe derives accumulated field statistics.

Parameters

[in]

post_cfg

Argument passed to _post_requests_field_statistics().

Returns

Value returned by _post_requests_field_statistics().

Definition at line 4706 of file core.py.

def _post_requests_field_statistics(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe derives accumulated field statistics.
    @param[in] post_cfg Argument passed to `_post_requests_field_statistics()`.
    @return Value returned by `_post_requests_field_statistics()`.
    """
    try:
        config = normalize_post_field_statistics_config(post_cfg)
        return bool(config["windows"] or config["ensembles"])
    except ValueError:
        # Malformed configuration is reported by validation, not by this predicate.
        return False
 
 

Here is the call graph for this function:

get_post_field_statistics_artifacts()

picurv_cli.core.get_post_field_statistics_artifacts	(	dict	post_cfg,
		str	run_dir
	)

Predict the per-window statistics artifacts a recipe will produce.

Returns one entry per window and format, so resume tracking can tell a half-finished window from a completed one.

Parameters

[in]	post_cfg	Parsed post-processing configuration.
[in]	run_dir	Run directory the outputs are written under.

Returns

List of (kind, path_prefix, window) tuples; kind is 'vtk', 'csv' (a history shared by every step) or 'profile' (a prefix taking _<step>.csv). window is None for a recipe ensemble, which every processed step produces.

Definition at line 4720 of file core.py.

def get_post_field_statistics_artifacts(post_cfg: dict, run_dir: str):
    """!
    @brief Predict the per-window statistics artifacts a recipe will produce.
    @details Returns one entry per window and format, so resume tracking can tell a
             half-finished window from a completed one.
    @param[in] post_cfg Parsed post-processing configuration.
    @param[in] run_dir Run directory the outputs are written under.
    @return List of (kind, path_prefix, window) tuples; kind is 'vtk', 'csv' (a history
            shared by every step) or 'profile' (a prefix taking `_<step>.csv`). window is
            None for a recipe ensemble, which every processed step produces.
    """
    config = normalize_post_field_statistics_config(post_cfg)
    if not (config["windows"] or config["ensembles"]):
        return []
    io_cfg = post_cfg.get("io", {}) or {}
    internal = (post_cfg or {}).get("_picurv_paths", {}) or {}
    visualization_dir = _post_output_directory_abs(run_dir, post_cfg)
    visualization_prefix = io_cfg.get("output_filename_prefix", "Field")
    csv_prefix_path = None
    if internal.get("field_statistics_prefix"):
        csv_prefix_path = os.path.join(run_dir, internal["field_statistics_prefix"])
    csv_base = csv_prefix_path or os.path.join(visualization_dir, str(visualization_prefix))
    artifacts = []
    # An ensemble is built from the step itself, so every processed step produces it;
    # its entries carry no window, which marks them as always expected.
    owners = [(window, window) for window in config["windows"]]
    owners += [(ensemble["name"], None) for ensemble in config["ensembles"]]
    for name, window in owners:
        if "vtk" in config["formats"]:
            artifacts.append(("vtk", os.path.join(
                visualization_dir, f"{visualization_prefix}_statistics_{name}"
            ), window))
        if "csv" in config["formats"] and window is not None:
            artifacts.append(("csv", f"{csv_base}_statistics_{name}.csv", window))
        if "csv" in config["formats"] and config["homogeneous"]:
            artifacts.append(("profile", f"{csv_base}_profile_{name}", window))
    return artifacts
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

build_post_recipe_config()

dict picurv_cli.core.build_post_recipe_config	(	dict	post_cfg,
			monitor_cfg = None
	)

Build the flat key=value mapping consumed by the C post-processor.

Parameters

[in]	post_cfg	Argument passed to build_post_recipe_config().
[in]	monitor_cfg	Optional parsed monitor YAML configuration dictionary.

Returns

Value returned by build_post_recipe_config().

Definition at line 4759 of file core.py.

def build_post_recipe_config(post_cfg: dict, monitor_cfg=None) -> dict:
    """!
    @brief Build the flat key=value mapping consumed by the C post-processor.
    @param[in] post_cfg Argument passed to `build_post_recipe_config()`.
    @param[in] monitor_cfg Optional parsed monitor YAML configuration dictionary.
    @return Value returned by `build_post_recipe_config()`.
    """
    c_config = {}
 
    c_config['startTime'] = get_post_run_control_value(post_cfg, 'start_step', 0)
    c_config['endTime'] = get_post_run_control_value(post_cfg, 'end_step', 0)
    c_config['timeStep'] = get_post_run_control_value(post_cfg, 'step_interval', 1)
 
    eulerian_pipeline_parts = []
    dimensionalize = bool(post_cfg.get('global_operations', {}).get('dimensionalize', False))
    if dimensionalize:
        # A setting rather than a pipeline stage: loaded fields are scaled as they are
        # read, derived statistics in the accumulator, particles after their MSD, and
        # spectra in their generator, each once, where the value is produced.
        c_config['dimensionalize'] = 'true'
 
    for task in post_cfg.get('eulerian_pipeline', []):
        task_name = task.get('task')
        if task_name == 'q_criterion':
            eulerian_pipeline_parts.append('ComputeQCriterion')
        elif task_name == 'normalize_field':
            field = task.get('field', 'P')
            eulerian_pipeline_parts.append(f'NormalizeRelativeField:{field}')
            ref_point = task.get('reference_point', [1, 1, 1])
            c_config['reference_ip'] = ref_point[0]
            c_config['reference_jp'] = ref_point[1]
            c_config['reference_kp'] = ref_point[2]
        elif task_name == 'nodal_average':
            in_field = task.get('input_field')
            out_field = task.get('output_field')
            if in_field and out_field:
                eulerian_pipeline_parts.append(f'CellToNodeAverage:{in_field}>{out_field}')
 
    if eulerian_pipeline_parts:
        c_config['process_pipeline'] = ";".join(eulerian_pipeline_parts)
 
    lagrangian_pipeline_parts = []
    for task in post_cfg.get('lagrangian_pipeline', []):
        task_name = task.get('task')
        if task_name == 'specific_ke':
            in_field = task.get('input_field')
            out_field = task.get('output_field')
            if in_field and out_field:
                lagrangian_pipeline_parts.append(f'ComputeSpecificKE:{in_field}>{out_field}')
    if lagrangian_pipeline_parts:
        c_config['particle_pipeline'] = ";".join(lagrangian_pipeline_parts)
 
    statistics_pipeline_parts = get_post_statistics_task_tokens(post_cfg)
    statistics_output_prefix = None
    stats_cfg = post_cfg.get('statistics_pipeline')
    if isinstance(stats_cfg, dict):
        statistics_output_prefix = stats_cfg.get('output_prefix')
 
    if statistics_pipeline_parts:
        c_config['statistics_pipeline'] = ";".join(statistics_pipeline_parts)
        statistics_output_prefix = resolve_post_statistics_output_prefix(post_cfg, monitor_cfg)
    elif statistics_output_prefix is None:
        statistics_output_prefix = post_cfg.get('statistics_output_prefix')
    if statistics_output_prefix:
        c_config['statistics_output_prefix'] = statistics_output_prefix
 
    io = post_cfg.get('io', {})
    internal_paths = post_cfg.get('_picurv_paths', {}) or {}
    field_statistics = normalize_post_field_statistics_config(post_cfg)
    if field_statistics["windows"] or field_statistics["ensembles"]:
        c_config['field_statistics_windows'] = ",".join(field_statistics["windows"])
        c_config['field_statistics_outputs'] = ",".join(field_statistics["outputs"])
        c_config['field_statistics_formats'] = ",".join(field_statistics["formats"])
        # An omitted source step means each processed step derives from its own
        # bundle, which is what turns a multi-step recipe into a convergence history.
        if field_statistics["source_step"] is not None:
            c_config['field_statistics_source_step'] = field_statistics["source_step"]
        if internal_paths.get("field_statistics_prefix"):
            c_config['field_statistics_output_prefix'] = internal_paths["field_statistics_prefix"]
        if field_statistics["homogeneous"]:
            c_config['field_statistics_homogeneous'] = ",".join(field_statistics["homogeneous"])
        # Ensemble lines are the run windows' option families under the ensemble kind;
        # the post-processor forwards them to the window parser it shares.
        if field_statistics["ensembles"]:
            c_config['field_statistics_ensemble_count'] = len(field_statistics["ensembles"])
        for index, ensemble in enumerate(field_statistics["ensembles"]):
            prefix = f"field_statistics_ensemble_{index}"
            c_config[f'{prefix}_name'] = ensemble["name"]
            c_config[f'{prefix}_source'] = ensemble["source"]
            c_config[f'{prefix}_field_count'] = len(ensemble["fields"])
            for field_index, field_entry in enumerate(ensemble["fields"]):
                c_config[f'{prefix}_field_{field_index}_name'] = field_entry["field"]
                c_config[f'{prefix}_field_{field_index}_moments'] = ",".join(field_entry["moments"])
            c_config[f'{prefix}_covariance_count'] = len(ensemble["covariances"])
            for pair_index, pair in enumerate(ensemble["covariances"]):
                c_config[f'{prefix}_covariance_{pair_index}'] = f"{pair[0]},{pair[1]}"
 
    c_config['output_prefix'] = io.get('output_directory', 'viz') + '/' + io.get('output_filename_prefix', 'Field')
    c_config['particle_output_prefix'] = io.get('output_directory', 'viz') + '/' + io.get('particle_filename_prefix', 'Particle')
    c_config['output_particles'] = io.get('output_particles', False)
    c_config['particle_output_freq'] = io.get('particle_subsampling_frequency', 1)
    c_config['output_fields_instantaneous'] = ",".join(io.get('eulerian_fields', []))
    c_config['particle_fields_instantaneous'] = ",".join(io.get('particle_fields', []))
    input_extensions = get_post_input_extensions(post_cfg)
    if isinstance(input_extensions, dict):
        for extension_name in ('eulerian', 'particle'):
            extension = input_extensions.get(extension_name)
            if extension and str(extension).strip().lstrip('.').lower() != 'dat':
                raise ValueError(
                    f"post input extension '{extension_name}' must be 'dat'; "
                    "committed checkpoint payload names are fixed."
                )
 
    source_directory = get_post_source_directory_template(post_cfg, default=None)
    if source_directory is not None:
        c_config['source_directory'] = source_directory
 
    # Spectra run in the conductor's Python stage, but the recipe fingerprint is
    # computed over this mapping, so the block has to be represented here or a
    # changed spectra recipe would leave its steps' records looking valid. The C
    # post-processor accepts and ignores the key.
    spectra = normalize_post_spectra_config(post_cfg)
    if spectra["tasks"]:
        c_config['spectra_signature'] = compute_post_spectra_signature(spectra)
 
    return c_config
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

compute_post_recipe_id()

str picurv_cli.core.compute_post_recipe_id

(

dict

post_cfg

)

Compute a stable human-readable identity for one post recipe.

Parameters

[in]

post_cfg

Parsed post configuration before runtime path injection.

Returns

Filesystem-safe recipe identity.

Definition at line 4887 of file core.py.

def compute_post_recipe_id(post_cfg: dict) -> str:
    """!
    @brief Compute a stable human-readable identity for one post recipe.
    @param[in] post_cfg Parsed post configuration before runtime path injection.
    @return Filesystem-safe recipe identity.
    """
    normalized = copy.deepcopy(post_cfg or {})
    normalized.pop("_picurv_paths", None)
    # source_data.directory is always replaced by the run's own output, so an absent
    # block and an emptied one are the same recipe; both hash as the emptied form that
    # every earlier recipe, which carried the directory, reduced to.
    source = normalized.setdefault("source_data", {})
    if isinstance(source, dict):
        source.pop("directory", None)
    io = normalized.get("io")
    label = "post"
    if isinstance(io, dict):
        io.pop("output_directory", None)
        # ParaView collection generation changes only how existing VTK artifacts are
        # indexed.  It must not split an otherwise identical computational recipe,
        # especially when a child enables lineage indexing for an ancestor whose VTK
        # files predate the option.
        io.pop("paraview_series", None)
        raw_label = io.get("output_filename_prefix")
        if isinstance(raw_label, str) and raw_label.strip():
            label = re.sub(r"[^A-Za-z0-9_.-]+", "-", raw_label.strip()).strip("-") or "post"
    run_control = normalized.get("run_control")
    if isinstance(run_control, dict):
        for key in POST_RUN_CONTROL_ALIASES["start_step"] + POST_RUN_CONTROL_ALIASES["end_step"]:
            run_control.pop(key, None)
    # Reducers read the recipe's outputs without changing them, so adding or revising
    # one must not move the recipe to a new home and recompute every field.
    normalized.pop("reducers", None)
    digest = hashlib.sha256(
        json.dumps(normalized, sort_keys=True, separators=(",", ":")).encode("utf-8")
    ).hexdigest()[:12]
    return f"{label}-{digest}"
 
 

Here is the caller graph for this function:

apply_canonical_post_paths()

"tuple[dict, str]" picurv_cli.core.apply_canonical_post_paths	(	dict	post_cfg,
		str	run_dir
	)

Route every post artifact into its fixed analysis or visualization home.

Parameters

[in]	post_cfg	Parsed user recipe.
[in]	run_dir	Run receiving derived artifacts.

Returns

Runtime-only config copy and stable recipe id.

Definition at line 4926 of file core.py.

def apply_canonical_post_paths(post_cfg: dict, run_dir: str) -> "tuple[dict, str]":
    """!
    @brief Route every post artifact into its fixed analysis or visualization home.
    @param[in] post_cfg Parsed user recipe.
    @param[in] run_dir Run receiving derived artifacts.
    @return Runtime-only config copy and stable recipe id.
    """
    recipe_id = compute_post_recipe_id(post_cfg)
    runtime = copy.deepcopy(post_cfg)
    if not isinstance(runtime.get("source_data"), dict):
        runtime["source_data"] = {}
    runtime["source_data"]["directory"] = os.path.join(
        os.path.abspath(run_dir), CANONICAL_RUN_PATHS["output"]
    )
    io = runtime.setdefault("io", {})
    io["output_directory"] = os.path.join(CANONICAL_RUN_PATHS["visualization"], recipe_id)
    output_prefix = io.get("output_filename_prefix", "Field")
    stats_cfg = runtime.get("statistics_pipeline")
    if isinstance(stats_cfg, dict):
        basename = stats_cfg.get("output_prefix", "Stats")
        stats_cfg["output_prefix"] = os.path.join(
            CANONICAL_RUN_PATHS["statistics"], recipe_id, os.path.basename(str(basename))
        )
    runtime["_picurv_paths"] = {
        "recipe_id": recipe_id,
        "recipe_root": os.path.join("config", "post-recipes", recipe_id),
        "visualization": io["output_directory"],
        "statistics": os.path.join(CANONICAL_RUN_PATHS["statistics"], recipe_id),
        "field_statistics_prefix": os.path.join(
            CANONICAL_RUN_PATHS["statistics"], recipe_id, str(output_prefix)
        ),
        "spectra": os.path.join(CANONICAL_RUN_PATHS["spectra"], recipe_id),
    }
    return runtime, recipe_id
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

normalize_post_recipe_signature()

dict picurv_cli.core.normalize_post_recipe_signature

(

dict

recipe_cfg

)

Normalize post recipe settings into a stable signature mapping.

Parameters

[in]

recipe_cfg

Argument passed to normalize_post_recipe_signature().

Returns

Value returned by normalize_post_recipe_signature().

Definition at line 4962 of file core.py.

def normalize_post_recipe_signature(recipe_cfg: dict) -> dict:
    """!
    @brief Normalize post recipe settings into a stable signature mapping.
    @param[in] recipe_cfg Argument passed to `normalize_post_recipe_signature()`.
    @return Value returned by `normalize_post_recipe_signature()`.
    """
    signature = {}
    for key, value in (recipe_cfg or {}).items():
        if key in POST_RECIPE_SIGNATURE_EXCLUDED_KEYS or value is None:
            continue
        if isinstance(value, bool):
            text = 'true' if value else 'false'
        else:
            text = str(value).strip()
            if text.lower() in {'true', 'false'}:
                text = text.lower()
        if text:
            signature[str(key)] = text
    return signature
 
 

Here is the caller graph for this function:

compute_post_recipe_fingerprint()

"tuple[dict, str]" picurv_cli.core.compute_post_recipe_fingerprint

(

dict

recipe_cfg

)

Return normalized recipe signature plus SHA-256 fingerprint.

Parameters

[in]

recipe_cfg

Argument passed to compute_post_recipe_fingerprint().

Returns

Value returned by compute_post_recipe_fingerprint().

Definition at line 4983 of file core.py.

def compute_post_recipe_fingerprint(recipe_cfg: dict) -> "tuple[dict, str]":
    """!
    @brief Return normalized recipe signature plus SHA-256 fingerprint.
    @param[in] recipe_cfg Argument passed to `compute_post_recipe_fingerprint()`.
    @return Value returned by `compute_post_recipe_fingerprint()`.
    """
    signature = normalize_post_recipe_signature(recipe_cfg)
    payload = json.dumps(signature, sort_keys=True, separators=(',', ':')).encode('utf-8')
    return signature, hashlib.sha256(payload).hexdigest()
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

get_post_resume_state_path()

str picurv_cli.core.get_post_resume_state_path	(	str	run_dir,
		dict	post_cfg = None
	)

Return the JSON resume metadata path for a run directory.

Parameters

[in]	run_dir	Argument passed to get_post_resume_state_path().
[in]	post_cfg	Optional versioned post recipe configuration.

Returns

Value returned by get_post_resume_state_path().

Definition at line 4994 of file core.py.

def get_post_resume_state_path(run_dir: str, post_cfg: dict = None) -> str:
    """!
    @brief Return the JSON resume metadata path for a run directory.
    @param[in] run_dir Argument passed to `get_post_resume_state_path()`.
    @param[in] post_cfg Optional versioned post recipe configuration.
    @return Value returned by `get_post_resume_state_path()`.
    """
    if post_cfg is None:
        return os.path.join(run_dir, 'config', POST_RESUME_STATE_FILENAME)
    return os.path.join(get_post_recipe_root(run_dir, post_cfg), "state.json")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

get_post_recipe_root()

str picurv_cli.core.get_post_recipe_root	(	str	run_dir,
		dict	post_cfg
	)

Return the versioned run-local control directory for one post recipe.

Parameters

[in]	run_dir	Owning run root.
[in]	post_cfg	Runtime post config with canonical paths, or a user recipe.

Returns

Absolute recipe control directory.

Definition at line 5006 of file core.py.

def get_post_recipe_root(run_dir: str, post_cfg: dict) -> str:
    """!
    @brief Return the versioned run-local control directory for one post recipe.
    @param[in] run_dir Owning run root.
    @param[in] post_cfg Runtime post config with canonical paths, or a user recipe.
    @return Absolute recipe control directory.
    """
    internal = (post_cfg or {}).get("_picurv_paths", {}) or {}
    recipe_id = internal.get("recipe_id") or compute_post_recipe_id(post_cfg)
    return os.path.join(os.path.abspath(run_dir), "config", "post-recipes", recipe_id)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

get_post_lock_paths()

dict picurv_cli.core.get_post_lock_paths	(	str	run_dir,
		str	recipe_id = None
	)

Return lock-wrapper related paths for a run directory.

Parameters

[in]	run_dir	Argument passed to get_post_lock_paths().
[in]	recipe_id	Optional stable recipe identity used to scope the lock.

Returns

Value returned by get_post_lock_paths().

Definition at line 5018 of file core.py.

def get_post_lock_paths(run_dir: str, recipe_id: str = None) -> dict:
    """!
    @brief Return lock-wrapper related paths for a run directory.
    @param[in] run_dir Argument passed to `get_post_lock_paths()`.
    @param[in] recipe_id Optional stable recipe identity used to scope the lock.
    @return Value returned by `get_post_lock_paths()`.
    """
    scheduler_dir = os.path.join(run_dir, 'scheduler')
    suffix = f".{recipe_id}" if recipe_id else ""
    return {
        'lock_file': os.path.join(scheduler_dir, f"post{suffix}.lock"),
        'metadata_file': os.path.join(scheduler_dir, f"post{suffix}.lock.json"),
        'wrapper_path': os.path.join(scheduler_dir, POST_LOCK_WRAPPER_FILENAME),
    }
 
 

Here is the caller graph for this function:

_post_output_directory_abs()

str picurv_cli.core._post_output_directory_abs ( str  run_dir, dict  post_cfg  )

protected

Resolve the absolute post output directory for the current recipe.

Parameters

[in]	run_dir	Argument passed to _post_output_directory_abs().
[in]	post_cfg	Argument passed to _post_output_directory_abs().

Returns

Value returned by _post_output_directory_abs().

Definition at line 5034 of file core.py.

def _post_output_directory_abs(run_dir: str, post_cfg: dict) -> str:
    """!
    @brief Resolve the absolute post output directory for the current recipe.
    @param[in] run_dir Argument passed to `_post_output_directory_abs()`.
    @param[in] post_cfg Argument passed to `_post_output_directory_abs()`.
    @return Value returned by `_post_output_directory_abs()`.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    internal = (post_cfg or {}).get("_picurv_paths", {}) or {}
    relative = internal.get("visualization") or io_cfg.get('output_directory')
    if not relative:
        relative = os.path.join(CANONICAL_RUN_PATHS["visualization"], compute_post_recipe_id(post_cfg))
    return os.path.abspath(os.path.join(run_dir, relative))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_post_requests_eulerian_output()

bool picurv_cli.core._post_requests_eulerian_output ( dict  post_cfg )

protected

Return whether the current post recipe expects Eulerian VTK output artifacts.

Parameters

[in]

post_cfg

Argument passed to _post_requests_eulerian_output().

Returns

Value returned by _post_requests_eulerian_output().

Definition at line 5049 of file core.py.

def _post_requests_eulerian_output(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe expects Eulerian VTK output artifacts.
    @param[in] post_cfg Argument passed to `_post_requests_eulerian_output()`.
    @return Value returned by `_post_requests_eulerian_output()`.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    return bool(io_cfg.get('eulerian_fields'))
 
 

Here is the caller graph for this function:

_post_requests_particle_output()

bool picurv_cli.core._post_requests_particle_output ( dict  post_cfg )

protected

Return whether the current post recipe expects particle VTP output artifacts.

Parameters

[in]

post_cfg

Argument passed to _post_requests_particle_output().

Returns

Value returned by _post_requests_particle_output().

Definition at line 5059 of file core.py.

def _post_requests_particle_output(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe expects particle VTP output artifacts.
    @param[in] post_cfg Argument passed to `_post_requests_particle_output()`.
    @return Value returned by `_post_requests_particle_output()`.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    return bool(io_cfg.get('output_particles')) and bool(io_cfg.get('particle_fields'))
 
 

Here is the caller graph for this function:

normalize_post_paraview_series_config()

dict picurv_cli.core.normalize_post_paraview_series_config

(

dict

post_cfg

)

Normalize the optional ParaView collection policy in a post recipe.

Parameters

[in]

post_cfg

Parsed post-processing configuration.

Returns

Mapping with enabled and scope keys.

Definition at line 5072 of file core.py.

def normalize_post_paraview_series_config(post_cfg: dict) -> dict:
    """!
    @brief Normalize the optional ParaView collection policy in a post recipe.
    @param[in] post_cfg Parsed post-processing configuration.
    @return Mapping with enabled and scope keys.
    """
    raw = ((post_cfg or {}).get("io") or {}).get("paraview_series")
    if raw is None:
        return {"enabled": False, "scope": "run"}
    if isinstance(raw, bool):
        return {"enabled": raw, "scope": "lineage" if raw else "run"}
    if not isinstance(raw, dict):
        raise ValueError("'io.paraview_series' must be a boolean or mapping.")
    enabled = raw.get("enabled", True)
    scope = str(raw.get("scope", "lineage")).strip().lower()
    if not isinstance(enabled, bool):
        raise ValueError("'io.paraview_series.enabled' must be a boolean.")
    if scope not in POST_PARAVIEW_SERIES_SCOPES:
        raise ValueError("'io.paraview_series.scope' must be 'run' or 'lineage'.")
    return {"enabled": enabled, "scope": scope}
 
 

Here is the caller graph for this function:

_resolve_lineage_parent_run()

str picurv_cli.core._resolve_lineage_parent_run ( str  child_run_dir, dict  lineage  )

protected

Resolve and identity-check one recorded lineage parent.

Parameters

[in]	child_run_dir	Child run directory used to resolve workspace-relative paths.
[in]	lineage	Recorded branch-lineage mapping.

Returns

Absolute path to the identity-matched parent run.

Definition at line 5094 of file core.py.

def _resolve_lineage_parent_run(child_run_dir: str, lineage: dict) -> str:
    """!
    @brief Resolve and identity-check one recorded lineage parent.
    @param[in] child_run_dir Child run directory used to resolve workspace-relative paths.
    @param[in] lineage Recorded branch-lineage mapping.
    @return Absolute path to the identity-matched parent run.
    """
    recorded = lineage.get("parent_path")
    parent_id = lineage.get("parent_run_id")
    if not recorded or not parent_id:
        raise ValueError(f"Run lineage is missing parent_path or parent_run_id: {child_run_dir}")
    if os.path.isabs(str(recorded)):
        candidates = [os.path.abspath(str(recorded))]
    else:
        workspace_root = find_workspace_root(child_run_dir)
        candidates = ([os.path.abspath(os.path.join(workspace_root, str(recorded)))]
                      if workspace_root else [])
    workspace_root = find_workspace_root(child_run_dir)
    if workspace_root:
        runs_root = os.path.join(workspace_root, "runs")
        if os.path.isdir(runs_root):
            candidates.extend(
                os.path.join(runs_root, name) for name in os.listdir(runs_root)
                if os.path.isdir(os.path.join(runs_root, name))
            )
    seen = set()
    for candidate in candidates:
        candidate = os.path.abspath(candidate)
        if candidate in seen or not os.path.isdir(candidate):
            continue
        seen.add(candidate)
        try:
            identity = read_artifact_identity(candidate)
        except (OSError, ValueError, KeyError):
            continue
        if identity.get("run_id") == parent_id:
            return candidate
    raise ValueError(
        f"Lineage parent '{parent_id}' for run '{os.path.basename(child_run_dir)}' "
        f"could not be resolved from recorded path '{recorded}'."
    )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_run_lineage()

list picurv_cli.core.resolve_run_lineage	(	str	run_dir,
		str	scope = "lineage"
	)

Return root-to-leaf run segments, for a ParaView collection or a reducer's metrics.

Parameters

[in]	run_dir	Leaf run whose lineage is resolved.
[in]	scope	Either run-local or full-lineage collection scope.

Returns

Ordered run-segment mappings from root to leaf.

Each entry carries the run path, manifest, and the checkpoint at which that run branched from its parent. Cycles and unresolved parents fail.

Definition at line 5137 of file core.py.

def resolve_run_lineage(run_dir: str, scope: str = "lineage") -> list:
    """!
    @brief Return root-to-leaf run segments, for a ParaView collection or a reducer's metrics.
    @param[in] run_dir Leaf run whose lineage is resolved.
    @param[in] scope Either run-local or full-lineage collection scope.
    @return Ordered run-segment mappings from root to leaf.
    @details Each entry carries the run path, manifest, and the checkpoint at which
             that run branched from its parent. Cycles and unresolved parents fail.
    """
    current = os.path.abspath(run_dir)
    reverse = []
    seen_ids = set()
    while True:
        manifest = _read_json_if_exists(os.path.join(current, "manifest.json")) or {}
        run_id = manifest.get("run_id") or os.path.basename(current)
        if run_id in seen_ids:
            chain = " -> ".join([entry["run_id"] for entry in reversed(reverse)] + [run_id])
            raise ValueError(f"Cycle detected while resolving visualization lineage: {chain}")
        seen_ids.add(run_id)
        lineage = manifest.get("lineage") or {"relationship": "root"}
        reverse.append({
            "run_dir": current,
            "run_id": run_id,
            "manifest": manifest,
            "lineage": lineage,
            "fork_step": (int(lineage["checkpoint_step"])
                          if lineage.get("relationship") == "branch" else None),
        })
        if scope == "run" or lineage.get("relationship") != "branch":
            break
        current = _resolve_lineage_parent_run(current, lineage)
    return list(reversed(reverse))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_existing_pvd_times()

dict picurv_cli.core._existing_pvd_times ( str  pvd_path )

protected

Read step-to-time fallbacks from an existing PVD collection.

Parameters

[in]

pvd_path

Existing collection path.

Returns

Mapping from output step to physical time.

Definition at line 5171 of file core.py.

def _existing_pvd_times(pvd_path: str) -> dict:
    """!
    @brief Read step-to-time fallbacks from an existing PVD collection.
    @param[in] pvd_path Existing collection path.
    @return Mapping from output step to physical time.
    """
    if not os.path.isfile(pvd_path):
        return {}
    try:
        root = ElementTree.parse(pvd_path).getroot()
    except (ElementTree.ParseError, OSError):
        return {}
    result = {}
    for dataset in root.findall(".//DataSet"):
        filename = os.path.basename(dataset.get("file", ""))
        match = re.search(r"_(\d+)\.(?:vts|vtp)$", filename)
        try:
            if match:
                result[int(match.group(1))] = float(dataset.get("timestep"))
        except (TypeError, ValueError):
            continue
    return result
 
 

Here is the caller graph for this function:

_checkpoint_time_for_series()

float picurv_cli.core._checkpoint_time_for_series ( str  run_dir, int  step, dict  fallback, float   time_scale = 1.0  )

protected

Read the authoritative time of one visualization frame.

Checkpoints record solver time. A dimensionalized recipe writes physical frames, so its collection reports physical time: the checkpoint time multiplied by the owning run's reference time.

Parameters

[in]	run_dir	Run owning the frame.
[in]	step	Frame checkpoint step.
[in]	fallback	Existing collection times, already in the collection's units, used after checkpoint pruning.
[in]	time_scale	Factor from solver time to the collection's time unit.

Returns

Frame time in the collection's unit system.

Definition at line 5195 of file core.py.

def _checkpoint_time_for_series(run_dir: str, step: int, fallback: dict, time_scale: float = 1.0) -> float:
    """!
    @brief Read the authoritative time of one visualization frame.
    @details Checkpoints record solver time. A dimensionalized recipe writes physical
             frames, so its collection reports physical time: the checkpoint time
             multiplied by the owning run's reference time.
    @param[in] run_dir Run owning the frame.
    @param[in] step Frame checkpoint step.
    @param[in] fallback Existing collection times, already in the collection's units,
               used after checkpoint pruning.
    @param[in] time_scale Factor from solver time to the collection's time unit.
    @return Frame time in the collection's unit system.
    """
    metadata_path = os.path.join(
        run_dir, CANONICAL_RUN_PATHS["checkpoints"],
        f"step_{step:0{CHECKPOINT_STEP_WIDTH}d}", "checkpoint.meta",
    )
    commit_path = os.path.join(os.path.dirname(metadata_path), "COMMITTED")
    if os.path.isfile(metadata_path) and os.path.isfile(commit_path):
        options = _read_checkpoint_options(metadata_path)
        try:
            recorded_step = int(options["checkpoint_step"])
            physical_time = float(options["checkpoint_time"])
        except (KeyError, TypeError, ValueError) as exc:
            raise ValueError(f"Checkpoint time metadata is malformed: {metadata_path}") from exc
        if recorded_step != step or not math.isfinite(physical_time):
            raise ValueError(f"Checkpoint time metadata does not match step {step}: {metadata_path}")
        return physical_time * time_scale
    if step in fallback:
        return float(fallback[step])
    raise ValueError(
        f"Visualization frame at step {step} has no locally available checkpoint time in "
        f"'{run_dir}'. Restore its checkpoints or retain an existing PVD carrying the time."
    )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_write_pvd_collection()

None picurv_cli.core._write_pvd_collection ( str  path, list  entries  )

protected

Atomically write one VTK Collection file.

Parameters

[in]	path	Destination PVD path.
[in]	entries	Ordered frame mappings.

Returns

None.

Definition at line 5231 of file core.py.

def _write_pvd_collection(path: str, entries: list) -> None:
    """!
    @brief Atomically write one VTK Collection file.
    @param[in] path Destination PVD path.
    @param[in] entries Ordered frame mappings.
    @return None.
    """
    root = ElementTree.Element("VTKFile", {
        "type": "Collection", "version": "0.1", "byte_order": "LittleEndian",
    })
    collection = ElementTree.SubElement(root, "Collection")
    base = os.path.dirname(os.path.abspath(path))
    for entry in entries:
        ElementTree.SubElement(collection, "DataSet", {
            "timestep": format(float(entry["time"]), ".17g"),
            "group": "", "part": "0",
            "file": os.path.relpath(entry["path"], base).replace(os.sep, "/"),
        })
    content = '<?xml version="1.0"?>\n' + ElementTree.tostring(root, encoding="unicode") + "\n"
    os.makedirs(base, exist_ok=True)
    temporary = f"{path}.tmp.{os.getpid()}"
    try:
        with open(temporary, "w", encoding="utf-8") as stream:
            stream.write(content)
            stream.flush()
            os.fsync(stream.fileno())
        os.replace(temporary, path)
    finally:
        if os.path.exists(temporary):
            os.unlink(temporary)
 
 

Here is the caller graph for this function:

_lineage_reset_index()

int picurv_cli.core._lineage_reset_index ( list  segments, str  family  )

protected

Return the first segment belonging to one continuous artifact family.

Parameters

[in]	segments	Root-to-leaf lineage segments.
[in]	family	Artifact family being indexed.

Returns

Index of the first segment after the last relevant reset.

Definition at line 5263 of file core.py.

def _lineage_reset_index(segments: list, family: str) -> int:
    """!
    @brief Return the first segment belonging to one continuous artifact family.
    @param[in] segments Root-to-leaf lineage segments.
    @param[in] family Artifact family being indexed.
    @return Index of the first segment after the last relevant reset.
    """
    start = 0
    for index, segment in enumerate(segments[1:], start=1):
        if family == "particle":
            case_path = os.path.join(segment["run_dir"], "config", "case.yml")
            case_cfg = read_yaml_file(case_path) if os.path.isfile(case_path) else {}
            particles = (((case_cfg.get("models") or {}).get("physics") or {}).get("particles") or {})
            if str(particles.get("restart_mode", "init")).strip().lower() != "load":
                start = index
        elif family == "statistics":
            if str(segment["lineage"].get("statistics_state", "reset")).lower() != "carry":
                start = index
    return start
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

finalize_post_paraview_series()

list picurv_cli.core.finalize_post_paraview_series	(	str	run_dir,
		dict	post_cfg
	)

Build physical-time ParaView collections from current or lineage VTK output.

Parameters

[in]	run_dir	Leaf run receiving the collection.
[in]	post_cfg	Parsed post-processing recipe.

Returns

Absolute PVD paths written. Disabled recipes return an empty list.

Definition at line 5284 of file core.py.

def finalize_post_paraview_series(run_dir: str, post_cfg: dict) -> list:
    """!
    @brief Build physical-time ParaView collections from current or lineage VTK output.
    @param[in] run_dir Leaf run receiving the collection.
    @param[in] post_cfg Parsed post-processing recipe.
    @return Absolute PVD paths written. Disabled recipes return an empty list.
    """
    policy = normalize_post_paraview_series_config(post_cfg)
    if not policy["enabled"]:
        return []
    run_dir = os.path.abspath(run_dir)
    if not isinstance((post_cfg or {}).get("_picurv_paths"), dict):
        post_cfg, _ = apply_canonical_post_paths(post_cfg, run_dir)
    recipe_id = post_cfg["_picurv_paths"]["recipe_id"]
    requested_start, requested_end, _interval = resolve_post_requested_window(
        post_cfg,
        read_yaml_file(os.path.join(run_dir, "config", "case.yml")),
    )
    segments = resolve_run_lineage(run_dir, policy["scope"])
    io_cfg = post_cfg.get("io", {}) or {}
    families = []
    if _post_requests_eulerian_output(post_cfg):
        families.append(("field", io_cfg.get("output_filename_prefix", "Field"), "vts"))
    if _post_requests_particle_output(post_cfg):
        families.append(("particle", io_cfg.get("particle_filename_prefix", "Particle"), "vtp"))
    for kind, prefix_path, _window in get_post_field_statistics_artifacts(post_cfg, run_dir):
        if kind == "vtk":
            families.append(("statistics", os.path.basename(prefix_path), "vts"))
 
    # Each run's frames are timed by that run's own reference time, so a lineage stays
    # physically continuous even across runs whose scales differ.
    dimensionalize = bool((post_cfg.get("global_operations") or {}).get("dimensionalize", False))
 
    def segment_time_scale(segment: dict) -> float:
        """!
        @brief Return the factor from one lineage run's solver time to the collection's time.
        @param[in] segment Lineage segment.
        @return Reference time of the run when dimensionalizing, otherwise 1.
        """
        if not dimensionalize:
            return 1.0
        case_path = os.path.join(segment["run_dir"], "config", "case.yml")
        return reference_scale(TIME, resolve_reference_scales(read_yaml_file(case_path)))
 
    written = []
    for family, prefix, extension in families:
        active_segments = segments[_lineage_reset_index(segments, family):]
        entries = []
        for index, segment in enumerate(active_segments):
            lower = requested_start
            if segment["fork_step"] is not None:
                lower = max(lower, int(segment["fork_step"]))
            upper = requested_end
            if index + 1 < len(active_segments):
                upper = min(upper, int(active_segments[index + 1]["fork_step"]) - 1)
            if lower > upper:
                continue
            viz_dir = os.path.join(
                segment["run_dir"], CANONICAL_RUN_PATHS["visualization"], recipe_id
            )
            pvd_path = os.path.join(viz_dir, f"{prefix}.pvd")
            fallback = _existing_pvd_times(pvd_path)
            pattern = re.compile(rf"^{re.escape(prefix)}_(\d+)\.{re.escape(extension)}$")
            found = []
            if os.path.isdir(viz_dir):
                for name in os.listdir(viz_dir):
                    match = pattern.match(name)
                    if match and lower <= int(match.group(1)) <= upper:
                        found.append((int(match.group(1)), os.path.join(viz_dir, name)))
            if not found and index + 1 < len(active_segments):
                raise ValueError(
                    f"Lineage run '{segment['run_id']}' has no {prefix} visualization "
                    f"frames for its required segment {lower}..{upper} and recipe '{recipe_id}'."
                )
            for step, frame_path in sorted(found):
                entries.append({
                    "step": step,
                    "time": _checkpoint_time_for_series(segment["run_dir"], step, fallback,
                                                        segment_time_scale(segment)),
                    "path": os.path.abspath(frame_path),
                    "run_id": segment["run_id"],
                })
        if not entries:
            continue
        for previous, current in zip(entries, entries[1:]):
            if current["time"] <= previous["time"]:
                raise ValueError(
                    f"ParaView series time is not strictly increasing: {previous['run_id']} "
                    f"step {previous['step']} has {previous['time']:.17g}, followed by "
                    f"{current['run_id']} step {current['step']} at {current['time']:.17g}."
                )
        output_dir = _post_output_directory_abs(run_dir, post_cfg)
        output_path = os.path.join(output_dir, f"{prefix}.pvd")
        _write_pvd_collection(output_path, entries)
        print(
            f"[SUCCESS] Wrote ParaView {family} series: {output_path} "
            f"({len(entries)} frame(s), time {entries[0]['time']:.17g}..{entries[-1]['time']:.17g})"
        )
        written.append(output_path)
    return written
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_post_finalize_python_source()

str picurv_cli.core._post_finalize_python_source ( )

protected

Return the importable serial finalizer used by generated jobs.

Returns

Python source suitable for a serial interpreter invocation.

Definition at line 5386 of file core.py.

def _post_finalize_python_source() -> str:
    """!
    @brief Return the importable serial finalizer used by generated jobs.
    @return Python source suitable for a serial interpreter invocation.
    """
    package_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
    return (
        "import os,sys;"
        f"sys.path.insert(0,{package_root!r});"
        "from picurv_cli.core import read_yaml_file,apply_canonical_post_paths,finalize_post_outputs;"
        "run=os.path.abspath(sys.argv[1]);cfg=read_yaml_file(sys.argv[2]);"
        "cfg,_=apply_canonical_post_paths(cfg,run);finalize_post_outputs(run,cfg,(sys.argv[3] if len(sys.argv)>3 else '').split(','))"
    )
 
 

Here is the caller graph for this function:

build_post_finalize_command()

list picurv_cli.core.build_post_finalize_command	(	str	run_dir,
		str	archived_post_path,
		dict	post_cfg,
			post_stages = POST_STAGE_NAMES
	)

Build the serial post-success command for staged execution.

It runs after the field post-processor succeeds, in the conductor or in the submitted job, so whatever reads the field stage's output belongs here: the ParaView collections and the reducers.

Parameters

[in]	run_dir	Run receiving the collection.
[in]	archived_post_path	Archived post recipe read by the finalizer.
[in]	post_cfg	Parsed post-processing recipe.
[in]	post_stages	Selected post stages; reducers run only when selected.

Returns

Command tokens, or an empty list when there is nothing to finalize.

Definition at line 5401 of file core.py.

                                post_stages=POST_STAGE_NAMES) -> list:
    """!
    @brief Build the serial post-success command for staged execution.
    @details It runs after the field post-processor succeeds, in the conductor or in the
             submitted job, so whatever reads the field stage's output belongs here: the
             ParaView collections and the reducers.
    @param[in] run_dir Run receiving the collection.
    @param[in] archived_post_path Archived post recipe read by the finalizer.
    @param[in] post_cfg Parsed post-processing recipe.
    @param[in] post_stages Selected post stages; reducers run only when selected.
    @return Command tokens, or an empty list when there is nothing to finalize.
    """
    reducers = "reducers" in post_stages and bool(normalize_post_reducers_config(post_cfg)["tasks"])
    if not normalize_post_paraview_series_config(post_cfg)["enabled"] and not reducers:
        return []
    return [
        sys.executable, "-c", _post_finalize_python_source(),
        os.path.abspath(run_dir), os.path.abspath(archived_post_path),
        "reducers" if reducers else "-",
    ]
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

finalize_post_outputs()

None picurv_cli.core.finalize_post_outputs	(	str	run_dir,
		dict	post_cfg,
			stages
	)

Run every serial step that reads a successful field stage's output.

Parameters

[in]	run_dir	Run directory.
[in]	post_cfg	Recipe with canonical paths applied.
[in]	stages	Stage names the finalizer covers beyond the collections.

Returns

None.

Definition at line 5424 of file core.py.

def finalize_post_outputs(run_dir: str, post_cfg: dict, stages) -> None:
    """!
    @brief Run every serial step that reads a successful field stage's output.
    @param[in] run_dir Run directory.
    @param[in] post_cfg Recipe with canonical paths applied.
    @param[in] stages Stage names the finalizer covers beyond the collections.
    @return None.
    """
    finalize_post_paraview_series(run_dir, post_cfg)
    if "reducers" in stages:
        run_post_reducers_stage(run_dir, post_cfg)
 
 

Here is the call graph for this function:

_post_requests_statistics()

bool picurv_cli.core._post_requests_statistics ( dict  post_cfg )

protected

Return whether the current post recipe expects statistics CSV artifacts.

Parameters

[in]

post_cfg

Argument passed to _post_requests_statistics().

Returns

Value returned by _post_requests_statistics().

Definition at line 5437 of file core.py.

def _post_requests_statistics(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe expects statistics CSV artifacts.
    @param[in] post_cfg Argument passed to `_post_requests_statistics()`.
    @return Value returned by `_post_requests_statistics()`.
    """
    return bool(get_post_statistics_task_tokens(post_cfg))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_post_needs_particle_source()

bool picurv_cli.core._post_needs_particle_source ( dict  post_cfg )

protected

Return whether the current post recipe requires particle source files to be present.

Parameters

[in]

post_cfg

Argument passed to _post_needs_particle_source().

Returns

Value returned by _post_needs_particle_source().

Definition at line 5446 of file core.py.

def _post_needs_particle_source(post_cfg: dict) -> bool:
    """!
    @brief Return whether the current post recipe requires particle source files to be present.
    @param[in] post_cfg Argument passed to `_post_needs_particle_source()`.
    @return Value returned by `_post_needs_particle_source()`.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    return bool(io_cfg.get('output_particles')) or bool(post_cfg.get('lagrangian_pipeline')) or _post_requests_statistics(post_cfg)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_iter_post_steps()

picurv_cli.core._iter_post_steps ( int  start_step, int  end_step, int  step_interval  )

protected

Yield configured post-processing steps inclusively.

Parameters

[in]	start_step	Argument passed to _iter_post_steps().
[in]	end_step	Argument passed to _iter_post_steps().
[in]	step_interval	Argument passed to _iter_post_steps().

Definition at line 5456 of file core.py.

def _iter_post_steps(start_step: int, end_step: int, step_interval: int):
    """!
    @brief Yield configured post-processing steps inclusively.
    @param[in] start_step Argument passed to `_iter_post_steps()`.
    @param[in] end_step Argument passed to `_iter_post_steps()`.
    @param[in] step_interval Argument passed to `_iter_post_steps()`.
    """
    if step_interval <= 0 or end_step < start_step:
        return
    step = start_step
    while step <= end_step:
        yield step
        step += step_interval
 
 

Here is the caller graph for this function:

resolve_post_requested_window()

"tuple[int, int, int]" picurv_cli.core.resolve_post_requested_window	(	dict	post_cfg,
		dict	case_cfg = None
	)

Resolve post requested start/end/interval, expanding end=-1 via case.yml when available.

Parameters

[in]	post_cfg	Argument passed to resolve_post_requested_window().
[in]	case_cfg	Optional case configuration for end-step expansion.

Returns

Value returned by resolve_post_requested_window().

Definition at line 5471 of file core.py.

def resolve_post_requested_window(post_cfg: dict, case_cfg: dict = None) -> "tuple[int, int, int]":
    """!
    @brief Resolve post requested start/end/interval, expanding end=-1 via case.yml when available.
    @param[in] post_cfg Argument passed to `resolve_post_requested_window()`.
    @param[in] case_cfg Optional case configuration for end-step expansion.
    @return Value returned by `resolve_post_requested_window()`.
    """
    start_step = int(get_post_run_control_value(post_cfg, 'start_step', 0) or 0)
    end_step = int(get_post_run_control_value(post_cfg, 'end_step', 0) or 0)
    step_interval = int(get_post_run_control_value(post_cfg, 'step_interval', 1))
    if step_interval <= 0:
        raise ValueError('run_control.step_interval must be positive.')
    if end_step < 0 and case_cfg:
        case_run = case_cfg.get('run_control', {}) or {}
        case_start = int(case_run.get('start_step', 0) or 0)
        case_total = int(case_run.get('total_steps', 0) or 0)
        end_step = case_start + case_total
    return start_step, end_step, step_interval
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_post_owned_start()

int picurv_cli.core.resolve_post_owned_start	(	str	run_dir,
		dict	post_cfg,
		int	requested_start,
		int	step_interval
	)

Intersect a recipe's logical cadence with this run's branch.

A branch run holds checkpoints only from the step it forked at, so steps before it belong to its ancestors and never appear here; the run's window starts at its first cadence step at or after the fork.

Parameters

[in]	run_dir	Run whose branch ownership is inspected.
[in]	post_cfg	Parsed post-processing recipe.
[in]	requested_start	Logical recipe start step.
[in]	step_interval	Logical recipe cadence.

Returns

First cadence step owned by the run.

Definition at line 5491 of file core.py.

                             step_interval: int) -> int:
    """!
    @brief Intersect a recipe's logical cadence with this run's branch.
    @details A branch run holds checkpoints only from the step it forked at, so steps
             before it belong to its ancestors and never appear here; the run's window
             starts at its first cadence step at or after the fork.
    @param[in] run_dir Run whose branch ownership is inspected.
    @param[in] post_cfg Parsed post-processing recipe.
    @param[in] requested_start Logical recipe start step.
    @param[in] step_interval Logical recipe cadence.
    @return First cadence step owned by the run.
    """
    del post_cfg
    manifest = _read_json_if_exists(os.path.join(run_dir, "manifest.json")) or {}
    lineage = manifest.get("lineage") or {}
    if lineage.get("relationship") != "branch":
        return requested_start
    fork_step = int(lineage["checkpoint_step"])
    if fork_step <= requested_start:
        return requested_start
    intervals = (fork_step - requested_start + step_interval - 1) // step_interval
    return requested_start + intervals * step_interval
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

prepare_effective_post_config()

dict picurv_cli.core.prepare_effective_post_config	(	dict	post_cfg,
		str	resolved_source_dir,
		int	start_step = None,
		int	end_step = None
	)

Return a copy of post_cfg with resolved source dir and optional effective bounds.

Parameters

[in]	post_cfg	Argument passed to prepare_effective_post_config().
[in]	resolved_source_dir	Argument passed to prepare_effective_post_config().
[in]	start_step	Argument passed to prepare_effective_post_config().
[in]	end_step	Argument passed to prepare_effective_post_config().

Returns

Value returned by prepare_effective_post_config().

Definition at line 5516 of file core.py.

def prepare_effective_post_config(post_cfg: dict, resolved_source_dir: str, start_step: int = None, end_step: int = None) -> dict:
    """!
    @brief Return a copy of post_cfg with resolved source dir and optional effective bounds.
    @param[in] post_cfg Argument passed to `prepare_effective_post_config()`.
    @param[in] resolved_source_dir Argument passed to `prepare_effective_post_config()`.
    @param[in] start_step Argument passed to `prepare_effective_post_config()`.
    @param[in] end_step Argument passed to `prepare_effective_post_config()`.
    @return Value returned by `prepare_effective_post_config()`.
    """
    effective_cfg = copy.deepcopy(post_cfg)
    if not isinstance(effective_cfg.get('source_data'), dict):
        effective_cfg['source_data'] = {}
    effective_cfg['source_data']['directory'] = resolved_source_dir
    rc = effective_cfg.setdefault('run_control', {})
    if start_step is not None:
        rc['start_step'] = int(start_step)
    if end_step is not None:
        rc['end_step'] = int(end_step)
    return effective_cfg
 
 

Here is the caller graph for this function:

_scan_post_vtk_steps()

"dict[int, str]" picurv_cli.core._scan_post_vtk_steps ( str  prefix_path, str  extension  )

protected

Collect the VTK files named with a prefix, step suffix, and extension.

Parameters

[in]	prefix_path	Output path prefix before the numeric step suffix.
[in]	extension	VTK file extension to match without its leading dot.

Returns

Mapping of each step number to its file path in the prefix directory.

Definition at line 5537 of file core.py.

def _scan_post_vtk_steps(prefix_path: str, extension: str) -> "dict[int, str]":
    """!
    @brief Collect the VTK files named with a prefix, step suffix, and extension.
    @param[in] prefix_path Output path prefix before the numeric step suffix.
    @param[in] extension VTK file extension to match without its leading dot.
    @return Mapping of each step number to its file path in the prefix directory.
    """
    directory = os.path.dirname(prefix_path)
    if not os.path.isdir(directory):
        return {}
    basename = os.path.basename(prefix_path)
    pattern = re.compile(rf'^{re.escape(basename)}_(\d+)\.{re.escape(extension)}$')
    steps = {}
    for name in os.listdir(directory):
        match = pattern.match(name)
        if match:
            steps[int(match.group(1))] = os.path.join(directory, name)
    return steps
 
 

Here is the caller graph for this function:

_scan_post_statistics_csv_steps()

"set[int]" picurv_cli.core._scan_post_statistics_csv_steps ( str  csv_path )

protected

Scan step ids from the first CSV column of a statistics artifact.

Parameters

[in]

csv_path

Argument passed to _scan_post_statistics_csv_steps().

Returns

Value returned by _scan_post_statistics_csv_steps().

Definition at line 5557 of file core.py.

def _scan_post_statistics_csv_steps(csv_path: str) -> "set[int]":
    """!
    @brief Scan step ids from the first CSV column of a statistics artifact.
    @param[in] csv_path Argument passed to `_scan_post_statistics_csv_steps()`.
    @return Value returned by `_scan_post_statistics_csv_steps()`.
    """
    if not os.path.isfile(csv_path):
        return set()
    steps = set()
    with open(csv_path, 'r', encoding='utf-8', errors='replace', newline='') as f:
        reader = csv.reader(f)
        for row in reader:
            if not row:
                continue
            head = str(row[0]).strip().lower()
            if head in {'step', 'timestep', 'time_step'}:
                continue
            step_val = _parse_int_loose(row[0])
            if step_val is not None:
                steps.add(step_val)
    return steps
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

collect_post_completion_families()

"list[tuple]" picurv_cli.core.collect_post_completion_families	(	str	run_dir,
		dict	post_cfg,
			monitor_cfg = None
	)

Collect the output files each output family of the current recipe holds per step.

Parameters

[in]	run_dir	Argument passed to collect_post_completion_families().
[in]	post_cfg	Argument passed to collect_post_completion_families().
[in]	monitor_cfg	Optional parsed monitor YAML configuration dictionary.

Returns

(step-to-path mapping, window, per_step) per family; window names the field-statistics window a family belongs to, or is None for a family every processed step must produce; per_step is False for a CSV shared by all steps.

Definition at line 5580 of file core.py.

def collect_post_completion_families(run_dir: str, post_cfg: dict, monitor_cfg=None) -> "list[tuple]":
    """!
    @brief Collect the output files each output family of the current recipe holds per step.
    @param[in] run_dir Argument passed to `collect_post_completion_families()`.
    @param[in] post_cfg Argument passed to `collect_post_completion_families()`.
    @param[in] monitor_cfg Optional parsed monitor YAML configuration dictionary.
    @return (step-to-path mapping, window, per_step) per family; window names the
            field-statistics window a family belongs to, or is None for a family every
            processed step must produce; per_step is False for a CSV shared by all steps.
    """
    io_cfg = post_cfg.get('io', {}) or {}
    output_dir_abs = _post_output_directory_abs(run_dir, post_cfg)
    families = []
 
    def csv_family(path):
        """!
        @brief Map every step a shared CSV holds to that CSV.
        @param[in] path CSV artifact path.
        @return Mapping of step to the CSV path.
        """
        return {step: path for step in _scan_post_statistics_csv_steps(path)}
 
    if _post_requests_eulerian_output(post_cfg):
        prefix = os.path.join(output_dir_abs, io_cfg.get('output_filename_prefix', 'Field'))
        families.append((_scan_post_vtk_steps(prefix, 'vts'), None, True))
 
    if _post_requests_particle_output(post_cfg):
        prefix = os.path.join(output_dir_abs, io_cfg.get('particle_filename_prefix', 'Particle'))
        families.append((_scan_post_vtk_steps(prefix, 'vtp'), None, True))
 
    for stats_path in get_post_statistics_output_artifacts(post_cfg, run_dir, monitor_cfg):
        families.append((csv_family(stats_path), None, False))
 
    # Each window and format is its own family, so a run that produced the Eulerian
    # fields but not the statistics is not mistaken for a completed step.
    for kind, path, window in get_post_field_statistics_artifacts(post_cfg, run_dir):
        if kind == 'vtk':
            families.append((_scan_post_vtk_steps(path, 'vts'), window, True))
        elif kind == 'profile':
            families.append((_scan_post_vtk_steps(path, 'csv'), window, True))
        else:
            families.append((csv_family(path), window, False))
 
    return families
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_field_statistics_window_samples()

picurv_cli.core._field_statistics_window_samples ( str  run_dir, int  step  )

protected

Read each field-statistics window's sample count from one committed checkpoint.

Parameters

[in]	run_dir	Run directory whose output holds the checkpoint.
[in]	step	Checkpoint step.

Returns

Mapping of window name to sample count, or None when the metadata is absent (never written, pruned, or offloaded).

Definition at line 5626 of file core.py.

def _field_statistics_window_samples(run_dir: str, step: int):
    """!
    @brief Read each field-statistics window's sample count from one committed checkpoint.
    @param[in] run_dir Run directory whose output holds the checkpoint.
    @param[in] step Checkpoint step.
    @return Mapping of window name to sample count, or None when the metadata is absent
            (never written, pruned, or offloaded).
    """
    metadata = os.path.join(
        _checkpoint_bundle_path(os.path.join(run_dir, CANONICAL_RUN_PATHS["output"]), step),
        "checkpoint.meta",
    )
    if not os.path.isfile(metadata):
        return None
    options = _read_checkpoint_options(metadata)
    samples = {}
    for index in range(int(options.get("checkpoint_statistics_window_count", 0) or 0)):
        name = options.get(f"checkpoint_statistics_window_{index}_name")
        if name is not None:
            samples[name] = int(options.get(f"checkpoint_statistics_window_{index}_sample_count", 0) or 0)
    return samples
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

post_step_outputs()

picurv_cli.core.post_step_outputs	(	str	run_dir,
		dict	post_cfg,
			monitor_cfg = None
	)

Return a lookup of the output files one step of the current recipe holds.

A step is complete when every family it must produce has its output. The post-processor writes a statistics window's output at a step only if the window had accumulated a sample in the bundle it reads, the pinned source_step or the step itself, so a window that had not opened yet is not required there.

Parameters

[in]	run_dir	Run whose output is inspected.
[in]	post_cfg	Runtime recipe with canonical paths.
[in]	monitor_cfg	Parsed monitor configuration.

Returns

Function mapping a step to (per-step files, shared files), or None when the step lacks an output it must have.

Definition at line 5649 of file core.py.

def post_step_outputs(run_dir: str, post_cfg: dict, monitor_cfg=None):
    """!
    @brief Return a lookup of the output files one step of the current recipe holds.
    @details A step is complete when every family it must produce has its output. The
             post-processor writes a statistics window's output at a step only if the
             window had accumulated a sample in the bundle it reads, the pinned
             source_step or the step itself, so a window that had not opened yet is not
             required there.
    @param[in] run_dir Run whose output is inspected.
    @param[in] post_cfg Runtime recipe with canonical paths.
    @param[in] monitor_cfg Parsed monitor configuration.
    @return Function mapping a step to (per-step files, shared files), or None when the
            step lacks an output it must have.
    """
    families = collect_post_completion_families(run_dir, post_cfg, monitor_cfg)
    pinned = normalize_post_field_statistics_config(post_cfg).get("source_step")
    sample_cache = {}
 
    def expected(window, step):
        """!
        @brief Whether a family's output must exist at this step.
        @param[in] window Field-statistics window the family belongs to, or None.
        @param[in] step Processed step.
        @return True when the family is always required or its window had samples.
        """
        if window is None:
            return True
        source = int(pinned) if pinned is not None else step
        if source not in sample_cache:
            sample_cache[source] = _field_statistics_window_samples(run_dir, source)
        samples = sample_cache[source]
        # Without the checkpoint's record the output cannot be ruled out, so it stays required.
        return samples is None or samples.get(window, 0) > 0
 
    def outputs(step):
        """!
        @brief Collect one step's output files.
        @param[in] step Processed step.
        @return (per-step files, shared files), or None when an expected output is missing.
        """
        own, shared = [], []
        for mapping, window, per_step in families:
            if step in mapping:
                (own if per_step else shared).append(mapping[step])
            elif expected(window, step):
                return None
        return own, shared
 
    return outputs
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_nearest_step()

picurv_cli.core._nearest_step ( "set[int]"  steps, int  target  )

protected

Return the complete source step nearest to a target step.

Parameters

[in]	steps	Candidate step numbers.
[in]	target	Target step number.

Returns

Nearest candidate, or None when no candidates exist.

Definition at line 5700 of file core.py.

def _nearest_step(steps: "set[int]", target: int):
    """!
    @brief Return the complete source step nearest to a target step.
    @param[in] steps Candidate step numbers.
    @param[in] target Target step number.
    @return Nearest candidate, or None when no candidates exist.
    """
    if not steps:
        return None
    return min(steps, key=lambda step: (abs(step - target), step))
 
 

Here is the caller graph for this function:

_format_optional_step()

str picurv_cli.core._format_optional_step (   step )

protected

Format an optional step number for user-facing diagnostics.

Parameters

[in]

step

Step number or None.

Returns

Printable step text.

Definition at line 5712 of file core.py.

def _format_optional_step(step) -> str:
    """!
    @brief Format an optional step number for user-facing diagnostics.
    @param[in] step Step number or None.
    @return Printable step text.
    """
    return 'none' if step is None else str(step)
 
 

_scan_complete_source_steps()

"tuple[set[int], dict]" picurv_cli.core._scan_complete_source_steps ( str  source_dir, dict  monitor_cfg, dict  post_cfg  )

protected

Scan source artifacts and return steps with every file required by the recipe.

Parameters

[in]	source_dir	Source output root directory.
[in]	monitor_cfg	Parsed monitor configuration.
[in]	post_cfg	Parsed post-processing configuration.

Returns

Tuple of complete source steps and source path metadata.

Definition at line 5721 of file core.py.

def _scan_complete_source_steps(source_dir: str, monitor_cfg: dict, post_cfg: dict) -> "tuple[set[int], dict]":
    """!
    @brief Scan source artifacts and return steps with every file required by the recipe.
    @param[in] source_dir Source output root directory.
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] post_cfg Parsed post-processing configuration.
    @return Tuple of complete source steps and source path metadata.
    """
    del monitor_cfg
    require_particles = _post_needs_particle_source(post_cfg)
    complete_steps = _scan_committed_checkpoint_steps(
        source_dir, require_particles=require_particles
    )
    return complete_steps, {
        'source_dir': os.path.abspath(source_dir),
        'require_particles': require_particles,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_expected_source_paths_for_step()

"list[str]" picurv_cli.core._expected_source_paths_for_step ( int  step, dict  source_scan, dict  post_cfg  )

protected

Build required source file paths for a single post-processing step.

Parameters

[in]	step	Requested step number.
[in]	source_scan	Metadata returned by _scan_complete_source_steps().
[in]	post_cfg	Parsed post-processing configuration.

Returns

Required source artifact paths.

Definition at line 5740 of file core.py.

def _expected_source_paths_for_step(step: int, source_scan: dict, post_cfg: dict) -> "list[str]":
    """!
    @brief Build required source file paths for a single post-processing step.
    @param[in] step Requested step number.
    @param[in] source_scan Metadata returned by `_scan_complete_source_steps()`.
    @param[in] post_cfg Parsed post-processing configuration.
    @return Required source artifact paths.
    """
    del post_cfg
    bundle = _checkpoint_bundle_path(source_scan['source_dir'], step)
    paths = [os.path.join(bundle, 'checkpoint.meta'), os.path.join(bundle, 'COMMITTED')]
    if source_scan.get('require_particles'):
        paths.append(os.path.join(bundle, 'particles', 'position.dat'))
    return paths
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

detect_post_source_frontier()

dict picurv_cli.core.detect_post_source_frontier	(	str	source_dir,
		dict	monitor_cfg,
		dict	post_cfg,
		int	start_step,
		int	end_step,
		int	step_interval
	)

Detect the highest contiguous fully available source step for live post-processing.

Parameters

[in]	source_dir	Argument passed to detect_post_source_frontier().
[in]	monitor_cfg	Argument passed to detect_post_source_frontier().
[in]	post_cfg	Argument passed to detect_post_source_frontier().
[in]	start_step	Argument passed to detect_post_source_frontier().
[in]	end_step	Argument passed to detect_post_source_frontier().
[in]	step_interval	Argument passed to detect_post_source_frontier().

Returns

Value returned by detect_post_source_frontier().

Definition at line 5756 of file core.py.

def detect_post_source_frontier(source_dir: str, monitor_cfg: dict, post_cfg: dict, start_step: int, end_step: int, step_interval: int) -> dict:
    """!
    @brief Detect the highest contiguous fully available source step for live post-processing.
    @param[in] source_dir Argument passed to `detect_post_source_frontier()`.
    @param[in] monitor_cfg Argument passed to `detect_post_source_frontier()`.
    @param[in] post_cfg Argument passed to `detect_post_source_frontier()`.
    @param[in] start_step Argument passed to `detect_post_source_frontier()`.
    @param[in] end_step Argument passed to `detect_post_source_frontier()`.
    @param[in] step_interval Argument passed to `detect_post_source_frontier()`.
    @return Value returned by `detect_post_source_frontier()`.
    """
    diagnostic = {
        'first_requested_step': start_step,
        'first_incomplete_step': None,
        'missing_files_for_first_incomplete_step': [],
        'closest_complete_step_to_start': None,
        'closest_complete_step_to_end': None,
    }
    if step_interval <= 0 or end_step < start_step or not os.path.isdir(source_dir):
        return {
            'frontier_step': None,
            'diagnostic': diagnostic,
        }
 
    complete_steps, source_scan = _scan_complete_source_steps(source_dir, monitor_cfg, post_cfg)
    diagnostic['closest_complete_step_to_start'] = _nearest_step(complete_steps, start_step)
    diagnostic['closest_complete_step_to_end'] = _nearest_step(complete_steps, end_step)
 
    frontier = None
    for step in _iter_post_steps(start_step, end_step, step_interval):
        try:
            validate_committed_checkpoint(
                source_dir, step,
                require_particles=source_scan.get('require_particles', False),
            )
        except CheckpointIndexWidthError:
            raise
        except ValueError:
            expected_paths = _expected_source_paths_for_step(step, source_scan, post_cfg)
            diagnostic['first_incomplete_step'] = step
            diagnostic['missing_files_for_first_incomplete_step'] = [
                os.path.relpath(path, source_dir) for path in expected_paths if not os.path.isfile(path)
            ]
            if not diagnostic['missing_files_for_first_incomplete_step']:
                diagnostic['missing_files_for_first_incomplete_step'] = [
                    os.path.relpath(_checkpoint_bundle_path(source_dir, step), source_dir)
                    + ' (invalid bundle)'
                ]
            break
        frontier = step
    return {
        'frontier_step': frontier,
        'diagnostic': diagnostic,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_read_post_records()

"tuple[dict, dict]" picurv_cli.core._read_post_records ( str  state_path )

protected

Read the per-step output records a recipe's state holds.

Parameters

[in]

state_path

The recipe's state.json.

Returns

(field-stage records, spectra records), each keyed by the step as text; both empty for a state written before records existed.

Definition at line 5812 of file core.py.

def _read_post_records(state_path: str) -> "tuple[dict, dict]":
    """!
    @brief Read the per-step output records a recipe's state holds.
    @param[in] state_path The recipe's state.json.
    @return (field-stage records, spectra records), each keyed by the step as text; both
            empty for a state written before records existed.
    """
    state = _read_json_if_exists(state_path)
    if not isinstance(state, dict) or state.get("schema_version") != POST_RESUME_SCHEMA_VERSION:
        return {}, {}
    return dict(state.get("steps") or {}), dict(state.get("spectra") or {})
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

persist_post_resume_state()

picurv_cli.core.persist_post_resume_state	(	str	run_dir,
		dict	plan,
			steps = None,
			spectra = None
	)

Write a recipe's state: the window last planned and its per-step output records.

Parameters

[in]	run_dir	Run the recipe belongs to.
[in]	plan	Plan from build_post_execution_plan().
[in]	steps	Field-stage records to merge in, keyed by step, or None.
[in]	spectra	Spectra records to merge in, keyed by step, or None.

Returns

Path of the written state file.

Definition at line 5825 of file core.py.

def persist_post_resume_state(run_dir: str, plan: dict, steps=None, spectra=None):
    """!
    @brief Write a recipe's state: the window last planned and its per-step output records.
    @param[in] run_dir Run the recipe belongs to.
    @param[in] plan Plan from build_post_execution_plan().
    @param[in] steps Field-stage records to merge in, keyed by step, or None.
    @param[in] spectra Spectra records to merge in, keyed by step, or None.
    @return Path of the written state file.
    """
    state_path = plan.get("resume_state_path") or get_post_resume_state_path(run_dir)
    field_records, spectra_records = _read_post_records(state_path)
    field_records.update({str(step): record for step, record in (steps or {}).items()})
    spectra_records.update({str(step): record for step, record in (spectra or {}).items()})
    write_json_file(state_path, {
        'schema_version': POST_RESUME_SCHEMA_VERSION,
        'run_id': plan.get('run_id'),
        'recipe_fingerprint': plan.get('recipe_fingerprint'),
        'recipe_signature': plan.get('recipe_signature'),
        'requested_start_step': plan.get('requested_start_step'),
        'requested_end_step': plan.get('requested_end_step'),
        'step_interval': plan.get('step_interval'),
        'source_directory': plan.get('source_data_directory'),
        'updated_at': datetime.now().isoformat(),
        'steps': dict(sorted(field_records.items(), key=lambda item: int(item[0]))),
        'spectra': dict(sorted(spectra_records.items(), key=lambda item: int(item[0]))),
    })
    return state_path
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_checkpoint_commit()

picurv_cli.core._checkpoint_commit ( str  source_dir, int  step  )

protected

Identify one committed checkpoint by its commit marker.

Parameters

[in]	source_dir	Output root holding the checkpoints.
[in]	step	Checkpoint step.

Returns

(marker digest, marker modification time), or None when the checkpoint is not local (never written, archived, or pruned).

Definition at line 5854 of file core.py.

def _checkpoint_commit(source_dir: str, step: int):
    """!
    @brief Identify one committed checkpoint by its commit marker.
    @param[in] source_dir Output root holding the checkpoints.
    @param[in] step Checkpoint step.
    @return (marker digest, marker modification time), or None when the checkpoint is not
            local (never written, archived, or pruned).
    """
    marker = os.path.join(_checkpoint_bundle_path(source_dir, step), "COMMITTED")
    try:
        with open(marker, "r", encoding="ascii") as stream:
            return stream.read().strip(), os.stat(marker).st_mtime
    except OSError:
        return None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

classify_post_step()

"str | None" picurv_cli.core.classify_post_step	(		record,
			files,
			commit,
		str	recipe,
		bool	recompute = False
	)

Decide whether one step's existing output is still valid.

Output stays valid while it was made by the same recipe from the checkpoint now on disk. The build that made it does not invalidate it: a rebuild changes every binary's hash, and redoing a whole window after each one is what --recompute is for. Output without a record (written before records existed, or by a job killed before it could record) is accepted when it is newer than its checkpoint, or when the checkpoint is no longer local.

Parameters

[in]	record	The step's record, or None.
[in]	files	Files the step's output consists of, or None when any is missing.
[in]	commit	Checkpoint identity from _checkpoint_commit(), or None.
[in]	recipe	Current recipe fingerprint.
[in]	recompute	Whether the invocation regenerates every step.

Returns

None when the output is valid, else the reason it must be (re)made: missing, recompute, recipe, or checkpoint.

Definition at line 5870 of file core.py.

def classify_post_step(record, files, commit, recipe: str, recompute: bool = False) -> "str | None":
    """!
    @brief Decide whether one step's existing output is still valid.
    @details Output stays valid while it was made by the same recipe from the checkpoint
             now on disk. The build that made it does not invalidate it: a rebuild changes
             every binary's hash, and redoing a whole window after each one is what
             `--recompute` is for. Output without a record (written before records
             existed, or by a job killed before it could record) is accepted when it is
             newer than its checkpoint, or when the checkpoint is no longer local.
    @param[in] record The step's record, or None.
    @param[in] files Files the step's output consists of, or None when any is missing.
    @param[in] commit Checkpoint identity from _checkpoint_commit(), or None.
    @param[in] recipe Current recipe fingerprint.
    @param[in] recompute Whether the invocation regenerates every step.
    @return None when the output is valid, else the reason it must be (re)made:
            `missing`, `recompute`, `recipe`, or `checkpoint`.
    """
    if files is None or (not files and record is None):
        return "missing"
    if recompute:
        return "recompute"
    if record is None:
        if commit is None or min(os.path.getmtime(path) for path in files) >= commit[1]:
            return None
        return "checkpoint"
    if record.get("recipe") != recipe:
        return "recipe"
    if commit is not None and record.get("checkpoint") not in (None, commit[0]):
        return "checkpoint"
    return None
 
 

Here is the caller graph for this function:

warn_overlapping_post_recipes()

None picurv_cli.core.warn_overlapping_post_recipes	(	str	run_dir,
		dict	post_cfg,
		dict	plan,
			post_stages
	)

Warn when another recipe in this run already produced outputs this one repeats.

A recipe writes one file per step holding all its fields, so a recipe that repeats another's fields recomputes them rather than reusing them. The warning names the shared fields and statistics windows and the overlapping steps, so the new outputs can go into a recipe of their own instead.

Parameters

[in]	run_dir	Run being post-processed.
[in]	post_cfg	Runtime recipe with canonical paths.
[in]	plan	Plan from build_post_execution_plan().
[in]	post_stages	Selected post stages.

Returns

None.

Definition at line 5902 of file core.py.

def warn_overlapping_post_recipes(run_dir: str, post_cfg: dict, plan: dict, post_stages) -> None:
    """!
    @brief Warn when another recipe in this run already produced outputs this one repeats.
    @details A recipe writes one file per step holding all its fields, so a recipe that
             repeats another's fields recomputes them rather than reusing them. The
             warning names the shared fields and statistics windows and the overlapping
             steps, so the new outputs can go into a recipe of their own instead.
    @param[in] run_dir Run being post-processed.
    @param[in] post_cfg Runtime recipe with canonical paths.
    @param[in] plan Plan from build_post_execution_plan().
    @param[in] post_stages Selected post stages.
    @return None.
    """
    if 'fields' not in post_stages:
        return
    current_id = ((post_cfg.get("_picurv_paths") or {}).get("recipe_id")
                  or compute_post_recipe_id(post_cfg))
    steps = set(plan['steps_to_process'])
    fields = set(((post_cfg.get('io') or {}).get('eulerian_fields')) or [])
    windows = set(normalize_post_field_statistics_config(post_cfg)["windows"])
    root = os.path.join(os.path.abspath(run_dir), "config", "post-recipes")
    if not steps or not (fields or windows) or not os.path.isdir(root):
        return
    for other_id in sorted(os.listdir(root)):
        archived = os.path.join(root, other_id, "post.yml")
        if other_id == current_id or not os.path.isfile(archived):
            continue
        try:
            other_cfg, resolved_id = apply_canonical_post_paths(read_yaml_file(archived), run_dir)
        except Exception:  # an unreadable archived recipe says nothing about overlap
            continue
        if resolved_id != other_id:
            continue
        labels, done = [], set()
        shared_fields = fields & set(((other_cfg.get('io') or {}).get('eulerian_fields')) or [])
        if shared_fields:
            prefix = os.path.join(_post_output_directory_abs(run_dir, other_cfg),
                                  (other_cfg.get('io') or {}).get('output_filename_prefix', 'Field'))
            found = steps & _scan_post_vtk_steps(prefix, 'vts').keys()
            if found:
                labels.append(f"fields {', '.join(sorted(shared_fields))}")
                done |= found
        shared_windows = []
        for kind, path, window in get_post_field_statistics_artifacts(other_cfg, run_dir):
            if kind == 'vtk' and window in windows:
                found = steps & _scan_post_vtk_steps(path, 'vts').keys()
                if found:
                    shared_windows.append(window)
                    done |= found
        if shared_windows:
            labels.append(f"statistics windows {', '.join(shared_windows)}")
        if labels:
            print(f"[WARNING] Recipe {other_id} already produced {'; '.join(labels)} for "
                  f"{len(done)} of these steps ({min(done)}..{max(done)}); this recipe computes "
                  "them again. If only some outputs are new, a recipe holding just those avoids "
                  "the repeat.", file=sys.stderr)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_build_post_lock_wrapper_source()

str picurv_cli.core._build_post_lock_wrapper_source ( )

protected

Return the Python wrapper that runs one post job under an exclusive lock.

Given --post-recipe, the wrapper plans the job's steps as it starts (prepare_post_job()), skips the postprocessor when none need work, and records the steps produced when the postprocessor exits, even on failure (finish_post_job()). It imports the conductor from this installation, so it must run under the conductor's interpreter.

Returns

Value returned by _build_post_lock_wrapper_source().

Definition at line 5960 of file core.py.

def _build_post_lock_wrapper_source() -> str:
    """!
    @brief Return the Python wrapper that runs one post job under an exclusive lock.
    @details Given `--post-recipe`, the wrapper plans the job's steps as it starts
             (prepare_post_job()), skips the postprocessor when none need work, and
             records the steps produced when the postprocessor exits, even on failure
             (finish_post_job()). It imports the conductor from this installation, so it
             must run under the conductor's interpreter.
    @return Value returned by `_build_post_lock_wrapper_source()`.
    """
    package_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
    return """#!/usr/bin/env python3
import argparse
import fcntl
import json
import os
import socket
import subprocess
import sys
import time
 
PICURV_PACKAGE_ROOT = """ + repr(package_root) + """
 
 
def main():
    parser = argparse.ArgumentParser(description='PICurv post-stage lock wrapper')
    parser.add_argument('--lock-file', required=True)
    parser.add_argument('--metadata-file', required=True)
    parser.add_argument('--run-dir', required=True)
    parser.add_argument('--recipe-fingerprint', default='')
    parser.add_argument('--post-recipe')
    parser.add_argument('--postprocessor')
    parser.add_argument('--recompute', action='store_true')
    parser.add_argument('--success-command-json')
    parser.add_argument('command', nargs=argparse.REMAINDER)
    args = parser.parse_args()
 
    command = list(args.command or [])
    if not command or command[0] != '--':
        parser.error("expected '-- <command ...>' after wrapper arguments")
    command = command[1:]
 
    os.makedirs(os.path.dirname(args.lock_file), exist_ok=True)
    fd = os.open(args.lock_file, os.O_RDWR | os.O_CREAT, 0o644)
    try:
        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
    except BlockingIOError:
        owner = None
        try:
            with open(args.metadata_file, 'r', encoding='utf-8') as handle:
                owner = json.load(handle)
        except Exception:
            owner = None
        if owner:
            print(
                f"[FATAL] Post stage already active for {args.run_dir} "
                f"(pid={owner.get('pid')}, host={owner.get('host')}, started_at={owner.get('started_at')}).",
                file=sys.stderr,
            )
        else:
            print(f"[FATAL] Post stage already active for {args.run_dir}.", file=sys.stderr)
        return 2
 
    metadata = {
        'pid': os.getpid(),
        'host': socket.gethostname(),
        'started_at': time.strftime('%Y-%m-%dT%H:%M:%S%z'),
        'run_dir': args.run_dir,
        'recipe_fingerprint': args.recipe_fingerprint,
        'command': command,
    }
    with open(args.metadata_file, 'w', encoding='utf-8') as handle:
        json.dump(metadata, handle, indent=2, sort_keys=True)
        handle.write('\\n')
 
    try:
        planned = None
        if args.post_recipe:
            sys.path.insert(0, PICURV_PACKAGE_ROOT)
            from picurv_cli.core import finish_post_job, prepare_post_job
            planned = prepare_post_job(args.run_dir, args.post_recipe, args.postprocessor,
                                       recompute=args.recompute)
            sys.stdout.flush()
        if planned != 0:
            result = None
            try:
                result = subprocess.run(command)
            finally:
                if args.post_recipe:
                    finish_post_job(args.run_dir, args.post_recipe,
                                    exited_cleanly=result is not None and result.returncode == 0)
                    sys.stdout.flush()
            if result.returncode != 0:
                return int(result.returncode)
        else:
            print('[INFO] Every requested step with a committed checkpoint is up to date; '
                  'the postprocessor is not launched.')
        if args.success_command_json:
            success_command = json.loads(args.success_command_json)
            if not isinstance(success_command, list) or not success_command:
                print('[FATAL] Invalid post success command.', file=sys.stderr)
                return 2
            result = subprocess.run([str(token) for token in success_command])
            return int(result.returncode)
        return 0
    finally:
        try:
            os.remove(args.metadata_file)
        except FileNotFoundError:
            pass
        os.close(fd)
 
 
if __name__ == '__main__':
    raise SystemExit(main())
"""
 
 

Here is the caller graph for this function:

ensure_post_lock_wrapper()

str picurv_cli.core.ensure_post_lock_wrapper

(

str

run_dir

)

Ensure the lock wrapper exists for a run directory and return its path.

Parameters

[in]

run_dir

Argument passed to ensure_post_lock_wrapper().

Returns

Value returned by ensure_post_lock_wrapper().

Definition at line 6078 of file core.py.

def ensure_post_lock_wrapper(run_dir: str) -> str:
    """!
    @brief Ensure the lock wrapper exists for a run directory and return its path.
    @param[in] run_dir Argument passed to `ensure_post_lock_wrapper()`.
    @return Value returned by `ensure_post_lock_wrapper()`.
    """
    paths = get_post_lock_paths(run_dir)
    wrapper_path = paths['wrapper_path']
    content = _build_post_lock_wrapper_source()
    existing_content = None
    os.makedirs(os.path.dirname(wrapper_path), exist_ok=True)
    if os.path.isfile(wrapper_path):
        with open(wrapper_path, 'r', encoding='utf-8', errors='replace') as f:
            existing_content = f.read()
    if existing_content != content:
        with open(wrapper_path, 'w', encoding='utf-8') as f:
            f.write(content)
        os.chmod(wrapper_path, 0o755)
    return wrapper_path
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

build_post_locked_command()

"tuple[list, dict]" picurv_cli.core.build_post_locked_command	(	str	run_dir,
		str	recipe_fingerprint,
		list	wrapped_command,
		bool	create_wrapper = True,
		"list | None"	success_command = None,
		"str | None"	post_recipe = None,
		"str | None"	postprocessor = None,
		bool	recompute = False
	)

Wrap a postprocessor command behind the run-dir-scoped lock wrapper.

Parameters

[in]	run_dir	Argument passed to build_post_locked_command().
[in]	recipe_fingerprint	Argument passed to build_post_locked_command().
[in]	wrapped_command	Argument passed to build_post_locked_command().
[in]	create_wrapper	Argument passed to build_post_locked_command().
[in]	success_command	Optional serial command run under the same lock after success.
[in]	post_recipe	Recipe whose steps the wrapper plans at launch; None runs the command as given.
[in]	postprocessor	Postprocessor the command launches, recorded with its output.
[in]	recompute	Regenerate every step whose checkpoint is committed.

Returns

Value returned by build_post_locked_command().

Definition at line 6099 of file core.py.

                              recompute: bool = False) -> "tuple[list, dict]":
    """!
    @brief Wrap a postprocessor command behind the run-dir-scoped lock wrapper.
    @param[in] run_dir Argument passed to `build_post_locked_command()`.
    @param[in] recipe_fingerprint Argument passed to `build_post_locked_command()`.
    @param[in] wrapped_command Argument passed to `build_post_locked_command()`.
    @param[in] create_wrapper Argument passed to `build_post_locked_command()`.
    @param[in] success_command Optional serial command run under the same lock after success.
    @param[in] post_recipe Recipe whose steps the wrapper plans at launch; None runs the
                           command as given.
    @param[in] postprocessor Postprocessor the command launches, recorded with its output.
    @param[in] recompute Regenerate every step whose checkpoint is committed.
    @return Value returned by `build_post_locked_command()`.
    """
    lock_paths = get_post_lock_paths(run_dir)
    wrapper_path = ensure_post_lock_wrapper(run_dir) if create_wrapper else lock_paths['wrapper_path']
    command = [
        sys.executable, wrapper_path,
        '--lock-file', lock_paths['lock_file'],
        '--metadata-file', lock_paths['metadata_file'],
        '--run-dir', run_dir,
        '--recipe-fingerprint', recipe_fingerprint,
    ]
    if post_recipe:
        command += ['--post-recipe', os.path.abspath(post_recipe),
                    '--postprocessor', os.path.abspath(postprocessor)]
        if recompute:
            command.append('--recompute')
    if success_command:
        command += ['--success-command-json', json.dumps(list(success_command))]
    command += ['--'] + list(wrapped_command)
    return command, lock_paths
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

run_post_finalize_locked()

None picurv_cli.core.run_post_finalize_locked	(	str	run_dir,
		str	recipe_fingerprint,
		list	finalize_command
	)

Refresh a collection-only result under the ordinary post writer lock.

Parameters

[in]	run_dir	Run whose post writer lock is acquired.
[in]	recipe_fingerprint	Recipe identity recorded in lock metadata.
[in]	finalize_command	Serial collection finalizer command.

Returns

None.

Definition at line 6138 of file core.py.

                             finalize_command: list) -> None:
    """!
    @brief Refresh a collection-only result under the ordinary post writer lock.
    @param[in] run_dir Run whose post writer lock is acquired.
    @param[in] recipe_fingerprint Recipe identity recorded in lock metadata.
    @param[in] finalize_command Serial collection finalizer command.
    @return None.
    """
    if not finalize_command:
        return
    command, _ = build_post_locked_command(
        run_dir, recipe_fingerprint, [sys.executable, "-c", "pass"],
        create_wrapper=True, success_command=finalize_command,
    )
    result = subprocess.run(command, cwd=run_dir)
    if result.returncode != 0:
        raise ValueError(
            f"Post finalization (ParaView series, reducers) failed with exit code {result.returncode}."
        )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

build_post_execution_plan()

dict picurv_cli.core.build_post_execution_plan	(	str	run_dir,
		str	run_id,
		dict	case_cfg,
		dict	monitor_cfg,
		dict	post_cfg,
		bool	recompute = False,
		bool	allow_source_frontier_scan = True,
		"str | None"	postprocessor_sha = None
	)

Decide which steps of a recipe's window one invocation processes.

Every requested step is classified by classify_post_step(): valid output is kept, and missing or stale output is (re)made once its checkpoint is committed. Steps need not be contiguous. When the solver stage has not run yet the source scan is deferred and every step without valid output is planned; the post job plans again when it starts (prepare_post_job()).

Parameters

[in]	run_dir	Run being post-processed.
[in]	run_id	Run identity recorded in the recipe state.
[in]	case_cfg	Parsed case configuration.
[in]	monitor_cfg	Parsed monitor configuration.
[in]	post_cfg	Parsed post recipe.
[in]	recompute	Regenerate every step whose checkpoint is committed.
[in]	allow_source_frontier_scan	False when the solver stage has not produced output yet.
[in]	postprocessor_sha	Hash of the postprocessor that would run, used only to report valid output another build made.

Returns

Plan mapping; see the keys of the returned dictionary.

Definition at line 6160 of file core.py.

) -> dict:
    """!
    @brief Decide which steps of a recipe's window one invocation processes.
    @details Every requested step is classified by classify_post_step(): valid output is
             kept, and missing or stale output is (re)made once its checkpoint is
             committed. Steps need not be contiguous. When the solver stage has not run
             yet the source scan is deferred and every step without valid output is
             planned; the post job plans again when it starts (prepare_post_job()).
    @param[in] run_dir Run being post-processed.
    @param[in] run_id Run identity recorded in the recipe state.
    @param[in] case_cfg Parsed case configuration.
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] post_cfg Parsed post recipe.
    @param[in] recompute Regenerate every step whose checkpoint is committed.
    @param[in] allow_source_frontier_scan False when the solver stage has not produced output yet.
    @param[in] postprocessor_sha Hash of the postprocessor that would run, used only to
                                 report valid output another build made.
    @return Plan mapping; see the keys of the returned dictionary.
    """
    if not isinstance((post_cfg or {}).get("_picurv_paths"), dict):
        post_cfg, _ = apply_canonical_post_paths(post_cfg, run_dir)
    requested_start_step, requested_end_step, step_interval = resolve_post_requested_window(post_cfg, case_cfg)
    owned_start_step = resolve_post_owned_start(
        run_dir, post_cfg, requested_start_step, step_interval
    )
    resolved_source_dir = _resolve_post_source_directory_preview(run_dir, monitor_cfg, post_cfg)
    resolved_post_cfg = prepare_effective_post_config(post_cfg, resolved_source_dir)
    recipe_cfg = build_post_recipe_config(resolved_post_cfg, monitor_cfg)
    recipe_signature, recipe_fingerprint = compute_post_recipe_fingerprint(recipe_cfg)
    state_path = get_post_resume_state_path(run_dir, resolved_post_cfg)
    records, _ = _read_post_records(state_path)
 
    source_frontier_deferred = not allow_source_frontier_scan
    available = None
    source_frontier_step = None
    source_frontier_diagnostic = None
    if not source_frontier_deferred:
        available = _scan_committed_checkpoint_steps(
            resolved_source_dir, require_particles=_post_needs_particle_source(resolved_post_cfg)
        )
        source_frontier_info = detect_post_source_frontier(
            resolved_source_dir, monitor_cfg, resolved_post_cfg,
            owned_start_step, requested_end_step, step_interval,
        )
        source_frontier_step = source_frontier_info['frontier_step']
        source_frontier_diagnostic = source_frontier_info['diagnostic']
 
    outputs = post_step_outputs(run_dir, resolved_post_cfg, monitor_cfg)
    process, unavailable, reasons, adopted = [], [], {}, {}
    current = other_build = 0
    for step in _iter_post_steps(owned_start_step, requested_end_step, step_interval):
        record = records.get(str(step))
        found = outputs(step)
        files = None if found is None else found[0] + found[1]
        commit = _checkpoint_commit(resolved_source_dir, step)
        reason = classify_post_step(record, files, commit, recipe_fingerprint, recompute)
        if reason is None:
            current += 1
            if record is None:
                record = adopted[step] = {
                    "recipe": recipe_fingerprint,
                    "checkpoint": commit[0] if commit else None,
                    "postprocessor": None,
                }
            if postprocessor_sha and record.get("postprocessor") != postprocessor_sha:
                other_build += 1
        elif available is None or step in available:
            process.append(step)
            reasons[reason] = reasons.get(reason, 0) + 1
        else:
            unavailable.append(step)
 
    skip_reason = None
    if not process:
        if not unavailable:
            skip_reason = 'already-complete-window'
        elif current:
            skip_reason = 'already-caught-up-to-current-source-frontier'
        else:
            skip_reason = 'nothing-available-yet'
    effective_start_step = process[0] if process else None
    effective_end_step = process[-1] if process else None
    effective_post_cfg = None
    if skip_reason is None:
        effective_post_cfg = prepare_effective_post_config(
            post_cfg, resolved_source_dir,
            start_step=effective_start_step, end_step=effective_end_step,
        )
 
    return {
        'run_id': run_id,
        'recompute': bool(recompute),
        'requested_start_step': requested_start_step,
        'requested_end_step': requested_end_step,
        'owned_start_step': owned_start_step,
        'step_interval': step_interval,
        'source_data_directory': resolved_source_dir,
        'recipe_config': recipe_cfg,
        'recipe_signature': recipe_signature,
        'recipe_fingerprint': recipe_fingerprint,
        'resume_state_path': state_path,
        'steps_to_process': process,
        'steps_unavailable': unavailable,
        'steps_current': current,
        'steps_other_build': other_build,
        'process_reasons': reasons,
        'adopted_records': adopted,
        'source_frontier_step': source_frontier_step,
        'source_frontier_diagnostic': source_frontier_diagnostic,
        'source_frontier_deferred': source_frontier_deferred,
        'source_committed_count': None if available is None else len(available),
        'source_latest_step': max(available) if available else None,
        'effective_start_step': effective_start_step,
        'effective_end_step': effective_end_step,
        'skip_reason': skip_reason,
        'resolved_post_cfg': resolved_post_cfg,
        'effective_post_cfg': effective_post_cfg,
        # The lock build_post_locked_command() takes: one post writer per run.
        'lock_paths': get_post_lock_paths(run_dir),
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

report_post_plan()

None picurv_cli.core.report_post_plan

(

dict

plan

)

Print which steps a post plan processes, keeps, and waits for.

Parameters

[in]

plan

Plan from build_post_execution_plan().

Returns

None.

Definition at line 6299 of file core.py.

def report_post_plan(plan: dict) -> None:
    """!
    @brief Print which steps a post plan processes, keeps, and waits for.
    @param[in] plan Plan from build_post_execution_plan().
    @return None.
    """
    process = plan['steps_to_process']
    if plan['source_frontier_deferred']:
        print(f"[INFO] Post steps: {len(process)} planned; the post job decides when it starts, "
              "after the solver has written them.")
        return
    why = ", ".join(f"{count} {POST_PROCESS_REASON_LABELS.get(reason, reason)}"
                    for reason, count in sorted(plan['process_reasons'].items()))
    span = f" ({process[0]}..{process[-1]}; {why})" if process else ""
    print(f"[INFO] Post steps: {len(process)} to process{span}, {plan['steps_current']} up to date, "
          f"{len(plan['steps_unavailable'])} without a committed checkpoint.")
    if plan['steps_other_build']:
        print(f"[INFO] {plan['steps_other_build']} up-to-date step(s) were made by another or an "
              "unrecorded postprocessor build and are kept; --recompute regenerates them.")
 
 

Here is the caller graph for this function:

get_post_step_list_path()

str picurv_cli.core.get_post_step_list_path	(	str	run_dir,
		dict	post_cfg
	)

Return the file naming the steps a launched post job processes.

Parameters

[in]	run_dir	Run directory.
[in]	post_cfg	Runtime recipe with canonical paths.

Returns

Absolute path; a companion <path>.json holds what recording needs.

Definition at line 6320 of file core.py.

def get_post_step_list_path(run_dir: str, post_cfg: dict) -> str:
    """!
    @brief Return the file naming the steps a launched post job processes.
    @param[in] run_dir Run directory.
    @param[in] post_cfg Runtime recipe with canonical paths.
    @return Absolute path; a companion `<path>.json` holds what recording needs.
    """
    return os.path.abspath(os.path.join(get_post_recipe_root(run_dir, post_cfg), "post.steps"))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_load_post_job_configs()

"tuple[dict, dict, dict]" picurv_cli.core._load_post_job_configs ( str  run_dir, str  post_recipe_path  )

protected

Load the configuration a post job needs from the run it runs in.

Parameters

[in]	run_dir	Run directory.
[in]	post_recipe_path	The recipe the job was staged with.

Returns

(case configuration, monitor configuration, runtime recipe with canonical paths).

Definition at line 6330 of file core.py.

def _load_post_job_configs(run_dir: str, post_recipe_path: str) -> "tuple[dict, dict, dict]":
    """!
    @brief Load the configuration a post job needs from the run it runs in.
    @param[in] run_dir Run directory.
    @param[in] post_recipe_path The recipe the job was staged with.
    @return (case configuration, monitor configuration, runtime recipe with canonical paths).
    """
    case_path, monitor_path, _ = auto_identify_run_inputs(os.path.join(run_dir, "config"))
    if not (case_path and monitor_path):
        raise ValueError(f"Could not identify the case and monitor files of {run_dir}.")
    post_cfg, _ = apply_canonical_post_paths(read_yaml_file(post_recipe_path), run_dir)
    return read_yaml_file(case_path), read_yaml_file(monitor_path), post_cfg
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

prepare_post_job()

int picurv_cli.core.prepare_post_job	(	str	run_dir,
		str	post_recipe_path,
		str	postprocessor,
		bool	recompute = False
	)

Decide, as a post job starts, which steps it processes.

Runs under the post lock immediately before the postprocessor, so a job staged long before it runs still skips output produced in the meantime and sees checkpoints the solver has written since. Writes the step list the postprocessor reads, and records what finish_post_job() needs.

Parameters

[in]	run_dir	Run directory.
[in]	post_recipe_path	The recipe the job was staged with.
[in]	postprocessor	Postprocessor executable the job launches.
[in]	recompute	Regenerate every step whose checkpoint is committed.

Returns

Number of steps to process; 0 means the postprocessor need not run.

Definition at line 6344 of file core.py.

                     recompute: bool = False) -> int:
    """!
    @brief Decide, as a post job starts, which steps it processes.
    @details Runs under the post lock immediately before the postprocessor, so a job
             staged long before it runs still skips output produced in the meantime and
             sees checkpoints the solver has written since. Writes the step list the
             postprocessor reads, and records what finish_post_job() needs.
    @param[in] run_dir Run directory.
    @param[in] post_recipe_path The recipe the job was staged with.
    @param[in] postprocessor Postprocessor executable the job launches.
    @param[in] recompute Regenerate every step whose checkpoint is committed.
    @return Number of steps to process; 0 means the postprocessor need not run.
    """
    run_dir = os.path.abspath(run_dir)
    case_cfg, monitor_cfg, post_cfg = _load_post_job_configs(run_dir, post_recipe_path)
    try:
        run_id = read_artifact_identity(run_dir)["run_id"]
    except Exception:
        run_id = os.path.basename(run_dir)
    sha = _file_sha256(postprocessor)
    plan = build_post_execution_plan(run_dir, run_id, case_cfg, monitor_cfg, post_cfg,
                                     recompute=recompute, postprocessor_sha=sha)
    report_post_plan(plan)
    persist_post_resume_state(run_dir, plan, steps=plan['adopted_records'])
    list_path = get_post_step_list_path(run_dir, post_cfg)
    steps = plan['steps_to_process'] if plan['skip_reason'] is None else []
    if not steps:
        for path in (list_path, list_path + ".json"):
            if os.path.exists(path):
                os.remove(path)
        return 0
    outputs = post_step_outputs(run_dir, plan['resolved_post_cfg'], monitor_cfg)
    before = {}
    for step in steps:
        found = outputs(step)
        before[str(step)] = {path: os.stat(path).st_mtime_ns
                             for path in (found[0] + found[1] if found else [])}
    write_json_file(list_path + ".json", {
        "postprocessor": sha,
        "outputs_before": before,
        "plan": {key: plan[key] for key in (
            "run_id", "recipe_fingerprint", "recipe_signature", "requested_start_step",
            "requested_end_step", "step_interval", "source_data_directory", "resume_state_path")},
    })
    with open(list_path, "w", encoding="utf-8") as stream:
        stream.write("".join(f"{step}\n" for step in steps))
    return len(steps)
 
 

Here is the call graph for this function:

finish_post_job()

int picurv_cli.core.finish_post_job	(	str	run_dir,
		str	post_recipe_path,
		bool	exited_cleanly = False
	)

Record, after a post job ends, which steps it produced.

Runs whether or not the postprocessor succeeded, so the steps a failed or interrupted job completed are kept. A step is credited only when all its output exists and was written by this job.

Parameters

[in]	run_dir	Run directory.
[in]	post_recipe_path	The recipe the job was staged with.
[in]	exited_cleanly	Whether the postprocessor exited with status zero; a clean exit that left an expected output unwritten is reported.

Returns

Number of steps recorded.

Definition at line 6394 of file core.py.

def finish_post_job(run_dir: str, post_recipe_path: str, exited_cleanly: bool = False) -> int:
    """!
    @brief Record, after a post job ends, which steps it produced.
    @details Runs whether or not the postprocessor succeeded, so the steps a failed or
             interrupted job completed are kept. A step is credited only when all its
             output exists and was written by this job.
    @param[in] run_dir Run directory.
    @param[in] post_recipe_path The recipe the job was staged with.
    @param[in] exited_cleanly Whether the postprocessor exited with status zero; a clean
                              exit that left an expected output unwritten is reported.
    @return Number of steps recorded.
    """
    run_dir = os.path.abspath(run_dir)
    _case_cfg, monitor_cfg, post_cfg = _load_post_job_configs(run_dir, post_recipe_path)
    list_path = get_post_step_list_path(run_dir, post_cfg)
    job = _read_json_if_exists(list_path + ".json")
    if not isinstance(job, dict):
        return 0
    plan = job["plan"]
    source = plan["source_data_directory"]
    runtime_cfg = prepare_effective_post_config(post_cfg, source)
    outputs = post_step_outputs(run_dir, runtime_cfg, monitor_cfg)
    records = {}
    incomplete = []
    for step_text, before in job["outputs_before"].items():
        step = int(step_text)
        found = outputs(step)
        if found is None:
            incomplete.append(step)
            continue
        # A shared CSV changes with every step, so it proves a step was written only
        # when the step has no file of its own.
        written = found[0] or found[1]
        if not written or any(before.get(path) == os.stat(path).st_mtime_ns for path in written):
            continue
        commit = _checkpoint_commit(source, step)
        records[step] = {
            "recipe": plan["recipe_fingerprint"],
            "checkpoint": commit[0] if commit else None,
            "postprocessor": job["postprocessor"],
        }
    persist_post_resume_state(run_dir, plan, steps=records)
    for path in (list_path, list_path + ".json"):
        if os.path.exists(path):
            os.remove(path)
    print(f"[INFO] Post job recorded {len(records)} of {len(job['outputs_before'])} planned step(s).")
    # A postprocessor that does not know a recipe key ignores it and still exits
    # cleanly, so a step can finish without an output the recipe expects. That is
    # what a pinned executable older than the recipe looks like.
    if incomplete and exited_cleanly:
        try:
            executable = run_executable_path(run_dir, "postprocessor")
        except ValueError:
            executable = "the run's postprocessor"
        print(f"[WARNING] The postprocessor exited cleanly, but {len(incomplete)} planned step(s) "
              f"lack an output this recipe expects (first: step {min(incomplete)}). It may "
              f"predate a requested output: {executable} ignores recipe keys it does not know. "
              "Check its build with 'picurv version', or post-process a branch of the run "
              "built from the current source.", file=sys.stderr)
    return len(records)
 
 

Here is the call graph for this function:

needs_restart_source()

bool picurv_cli.core.needs_restart_source	(	dict	case_cfg,
		dict	solver_cfg
	)

Return True when the solver requires restart data from disk.

Correctly identifies that analytical + init + start_step > 0 does NOT need a restart source (C code never reads from restart_dir in that case).

Parameters

[in]	case_cfg	Parsed case YAML dictionary.
[in]	solver_cfg	Parsed solver YAML dictionary.

Returns

True if a restart source (–restart-from or –continue) is required.

Definition at line 6456 of file core.py.

def needs_restart_source(case_cfg: dict, solver_cfg: dict) -> bool:
    """!
    @brief Return True when the solver requires restart data from disk.
    @details Correctly identifies that analytical + init + start_step > 0 does NOT
             need a restart source (C code never reads from restart_dir in that case).
    @param[in] case_cfg Parsed case YAML dictionary.
    @param[in] solver_cfg Parsed solver YAML dictionary.
    @return True if a restart source (--restart-from or --continue) is required.
    """
    try:
        start_step = int(case_cfg.get("run_control", {}).get("start_step", 0) or 0)
    except (TypeError, ValueError):
        start_step = 0
    eulerian_source = str(
        (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
    ).strip().lower()
    particle_restart_mode = str(
        (case_cfg.get("models", {}).get("physics", {}).get("particles", {}) or {}).get("restart_mode", "init")
    ).strip().lower()
    euler_needs = (eulerian_source == "load") or (eulerian_source == "solve" and start_step > 0)
    particle_needs = (particle_restart_mode == "load")
    return euler_needs or particle_needs
 
 

Here is the caller graph for this function:

resolve_run_output_dir()

str picurv_cli.core.resolve_run_output_dir	(	str	run_dir,
		dict	monitor_cfg
	)

Resolve the output data directory within a run directory.

Parameters

[in]	run_dir	Path to the run directory.
[in]	monitor_cfg	Parsed monitor YAML dictionary.

Returns

Absolute path to the output directory.

Definition at line 6480 of file core.py.

def resolve_run_output_dir(run_dir: str, monitor_cfg: dict) -> str:
    """!
    @brief Resolve the output data directory within a run directory.
    @param[in] run_dir Path to the run directory.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @return Absolute path to the output directory.
    """
    del monitor_cfg
    return os.path.abspath(os.path.join(run_dir, CANONICAL_RUN_PATHS["output"]))
 
 

Here is the caller graph for this function:

resolve_run_restart_dir()

str picurv_cli.core.resolve_run_restart_dir	(	str	run_dir,
		dict	monitor_cfg
	)

Resolve the restart staging directory within a run directory.

Parameters

[in]	run_dir	Path to the run directory.
[in]	monitor_cfg	Parsed monitor YAML dictionary.

Returns

Absolute path to the restart directory.

Definition at line 6491 of file core.py.

def resolve_run_restart_dir(run_dir: str, monitor_cfg: dict) -> str:
    """!
    @brief Resolve the restart staging directory within a run directory.
    @param[in] run_dir Path to the run directory.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @return Absolute path to the restart directory.
    """
    del monitor_cfg
    return os.path.abspath(os.path.join(run_dir, CANONICAL_RUN_PATHS["restart"]))
 
 

Here is the caller graph for this function:

compute_physical_case_identity()

str picurv_cli.core.compute_physical_case_identity

(

dict

case_cfg

)

Compute the hidden identity used to guard in-place continuation.

Run length/timestep controls, the MPI domain decomposition, and particle load-vs-init policy do not define the physical case. All other case.yml content does. Checkpoints are decomposition-independent, so a run may continue on a different rank layout.

Parameters

[in]

case_cfg

Parsed case configuration.

Returns

Lowercase SHA-256 identity of normalized physical-case content.

Definition at line 6502 of file core.py.

def compute_physical_case_identity(case_cfg: dict) -> str:
    """!
    @brief Compute the hidden identity used to guard in-place continuation.
    @details Run length/timestep controls, the MPI domain decomposition, and particle
             load-vs-init policy do not define the physical case. All other case.yml
             content does. Checkpoints are decomposition-independent, so a run may
             continue on a different rank layout.
    @param[in] case_cfg Parsed case configuration.
    @return Lowercase SHA-256 identity of normalized physical-case content.
    """
    normalized = copy.deepcopy(case_cfg)
    if isinstance(normalized, dict):
        normalized.pop("run_control", None)
        grid = normalized.get("grid")
        if isinstance(grid, dict):
            for key in GRID_DA_PROCESSOR_KEYS:
                grid.pop(key, None)
            if isinstance(grid.get("programmatic_settings"), dict):
                for key in GRID_DA_PROCESSOR_KEYS:
                    grid["programmatic_settings"].pop(key, None)
        particles = (((normalized.get("models") or {}).get("physics") or {}).get("particles"))
        if isinstance(particles, dict):
            particles.pop("restart_mode", None)
    payload = json.dumps(
        normalized, sort_keys=True, separators=(",", ":"), ensure_ascii=False
    ).encode("utf-8")
    return hashlib.sha256(payload).hexdigest()
 
 

Here is the caller graph for this function:

validate_continue_case_identity()

None picurv_cli.core.validate_continue_case_identity	(	str	run_dir,
		dict	case_cfg
	)

Reject in-place continuation when the physical case has changed.

Parameters

[in]	run_dir	Existing run directory being continued.
[in]	case_cfg	Newly requested case configuration.

Returns

None.

Definition at line 6531 of file core.py.

def validate_continue_case_identity(run_dir: str, case_cfg: dict) -> None:
    """!
    @brief Reject in-place continuation when the physical case has changed.
    @param[in] run_dir Existing run directory being continued.
    @param[in] case_cfg Newly requested case configuration.
    @return None.
    """
    saved_case_path = os.path.join(run_dir, "config", "case.yml")
    if not os.path.isfile(saved_case_path):
        raise ValueError(f"--continue run is missing its saved case.yml: {saved_case_path}")
    saved_case = read_yaml_file(saved_case_path)
    if compute_physical_case_identity(saved_case) != compute_physical_case_identity(case_cfg):
        raise ValueError(
            "--continue cannot change the physical case. Change only run_control, the "
            "da_processors layout, solver.yml, monitor.yml, or post.yml; use --restart-from "
            "for a new case branch."
        )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

populate_restart_directory()

picurv_cli.core.populate_restart_directory	(	str	source_output,
		str	target_restart,
		int	start_step,
		dict	monitor_cfg,
		"int | None"	end_step = None,
		bool	materialize = True
	)

Atomically materialize an immutable checkpoint interval into a run.

Parameters

[in]	source_output	Path to the source output directory containing checkpoint data.
[in]	target_restart	Path to the target restart directory to populate.
[in]	start_step	First checkpoint step to materialize.
[in]	monitor_cfg	Parsed monitor YAML dictionary (for subdirectory names).
[in]	end_step	Optional inclusive last checkpoint step.
[in]	materialize	Whether to copy the bundles, or only validate and resolve the path a real run would use. The dry-run planner needs the second: it reports what a run would refuse, and promises to write nothing.

Returns

Canonical restart root containing committed checkpoint bundles.

Definition at line 6550 of file core.py.

                               materialize: bool = True):
    """!
    @brief Atomically materialize an immutable checkpoint interval into a run.
    @param[in] source_output Path to the source output directory containing checkpoint data.
    @param[in] target_restart Path to the target restart directory to populate.
    @param[in] start_step First checkpoint step to materialize.
    @param[in] monitor_cfg Parsed monitor YAML dictionary (for subdirectory names).
    @param[in] end_step Optional inclusive last checkpoint step.
    @param[in] materialize Whether to copy the bundles, or only validate and resolve
               the path a real run would use. The dry-run planner needs the second:
               it reports what a run would refuse, and promises to write nothing.
    @return Canonical restart root containing committed checkpoint bundles.
    """
    del monitor_cfg
    checkpoints_root = os.path.join(os.path.abspath(target_restart), "checkpoints")
    if materialize:
        os.makedirs(checkpoints_root, exist_ok=True)
    final_step = start_step if end_step is None else end_step
    if final_step < start_step:
        raise ValueError("Restart checkpoint interval end must not precede its start.")
    for step in range(start_step, final_step + 1):
        source = validate_committed_checkpoint(source_output, step)["bundle"]
        if not materialize:
            continue
        destination = os.path.join(
            checkpoints_root, f"step_{step:0{CHECKPOINT_STEP_WIDTH}d}"
        )
        if os.path.isdir(destination):
            validate_committed_checkpoint(destination, step)
            print(f"[INFO] Reusing committed restart bundle: {destination}")
            continue
        temporary = os.path.join(
            checkpoints_root,
            f".step_{step:0{CHECKPOINT_STEP_WIDTH}d}.copying.{os.getpid()}",
        )
        if os.path.exists(temporary):
            raise ValueError(f"Restart staging path already exists: {temporary}")
        try:
            os.makedirs(temporary)
            for current, dirnames, filenames in os.walk(source):
                relative = os.path.relpath(current, source)
                target_dir = temporary if relative == "." else os.path.join(temporary, relative)
                os.makedirs(target_dir, exist_ok=True)
                for dirname in dirnames:
                    os.makedirs(os.path.join(target_dir, dirname), exist_ok=True)
                for filename in filenames:
                    _materialize_asset_file(
                        os.path.join(current, filename), os.path.join(target_dir, filename)
                    )
            validate_committed_checkpoint(temporary, step)
            os.replace(temporary, destination)
        except Exception:
            if os.path.isdir(temporary):
                shutil.rmtree(temporary)
            raise
        print(f"[INFO] Materialized committed restart bundle for step {step}: {destination}")
    return os.path.abspath(target_restart)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

validate_eulerian_checkpoint()

picurv_cli.core.validate_eulerian_checkpoint	(	str	source_dir,
		int	step,
		dict	monitor_cfg
	)

Validate the mandatory Eulerian field set required by ReadSimulationFields().

Parameters

[in]	source_dir	Root directory containing the Eulerian subdirectory.
[in]	step	Checkpoint step to validate.
[in]	monitor_cfg	Monitor configuration defining the Eulerian subdirectory.

Returns

Validated checkpoint description.

Exceptions

ValueError

if any mandatory Eulerian field is absent.

Definition at line 6611 of file core.py.

def validate_eulerian_checkpoint(source_dir: str, step: int, monitor_cfg: dict):
    """!
    @brief Validate the mandatory Eulerian field set required by `ReadSimulationFields()`.
    @param[in] source_dir Root directory containing the Eulerian subdirectory.
    @param[in] step Checkpoint step to validate.
    @param[in] monitor_cfg Monitor configuration defining the Eulerian subdirectory.
    @return Validated checkpoint description.
    @throws ValueError if any mandatory Eulerian field is absent.
    """
    del monitor_cfg
    return validate_committed_checkpoint(source_dir, step)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

detect_last_checkpoint_step()

picurv_cli.core.detect_last_checkpoint_step

(

str

output_dir

)

Scan output directory for the highest step number available.

Ignores incomplete temporary directories and invalid bundles.

Parameters

[in]

output_dir

Path to the output directory.

Returns

The highest step number found, or None if no checkpoints exist.

Definition at line 6624 of file core.py.

def detect_last_checkpoint_step(output_dir: str):
    """!
    @brief Scan output directory for the highest step number available.
    @details Ignores incomplete temporary directories and invalid bundles.
    @param[in] output_dir Path to the output directory.
    @return The highest step number found, or None if no checkpoints exist.
    """
    steps = _scan_committed_checkpoint_steps(output_dir)
    return max(steps) if steps else None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

detect_case_completion_status()

dict picurv_cli.core.detect_case_completion_status	(	str	run_dir,
		dict	monitor_cfg,
		int	target_final_step
	)

Determine whether a study case is complete, partially complete, or empty.

Parameters

[in]	run_dir	Path to the case run directory.
[in]	monitor_cfg	Parsed monitor YAML dictionary.
[in]	target_final_step	The step number the case should reach for completion.

Returns

Dictionary with keys 'last_step' (int or None), 'target_step' (int), and 'status' ('complete', 'partial', or 'empty').

Definition at line 6635 of file core.py.

def detect_case_completion_status(run_dir: str, monitor_cfg: dict, target_final_step: int) -> dict:
    """!
    @brief Determine whether a study case is complete, partially complete, or empty.
    @param[in] run_dir Path to the case run directory.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @param[in] target_final_step The step number the case should reach for completion.
    @return Dictionary with keys 'last_step' (int or None), 'target_step' (int),
            and 'status' ('complete', 'partial', or 'empty').
    """
    output_dir = resolve_run_output_dir(run_dir, monitor_cfg)
    last_step = detect_last_checkpoint_step(output_dir)
    if last_step is not None and last_step >= target_final_step:
        status = "complete"
    elif last_step is not None:
        status = "partial"
    else:
        status = "empty"
    return {"last_step": last_step, "target_step": target_final_step, "status": status}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

validate_load_mode_step_range()

picurv_cli.core.validate_load_mode_step_range	(	str	source_output,
		int	start_step,
		int	total_steps,
		dict	monitor_cfg
	)

Validate that all required eulerian step files exist for "load" mode.

Checks that ufield files exist for every step from start_step through start_step + total_steps (inclusive). Reports missing steps clearly.

Parameters

[in]	source_output	Path to the output directory containing eulerian data.
[in]	start_step	First step that will be loaded.
[in]	total_steps	Number of steps to run.
[in]	monitor_cfg	Parsed monitor YAML dictionary (for subdirectory names).

Definition at line 6655 of file core.py.

def validate_load_mode_step_range(source_output: str, start_step: int, total_steps: int, monitor_cfg: dict):
    """!
    @brief Validate that all required eulerian step files exist for "load" mode.
    @details Checks that ufield files exist for every step from start_step through
             start_step + total_steps (inclusive). Reports missing steps clearly.
    @param[in] source_output Path to the output directory containing eulerian data.
    @param[in] start_step First step that will be loaded.
    @param[in] total_steps Number of steps to run.
    @param[in] monitor_cfg Parsed monitor YAML dictionary (for subdirectory names).
    """
    missing = []
    for step in range(start_step, start_step + total_steps + 1):
        try:
            validate_eulerian_checkpoint(source_output, step, monitor_cfg)
        except CheckpointIndexWidthError:
            raise
        except ValueError:
            missing.append(step)
 
    if missing:
        sample = missing[:3] + (["..."] if len(missing) > 6 else []) + missing[-3:]
        raise ValueError(
            f"Eulerian 'load' mode: {len(missing)} committed checkpoint(s) missing in {source_output}. "
            f"Missing steps include: {sample}"
        )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

validate_particle_checkpoint()

picurv_cli.core.validate_particle_checkpoint	(	str	source_dir,
		int	start_step,
		dict	monitor_cfg
	)

Validate that particle checkpoint files exist for the given step.

Checks that at least a position file exists at the expected step in the particle subdirectory.

Parameters

[in]	source_dir	Path to the directory containing the particle subdirectory.
[in]	start_step	The step number whose particle checkpoint is expected.
[in]	monitor_cfg	Parsed monitor YAML dictionary (for subdirectory names).

Returns

Validated checkpoint description.

Definition at line 6682 of file core.py.

def validate_particle_checkpoint(source_dir: str, start_step: int, monitor_cfg: dict):
    """!
    @brief Validate that particle checkpoint files exist for the given step.
    @details Checks that at least a position file exists at the expected step in
             the particle subdirectory.
    @param[in] source_dir Path to the directory containing the particle subdirectory.
    @param[in] start_step The step number whose particle checkpoint is expected.
    @param[in] monitor_cfg Parsed monitor YAML dictionary (for subdirectory names).
    @return Validated checkpoint description.
    """
    del monitor_cfg
    return validate_committed_checkpoint(source_dir, start_step, require_particles=True)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

read_monitor_from_run()

dict picurv_cli.core.read_monitor_from_run

(

str

run_dir

)

Read the monitor.yml from a run directory's config/ subdirectory.

Parameters

[in]

run_dir

Path to the run directory.

Returns

Parsed monitor YAML dictionary.

Definition at line 6696 of file core.py.

def read_monitor_from_run(run_dir: str) -> dict:
    """!
    @brief Read the monitor.yml from a run directory's config/ subdirectory.
    @param[in] run_dir Path to the run directory.
    @return Parsed monitor YAML dictionary.
    """
    monitor_path = os.path.join(run_dir, "config", "monitor.yml")
    if not os.path.isfile(monitor_path):
        raise ValueError(f"Run directory is missing config/monitor.yml: {monitor_path}")
    return read_yaml_file(monitor_path)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_latest_restart_run()

str picurv_cli.core.resolve_latest_restart_run	(	dict	case_cfg,
		str	case_path,
		int	start_step
	)

Select the newest local workspace run compatible with a requested restart.

Parameters

[in]	case_cfg	Current case configuration.
[in]	case_path	Current case path.
[in]	start_step	Required committed checkpoint.

Returns

Absolute source run directory.

Definition at line 6708 of file core.py.

def resolve_latest_restart_run(case_cfg: dict, case_path: str, start_step: int) -> str:
    """!
    @brief Select the newest local workspace run compatible with a requested restart.
    @param[in] case_cfg Current case configuration.
    @param[in] case_path Current case path.
    @param[in] start_step Required committed checkpoint.
    @return Absolute source run directory.
    """
    workspace_root = find_workspace_root(case_path, os.getcwd())
    if not workspace_root:
        raise ValueError("--from latest requires an initialized workspace.")
    current_graph = build_case_asset_graph(case_cfg, case_path)
    current_grid = next(
        (item for item in current_graph.get("providers", []) if item.get("kind") == "grid"),
        None,
    )
    candidates = []
    for candidate in Path(workspace_root, "runs").iterdir():
        if not candidate.is_dir():
            continue
        manifest = _read_json_if_exists(str(candidate / "manifest.json")) or {}
        lock = read_yaml_file(str(candidate / "inputs" / "assets.lock.yml")) \
            if (candidate / "inputs" / "assets.lock.yml").is_file() else {}
        locked_grid = (lock.get("assets") or {}).get("grid")
        runtime_grid = (lock.get("runtime_providers") or {}).get("grid")
        if current_grid:
            recorded_hash = None
            if isinstance(locked_grid, dict):
                recorded_hash = locked_grid.get("provider_spec_sha256")
            elif isinstance(runtime_grid, dict):
                recorded_hash = runtime_grid.get("provider_spec_sha256")
            if recorded_hash and recorded_hash != current_grid.get("spec_sha256"):
                continue
        output_root = candidate / CANONICAL_RUN_PATHS["output"]
        try:
            validate_committed_checkpoint(str(output_root), start_step)
        except CheckpointIndexWidthError:
            raise
        except (OSError, ValueError):
            continue
        ordering = manifest.get("updated_at") or manifest.get("created_at") or ""
        candidates.append((ordering, candidate.stat().st_mtime_ns, str(candidate)))
    if not candidates:
        raise ValueError(
            f"No local workspace run has a compatible committed checkpoint at step {start_step}. "
            "Restore a run from storage first, or name one explicitly with --from <run-dir>."
        )
    candidates.sort(reverse=True)
    selected = candidates[0][2]
    print(f"[INFO] Selected latest compatible restart run: {os.path.relpath(selected, workspace_root)}")
    return selected
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_restart_source()

picurv_cli.core.resolve_restart_source	(		args,
		dict	case_cfg,
		dict	solver_cfg,
		dict	monitor_cfg,
		str	run_dir,
		bool	materialize = True
	)

Resolve the restart source directory based on –restart-from or –continue CLI flags.

Implements the full restart resolution logic including smart resolution for –continue (checks restart/ first for user-curated data, falls back to output/) and direct reference for eulerian "load" mode.

Parameters

[in]	args	Parsed CLI arguments (must have restart_from, continue_run, run_dir attrs).
[in]	case_cfg	Parsed case YAML dictionary.
[in]	solver_cfg	Parsed solver YAML dictionary.
[in]	monitor_cfg	Parsed monitor YAML dictionary.
[in]	run_dir	Path to the current run directory.
[in]	materialize	Whether to copy restart bundles into the run. The dry-run planner passes False: it still validates and resolves, but writes nothing.

Returns

Tuple of (restart_source_dir, continue_mode, lineage) where restart_source_dir is the resolved path (or None), continue_mode is a boolean, and lineage is the branch provenance record from build_run_lineage(), or None when this run did not branch from another.

Definition at line 6761 of file core.py.

                           run_dir: str, materialize: bool = True):
    """!
    @brief Resolve the restart source directory based on --restart-from or --continue CLI flags.
    @details Implements the full restart resolution logic including smart resolution for
             --continue (checks restart/ first for user-curated data, falls back to output/)
             and direct reference for eulerian "load" mode.
    @param[in] args Parsed CLI arguments (must have restart_from, continue_run, run_dir attrs).
    @param[in] case_cfg Parsed case YAML dictionary.
    @param[in] solver_cfg Parsed solver YAML dictionary.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @param[in] run_dir Path to the current run directory.
    @param[in] materialize Whether to copy restart bundles into the run. The dry-run
               planner passes False: it still validates and resolves, but writes nothing.
    @return Tuple of (restart_source_dir, continue_mode, lineage) where restart_source_dir
            is the resolved path (or None), continue_mode is a boolean, and lineage is the
            branch provenance record from `build_run_lineage()`, or None when this run did
            not branch from another.
    """
    try:
        start_step = int(case_cfg.get("run_control", {}).get("start_step", 0) or 0)
    except (TypeError, ValueError):
        start_step = 0
    try:
        total_steps = int(case_cfg.get("run_control", {}).get("total_steps", 0) or 0)
    except (TypeError, ValueError):
        total_steps = 0
 
    eulerian_source = str(
        (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
    ).strip().lower()
 
    particle_restart_mode = str(
        (case_cfg.get("models", {}).get("physics", {}).get("particles", {}) or {}).get("restart_mode", "init")
    ).strip().lower()
    particle_needs = (particle_restart_mode == "load")
 
    requires_source = needs_restart_source(case_cfg, solver_cfg)
    restart_from = getattr(args, 'restart_from', None)
    continue_run = getattr(args, 'continue_run', False)
 
    if restart_from and continue_run:
        raise ValueError("--restart-from and --continue are mutually exclusive.")
 
    # The named run must exist before its start step can mean anything.
    if continue_run and getattr(args, 'run_dir', None) and not os.path.isdir(args.run_dir):
        raise ValueError(f"--run-dir does not exist: {os.path.abspath(args.run_dir)}")
    if continue_run and start_step <= 0:
        raise ValueError(
            "--continue with --solve requires run_control.start_step > 0; "
            "start_step=0 is a fresh start. Omit --continue to start a fresh run."
        )
 
    if restart_from:
        requested_restart_source = str(restart_from)
        if str(restart_from).strip().lower() == "latest":
            restart_from = resolve_latest_restart_run(
                case_cfg, getattr(args, "case", "case.yml"), start_step
            )
        # A branch may follow a different physical trajectory than the samples already
        # collected, so the retention of the parent's windows is the user's decision and
        # not a default's. Silently resetting reports a sample count that describes a
        # shorter average than the user expects; silently carrying averages two
        # different flows together. Neither is safe to guess, so the flag is required
        # whenever there are windows to decide about.
        requested_statistics_state = getattr(args, "statistics_state", None)
        statistics_enabled = normalize_field_statistics_config(monitor_cfg or {})["enabled"]
        if requested_statistics_state is None:
            if statistics_enabled:
                raise ValueError(
                    "A branched restart of a run with field_statistics.enabled: true must "
                    "state what happens to the parent's accumulated windows. Pass "
                    "--statistics-state reset to discard them and start the averages over, "
                    "or --statistics-state carry to resume compatible saved window state."
                )
            requested_statistics_state = "reset"
        statistics_state = str(requested_statistics_state).lower()
        if statistics_state == "carry" and not statistics_enabled:
            raise ValueError("--statistics-state carry requires field_statistics.enabled: true.")
        # Carried windows are read from the source checkpoint even when nothing else is:
        # an analytical Eulerian source restores no fields, but its statistics still
        # live in that bundle, and an unstaged restart directory fails at start-up.
        if statistics_state == "carry":
            requires_source = True
 
        # === MODE 1: New run, restart from another run ===
        source_run = os.path.abspath(restart_from)
        if not os.path.isdir(source_run):
            raise ValueError(f"--restart-from run directory does not exist: {source_run}")
        try:
            require_storage_payload_local(source_run, "--restart-from", checkpoint=start_step)
        except StorageError as exc:
            raise ValueError(str(exc)) from exc
        source_monitor = read_monitor_from_run(source_run)
        source_output = resolve_run_output_dir(source_run, source_monitor)
        if not os.path.isdir(source_output):
            raise ValueError(f"Source output directory does not exist: {source_output}")
        lineage = build_run_lineage(
            source_run, start_step,
            workspace_root=find_workspace_root(run_dir),
            statistics_state=statistics_state,
            requested_source=requested_restart_source,
        )
 
        if not requires_source:
            # R7: analytical + init — warn that --restart-from is unused
            print(
                "[WARNING] --restart-from has no effect: an analytical flow with freshly "
                "initialized particles reads no restart data.",
                file=sys.stderr,
            )
            return None, False, None
 
        if eulerian_source == "load":
            # A load-mode run may consume a complete saved sequence. Materialize it
            # into this run so storage never depends on another run remaining local.
            validate_load_mode_step_range(source_output, start_step, total_steps, source_monitor)
            target_restart = resolve_run_restart_dir(run_dir, monitor_cfg)
            restart_root = populate_restart_directory(
                source_output, target_restart, start_step, monitor_cfg,
                end_step=start_step + total_steps, materialize=materialize,
            )
            if particle_needs:
                validate_particle_checkpoint(
                    restart_root if materialize else source_output, start_step, monitor_cfg
                )
            return restart_root, False, lineage
        else:
            # Materialize one immutable bundle into the new run's restart input.
            target_restart = resolve_run_restart_dir(run_dir, monitor_cfg)
            restart_root = populate_restart_directory(
                source_output, target_restart, start_step, monitor_cfg,
                materialize=materialize,
            )
            if particle_needs:
                validate_particle_checkpoint(
                    restart_root if materialize else source_output, start_step, monitor_cfg
                )
            return restart_root, False, lineage
 
    elif continue_run:
        # === MODE 2: Continue in-place ===
        continue_run_dir = getattr(args, 'run_dir', None)
        if not continue_run_dir:
            raise ValueError(RESTART_RUN_DIR_REQUIRED_MESSAGE)
        continue_run_dir = os.path.abspath(continue_run_dir)
        try:
            require_storage_payload_local(continue_run_dir, "--continue", checkpoint=start_step)
        except StorageError as exc:
            raise ValueError(str(exc)) from exc
        validate_continue_case_identity(continue_run_dir, case_cfg)
 
        source_output = resolve_run_output_dir(continue_run_dir, monitor_cfg)
        last_step = detect_last_checkpoint_step(source_output)
        # The solver never overwrites a committed checkpoint, so continuing from an earlier
        # one would keep the old states after it and mix two histories in one run.
        if last_step is not None and start_step < last_step:
            raise ValueError(
                f"--continue starts at step {start_step}, but this run already has committed "
                f"checkpoints through step {last_step}. Continuing in place from an earlier "
                "checkpoint would keep the later ones from the old trajectory. Set "
                f"run_control.start_step to {last_step} to extend the run, or branch a new run "
                f"from step {start_step} with --restart-from {continue_run_dir}."
            )
        if last_step is not None and start_step > last_step:
            raise ValueError(
                f"--continue starts at step {start_step}, but this run's last committed "
                f"checkpoint is step {last_step}. Set run_control.start_step to {last_step}."
            )
 
        if eulerian_source == "load":
            # Preserve the saved sequence under the run's immutable restart input.
            validate_load_mode_step_range(source_output, start_step, total_steps, monitor_cfg)
            target_restart = resolve_run_restart_dir(run_dir, monitor_cfg)
            restart_root = populate_restart_directory(
                source_output, target_restart, start_step, monitor_cfg,
                end_step=start_step + total_steps, materialize=materialize,
            )
            if particle_needs:
                validate_particle_checkpoint(
                    restart_root if materialize else source_output, start_step, monitor_cfg
                )
            return restart_root, True, None
        elif not requires_source:
            # C6: analytical + init — only log-append behavior, no data needed
            return None, True, None
        else:
            # In-place continuation also uses the fixed restart-input home. Reflink or
            # hardlink materialization normally makes this metadata-cheap.
            target_restart = resolve_run_restart_dir(run_dir, monitor_cfg)
            restart_root = populate_restart_directory(
                source_output, target_restart, start_step, monitor_cfg,
                materialize=materialize,
            )
            validate_committed_checkpoint(
                restart_root if materialize else source_output, start_step,
                require_particles=particle_needs,
            )
            return restart_root, True, None
 
    elif requires_source:
        raise ValueError(
            "Restart data required but no source specified. Use:\n"
            "  --restart-from <run_dir>  (new run from another run's data)\n"
            "  --continue --run-dir <run_dir>  (resume in same directory)"
        )
 
    return None, False, None
 

Here is the call graph for this function:

Here is the caller graph for this function:

absolutize_case_external_paths()

picurv_cli.core.absolutize_case_external_paths	(	dict	case_cfg,
		str	case_anchor_path
	)

Convert external grid/generator paths in case config to absolute paths.

Parameters

[in]	case_cfg	Argument passed to absolutize_case_external_paths().
[in]	case_anchor_path	Argument passed to absolutize_case_external_paths().

Definition at line 6970 of file core.py.

def absolutize_case_external_paths(case_cfg: dict, case_anchor_path: str):
    """!
    @brief Convert external grid/generator paths in case config to absolute paths.
    @param[in] case_cfg Argument passed to `absolutize_case_external_paths()`.
    @param[in] case_anchor_path Argument passed to `absolutize_case_external_paths()`.
    """
    # Initialized workspaces deliberately keep portable, root-relative paths in
    # every materialized study member.  The run/study directory remains below
    # the workspace, so normal resolution can still find the owning manifest.
    if find_workspace_root(case_anchor_path):
        return
    grid_cfg = case_cfg.get("grid", {})
    if not isinstance(grid_cfg, dict):
        return
    mode = grid_cfg.get("mode")
    if mode == "file":
        source_file = grid_cfg.get("source_file")
        if isinstance(source_file, str):
            grid_cfg["source_file"] = resolve_path(case_anchor_path, source_file)
    elif mode == "grid_gen":
        gen = grid_cfg.get("generator", {})
        if isinstance(gen, dict):
            for key in ("script", "config_file"):
                val = gen.get(key)
                if isinstance(val, str):
                    gen[key] = resolve_path(case_anchor_path, val)
    ic = (case_cfg.get("properties", {}) or {}).get("initial_conditions", {})
    if isinstance(ic, dict):
        if str(ic.get("mode", "")).strip().lower() == "file":
            source_file = ic.get("source_file")
            if isinstance(source_file, str):
                ic["source_file"] = resolve_path(case_anchor_path, source_file)
        elif str(ic.get("generator", "")).strip().lower() == "ic_gen":
            params = ic.get("params", {})
            if isinstance(params, dict):
                for key in ("script", "config_file"):
                    value = params.get(key)
                    if isinstance(value, str):
                        params[key] = resolve_path(case_anchor_path, value)
    boundary_conditions = case_cfg.get("boundary_conditions", [])
    blocks = boundary_conditions if boundary_conditions and isinstance(boundary_conditions[0], list) else [boundary_conditions]
    for block in blocks:
        if not isinstance(block, list):
            continue
        for bc in block:
            if not isinstance(bc, dict) or str(bc.get("handler", "")).strip().lower() != "prescribed_flow":
                continue
            source = ((bc.get("params") or {}).get("source") or {})
            if not isinstance(source, dict):
                continue
            source_type = str(source.get("type", "")).strip().lower()
            if source_type == "file":
                keys = ("path",)
            elif source_type == "generated":
                keys = ("script",)
            elif source_type == "field_slice":
                keys = ("script", "field_file", "grid_file", "source_case")
            else:
                keys = ()
            for key in keys:
                value = source.get(key)
                if isinstance(value, str):
                    source[key] = resolve_path(case_anchor_path, value)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

prepare_case_for_continuation()

picurv_cli.core.prepare_case_for_continuation	(	str	run_dir,
		str	case_id,
		int	last_step,
		int	target_final_step,
		dict	cluster_cfg
	)

Set up a partially-completed study case for continuation in-place.

Updates the case config with new start_step/total_steps, sets particle restart_mode to 'load' if checkpoint exists, populates the restart directory, and regenerates the solver control file with continue_mode. Delegates all restart resolution to resolve_restart_source().

Parameters

[in]	run_dir	Path to the case run directory.
[in]	case_id	The case identifier (e.g. 'case_0002').
[in]	last_step	The last checkpoint step found in the output directory.
[in]	target_final_step	The step number the case should reach for completion.
[in]	cluster_cfg	Parsed cluster YAML dictionary (for num_procs, walltime guard).

Returns

The absolute path to the regenerated control file.

Definition at line 7035 of file core.py.

                                   target_final_step: int, cluster_cfg: dict):
    """!
    @brief Set up a partially-completed study case for continuation in-place.
    @details Updates the case config with new start_step/total_steps, sets particle
             restart_mode to 'load' if checkpoint exists, populates the restart
             directory, and regenerates the solver control file with continue_mode.
             Delegates all restart resolution to resolve_restart_source().
    @param[in] run_dir Path to the case run directory.
    @param[in] case_id The case identifier (e.g. 'case_0002').
    @param[in] last_step The last checkpoint step found in the output directory.
    @param[in] target_final_step The step number the case should reach for completion.
    @param[in] cluster_cfg Parsed cluster YAML dictionary (for num_procs, walltime guard).
    @return The absolute path to the regenerated control file.
    """
    config_dir = os.path.join(run_dir, "config")
    case_cfg = read_yaml_file(os.path.join(config_dir, "case.yml"))
    solver_cfg = read_yaml_file(os.path.join(config_dir, "solver.yml"))
    monitor_cfg = read_yaml_file(os.path.join(config_dir, "monitor.yml"))
 
    remaining = target_final_step - last_step
    case_cfg["run_control"]["start_step"] = last_step
    case_cfg["run_control"]["total_steps"] = remaining
    print(f"[INFO] {case_id}: updating start_step={last_step}, total_steps={remaining}")
 
    output_dir = resolve_run_output_dir(run_dir, monitor_cfg)
    particles_cfg = (case_cfg.get("models", {}).get("physics", {}) or {}).get("particles")
    checkpoint_has_particles = False
    try:
        checkpoint_has_particles = validate_committed_checkpoint(
            output_dir, last_step, require_particles=True
        )["has_particles"]
    except CheckpointIndexWidthError:
        raise
    except ValueError:
        checkpoint_has_particles = False
    if particles_cfg is not None and checkpoint_has_particles:
        current_mode = str(particles_cfg.get("restart_mode", "init")).strip().lower()
        if current_mode != "load":
            particles_cfg["restart_mode"] = "load"
            print(f"[INFO] {case_id}: setting particle restart_mode='load' (checkpoint found)")
 
    write_yaml_file(os.path.join(config_dir, "case.yml"), case_cfg)
 
    mock_args = argparse.Namespace(restart_from=None, continue_run=True, run_dir=run_dir)
    restart_source_dir, continue_mode, _lineage = resolve_restart_source(
        mock_args, case_cfg, solver_cfg, monitor_cfg, run_dir
    )
 
    source_files = {
        'Case': os.path.join(config_dir, "case.yml"),
        'Solver': os.path.join(config_dir, "solver.yml"),
        'Monitor': os.path.join(config_dir, "monitor.yml"),
    }
    monitor_files = prepare_monitor_files(run_dir, case_id, monitor_cfg, source_files)
    cluster_tasks = get_cluster_total_tasks(cluster_cfg)
    configs = {
        "case": case_cfg, "case_path": source_files['Case'],
        "solver": solver_cfg, "solver_path": source_files['Solver'],
        "monitor": monitor_cfg, "monitor_path": source_files['Monitor'],
        "walltime_guard_policy": resolve_walltime_guard_policy(cluster_cfg),
        "cluster_cfg": cluster_cfg,
    }
    control_file = generate_solver_control_file(
        run_dir, case_id, configs, cluster_tasks, monitor_files,
        restart_source_dir=restart_source_dir, continue_mode=continue_mode,
    )
    print(f"[SUCCESS] {case_id}: regenerated control file for continuation")
    return control_file
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

is_valid_email()

bool picurv_cli.core.is_valid_email

(

str

email

)

Lightweight email validation for scheduler notifications.

Parameters

[in]

email

Argument passed to is_valid_email().

Returns

Value returned by is_valid_email().

Definition at line 7106 of file core.py.

def is_valid_email(email: str) -> bool:
    """!
    @brief Lightweight email validation for scheduler notifications.
    @param[in] email Argument passed to `is_valid_email()`.
    @return Value returned by `is_valid_email()`.
    """
    if not isinstance(email, str):
        return False
    pattern = r"^[^@\s]+@[^@\s]+\.[^@\s]+$"
    return re.match(pattern, email.strip()) is not None
 

Here is the caller graph for this function:

normalize_statistics_task()

str picurv_cli.core.normalize_statistics_task

(

str

task_name

)

Normalizes user-facing statistics task names to C pipeline keywords.

Parameters

[in]

task_name

Task name from YAML.

Returns

Canonical keyword accepted by C statistics pipeline.

Exceptions

ValueError

if task is unsupported.

Definition at line 7117 of file core.py.

def normalize_statistics_task(task_name: str) -> str:
    """!
    @brief Normalizes user-facing statistics task names to C pipeline keywords.
    @param[in] task_name Task name from YAML.
    @return Canonical keyword accepted by C statistics pipeline.
    @throws ValueError if task is unsupported.
    """
    # Only implemented statistics kernels belong here.
    if task_name is None:
        raise ValueError("statistics task cannot be None")
    normalized = str(task_name).strip().lower().replace("-", "_").replace(" ", "_")
    if normalized != "msd":
        raise ValueError(f"Unsupported statistics task '{task_name}'. Currently supported: 'msd'.")
    return "ComputeMSD"
 

Here is the caller graph for this function:

_iter_nonempty_noncomment_lines()

picurv_cli.core._iter_nonempty_noncomment_lines (   file_obj )

protected

Yield (lineno, stripped_line) for non-empty, non-comment lines.

Parameters

[in]

file_obj

Argument passed to _iter_nonempty_noncomment_lines().

Definition at line 7132 of file core.py.

def _iter_nonempty_noncomment_lines(file_obj):
    """!
    @brief Yield (lineno, stripped_line) for non-empty, non-comment lines.
    @param[in] file_obj Argument passed to `_iter_nonempty_noncomment_lines()`.
    """
    for lineno, raw in enumerate(file_obj, start=1):
        line = raw.strip()
        if not line or line.startswith("#"):
            continue
        yield lineno, line
 

Here is the caller graph for this function:

format_picgrid_coordinate()

str picurv_cli.core.format_picgrid_coordinate

(

float

value

)

Format a coordinate with round-trip-safe binary64 precision.

Parameters

[in]

value

Coordinate value.

Returns

Formatted coordinate.

Definition at line 7146 of file core.py.

def format_picgrid_coordinate(value: float) -> str:
    """!
    @brief Format a coordinate with round-trip-safe binary64 precision.
    @param[in] value Coordinate value.
    @return Formatted coordinate.
    """
    return format(value, PICGRID_FLOAT_FORMAT)
 
 

validate_and_nondimensionalize_picgrid()

dict picurv_cli.core.validate_and_nondimensionalize_picgrid	(	str	source_grid,
		str	dest_grid,
		float	L_ref,
		int	expected_nblk = None
	)

Validates PICGRID payload and writes a non-dimensionalized copy.

Requires canonical PICGRID input with leading "PICGRID" token. Output is always written in canonical PICGRID format with header and per-block dims.

Parameters

[in]	source_grid	Input grid file path.
[in]	dest_grid	Output grid file path.
[in]	L_ref	Reference length for non-dimensionalization.
[in]	expected_nblk	Optional expected block count.

Returns

Summary dictionary with nblk, dims, and total_nodes.

Exceptions

ValueError

on malformed grid.

Definition at line 7155 of file core.py.

def validate_and_nondimensionalize_picgrid(source_grid: str, dest_grid: str, L_ref: float, expected_nblk: int = None) -> dict:
    """!
    @brief Validates PICGRID payload and writes a non-dimensionalized copy.
    @details Requires canonical PICGRID input with leading "PICGRID" token.
             Output is always written in canonical PICGRID format with header and per-block dims.
    @param[in] source_grid Input grid file path.
    @param[in] dest_grid Output grid file path.
    @param[in] L_ref Reference length for non-dimensionalization.
    @param[in] expected_nblk Optional expected block count.
    @return Summary dictionary with nblk, dims, and total_nodes.
    @throws ValueError on malformed grid.
    """
    if L_ref == 0.0:
        raise ValueError("length_ref must be non-zero when processing grid coordinates.")
    if not os.path.isfile(source_grid):
        raise ValueError(f"Grid file not found: {source_grid}")
 
    with open(source_grid, "r") as fin:
        line_iter = _iter_nonempty_noncomment_lines(fin)
        try:
            _, first_token = next(line_iter)
        except StopIteration:
            raise ValueError(f"Grid file '{source_grid}' is empty.")
 
        if first_token != "PICGRID":
            raise ValueError(
                f"Grid file '{source_grid}' must begin with the canonical PICGRID header token."
            )
        try:
            _, nblk_line = next(line_iter)
        except StopIteration:
            raise ValueError(f"Grid file '{source_grid}' missing block count after PICGRID header.")
 
        try:
            nblk = int(nblk_line)
        except ValueError:
            raise ValueError(f"Invalid block count '{nblk_line}' in grid file '{source_grid}'.")
        if nblk <= 0:
            raise ValueError(f"Grid file '{source_grid}' has non-positive block count: {nblk}.")
        if expected_nblk is not None and nblk != expected_nblk:
            raise ValueError(
                f"Grid file block count mismatch: case expects {expected_nblk}, grid contains {nblk}."
            )
 
        dims = []
        for bi in range(nblk):
            try:
                lineno, dim_line = next(line_iter)
            except StopIteration:
                raise ValueError(f"Grid file '{source_grid}' missing dimensions for block {bi}.")
            parts = dim_line.split()
            if len(parts) != 3:
                raise ValueError(
                    f"Invalid dimensions line at {source_grid}:{lineno}. Expected 3 integers, got: '{dim_line}'."
                )
            try:
                im, jm, km = (int(parts[0]), int(parts[1]), int(parts[2]))
            except ValueError:
                raise ValueError(
                    f"Invalid dimensions line at {source_grid}:{lineno}. Non-integer values: '{dim_line}'."
                )
            if im <= 0 or jm <= 0 or km <= 0:
                raise ValueError(
                    f"Invalid block dimensions at {source_grid}:{lineno}: ({im}, {jm}, {km}). Must be > 0."
                )
            dims.append((im, jm, km))
 
        total_nodes_expected = sum(im * jm * km for (im, jm, km) in dims)
        os.makedirs(os.path.dirname(dest_grid), exist_ok=True)
        with open(dest_grid, "w") as fout:
            fout.write("PICGRID\n")
            fout.write(f"{nblk}\n")
            for (im, jm, km) in dims:
                fout.write(f"{im} {jm} {km}\n")
 
            total_nodes_seen = 0
            for lineno, coord_line in line_iter:
                parts = coord_line.split()
                if len(parts) != 3:
                    raise ValueError(
                        f"Invalid coordinate row at {source_grid}:{lineno}. Expected 3 floats, got: '{coord_line}'."
                    )
                try:
                    x = float(parts[0]) / L_ref
                    y = float(parts[1]) / L_ref
                    z = float(parts[2]) / L_ref
                except ValueError:
                    raise ValueError(
                        f"Invalid coordinate row at {source_grid}:{lineno}. Non-numeric values: '{coord_line}'."
                    )
                total_nodes_seen += 1
                if total_nodes_seen > total_nodes_expected:
                    raise ValueError(
                        f"Grid file '{source_grid}' has more coordinates ({total_nodes_seen}) than expected ({total_nodes_expected})."
                    )
                fout.write(
                    f"{format_picgrid_coordinate(x)} {format_picgrid_coordinate(y)} "
                    f"{format_picgrid_coordinate(z)}\n"
                )
 
        if total_nodes_seen != total_nodes_expected:
            raise ValueError(
                f"Grid file '{source_grid}' has {total_nodes_seen} coordinates, expected {total_nodes_expected} from header."
            )
 
    return {"nblk": nblk, "dims": dims, "total_nodes": total_nodes_expected}
 

Here is the call graph for this function:

Here is the caller graph for this function:

read_picgrid_header_dimensions()

list picurv_cli.core.read_picgrid_header_dimensions	(	str	source_grid,
		int	expected_nblk = None
	)

Read only the canonical PICGRID header dimensions.

Parameters

[in]	source_grid	Input grid file path.
[in]	expected_nblk	Optional expected block count.

Returns

List of (IM, JM, KM) node-count tuples.

Exceptions

ValueError

on malformed header.

Definition at line 7262 of file core.py.

def read_picgrid_header_dimensions(source_grid: str, expected_nblk: int = None) -> list:
    """!
    @brief Read only the canonical PICGRID header dimensions.
    @param[in] source_grid Input grid file path.
    @param[in] expected_nblk Optional expected block count.
    @return List of (IM, JM, KM) node-count tuples.
    @throws ValueError on malformed header.
    """
    if not os.path.isfile(source_grid):
        raise ValueError(f"Grid file not found: {source_grid}")
 
    with open(source_grid, "r") as fin:
        line_iter = _iter_nonempty_noncomment_lines(fin)
        try:
            _, first_token = next(line_iter)
        except StopIteration:
            raise ValueError(f"Grid file '{source_grid}' is empty.")
        if first_token != "PICGRID":
            raise ValueError(f"Grid file '{source_grid}' must begin with the canonical PICGRID header token.")
 
        try:
            _, nblk_line = next(line_iter)
            nblk = int(nblk_line)
        except StopIteration:
            raise ValueError(f"Grid file '{source_grid}' missing block count after PICGRID header.")
        except ValueError:
            raise ValueError(f"Invalid block count '{nblk_line}' in grid file '{source_grid}'.")
        if nblk <= 0:
            raise ValueError(f"Grid file '{source_grid}' has non-positive block count: {nblk}.")
        if expected_nblk is not None and nblk != expected_nblk:
            raise ValueError(f"Grid file block count mismatch: case expects {expected_nblk}, grid contains {nblk}.")
 
        dims = []
        for bi in range(nblk):
            try:
                lineno, dim_line = next(line_iter)
            except StopIteration:
                raise ValueError(f"Grid file '{source_grid}' missing dimensions for block {bi}.")
            parts = dim_line.split()
            if len(parts) != 3:
                raise ValueError(
                    f"Invalid dimensions line at {source_grid}:{lineno}. Expected 3 integers, got: '{dim_line}'."
                )
            try:
                im, jm, km = (int(parts[0]), int(parts[1]), int(parts[2]))
            except ValueError:
                raise ValueError(
                    f"Invalid dimensions line at {source_grid}:{lineno}. Non-integer values: '{dim_line}'."
                )
            if im <= 0 or jm <= 0 or km <= 0:
                raise ValueError(
                    f"Invalid block dimensions at {source_grid}:{lineno}: ({im}, {jm}, {km}). Must be > 0."
                )
            dims.append((im, jm, km))
 
    return dims
 

Here is the call graph for this function:

Here is the caller graph for this function:

validate_and_nondimensionalize_picslice()

dict picurv_cli.core.validate_and_nondimensionalize_picslice	(	str	source_slice,
		str	dest_slice,
		float	U_ref,
		tuple	expected_dims = None
	)

Validate a canonical PICSLICE payload and write a solver-scale copy.

Parameters

[in]	source_slice	Input PICSLICE path.
[in]	dest_slice	Output staged PICSLICE path.
[in]	U_ref	Reference velocity for non-dimensionalization.
[in]	expected_dims	Optional expected (n1, n2) slice dimensions.

Returns

Summary dictionary with frame_count, dims, value_count, min_speed, max_speed.

Exceptions

ValueError

on malformed slice.

Definition at line 7319 of file core.py.

                                            expected_dims: tuple = None) -> dict:
    """!
    @brief Validate a canonical PICSLICE payload and write a solver-scale copy.
    @param[in] source_slice Input PICSLICE path.
    @param[in] dest_slice Output staged PICSLICE path.
    @param[in] U_ref Reference velocity for non-dimensionalization.
    @param[in] expected_dims Optional expected (n1, n2) slice dimensions.
    @return Summary dictionary with frame_count, dims, value_count, min_speed, max_speed.
    @throws ValueError on malformed slice.
    """
    if U_ref == 0.0:
        raise ValueError("velocity_ref must be non-zero when processing PICSLICE speeds.")
    if not os.path.isfile(source_slice):
        raise ValueError(f"PICSLICE file not found: {source_slice}")
 
    with open(source_slice, "r") as fin:
        line_iter = _iter_nonempty_noncomment_lines(fin)
        try:
            _, first_token = next(line_iter)
        except StopIteration:
            raise ValueError(f"PICSLICE file '{source_slice}' is empty.")
        if first_token != "PICSLICE":
            raise ValueError(f"PICSLICE file '{source_slice}' must begin with the canonical PICSLICE header token.")
 
        try:
            _, frame_line = next(line_iter)
            frame_count = int(frame_line)
        except StopIteration:
            raise ValueError(f"PICSLICE file '{source_slice}' missing frame count after PICSLICE header.")
        except ValueError:
            raise ValueError(f"Invalid frame count '{frame_line}' in PICSLICE file '{source_slice}'.")
        if frame_count != 1:
            raise ValueError(
                f"PICSLICE file '{source_slice}' has frame count {frame_count}; PICurv reads exactly one frame."
            )
 
        try:
            lineno, dim_line = next(line_iter)
        except StopIteration:
            raise ValueError(f"PICSLICE file '{source_slice}' missing slice dimensions.")
        parts = dim_line.split()
        if len(parts) != 2:
            raise ValueError(
                f"Invalid PICSLICE dimensions at {source_slice}:{lineno}. Expected 2 integers, got: '{dim_line}'."
            )
        try:
            n1, n2 = (int(parts[0]), int(parts[1]))
        except ValueError:
            raise ValueError(
                f"Invalid PICSLICE dimensions at {source_slice}:{lineno}. Non-integer values: '{dim_line}'."
            )
        if n1 <= 0 or n2 <= 0:
            raise ValueError(f"Invalid PICSLICE dimensions at {source_slice}:{lineno}: ({n1}, {n2}). Must be > 0.")
        if expected_dims is not None and (n1, n2) != tuple(expected_dims):
            raise ValueError(
                f"PICSLICE dimension mismatch for '{source_slice}': expected {tuple(expected_dims)}, found {(n1, n2)}."
            )
 
        values = []
        for lineno, value_line in line_iter:
            parts = value_line.split()
            if len(parts) != 1:
                raise ValueError(
                    f"Invalid PICSLICE value row at {source_slice}:{lineno}. Expected 1 float, got: '{value_line}'."
                )
            try:
                value = float(parts[0])
            except ValueError:
                raise ValueError(f"Invalid PICSLICE value at {source_slice}:{lineno}: '{value_line}'.")
            if not math.isfinite(value):
                raise ValueError(f"PICSLICE value at {source_slice}:{lineno} must be finite.")
            if value < 0.0:
                raise ValueError(f"PICSLICE value at {source_slice}:{lineno} must be nonnegative.")
            values.append(value)
 
    expected_count = n1 * n2
    if len(values) != expected_count:
        raise ValueError(
            f"PICSLICE file '{source_slice}' has {len(values)} values, expected {expected_count} from dimensions {(n1, n2)}."
        )
 
    os.makedirs(os.path.dirname(dest_slice), exist_ok=True)
    with open(dest_slice, "w") as fout:
        fout.write("PICSLICE\n")
        fout.write("1\n")
        fout.write(f"{n1} {n2}\n")
        for value in values:
            fout.write(f"{value / U_ref:.8e}\n")
 
    return {
        "frame_count": frame_count,
        "dims": (n1, n2),
        "value_count": len(values),
        "min_speed": min(values) if values else 0.0,
        "max_speed": max(values) if values else 0.0,
    }
 

Here is the call graph for this function:

Here is the caller graph for this function:

_face_artifact_token()

str picurv_cli.core._face_artifact_token ( str  face )

protected

Convert a BC face token into a filesystem-friendly artifact token.

Parameters

[in]

face

Canonical face token such as -Zeta.

Returns

Filesystem-friendly face token.

Definition at line 7417 of file core.py.

def _face_artifact_token(face: str) -> str:
    """!
    @brief Convert a BC face token into a filesystem-friendly artifact token.
    @param[in] face Canonical face token such as -Zeta.
    @return Filesystem-friendly face token.
    """
    return face.replace("+", "pos").replace("-", "neg")
 

Here is the caller graph for this function:

_resolve_run_artifact_path()

str picurv_cli.core._resolve_run_artifact_path ( str  run_dir, str  configured_path, str  default_path, bool   default_to_config_dir = False  )

protected

Resolve a run artifact path with run-dir-relative defaults.

Parameters

[in]	run_dir	Run/precompute directory root.
[in]	configured_path	Optional user-provided artifact path.
[in]	default_path	Default path relative to run_dir.
[in]	default_to_config_dir	If true, bare relative names are placed under config/.

Returns

Absolute artifact path.

Definition at line 7425 of file core.py.

                               default_to_config_dir: bool = False) -> str:
    """!
    @brief Resolve a run artifact path with run-dir-relative defaults.
    @param[in] run_dir Run/precompute directory root.
    @param[in] configured_path Optional user-provided artifact path.
    @param[in] default_path Default path relative to run_dir.
    @param[in] default_to_config_dir If true, bare relative names are placed under config/.
    @return Absolute artifact path.
    """
    path = configured_path if configured_path else default_path
    if not isinstance(path, str) or not path.strip():
        raise ValueError("generated profile output_file must be a non-empty path when provided.")
    path = path.strip()
    if os.path.isabs(path):
        return os.path.abspath(path)
    if default_to_config_dir and os.path.dirname(path) == "":
        path = os.path.join("config", path)
    return os.path.abspath(os.path.join(run_dir, path))
 

_resolve_generator_script()

str picurv_cli.core._resolve_generator_script ( str  configured_script, str  case_path, str  default_name  )

protected

Resolve an optional generator script override or repository default.

Parameters

[in]	configured_script	Optional absolute or case-relative script path.
[in]	case_path	Current case.yml path used to anchor relative overrides.
[in]	default_name	Repository generator filename under GENERATORS_PATH.

Returns

Absolute generator script path.

Definition at line 7445 of file core.py.

def _resolve_generator_script(configured_script: str, case_path: str, default_name: str) -> str:
    """!
    @brief Resolve an optional generator script override or repository default.
    @param[in] configured_script Optional absolute or case-relative script path.
    @param[in] case_path Current case.yml path used to anchor relative overrides.
    @param[in] default_name Repository generator filename under GENERATORS_PATH.
    @return Absolute generator script path.
    """
    if configured_script is None:
        return os.path.join(GENERATORS_PATH, default_name)
    if not isinstance(configured_script, str) or not configured_script.strip():
        raise ValueError(f"Generator script override for {default_name} must be a non-empty path.")
    script = configured_script.strip()
    case_dir = os.path.dirname(os.path.abspath(case_path)) if case_path else os.getcwd()
    return _resolve_case_relative_path(script, case_dir)
 

Here is the call graph for this function:

Here is the caller graph for this function:

_normalize_square_duct_poiseuille_params()

dict picurv_cli.core._normalize_square_duct_poiseuille_params (   params, str  field_name  )

protected

Validate square-duct Poiseuille generator parameters.

Parameters

[in]	params	Generator params mapping.
[in]	field_name	Human-readable YAML field name for diagnostics.

Returns

Normalized params.

Definition at line 7461 of file core.py.

def _normalize_square_duct_poiseuille_params(params, field_name: str) -> dict:
    """!
    @brief Validate square-duct Poiseuille generator parameters.
    @param[in] params Generator params mapping.
    @param[in] field_name Human-readable YAML field name for diagnostics.
    @return Normalized params.
    """
    if params is None:
        params = {}
    if not isinstance(params, dict):
        raise ValueError(f"{field_name}.params must be a mapping when provided.")
    unknown = sorted(set(params.keys()) - {"bulk_velocity", "n_terms"})
    if unknown:
        raise ValueError(f"Unknown keys in {field_name}.params: {unknown}. Allowed: ['bulk_velocity', 'n_terms'].")
    bulk_velocity = _to_float(params.get("bulk_velocity", 1.0), f"{field_name}.params.bulk_velocity")
    if bulk_velocity <= 0.0:
        raise ValueError(f"{field_name}.params.bulk_velocity must be positive.")
    try:
        n_terms = int(params.get("n_terms", 101))
    except (TypeError, ValueError):
        raise ValueError(f"{field_name}.params.n_terms must be a positive odd integer.")
    if n_terms <= 0 or n_terms % 2 == 0:
        raise ValueError(f"{field_name}.params.n_terms must be a positive odd integer.")
    return {"bulk_velocity": bulk_velocity, "n_terms": n_terms}
 

Here is the call graph for this function:

Here is the caller graph for this function:

_normalize_field_slice_source()

dict picurv_cli.core._normalize_field_slice_source (   source, str  field_name  )

protected

Validate a prescribed_flow field_slice source block.

Parameters

[in]	source	Source mapping from case.yml.
[in]	field_name	Human-readable YAML path for diagnostics.

Returns

Normalized source mapping.

Definition at line 7488 of file core.py.

def _normalize_field_slice_source(source, field_name: str) -> dict:
    """!
    @brief Validate a prescribed_flow field_slice source block.
    @param[in] source Source mapping from case.yml.
    @param[in] field_name Human-readable YAML path for diagnostics.
    @return Normalized source mapping.
    """
    allowed = {
        "type",
        "script",
        "field_file",
        "grid_file",
        "source_case",
        "velocity_scale",
        "source_block",
        "slice",
    }
    if "output_file" in source:
        raise ValueError(retired_destination_message(field_name, "output_file"))
    unknown = sorted(set(source.keys()) - allowed)
    if unknown:
        raise ValueError(f"Unknown keys in {field_name}: {unknown}. Allowed: {sorted(allowed)}.")
    field_file = source.get("field_file")
    grid_file = source.get("grid_file")
    if not isinstance(field_file, str) or not field_file.strip():
        raise ValueError(f"{field_name}.field_file must be a non-empty path.")
    if not isinstance(grid_file, str) or not grid_file.strip():
        raise ValueError(f"{field_name}.grid_file must be a non-empty path.")
    if source.get("source_case") is None and source.get("velocity_scale") is None:
        raise ValueError(f"{field_name} requires source_case or velocity_scale.")
 
    normalized = {
        "type": "field_slice",
        "field_file": field_file.strip(),
        "grid_file": grid_file.strip(),
        "slice": _normalize_field_slice_selector(source.get("slice"), f"{field_name}.slice"),
    }
    if source.get("script") is not None:
        script = source.get("script")
        if not isinstance(script, str) or not script.strip():
            raise ValueError(f"{field_name}.script must be a non-empty path when provided.")
        normalized["script"] = script.strip()
    if source.get("source_case") is not None:
        source_case = source.get("source_case")
        if not isinstance(source_case, str) or not source_case.strip():
            raise ValueError(f"{field_name}.source_case must be a non-empty path when provided.")
        normalized["source_case"] = source_case.strip()
    if source.get("velocity_scale") is not None:
        velocity_scale = _to_float(source.get("velocity_scale"), f"{field_name}.velocity_scale")
        if velocity_scale <= 0.0:
            raise ValueError(f"{field_name}.velocity_scale must be positive.")
        normalized["velocity_scale"] = velocity_scale
    if source.get("source_block") is not None:
        try:
            source_block = int(source.get("source_block"))
        except (TypeError, ValueError):
            raise ValueError(f"{field_name}.source_block must be a non-negative integer.")
        if source_block < 0:
            raise ValueError(f"{field_name}.source_block must be a non-negative integer.")
        normalized["source_block"] = source_block
    return normalized
 

Here is the call graph for this function:

Here is the caller graph for this function:

_normalize_field_slice_selector()

dict picurv_cli.core._normalize_field_slice_selector (   slice_cfg, str  field_name  )

protected

Validate the field_slice slice selector.

Parameters

[in]	slice_cfg	Slice selector mapping.
[in]	field_name	Human-readable YAML path for diagnostics.

Returns

Normalized selector mapping.

Definition at line 7550 of file core.py.

def _normalize_field_slice_selector(slice_cfg, field_name: str) -> dict:
    """!
    @brief Validate the field_slice slice selector.
    @param[in] slice_cfg Slice selector mapping.
    @param[in] field_name Human-readable YAML path for diagnostics.
    @return Normalized selector mapping.
    """
    if not isinstance(slice_cfg, dict):
        raise ValueError(f"{field_name} must be a mapping.")
    orientation = str(slice_cfg.get("orientation", "opposite")).strip().lower()
    if orientation not in {"opposite", "same"}:
        raise ValueError(f"{field_name}.orientation must be 'opposite' or 'same'.")
    normal_tolerance = _to_float(slice_cfg.get("normal_tolerance", 0.99), f"{field_name}.normal_tolerance")
    if normal_tolerance <= 0.0 or normal_tolerance > 1.0:
        raise ValueError(f"{field_name}.normal_tolerance must be in the range (0, 1].")
 
    if slice_cfg.get("face") is not None:
        unknown = sorted(set(slice_cfg.keys()) - {"face", "orientation", "normal_tolerance"})
        if unknown:
            raise ValueError(
                f"Unknown keys in {field_name}: {unknown}. "
                "Use either face or axis/index/normal, plus orientation/normal_tolerance."
            )
        face = str(slice_cfg.get("face", "")).strip()
        if face.lower() not in BC_FACE_MAP:
            raise ValueError(f"{field_name}.face must be one of {sorted(BC_FACE_MAP.values())}.")
        return {
            "face": BC_FACE_MAP[face.lower()],
            "orientation": orientation,
            "normal_tolerance": normal_tolerance,
        }
 
    required = {"axis", "index", "normal"}
    missing = sorted(key for key in required if slice_cfg.get(key) is None)
    if missing:
        raise ValueError(f"{field_name} requires either face or axis/index/normal; missing {missing}.")
    unknown = sorted(set(slice_cfg.keys()) - {"axis", "index", "normal", "orientation", "normal_tolerance"})
    if unknown:
        raise ValueError(
            f"Unknown keys in {field_name}: {unknown}. "
            "Use either face or axis/index/normal, plus orientation/normal_tolerance."
        )
    axis = str(slice_cfg.get("axis", "")).strip()
    axis_map = {"xi": "Xi", "eta": "Eta", "zeta": "Zeta"}
    if axis.lower() not in axis_map:
        raise ValueError(f"{field_name}.axis must be one of Xi, Eta, Zeta.")
    normal = str(slice_cfg.get("normal", "")).strip()
    if normal.lower() not in BC_FACE_MAP:
        raise ValueError(f"{field_name}.normal must be one of {sorted(BC_FACE_MAP.values())}.")
    normal = BC_FACE_MAP[normal.lower()]
    if normal[1:].lower() != axis.lower():
        raise ValueError(f"{field_name}.normal must use the same axis as {field_name}.axis.")
    try:
        index = int(slice_cfg.get("index"))
    except (TypeError, ValueError):
        raise ValueError(f"{field_name}.index must be an integer.")
    if index < 0:
        raise ValueError(f"{field_name}.index must be non-negative.")
    return {
        "axis": axis_map[axis.lower()],
        "index": index,
        "normal": normal,
        "orientation": orientation,
        "normal_tolerance": normal_tolerance,
    }
 

Here is the call graph for this function:

Here is the caller graph for this function:

generate_square_duct_poiseuille_picslice()

dict picurv_cli.core.generate_square_duct_poiseuille_picslice	(	str	output_path,
		tuple	dims,
		dict	params,
		str	target_grid = None,
		int	target_block = 0,
		str	target_face = None,
		str	script = None,
		str	case_path = None
	)

Generate a dimensional canonical PICSLICE for square-duct Poiseuille flow.

Parameters

[in]	output_path	Path to write.
[in]	dims	PICSLICE dimensions in face storage order (n1, n2).
[in]	params	Normalized generator params.
[in]	target_grid	Optional canonical target PICGRID for grid-aware sampling.
[in]	target_block	Target block index when target_grid is provided.
[in]	target_face	Target inlet face when target_grid is provided.
[in]	script	Optional profile.gen-compatible script override.
[in]	case_path	Current case.yml path used to anchor relative script overrides.

Returns

Summary dictionary.

Definition at line 7616 of file core.py.

                                             case_path: str = None) -> dict:
    """!
    @brief Generate a dimensional canonical PICSLICE for square-duct Poiseuille flow.
    @param[in] output_path Path to write.
    @param[in] dims PICSLICE dimensions in face storage order (n1, n2).
    @param[in] params Normalized generator params.
    @param[in] target_grid Optional canonical target PICGRID for grid-aware sampling.
    @param[in] target_block Target block index when `target_grid` is provided.
    @param[in] target_face Target inlet face when `target_grid` is provided.
    @param[in] script Optional profile.gen-compatible script override.
    @param[in] case_path Current case.yml path used to anchor relative script overrides.
    @return Summary dictionary.
    """
    n1, n2 = tuple(dims)
    profilegen_script = _resolve_generator_script(script, case_path, "profile.gen")
    if not os.path.isfile(profilegen_script):
        raise ValueError(f"profile.gen script not found: {profilegen_script}")
    cmd = [
        sys.executable,
        profilegen_script,
        "square_duct_poiseuille",
        "--output",
        output_path,
        "--dims",
        str(n1),
        str(n2),
        "--bulk-velocity",
        str(float(params["bulk_velocity"])),
        "--n-terms",
        str(int(params["n_terms"])),
    ]
    if target_grid:
        cmd.extend([
            "--target-grid",
            target_grid,
            "--target-block",
            str(int(target_block)),
            f"--target-face={target_face}",
        ])
    result = subprocess.run(cmd, text=True, capture_output=True)
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "").strip()
        raise ValueError(f"profile.gen failed with exit code {result.returncode}. Details:\n{details}")
    try:
        summary = json.loads((result.stdout or "").strip().splitlines()[-1])
    except (IndexError, json.JSONDecodeError) as exc:
        raise ValueError(f"profile.gen did not emit valid JSON summary. Output:\n{result.stdout}") from exc
    summary["dims"] = tuple(summary["dims"])
    return summary
 

Here is the call graph for this function:

Here is the caller graph for this function:

generate_field_slice_picslice()

dict picurv_cli.core.generate_field_slice_picslice	(	str	output_path,
		tuple	expected_dims,
		dict	source,
		str	target_grid,
		str	target_face,
		int	target_block,
		str	case_path
	)

Invoke profile.gen to extract a field_slice PICSLICE artifact.

Parameters

[in]	output_path	Path to write.
[in]	expected_dims	Expected PICSLICE dimensions.
[in]	source	Normalized field_slice source mapping.
[in]	target_grid	Target canonical PICGRID path.
[in]	target_face	Target inlet face token.
[in]	target_block	Target block index.
[in]	case_path	Path to current case.yml for relative source resolution.

Returns

Summary dictionary from profile.gen.

Definition at line 7669 of file core.py.

                                  case_path: str) -> dict:
    """!
    @brief Invoke profile.gen to extract a field_slice PICSLICE artifact.
    @param[in] output_path Path to write.
    @param[in] expected_dims Expected PICSLICE dimensions.
    @param[in] source Normalized field_slice source mapping.
    @param[in] target_grid Target canonical PICGRID path.
    @param[in] target_face Target inlet face token.
    @param[in] target_block Target block index.
    @param[in] case_path Path to current case.yml for relative source resolution.
    @return Summary dictionary from profile.gen.
    """
    case_dir = os.path.dirname(os.path.abspath(case_path)) if case_path else os.getcwd()
    field_file = _resolve_case_relative_path(source["field_file"], case_dir)
    source_grid = _resolve_case_relative_path(source["grid_file"], case_dir)
    velocity_scale = _resolve_field_slice_velocity_scale(source, case_dir)
    profilegen_script = _resolve_generator_script(source.get("script"), case_path, "profile.gen")
    if not os.path.isfile(profilegen_script):
        raise ValueError(f"profile.gen script not found: {profilegen_script}")
    n1, n2 = tuple(expected_dims)
    slice_cfg = source["slice"]
    cmd = [
        sys.executable,
        profilegen_script,
        "field-slice",
        "--output",
        output_path,
        "--field-file",
        field_file,
        "--source-grid",
        source_grid,
        "--target-grid",
        target_grid,
        "--source-block",
        str(int(source.get("source_block", 0))),
        "--target-block",
        str(int(target_block)),
        f"--target-face={target_face}",
        "--orientation",
        slice_cfg["orientation"],
        "--normal-tolerance",
        str(float(slice_cfg["normal_tolerance"])),
        "--velocity-scale",
        str(float(velocity_scale)),
        "--expected-dims",
        str(n1),
        str(n2),
        *petsc_index_arguments(payload_petsc_index_bytes(field_file)),
    ]
    if "face" in slice_cfg:
        cmd.append(f"--slice-face={slice_cfg['face']}")
    else:
        cmd.extend([
            "--slice-axis",
            slice_cfg["axis"],
            "--slice-index",
            str(int(slice_cfg["index"])),
            f"--slice-normal={slice_cfg['normal']}",
        ])
    result = subprocess.run(cmd, text=True, capture_output=True)
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "").strip()
        raise ValueError(f"profile.gen field-slice failed with exit code {result.returncode}. Details:\n{details}")
    try:
        summary = json.loads((result.stdout or "").strip().splitlines()[-1])
    except (IndexError, json.JSONDecodeError) as exc:
        raise ValueError(f"profile.gen field-slice did not emit valid JSON summary. Output:\n{result.stdout}") from exc
    summary["dims"] = tuple(summary["dims"])
    return summary
 

Here is the call graph for this function:

Here is the caller graph for this function:

_resolve_case_relative_path()

str picurv_cli.core._resolve_case_relative_path ( str  path_value, str  case_dir  )

protected

Resolve a path relative to the current case directory.

Parameters

[in]	path_value	Path from case.yml.
[in]	case_dir	Current case directory.

Returns

Absolute path.

Definition at line 7741 of file core.py.

def _resolve_case_relative_path(path_value: str, case_dir: str) -> str:
    """!
    @brief Resolve a path relative to the current case directory.
    @param[in] path_value Path from case.yml.
    @param[in] case_dir Current case directory.
    @return Absolute path.
    """
    if not isinstance(path_value, str) or not path_value.strip():
        raise ValueError("path value must be a non-empty string.")
    workspace_root = find_workspace_root(case_dir)
    if workspace_root:
        if os.path.isabs(path_value):
            raise ValueError(
                f"absolute path {path_value!r} is not allowed in workspace case configuration; "
                "use 'picurv inputs import --mode reference' for an explicit external reference."
            )
        resolved = os.path.abspath(os.path.join(workspace_root, path_value))
        if os.path.commonpath([workspace_root, resolved]) != os.path.abspath(workspace_root):
            raise ValueError(f"path {path_value!r} escapes the workspace.")
        if resolved.endswith(".reference.yml") and os.path.isfile(resolved):
            pointer = read_yaml_file(resolved)
            external = pointer.get("picurv_external_reference") if isinstance(pointer, dict) else None
            if not isinstance(external, str) or not os.path.isabs(external):
                raise ValueError(f"Invalid external-reference descriptor: {resolved}")
            if not os.path.isfile(external):
                raise ValueError(f"Registered external input is unavailable: {external}")
            return external
        return resolved
    if os.path.isabs(path_value):
        return os.path.abspath(path_value)
    return os.path.abspath(os.path.join(case_dir, path_value))
 

Here is the call graph for this function:

Here is the caller graph for this function:

_resolve_field_slice_velocity_scale()

float picurv_cli.core._resolve_field_slice_velocity_scale ( dict  source, str  case_dir  )

protected

Resolve field_slice dimensional velocity scale.

Parameters

[in]	source	Normalized field_slice source mapping.
[in]	case_dir	Current case directory.

Returns

Positive velocity scale.

Definition at line 7773 of file core.py.

def _resolve_field_slice_velocity_scale(source: dict, case_dir: str) -> float:
    """!
    @brief Resolve field_slice dimensional velocity scale.
    @param[in] source Normalized field_slice source mapping.
    @param[in] case_dir Current case directory.
    @return Positive velocity scale.
    """
    if source.get("velocity_scale") is not None:
        return float(source["velocity_scale"])
    source_case = _resolve_case_relative_path(source["source_case"], case_dir)
    source_case_cfg = read_yaml_file(source_case)
    try:
        velocity_scale = _to_float(
            source_case_cfg.get("properties", {}).get("scaling", {}).get("velocity_ref"),
            "source_case.properties.scaling.velocity_ref",
        )
    except AttributeError as exc:
        raise ValueError("source_case must contain properties.scaling.velocity_ref.") from exc
    if velocity_scale <= 0.0:
        raise ValueError("source_case.properties.scaling.velocity_ref must be positive.")
    return velocity_scale
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_target_grid_for_field_slice()

str picurv_cli.core.resolve_target_grid_for_field_slice	(	dict	case_cfg,
		str	case_path,
		str	run_dir
	)

Resolve the target canonical PICGRID path needed for field_slice normals.

Parameters

[in]	case_cfg	Parsed current case config.
[in]	case_path	Current case.yml path.
[in]	run_dir	Current run/precompute directory.

Returns

Absolute target PICGRID path.

Definition at line 7795 of file core.py.

def resolve_target_grid_for_field_slice(case_cfg: dict, case_path: str, run_dir: str) -> str:
    """!
    @brief Resolve the target canonical PICGRID path needed for field_slice normals.
    @param[in] case_cfg Parsed current case config.
    @param[in] case_path Current case.yml path.
    @param[in] run_dir Current run/precompute directory.
    @return Absolute target PICGRID path.
    """
    grid_cfg = case_cfg.get("grid", {}) or {}
    grid_mode = grid_cfg.get("mode")
    case_dir = os.path.dirname(os.path.abspath(case_path)) if case_path else os.getcwd()
    if grid_mode == "file":
        source_grid = grid_cfg.get("source_file")
        if not isinstance(source_grid, str) or not source_grid.strip():
            raise ValueError("grid.source_file is required for field_slice target-grid normals.")
        source_grid = _resolve_case_relative_path(source_grid, case_dir)
        return source_grid
    if grid_mode == "grid_gen":
        candidate = os.path.abspath(os.path.join(run_dir, "inputs", "grid", "grid.generated.picgrid"))
        if os.path.isfile(candidate):
            return candidate
        staged = os.path.join(run_dir, "inputs", "grid", "grid.run")
        if os.path.isfile(staged):
            return staged
        raise ValueError("field_slice requires the generated target PICGRID to exist before profile extraction.")
    raise ValueError(
        f"field_slice requires grid.mode 'file' or 'grid_gen' for target-grid normals; got '{grid_mode}'."
    )
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_target_grid_for_generated_profile()

str picurv_cli.core.resolve_target_grid_for_generated_profile	(	dict	case_cfg,
		str	case_path,
		str	run_dir
	)

Resolve the target canonical PICGRID for generated profile sampling.

The simulator builds a programmatic_c grid itself, so no grid file exists here. The profile is sampled instead on the bridge PICGRID that a Python initial condition already uses, written with the solver's own node formula. Without a grid the generator could only sample uniform logical points and normalize to the continuous-area mean, which delivered about 2/n too much flux on n cells across (programmatic-inlet-flux-2026-09-18).

Parameters

[in]	case_cfg	Parsed current case config.
[in]	case_path	Current case.yml path.
[in]	run_dir	Current run/precompute directory.

Returns

Absolute target PICGRID path.

Definition at line 7824 of file core.py.

def resolve_target_grid_for_generated_profile(case_cfg: dict, case_path: str, run_dir: str) -> str:
    """!
    @brief Resolve the target canonical PICGRID for generated profile sampling.
    @details The simulator builds a programmatic_c grid itself, so no grid file exists
             here. The profile is sampled instead on the bridge PICGRID that a Python
             initial condition already uses, written with the solver's own node formula.
             Without a grid the generator could only sample uniform logical points and
             normalize to the continuous-area mean, which delivered about 2/n too much
             flux on n cells across (programmatic-inlet-flux-2026-09-18).
    @param[in] case_cfg Parsed current case config.
    @param[in] case_path Current case.yml path.
    @param[in] run_dir Current run/precompute directory.
    @return Absolute target PICGRID path.
    """
    grid_cfg = case_cfg.get("grid", {}) or {}
    if grid_cfg.get("mode") == "programmatic_c":
        bridge = os.path.abspath(os.path.join(run_dir, "inputs", "grid", "grid.run"))
        if not os.path.isfile(bridge):
            generate_picgrid_from_programmatic_settings(
                grid_cfg.get("programmatic_settings", {}), bridge,
                input_reference_scale(("case", "grid", "programmatic_settings", "xMins"),
                                      resolve_reference_scales(case_cfg)),
            )
        return bridge
    return resolve_target_grid_for_field_slice(case_cfg, case_path, run_dir)
 

Here is the call graph for this function:

Here is the caller graph for this function:

write_profile_info()

str picurv_cli.core.write_profile_info	(	str	config_dir,
		list	summaries
	)

Write a profile.info summary for generated inlet profiles.

Parameters

[in]	config_dir	Run/precompute config directory.
[in]	summaries	Generated profile summaries.

Returns

Path to profile.info.

Definition at line 7850 of file core.py.

def write_profile_info(config_dir: str, summaries: list) -> str:
    """!
    @brief Write a profile.info summary for generated inlet profiles.
    @param[in] config_dir Run/precompute config directory.
    @param[in] summaries Generated profile summaries.
    @return Path to profile.info.
    """
    info_path = os.path.join(config_dir, "profile.info")
    os.makedirs(config_dir, exist_ok=True)
    with open(info_path, "w") as fout:
        fout.write("# PICurv generated profile summary\n")
        fout.write(f"profile_count = {len(summaries)}\n\n")
        for idx, summary in enumerate(summaries):
            dims = summary.get("dims", (0, 0))
            fout.write(f"[profile_{idx}]\n")
            fout.write(f"generator = {summary.get('generator')}\n")
            fout.write(f"block = {summary.get('block')}\n")
            fout.write(f"face = {summary.get('face')}\n")
            fout.write(f"dimensions = {dims[0]} {dims[1]}\n")
            if summary.get("bulk_velocity") is not None:
                fout.write(f"bulk_velocity = {summary.get('bulk_velocity'):.16e}\n")
            if summary.get("n_terms") is not None:
                fout.write(f"n_terms = {summary.get('n_terms')}\n")
            fout.write(f"mean_speed = {summary.get('mean_speed'):.16e}\n")
            if "area_mean_speed" in summary:
                fout.write(f"area_mean_speed = {summary.get('area_mean_speed'):.16e}\n")
            if "discrete_mean_speed" in summary:
                fout.write(f"discrete_mean_speed = {summary.get('discrete_mean_speed'):.16e}\n")
            fout.write(f"min_speed = {summary.get('min_speed'):.16e}\n")
            fout.write(f"max_speed = {summary.get('max_speed'):.16e}\n")
            if summary.get("umax_over_ubulk") is not None:
                fout.write(f"umax_over_ubulk = {summary.get('umax_over_ubulk'):.16e}\n")
            for key in (
                "normalization",
                "sampling",
                "area_weighted_mean_before_normalization",
                "area_weighted_mean_after_normalization",
                "total_inlet_area",
                "face_area_min",
                "face_area_max",
                "source_field",
                "source_grid",
                "target_grid",
                "source_block",
                "target_block",
                "target_face",
                "source_slice",
                "orientation",
                "normal_tolerance",
                "normal_dot",
                "velocity_scale",
            ):
                if key in summary:
                    fout.write(f"{key} = {summary.get(key)}\n")
            fout.write(f"output_file = {summary.get('path')}\n\n")
    return info_path
 
#: Generator flags whose values are drawn from a closed choice set. Checking them where
#: the case is validated turns a mid-run subprocess failure into a startup error.

Here is the caller graph for this function:

validate_grid_generator_cli_args()

list picurv_cli.core.validate_grid_generator_cli_args	(		cli_args,
		str	case_path
	)

Check closed-choice values inside the generator's opaque token list.

cli_args is passed through to grid.gen untouched, so a misspelled geometry selector there is only discovered when the subprocess exits nonzero partway into a run. The generator remains the authority; this reports the same set earlier, and stays silent on anything it does not recognize.

Parameters

[in]	cli_args	Raw token list from grid.generator.cli_args.
[in]	case_path	Case file path for diagnostics.

Returns

List of error strings.

Definition at line 7925 of file core.py.

def validate_grid_generator_cli_args(cli_args, case_path: str) -> list:
    """!
    @brief Check closed-choice values inside the generator's opaque token list.
    @details `cli_args` is passed through to grid.gen untouched, so a misspelled geometry
             selector there is only discovered when the subprocess exits nonzero partway
             into a run. The generator remains the authority; this reports the same set
             earlier, and stays silent on anything it does not recognize.
    @param[in] cli_args Raw token list from grid.generator.cli_args.
    @param[in] case_path Case file path for diagnostics.
    @return List of error strings.
    """
    if not isinstance(cli_args, list):
        return []
    tokens = [str(token) for token in cli_args]
    errors = []
    for index, token in enumerate(tokens):
        values = []
        for follower in tokens[index + 1:]:
            if follower.startswith("--"):
                break
            values.append(follower)
        if token in GRID_GENERATOR_CHOICE_FLAGS:
            allowed = GRID_GENERATOR_CHOICE_FLAGS[token]
            for value in values[:1]:
                if value not in allowed:
                    errors.append(
                        f"  {case_path}: grid.generator.cli_args {token} must be one of "
                        f"{list(allowed)} (got '{value}')."
                    )
        elif token in GRID_GENERATOR_SPEC_FLAGS:
            allowed = GRID_GENERATOR_SPEC_FLAGS[token]
            for value in values:
                kind = value.split(":", 1)[0]
                if kind not in allowed:
                    errors.append(
                        f"  {case_path}: grid.generator.cli_args {token} entry '{value}' "
                        f"names '{kind}', which is not one of {list(allowed)}."
                    )
    return errors
 
 

Here is the caller graph for this function:

run_grid_generator()

str picurv_cli.core.run_grid_generator	(	str	case_path,
		str	run_dir,
		dict	grid_cfg,
		dict	case_cfg = None
	)

Runs generators/grid.gen to produce a PICGRID file for this run.

Parameters

[in]	case_path	Path to case.yml (used for relative path resolution).
[in]	run_dir	Run directory path.
[in]	grid_cfg	The grid config section from case.yml.
[in]	case_cfg	Parsed case configuration, when available. Its reference scales are handed to the generator so the quality report can carry solver and wall units. Reporting only: the generator never scales coordinates, which validate_and_nondimensionalize_picgrid does once for every grid regardless of origin.

Returns

Absolute path to generated dimensional PICGRID file.

Exceptions

ValueError

on invalid config or generator failure.

Definition at line 7966 of file core.py.

                       case_cfg: dict = None) -> str:
    """!
    @brief Runs generators/grid.gen to produce a PICGRID file for this run.
    @param[in] case_path Path to case.yml (used for relative path resolution).
    @param[in] run_dir Run directory path.
    @param[in] grid_cfg The grid config section from case.yml.
    @param[in] case_cfg Parsed case configuration, when available. Its reference scales
                        are handed to the generator so the quality report can carry
                        solver and wall units. Reporting only: the generator never scales
                        coordinates, which validate_and_nondimensionalize_picgrid does
                        once for every grid regardless of origin.
    @return Absolute path to generated dimensional PICGRID file.
    @throws ValueError on invalid config or generator failure.
    """
    generator = grid_cfg.get("generator", {})
    if not isinstance(generator, dict):
        raise ValueError("grid.generator must be a mapping when grid.mode is 'grid_gen'.")
 
    case_dir = os.path.dirname(os.path.abspath(case_path))
    gridgen_script = generator.get("script", os.path.join(GENERATORS_PATH, "grid.gen"))
    if generator.get("script"):
        gridgen_script = _resolve_case_relative_path(gridgen_script, case_dir)
    else:
        gridgen_script = os.path.abspath(gridgen_script)
    if not os.path.isfile(gridgen_script):
        raise ValueError(f"grid.gen script not found: {gridgen_script}")
 
    config_file = generator.get("config_file")
    if not config_file:
        raise ValueError("grid.generator.config_file is required when grid.mode is 'grid_gen'.")
    config_file = _resolve_case_relative_path(config_file, case_dir)
    if not os.path.isfile(config_file):
        raise ValueError(f"grid.generator.config_file not found: {config_file}")
 
    output_file = os.path.abspath(os.path.join(run_dir, "inputs", "grid", "grid.generated.picgrid"))
    os.makedirs(os.path.dirname(output_file), exist_ok=True)
 
    grid_type = generator.get("grid_type")
    cli_args = generator.get("cli_args", [])
    if cli_args is None:
        cli_args = []
    if not isinstance(cli_args, list):
        raise ValueError("grid.generator.cli_args must be a list of CLI tokens.")
 
    cmd = [sys.executable, gridgen_script, "-c", config_file]
    if grid_type:
        cmd.append(str(grid_type))
    cmd.extend([str(token) for token in cli_args])
    cmd.extend(["--output", output_file])
 
    # Destinations are PICurv's, not the user's. Inspection material is produced
    # unconditionally so a published asset is always something the user can look at,
    # rather than only when a configuration file happened to name an output path.
    vts_file = os.path.abspath(
        os.path.join(run_dir, "output", "visualization", "precompute", "grid.vts")
    )
    os.makedirs(os.path.dirname(vts_file), exist_ok=True)
    cmd.extend(["--vts", vts_file])
 
    stats_file = os.path.abspath(
        os.path.join(run_dir, "output", "analysis", "metrics", "grid.info")
    )
    os.makedirs(os.path.dirname(stats_file), exist_ok=True)
    cmd.extend(["--stats-file", stats_file])
 
    # The case already knows these; the generator would otherwise report a grid in metres
    # with no way to say what it becomes downstream. Resolution is best-effort: a case
    # that omits them still gets its grid, just without the derived-unit sections.
    if case_cfg:
        try:
            scaling = resolve_fluid_scaling(case_cfg)
        except (KeyError, ValueError, TypeError):
            scaling = None
        if scaling:
            cmd.extend(["--length-ref", repr(scaling["length_ref"]),
                        "--velocity-ref", repr(scaling["velocity_ref"]),
                        "--nu", repr(scaling["physical_kinematic_viscosity"])])
 
    print(f"[INFO] Grid generator command: {' '.join(cmd)}")
    result = subprocess.run(cmd, cwd=case_dir, text=True, capture_output=True)
    if result.returncode != 0:
        stderr = (result.stderr or "").strip()
        stdout = (result.stdout or "").strip()
        details = stderr if stderr else stdout
        raise ValueError(
            f"grid.gen failed with exit code {result.returncode}. Details:\n{details}"
        )
    if result.stdout:
        print(result.stdout.strip())
    if result.stderr:
        print(result.stderr.strip())
 
    if not os.path.isfile(output_file):
        raise ValueError(f"grid.gen did not produce expected output file: {output_file}")
 
    return output_file
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_normalize_prescribed_flow_source()

dict picurv_cli.core._normalize_prescribed_flow_source (   source, str  field_name  )

protected

Validate the structured source block for prescribed_flow BCs.

Parameters

[in]	source	Source mapping from case.yml.
[in]	field_name	Human-readable YAML path for diagnostics.

Returns

Normalized source mapping.

Exceptions

ValueError

on invalid source contract.

Definition at line 8156 of file core.py.

def _normalize_prescribed_flow_source(source, field_name: str) -> dict:
    """!
    @brief Validate the structured source block for prescribed_flow BCs.
    @param[in] source Source mapping from case.yml.
    @param[in] field_name Human-readable YAML path for diagnostics.
    @return Normalized source mapping.
    @throws ValueError on invalid source contract.
    """
    if not isinstance(source, dict):
        raise ValueError(f"{field_name} must be a mapping with type: file, generated, or field_slice.")
    source_type = str(source.get("type", "")).strip().lower()
    if source_type == "file":
        path = source.get("path")
        if not isinstance(path, str) or not path.strip():
            raise ValueError(f"{field_name}.path must be a non-empty file path.")
        unknown = sorted(set(source.keys()) - {"type", "path"})
        if unknown:
            raise ValueError(f"Unknown keys in {field_name}: {unknown}. Allowed: ['path', 'type'].")
        return {"type": "file", "path": path.strip()}
 
    if source_type == "generated":
        generator = str(source.get("generator", "")).strip().lower()
        if generator not in GENERATED_PROFILE_GENERATORS:
            raise ValueError(
                f"{field_name}.generator must be one of {sorted(GENERATED_PROFILE_GENERATORS)} "
                f"(got '{source.get('generator')}')."
            )
        if "output_file" in source:
            raise ValueError(retired_destination_message(field_name, "output_file"))
        unknown = sorted(set(source.keys()) - {"type", "generator", "script", "params"})
        if unknown:
            raise ValueError(
                f"Unknown keys in {field_name}: {unknown}. "
                "Allowed: ['generator', 'params', 'script', 'type']."
            )
        normalized = {
            "type": "generated",
            "generator": generator,
            "params": _normalize_square_duct_poiseuille_params(source.get("params", {}), field_name),
        }
        script = source.get("script")
        if script is not None:
            if not isinstance(script, str) or not script.strip():
                raise ValueError(f"{field_name}.script must be a non-empty path when provided.")
            normalized["script"] = script.strip()
        return normalized
 
    if source_type == "field_slice":
        return _normalize_field_slice_source(source, field_name)
 
    raise ValueError(f"{field_name}.type must be 'file', 'generated', or 'field_slice'.")
 

Here is the call graph for this function:

Here is the caller graph for this function:

_bc_profile_expected_dims()

tuple picurv_cli.core._bc_profile_expected_dims ( str  face, tuple  block_dims  )

protected

Return expected PICSLICE dimensions for a face and block node dimensions.

Parameters

[in]	face	Canonical BC face token.
[in]	block_dims	(IM, JM, KM) node counts.

Returns

(n1, n2) dimensions in profile storage order.

Definition at line 8208 of file core.py.

def _bc_profile_expected_dims(face: str, block_dims: tuple) -> tuple:
    """!
    @brief Return expected PICSLICE dimensions for a face and block node dimensions.
    @param[in] face Canonical BC face token.
    @param[in] block_dims (IM, JM, KM) node counts.
    @return (n1, n2) dimensions in profile storage order.
    """
    im, jm, km = block_dims
    if min(im, jm, km) < 2:
        raise ValueError(
            f"Block dimensions {block_dims} are too small for an inlet profile; each axis needs at least 2 nodes."
        )
    if face in {"-Xi", "+Xi"}:
        return (km - 1, jm - 1)
    if face in {"-Eta", "+Eta"}:
        return (km - 1, im - 1)
    if face in {"-Zeta", "+Zeta"}:
        return (jm - 1, im - 1)
    raise ValueError(f"Unsupported face '{face}' for prescribed_flow profile dimensions.")
 

Here is the caller graph for this function:

resolve_grid_block_dimensions_for_profiles()

list picurv_cli.core.resolve_grid_block_dimensions_for_profiles	(	dict	case_cfg,
		str	case_path,
		str	run_dir = None
	)

Resolve per-block node dimensions for prescribed inlet profile validation.

Parameters

[in]	case_cfg	Parsed case.yml configuration.
[in]	case_path	Path to case.yml for relative path resolution.
[in]	run_dir	Current run directory, used for optional generated grid outputs.

Returns

List of (IM, JM, KM) node-count tuples.

Exceptions

ValueError

when dimensions cannot be resolved.

Definition at line 8228 of file core.py.

def resolve_grid_block_dimensions_for_profiles(case_cfg: dict, case_path: str, run_dir: str = None) -> list:
    """!
    @brief Resolve per-block node dimensions for prescribed inlet profile validation.
    @param[in] case_cfg Parsed case.yml configuration.
    @param[in] case_path Path to case.yml for relative path resolution.
    @param[in] run_dir Current run directory, used for optional generated grid outputs.
    @return List of (IM, JM, KM) node-count tuples.
    @throws ValueError when dimensions cannot be resolved.
    """
    num_blocks = int(case_cfg.get('models', {}).get('domain', {}).get('blocks', 1))
    grid_cfg = case_cfg.get("grid", {})
    grid_mode = grid_cfg.get("mode")
    case_dir = os.path.dirname(os.path.abspath(case_path)) if case_path else os.getcwd()
 
    if grid_mode == "programmatic_c":
        settings = grid_cfg.get("programmatic_settings", {})
        dims_by_axis = []
        for key in ("im", "jm", "km"):
            raw = settings.get(key)
            if raw is None:
                raise ValueError(f"grid.programmatic_settings.{key} is required for prescribed_flow profiles.")
            if isinstance(raw, list):
                if len(raw) != num_blocks:
                    raise ValueError(
                        f"grid.programmatic_settings.{key} has {len(raw)} entries, expected {num_blocks} blocks."
                    )
                values = raw
            else:
                values = [raw] * num_blocks
            try:
                values = [int(v) + 1 for v in values]
            except (TypeError, ValueError):
                raise ValueError(f"grid.programmatic_settings.{key} values must be positive integer cell counts.")
            if any(v <= 1 for v in values):
                raise ValueError(f"grid.programmatic_settings.{key} values must be positive integer cell counts.")
            dims_by_axis.append(values)
        return list(zip(dims_by_axis[0], dims_by_axis[1], dims_by_axis[2]))
 
    if grid_mode == "file":
        source_grid = grid_cfg.get("source_file")
        if not isinstance(source_grid, str) or not source_grid.strip():
            raise ValueError("grid.source_file is required for file-grid prescribed_flow profile validation.")
        source_grid = _resolve_case_relative_path(source_grid, case_dir)
        return read_picgrid_header_dimensions(source_grid, expected_nblk=num_blocks)
 
    if grid_mode == "grid_gen":
        candidates = []
        if run_dir:
            candidates.append(os.path.join(run_dir, "inputs", "grid", "grid.generated.picgrid"))
            candidates.append(os.path.join(run_dir, "inputs", "grid", "grid.run"))
        for candidate in candidates:
            if os.path.isfile(candidate):
                return read_picgrid_header_dimensions(candidate, expected_nblk=num_blocks)
        raise ValueError(
            "prescribed_flow profile dimension validation for grid.mode='grid_gen' requires an existing generated "
            "PICGRID output. Run or stage the grid first, or use grid.mode='file' with the generated .picgrid."
        )
 
    raise ValueError(f"Unsupported grid.mode '{grid_mode}' for prescribed_flow profile validation.")
 

Here is the call graph for this function:

Here is the caller graph for this function:

materialize_generated_prescribed_flow_profiles()

list picurv_cli.core.materialize_generated_prescribed_flow_profiles	(	str	run_dir,
		dict	case_cfg,
		str	case_path,
		list	profile_grid_dims = None
	)

Generate dimensional PICSLICE artifacts for generated/field_slice prescribed_flow sources.

Parameters

[in]	run_dir	Run/precompute directory root.
[in]	case_cfg	Parsed case.yml.
[in]	case_path	Path to case.yml for relative grid/source resolution.
[in]	profile_grid_dims	Optional pre-resolved block node dimensions.

Returns

List of generated profile summaries.

Definition at line 8288 of file core.py.

                                                   profile_grid_dims: list = None) -> list:
    """!
    @brief Generate dimensional PICSLICE artifacts for generated/field_slice prescribed_flow sources.
    @param[in] run_dir Run/precompute directory root.
    @param[in] case_cfg Parsed case.yml.
    @param[in] case_path Path to case.yml for relative grid/source resolution.
    @param[in] profile_grid_dims Optional pre-resolved block node dimensions.
    @return List of generated profile summaries.
    """
    prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    if not any(
        bc.get("handler") == "prescribed_flow"
        and ((bc.get("params") or {}).get("source") or {}).get("type") in PRESCRIBED_FLOW_SOURCE_TYPES[1:]
        for block in prepared_blocks for bc in block
    ):
        return []
    if profile_grid_dims is None:
        profile_grid_dims = resolve_grid_block_dimensions_for_profiles(case_cfg, case_path, run_dir)
 
    profile_dir = os.path.join(run_dir, "inputs", "inlet_profiles")
    target_grid = None
    generated_target_grid = None
    summaries = []
    for block_idx, block in enumerate(prepared_blocks):
        for bc in block:
            if bc.get("handler") != "prescribed_flow":
                continue
            source = (bc.get("params") or {}).get("source", {})
            if source.get("type") not in PRESCRIBED_FLOW_SOURCE_TYPES[1:]:
                continue
            face = bc["face"]
            dims = _bc_profile_expected_dims(face, profile_grid_dims[block_idx])
            face_token = _face_artifact_token(face)
            suffix = "generated" if source.get("type") == "generated" else "sliced"
            output_path = os.path.join(
                profile_dir,
                f"inlet_profile_block{block_idx}_{face_token}.{suffix}.dimensional.picslice",
            )
            if source.get("type") == "generated" and source["generator"] == "square_duct_poiseuille":
                if generated_target_grid is None:
                    generated_target_grid = resolve_target_grid_for_generated_profile(case_cfg, case_path, run_dir)
                summary = generate_square_duct_poiseuille_picslice(
                    output_path,
                    dims,
                    source["params"],
                    target_grid=generated_target_grid,
                    target_block=block_idx,
                    target_face=face,
                    script=source.get("script"),
                    case_path=case_path,
                )
            elif source.get("type") == "generated":
                raise ValueError(f"Unsupported generated profile generator '{source['generator']}'.")
            else:
                if target_grid is None:
                    target_grid = resolve_target_grid_for_field_slice(case_cfg, case_path, run_dir)
                summary = generate_field_slice_picslice(
                    output_path,
                    dims,
                    source,
                    target_grid,
                    face,
                    block_idx,
                    case_path,
                )
            summary.update({"block": block_idx, "face": face})
            summaries.append(summary)
            print(
                f"[SUCCESS] Materialized prescribed_flow profile for block {block_idx}, face {face}: "
                f"{os.path.relpath(output_path)} dims={summary['dims']}"
            )
 
    if summaries:
        info_path = write_profile_info(profile_dir, summaries)
        print(f"[SUCCESS] Wrote generated profile summary: {os.path.relpath(info_path)}")
    return summaries
 

Here is the call graph for this function:

_to_float()

float picurv_cli.core._to_float (   value, str  field_name  )

protected

Convert a YAML scalar to float with a clear error message.

Parameters

[in]	value	Argument passed to _to_float().
[in]	field_name	Argument passed to _to_float().

Returns

Value returned by _to_float().

Definition at line 8366 of file core.py.

def _to_float(value, field_name: str) -> float:
    """!
    @brief Convert a YAML scalar to float with a clear error message.
    @param[in] value Argument passed to `_to_float()`.
    @param[in] field_name Argument passed to `_to_float()`.
    @return Value returned by `_to_float()`.
    """
    try:
        return float(value)
    except (TypeError, ValueError):
        raise ValueError(f"'{field_name}' must be numeric (got {value!r}).")
 
 

Here is the caller graph for this function:

_to_finite_float()

float picurv_cli.core._to_finite_float (   value, str  field_name  )

protected

Convert a non-boolean YAML scalar to a finite float.

Parameters

[in]	value	Raw YAML scalar.
[in]	field_name	User-facing configuration path.

Returns

Finite floating-point value.

Definition at line 8379 of file core.py.

def _to_finite_float(value, field_name: str) -> float:
    """!
    @brief Convert a non-boolean YAML scalar to a finite float.
    @param[in] value Raw YAML scalar.
    @param[in] field_name User-facing configuration path.
    @return Finite floating-point value.
    """
    if isinstance(value, bool):
        raise ValueError(f"'{field_name}' must be numeric, not boolean.")
    parsed = _to_float(value, field_name)
    if not math.isfinite(parsed):
        raise ValueError(f"'{field_name}' must be finite (got {value!r}).")
    return parsed
 

Here is the call graph for this function:

Here is the caller graph for this function:

_to_bool()

bool picurv_cli.core._to_bool (   value, str  field_name  )

protected

Convert a YAML scalar/string to bool with a clear error message.

Parameters

[in]	value	Argument passed to _to_bool().
[in]	field_name	Argument passed to _to_bool().

Returns

Value returned by _to_bool().

Definition at line 8393 of file core.py.

def _to_bool(value, field_name: str) -> bool:
    """!
    @brief Convert a YAML scalar/string to bool with a clear error message.
    @param[in] value Argument passed to `_to_bool()`.
    @param[in] field_name Argument passed to `_to_bool()`.
    @return Value returned by `_to_bool()`.
    """
    if isinstance(value, bool):
        return value
    if isinstance(value, str):
        raw = value.strip().lower()
        if raw in {"true", "1", "yes"}:
            return True
        if raw in {"false", "0", "no"}:
            return False
    raise ValueError(f"'{field_name}' must be boolean (got {value!r}).")
 

Here is the caller graph for this function:

normalize_boundary_conditions_layout()

picurv_cli.core.normalize_boundary_conditions_layout	(		all_blocks_bcs,
		int	num_blocks
	)

Normalize boundary_conditions to list-of-lists form and validate block count.

Parameters

[in]	all_blocks_bcs	Argument passed to normalize_boundary_conditions_layout().
[in]	num_blocks	Argument passed to normalize_boundary_conditions_layout().

Returns

Value returned by normalize_boundary_conditions_layout().

Definition at line 8410 of file core.py.

def normalize_boundary_conditions_layout(all_blocks_bcs, num_blocks: int):
    """!
    @brief Normalize boundary_conditions to list-of-lists form and validate block count.
    @param[in] all_blocks_bcs Argument passed to `normalize_boundary_conditions_layout()`.
    @param[in] num_blocks Argument passed to `normalize_boundary_conditions_layout()`.
    @return Value returned by `normalize_boundary_conditions_layout()`.
    """
    if not all_blocks_bcs:
        raise ValueError("The 'boundary_conditions' section in case.yml is empty.")
 
    is_simple_list = isinstance(all_blocks_bcs[0], dict)
    if num_blocks == 1 and is_simple_list:
        all_blocks_bcs = [all_blocks_bcs]
    elif is_simple_list and num_blocks > 1:
        raise ValueError(
            f"case.yml declares {num_blocks} blocks but boundary_conditions is a single face-list. "
            "Use a list-of-lists, one inner list per block."
        )
 
    if len(all_blocks_bcs) != num_blocks:
        raise ValueError(
            f"Mismatch: case.yml declares {num_blocks} block(s) but found {len(all_blocks_bcs)} BC definitions."
        )
    return all_blocks_bcs
 

Here is the caller graph for this function:

_les_periodic_axes()

set picurv_cli.core._les_periodic_axes ( dict  case_cfg )

protected

Reports which logical axes a case declares periodic on both faces.

Parameters

[in]

case_cfg

Parsed case.yml mapping.

Returns

Set of axis letters drawn from {'i', 'j', 'k'}.

Definition at line 8435 of file core.py.

def _les_periodic_axes(case_cfg: dict) -> set:
    """!
    @brief Reports which logical axes a case declares periodic on both faces.
    @param[in] case_cfg Parsed case.yml mapping.
    @return Set of axis letters drawn from {'i', 'j', 'k'}.
    """
    axis_faces = {"i": ("-Xi", "+Xi"), "j": ("-Eta", "+Eta"), "k": ("-Zeta", "+Zeta")}
    declared = {}
    entries = case_cfg.get("boundary_conditions") or []
    if entries and isinstance(entries[0], list):
        entries = entries[0]
    for entry in entries:
        if isinstance(entry, dict):
            declared[str(entry.get("face"))] = str(entry.get("type", "")).upper()
    return {
        axis for axis, faces in axis_faces.items()
        if all(declared.get(face) == "PERIODIC" for face in faces)
    }
 
 
#: Refused whenever a case carries a RANS block. The k-omega transport update was never
#: written and its fields were never allocated, so the closure was removed on 2026-09-22
#: and the subsystem returned to `planned`; src/guide.md records the hooks that went with
#: it. The message names the status rather than leaving a silently ignored block.

Here is the caller graph for this function:

validate_wall_model_pairing()

picurv_cli.core.validate_wall_model_pairing	(	dict	case_cfg,
			les_cfg,
			wall_cfg,
		str	case_path,
		list	errors,
		list	warnings
	)

Rejects wall-model selections that no turbulence treatment can support.

A wall model replaces the near-wall flow with an analytic profile so that the boundary layer need not be resolved. That only means something if the unresolved motions are modelled somewhere. Three combinations cannot be, and each fails here rather than after the mesh is built.

Parameters

case_cfg	Parsed case configuration, read for the Reynolds number.
les_cfg	models.physics.turbulence.les, or None.
wall_cfg	models.physics.turbulence.wall_function, or None.
case_path	Case path, for message prefixes.
errors	Collected blocking messages, appended to.
warnings	Collected advisory messages, appended to.

Definition at line 8467 of file core.py.

                                case_path: str, errors: list, warnings: list):
    """!
    @brief Rejects wall-model selections that no turbulence treatment can support.
 
    A wall model replaces the near-wall flow with an analytic profile so that the
    boundary layer need not be resolved. That only means something if the unresolved
    motions are modelled somewhere. Three combinations cannot be, and each fails here
    rather than after the mesh is built.
 
    @param case_cfg Parsed case configuration, read for the Reynolds number.
    @param les_cfg  `models.physics.turbulence.les`, or None.
    @param wall_cfg `models.physics.turbulence.wall_function`, or None.
    @param case_path Case path, for message prefixes.
    @param errors   Collected blocking messages, appended to.
    @param warnings Collected advisory messages, appended to.
    """
    if not isinstance(wall_cfg, dict):
        return
    if not bool(wall_cfg.get('enabled', False)):
        return
 
    try:
        model = normalize_wall_function_model(wall_cfg.get('model', 'log_law'))
    except ValueError:
        return  # The selector's own validation already reported this.
 
    les_on = isinstance(les_cfg, dict) and bool(les_cfg.get('enabled', False)) \
        and str(les_cfg.get('model', 'dynamic_smagorinsky')).strip().lower() != 'none'
    # A wall model with nothing to sit on. The convective scheme here is QUICK, whose
    # dissipation is linear and upwind-biased; it is not a limiter-based scheme whose
    # truncation error stands in for a subgrid stress, so there is no implicit LES to
    # appeal to.
    if not les_on:
        errors.append(
            f"  {case_path}: models.physics.turbulence.wall_function is enabled with no "
            "turbulence model. A wall model supplies the stress of a boundary layer it "
            "does not resolve, which needs the unresolved motions modelled somewhere. "
            "This solver has no implicit-LES scheme to supply that - its convection is "
            "QUICK, whose numerical dissipation is not a subgrid model - so enable "
            "models.physics.turbulence.les, or resolve the wall and disable the wall "
            "function.")
 
    # A wall law describes a turbulent boundary layer. Below transition there is no
    # inertial region for it to stand on, and it would impose a profile the flow does not
    # have. The threshold is deliberately far below any transitional value, so that it
    # only catches cases that are unambiguously laminar.
    reynolds = _case_reynolds_number(case_cfg)
    if reynolds is not None and reynolds < 1000.0:
        errors.append(
            f"  {case_path}: models.physics.turbulence.wall_function is enabled at "
            f"Reynolds number {reynolds:g}, which is laminar. The log law and the "
            "Werner-Wengle power law both describe a turbulent boundary layer; at this "
            "Reynolds number there is no inertial region for either to represent, and "
            "the model would impose a profile the flow does not have. Resolve the wall "
            "instead.")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_case_reynolds_number()

picurv_cli.core._case_reynolds_number ( dict  case_cfg )

protected

Reynolds number implied by a case's scaling and fluid properties.

Parameters

case_cfg

Parsed case configuration.

Returns

The Reynolds number, or None when the inputs are absent or unusable.

Definition at line 8525 of file core.py.

def _case_reynolds_number(case_cfg: dict):
    """!
    @brief Reynolds number implied by a case's scaling and fluid properties.
    @param case_cfg Parsed case configuration.
    @return The Reynolds number, or None when the inputs are absent or unusable.
    """
    try:
        props = case_cfg.get('properties', {}) or {}
        scaling = props.get('scaling', {}) or {}
        fluid = props.get('fluid', {}) or {}
        density = float(fluid.get('density'))
        viscosity = float(fluid.get('viscosity'))
        length_ref = float(scaling.get('length_ref'))
        velocity_ref = float(scaling.get('velocity_ref'))
    except (TypeError, ValueError):
        return None
    if viscosity <= 0.0:
        return None
    return density * velocity_ref * length_ref / viscosity
 
 

Here is the caller graph for this function:

validate_les_configuration()

picurv_cli.core.validate_les_configuration	(	dict	case_cfg,
		dict	les_cfg,
		str	case_path,
		list	errors,
		list	warnings
	)

Checks the structured LES block for values the closure cannot honour.

Parameters

[in]	case_cfg	Parsed case.yml mapping, used to read declared periodicity.
[in]	les_cfg	Parsed models.physics.turbulence.les mapping.
[in]	case_path	Case file path used to prefix diagnostics.
[out]	errors	List collecting blocking validation failures.
[out]	warnings	List collecting advisory messages.

Returns

None; findings are appended to errors and warnings.

Definition at line 8546 of file core.py.

                               errors: list, warnings: list):
    """!
    @brief Checks the structured LES block for values the closure cannot honour.
    @param[in] case_cfg Parsed case.yml mapping, used to read declared periodicity.
    @param[in] les_cfg Parsed `models.physics.turbulence.les` mapping.
    @param[in] case_path Case file path used to prefix diagnostics.
    @param[out] errors List collecting blocking validation failures.
    @param[out] warnings List collecting advisory messages.
    @return None; findings are appended to `errors` and `warnings`.
    """
    def _numeric(container, key, path, minimum=None, exclusive_minimum=None):
        """!
        @brief Reads one numeric key and records a range or type failure against it.
        @param[in] container Mapping holding the key.
        @param[in] key Key to read; absent keys are accepted silently.
        @param[in] path Dotted key path used in diagnostics.
        @param[in] minimum Inclusive lower bound, or None to impose none.
        @param[in] exclusive_minimum Exclusive lower bound, or None to impose none.
        @return The parsed value, or None when the key is absent or unparseable.
        """
        if key not in container:
            return None
        try:
            value = float(container[key])
        except (TypeError, ValueError):
            errors.append(f"  {case_path}: {path} must be numeric.")
            return None
        if minimum is not None and value < minimum:
            errors.append(f"  {case_path}: {path} must be at least {minimum}.")
        if exclusive_minimum is not None and value <= exclusive_minimum:
            errors.append(f"  {case_path}: {path} must be greater than {exclusive_minimum}.")
        return value
 
    if 'enabled' in les_cfg and not isinstance(les_cfg['enabled'], bool):
        errors.append(f"  {case_path}: models.physics.turbulence.les.enabled must be true or false.")
 
    _numeric(les_cfg, 'constant_cs', "models.physics.turbulence.les.constant_cs", minimum=0.0)
    _numeric(les_cfg, 'vreman_coefficient', "models.physics.turbulence.les.vreman_coefficient", minimum=0.0)
    _numeric(les_cfg, 'wale_coefficient', "models.physics.turbulence.les.wale_coefficient", minimum=0.0)
 
    if 'dynamic_frequency' in les_cfg:
        try:
            if int(les_cfg['dynamic_frequency']) <= 0:
                errors.append(f"  {case_path}: models.physics.turbulence.les.dynamic_frequency must be positive.")
        except (TypeError, ValueError):
            errors.append(f"  {case_path}: models.physics.turbulence.les.dynamic_frequency must be an integer.")
 
    for key, normalizer in (('filter_width', normalize_les_filter_width),):
        if key in les_cfg:
            try:
                normalizer(les_cfg[key])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
 
    periodic = _les_periodic_axes(case_cfg)
 
    test_filter = les_cfg.get('test_filter')
    if test_filter is not None:
        if not isinstance(test_filter, dict):
            test_filter = {'kernel': test_filter}
        if 'kernel' in test_filter:
            try:
                kernel = normalize_les_test_filter(test_filter['kernel'])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
            else:
                # The Simpson stencil collapses onto the central eta-plane, which is
                # only a valid average when xi and zeta are homogeneous.
                if kernel == 1 and not {"i", "k"} <= periodic:
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.les.test_filter.kernel "
                        "'simpson_ik' assumes the xi and zeta directions are homogeneous, but "
                        "this case does not declare both of them PERIODIC. Use "
                        "'volume_weighted_box' instead."
                    )
        # A test filter no wider than the grid filter leaves the dynamic procedure with
        # nothing to measure, because both terms of the model tensor coincide.
        _numeric(test_filter, 'width_ratio',
                 "models.physics.turbulence.les.test_filter.width_ratio", exclusive_minimum=1.0)
 
    averaging = les_cfg.get('averaging')
    if averaging is not None:
        if not isinstance(averaging, dict):
            averaging = {'mode': averaging}
        mode = None
        if 'mode' in averaging:
            try:
                mode = normalize_les_averaging_mode(averaging['mode'])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
        directions = None
        if 'directions' in averaging:
            try:
                directions = normalize_les_averaging_directions(averaging['directions'])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
            else:
                if not directions:
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.les.averaging.directions "
                        "cannot be empty; omit the key to use the periodic axes."
                    )
                if mode is not None and mode != 1:
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.les.averaging.directions "
                        "applies only to mode 'homogeneous'; local and global averaging choose "
                        "their own directions."
                    )
                for axis in directions:
                    if axis not in periodic:
                        warnings.append(
                            f"{case_path}: models.physics.turbulence.les.averaging.directions "
                            f"names '{axis}', which this case does not declare PERIODIC. "
                            "Averaging assumes the flow is statistically homogeneous there."
                        )
        if mode == 1 and directions is None and not periodic:
            errors.append(
                f"  {case_path}: models.physics.turbulence.les.averaging.mode 'homogeneous' "
                "derives its directions from the periodic boundary pairs, and this case declares "
                "none. Name the directions explicitly or use 'local'."
            )
 
    clipping = les_cfg.get('clipping')
    if clipping is not None:
        if not isinstance(clipping, dict):
            clipping = {'mode': clipping}
        mode = None
        if 'mode' in clipping:
            try:
                mode = normalize_les_clip_mode(clipping['mode'])
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
        _numeric(clipping, 'max_cs', "models.physics.turbulence.les.clipping.max_cs", minimum=0.0)
        _numeric(clipping, 'min_viscosity_ratio',
                 "models.physics.turbulence.les.clipping.min_viscosity_ratio", minimum=0.0)
        if 'max_cs' in clipping and mode is not None and mode != 0:
            errors.append(
                f"  {case_path}: models.physics.turbulence.les.clipping.max_cs applies only to "
                "mode 'clamp'; 'positive' and 'signed' impose no upper bound. Remove the key or "
                "select mode 'clamp'."
            )
 
    # The dynamic procedure's controls have no meaning for a prescribed coefficient.
    # Only an explicitly named constant model triggers this: a template that documents
    # every key while LES is switched off should not be rejected on an inferred default.
    try:
        model_code = normalize_les_model(les_cfg['model']) if 'model' in les_cfg else None
    except ValueError:
        model_code = None
    if model_code in LES_MODEL_OWNED_KEYS and les_cfg.get('enabled', True):
        # Each model's own parameters are refused under any other, so a key that would be
        # silently ignored at runtime fails at validation instead. filter_width is shared
        # by every model that takes a scalar width; Vreman resolves each direction from
        # the cell's own edges and takes none.
        model_name = LES_MODEL_NAMES[model_code]
        for owner, keys in LES_MODEL_OWNED_KEYS.items():
            if owner == model_code:
                continue
            for key in keys:
                if key in les_cfg:
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.les.{key} configures "
                        f"{LES_MODEL_KEY_OWNER_DESCRIPTIONS[owner]} and cannot be used with "
                        f"model '{model_name}'."
                    )
        if model_code == 3 and 'filter_width' in les_cfg:
            errors.append(
                f"  {case_path}: models.physics.turbulence.les.filter_width cannot be used with "
                "model 'vreman', which weights each grid direction by the cell's own edge "
                "rather than by one scalar width."
            )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

validate_and_prepare_boundary_conditions()

picurv_cli.core.validate_and_prepare_boundary_conditions

(

dict

case_cfg

)

Validate BC entries against currently supported C-side handlers/types and.

return normalized entries ready for bcs.run generation.

Parameters

[in]

case_cfg

Argument passed to validate_and_prepare_boundary_conditions().

Returns

Value returned by validate_and_prepare_boundary_conditions().

Definition at line 8720 of file core.py.

def validate_and_prepare_boundary_conditions(case_cfg: dict):
    """!
    @brief Validate BC entries against currently supported C-side handlers/types and
    @details return normalized entries ready for bcs.run generation.
    @param[in] case_cfg Argument passed to `validate_and_prepare_boundary_conditions()`.
    @return Value returned by `validate_and_prepare_boundary_conditions()`.
    """
    num_blocks = int(case_cfg.get('models', {}).get('domain', {}).get('blocks', 1))
    scales = resolve_reference_scales(case_cfg)
 
    all_blocks_bcs = normalize_boundary_conditions_layout(case_cfg.get('boundary_conditions', []), num_blocks)
    prepared_blocks = []
 
    expected_faces = {"-Xi", "+Xi", "-Eta", "+Eta", "-Zeta", "+Zeta"}
    axis_pairs = [("-Xi", "+Xi"), ("-Eta", "+Eta"), ("-Zeta", "+Zeta")]
 
    for bi, block_bcs in enumerate(all_blocks_bcs):
        if not isinstance(block_bcs, list):
            raise ValueError(f"boundary_conditions[{bi}] must be a list of face configs.")
 
        prepared_block = []
        seen_faces = {}
 
        for idx, bc in enumerate(block_bcs):
            if not isinstance(bc, dict):
                raise ValueError(f"boundary_conditions[{bi}][{idx}] must be a mapping.")
 
            for req in ("face", "type", "handler"):
                if req not in bc:
                    raise ValueError(f"boundary_conditions[{bi}][{idx}] missing required key '{req}'.")
 
            face_raw = str(bc["face"]).strip()
            face_key = face_raw.lower()
            face = BC_FACE_MAP.get(face_key)
            if face is None:
                raise ValueError(
                    f"Unsupported BC face '{face_raw}' at boundary_conditions[{bi}][{idx}]. "
                    f"Supported: {sorted(expected_faces)}."
                )
            if face in seen_faces:
                raise ValueError(f"Duplicate face '{face}' in boundary_conditions[{bi}] (entries {seen_faces[face]} and {idx}).")
            seen_faces[face] = idx
 
            bc_type_raw = str(bc["type"]).strip()
            bc_type = BC_TYPE_MAP.get(bc_type_raw.lower())
            # A symmetry plane is a free-slip wall; the separate type was retired.
            if bc_type_raw.lower() == "symmetry":
                raise ValueError(
                    f"BC type 'symmetry' for face {face} in block {bi} is retired: a symmetry plane "
                    "is a free-slip wall, so use type 'wall' with handler 'free_slip'."
                )
            if bc_type is None:
                raise ValueError(
                    f"Unsupported BC type '{bc_type_raw}' for face {face} in block {bi}. "
                    f"Supported: {sorted(set(BC_TYPE_MAP.values()))}."
                )
 
            handler = str(bc["handler"]).strip().lower()
            handler_spec = BC_HANDLER_SPECS.get(handler)
            if handler_spec is None:
                raise ValueError(
                    f"Unsupported BC handler '{bc['handler']}' for face {face} in block {bi}. "
                    f"Supported now: {sorted(BC_HANDLER_SPECS.keys())}."
                )
            if bc_type not in handler_spec["types"]:
                raise ValueError(
                    f"Invalid BC combination on block {bi}, face {face}: type '{bc_type}' cannot use handler '{handler}'."
                )
 
            params = bc.get("params", {})
            if params is None:
                params = {}
            if not isinstance(params, dict):
                raise ValueError(f"'params' for block {bi}, face {face} must be a mapping.")
 
            # Reject unsupported older structured keys explicitly.
            if "vector" in params or "velocity" in params:
                raise ValueError(
                    f"Unsupported older params key ('vector'/'velocity') found on block {bi}, face {face}. "
                    "Use scalar keys 'vx', 'vy', 'vz'."
                )
 
            required = handler_spec["required_params"]
            optional = handler_spec["optional_params"]
            allowed = required | optional
 
            missing = sorted(required - set(params.keys()))
            if missing:
                raise ValueError(
                    f"Missing required params for handler '{handler}' on block {bi}, face {face}: {missing}."
                )
            unknown = sorted(set(params.keys()) - allowed)
            if unknown:
                raise ValueError(
                    f"Unknown params for handler '{handler}' on block {bi}, face {face}: {unknown}. "
                    f"Allowed: {sorted(allowed)}."
                )
 
            converted_params = {}
            for key, value in params.items():
                if key in _NUMERIC_BC_PARAMS:
                    converted_params[key] = quantity_to_solver_units(
                        value, BC_PARAM_QUANTITIES[key], scales,
                        f"boundary_conditions[{bi}][{idx}].params.{key}")
                elif key in _BOOL_BC_PARAMS:
                    canonical = _DEPRECATED_BC_PARAM_ALIASES.get(key, key)
                    if canonical != key:
                        if canonical in params:
                            raise ValueError(
                                f"boundary_conditions[{bi}][{idx}].params sets both '{key}' and its "
                                f"replacement '{canonical}'. Use '{canonical}' only."
                            )
                        print(
                            f"[WARNING] boundary_conditions[{bi}][{idx}].params.{key} is deprecated; "
                            f"use '{canonical}'. It enables the local seam-flux correction on the "
                            "periodic boundary plane, on top of the body force that sustains the bulk "
                            "flow. See docs/pages/54_Geometric_Periodic_Boundaries.md.",
                            file=sys.stderr,
                        )
                    converted_params[canonical] = _to_bool(
                        value, f"boundary_conditions[{bi}][{idx}].params.{key}")
                elif handler == "prescribed_flow" and key == "source":
                    converted_params[key] = _normalize_prescribed_flow_source(
                        value, f"boundary_conditions[{bi}][{idx}].params.source"
                    )
                else:
                    # Defensive fallback; should not happen due unknown-key gate above.
                    converted_params[key] = value
 
            policy = str(bc.get("particle_policy", handler_spec["particle_policy"])).strip().lower()
            if policy not in PARTICLE_BOUNDARY_POLICIES:
                raise ValueError(
                    f"Unsupported particle_policy '{bc.get('particle_policy')}' for face {face} in block {bi}. "
                    f"Supported: {list(PARTICLE_BOUNDARY_POLICIES)}."
                )
            if (policy == "wrap") != (bc_type == "PERIODIC"):
                raise ValueError(
                    f"boundary_conditions[{bi}][{idx}].particle_policy '{policy}' does not fit a {bc_type} face: "
                    "PERIODIC faces wrap particles to the paired face, and only they can."
                )
            converted_params["particle_policy"] = policy
 
            prepared_block.append({
                "face": face,
                "type": bc_type,
                "handler": handler,
                "params": converted_params,
            })
 
        missing_faces = sorted(expected_faces - set(seen_faces.keys()))
        if missing_faces:
            raise ValueError(
                f"boundary_conditions[{bi}] is incomplete. Missing faces: {missing_faces}. "
                "Provide all six faces explicitly."
            )
 
        # Pairwise periodic consistency checks.
        face_map = {entry["face"]: entry for entry in prepared_block}
        for neg_face, pos_face in axis_pairs:
            neg = face_map[neg_face]
            pos = face_map[pos_face]
            neg_periodic = (neg["type"] == "PERIODIC")
            pos_periodic = (pos["type"] == "PERIODIC")
            if neg_periodic != pos_periodic:
                raise ValueError(
                    f"Inconsistent periodicity in block {bi}: {neg_face} and {pos_face} must both be PERIODIC or neither."
                )
 
            driven_handlers = {"constant_flux", "initial_flux"}
            if (neg["handler"] in driven_handlers) or (pos["handler"] in driven_handlers):
                if neg["handler"] != pos["handler"]:
                    raise ValueError(
                        f"In block {bi}, driven periodic handlers on {neg_face}/{pos_face} must match exactly."
                    )
                if not (neg_periodic and pos_periodic):
                    raise ValueError(
                        f"In block {bi}, driven periodic handler '{neg['handler']}' requires PERIODIC type on both faces."
                    )
 
        prepared_blocks.append(prepared_block)
 
    return prepared_blocks
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_schema_path_text()

str picurv_cli.core._schema_path_text ( tuple  path )

protected

Render an internal schema path tuple as a user-facing YAML path.

Parameters

[in]

path

Internal path tuple.

Returns

Dotted YAML path.

Definition at line 8904 of file core.py.

def _schema_path_text(path: tuple) -> str:
    """!
    @brief Render an internal schema path tuple as a user-facing YAML path.
    @param[in] path Internal path tuple.
    @return Dotted YAML path.
    """
    return ".".join(part for part in path if part != "[]") or "<root>"
 
 

Here is the caller graph for this function:

_lookup_allowed_schema_keys()

picurv_cli.core._lookup_allowed_schema_keys ( dict  schema, tuple  path  )

protected

Return allowed keys for a path, honoring '*' dynamic mapping entries.

Parameters

[in]	schema	Role schema mapping.
[in]	path	Internal path tuple.

Returns

Allowed key set, None for free-form mappings, or False when path is not schema-checked.

Definition at line 8913 of file core.py.

def _lookup_allowed_schema_keys(schema: dict, path: tuple):
    """!
    @brief Return allowed keys for a path, honoring '*' dynamic mapping entries.
    @param[in] schema Role schema mapping.
    @param[in] path Internal path tuple.
    @return Allowed key set, None for free-form mappings, or False when path is not schema-checked.
    """
    if path in schema:
        return schema[path]
    for idx, part in enumerate(path):
        if part == "[]":
            continue
        candidate = path[:idx] + ("*",) + path[idx + 1:]
        if candidate in schema:
            return schema[candidate]
    return False
 
 

Here is the caller graph for this function:

_schema_key_hint()

str picurv_cli.core._schema_key_hint ( dict  schema, tuple  path, str  key, set  allowed  )

protected

Build a concise typo or hierarchy hint for an unsupported YAML key.

Parameters

[in]	schema	Role schema mapping.
[in]	path	Current internal YAML path tuple.
[in]	key	Unsupported YAML key.
[in]	allowed	Allowed keys at the current path.

Returns

Optional hint string.

Definition at line 8931 of file core.py.

def _schema_key_hint(schema: dict, path: tuple, key: str, allowed: set) -> str:
    """!
    @brief Build a concise typo or hierarchy hint for an unsupported YAML key.
    @param[in] schema Role schema mapping.
    @param[in] path Current internal YAML path tuple.
    @param[in] key Unsupported YAML key.
    @param[in] allowed Allowed keys at the current path.
    @return Optional hint string.
    """
    hints = []
    allowed_strings = sorted(str(item) for item in allowed)
    lower_matches = [item for item in allowed_strings if item.lower() == key.lower()]
    close_matches = lower_matches or difflib.get_close_matches(key, allowed_strings, n=1, cutoff=0.80)
    if close_matches:
        hints.append(f"Did you mean '{close_matches[0]}'?")
 
    valid_paths = []
    for schema_path, schema_allowed in schema.items():
        if schema_path == path or not schema_allowed:
            continue
        if key in schema_allowed:
            valid_paths.append(_schema_path_text(schema_path))
    if valid_paths:
        hints.append(f"This key is valid at: {', '.join(sorted(valid_paths))}.")
 
    return " ".join(hints)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_validate_yaml_schema_keys()

None picurv_cli.core._validate_yaml_schema_keys (   cfg, dict  schema, str  file_path, list  errors, tuple   path = ()  )

protected

Reject unsupported YAML keys before they can be silently ignored by staging.

Parameters

[in]	cfg	Parsed YAML node.
[in]	schema	Role schema mapping.
[in]	file_path	Source file path for diagnostics.
[in,out]	errors	Validation error accumulator.
[in]	path	Current internal YAML path tuple.

Definition at line 8959 of file core.py.

def _validate_yaml_schema_keys(cfg, schema: dict, file_path: str, errors: list, path: tuple = ()) -> None:
    """!
    @brief Reject unsupported YAML keys before they can be silently ignored by staging.
    @param[in] cfg Parsed YAML node.
    @param[in] schema Role schema mapping.
    @param[in] file_path Source file path for diagnostics.
    @param[in,out] errors Validation error accumulator.
    @param[in] path Current internal YAML path tuple.
    """
    if isinstance(cfg, dict):
        allowed = _lookup_allowed_schema_keys(schema, path)
        if allowed is not False and allowed is not None:
            unknown = sorted(str(key) for key in cfg.keys() if key not in allowed)
            for key in unknown:
                hint = _schema_key_hint(schema, path, key, allowed)
                hint_text = f" {hint}" if hint else ""
                errors.append(
                    f"  {file_path}: unsupported key at {_schema_path_text(path)}: '{key}'. "
                    f"Allowed keys: {sorted(allowed)}.{hint_text}"
                )
        if allowed is None:
            return
        for key, value in cfg.items():
            _validate_yaml_schema_keys(value, schema, file_path, errors, path + (key,))
    elif isinstance(cfg, list) and _lookup_allowed_schema_keys(schema, path + ("[]",)) is not False:
        for item in cfg:
            _validate_yaml_schema_keys(item, schema, file_path, errors, path + ("[]",))
    elif (isinstance(cfg, (str, int, float, list)) and not isinstance(cfg, bool)
          and path and path[-1] != "[]" and _lookup_allowed_schema_keys(schema, path) is not False):
        # A section given as a string, number or list would reach code that reads it as a
        # mapping. A boolean is left alone: several sections take true/false as shorthand
        # (models.physics.turbulence.les, io.paraview_series). So are list items, some of
        # which accept a scalar shorthand (a study metric name).
        errors.append(
            f"  {file_path}: '{_schema_path_text(path)}' must be a mapping, not "
            f"{type(cfg).__name__} {cfg!r}."
        )
    elif isinstance(cfg, list):
        for item in cfg:
            _validate_yaml_schema_keys(item, schema, file_path, errors, path + ("[]",))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_ensemble_source_fields()

dict picurv_cli.core._ensemble_source_fields ( str  source )

protected

Return the field table an ensemble of one source names its fields from.

Parameters

[in]

source

One of POST_STATISTICS_ENSEMBLE_SOURCES.

Returns

The particle or the Eulerian statistics field table.

Definition at line 9231 of file core.py.

def _ensemble_source_fields(source: str) -> dict:
    """!
    @brief Return the field table an ensemble of one source names its fields from.
    @param[in] source One of `POST_STATISTICS_ENSEMBLE_SOURCES`.
    @return The particle or the Eulerian statistics field table.
    """
    return STATISTICS_PARTICLE_FIELDS if source == "particles" else STATISTICS_ELIGIBLE_FIELDS
 
 
#: Moment names one field may request. Higher moments cannot be recovered from
#: centered state after the fact, so they need their own accumulation rather than
#: an extension of this list.

Here is the caller graph for this function:

input_quantity()

tuple picurv_cli.core.input_quantity

(

tuple

path

)

Return the (dimension, conversion site) recorded for one configuration input.

Parameters

[in]

path

Role followed by the schema path, e.g. ("case", "run_control", "dt_physical").

Returns

The entry for the path, or for its nearest covering ancestor.

Exceptions

KeyError

when no entry covers the path.

Definition at line 9571 of file core.py.

def input_quantity(path: tuple) -> tuple:
    """!
    @brief Return the `(dimension, conversion site)` recorded for one configuration input.
    @param[in] path Role followed by the schema path, e.g. `("case", "run_control", "dt_physical")`.
    @return The entry for the path, or for its nearest covering ancestor.
    @throws KeyError when no entry covers the path.
    """
    for length in range(len(path), 0, -1):
        entry = INPUT_QUANTITIES.get(tuple(path[:length]))
        if entry is not None:
            return entry
    raise KeyError(f"No physical dimension is recorded for input {'.'.join(map(str, path))}.")
 
 

Here is the caller graph for this function:

reference_scale()

float picurv_cli.core.reference_scale	(	tuple	dimension,
		dict	scales
	)

Return the factor that turns a physical quantity of this dimension into solver units.

Parameters

[in]	dimension	(length, velocity, density) exponents.
[in]	scales	Mapping with length_ref and velocity_ref, and density when used.

Returns

length_ref**a * velocity_ref**b * density**c.

Definition at line 9585 of file core.py.

def reference_scale(dimension: tuple, scales: dict) -> float:
    """!
    @brief Return the factor that turns a physical quantity of this dimension into solver units.
    @param[in] dimension `(length, velocity, density)` exponents.
    @param[in] scales Mapping with `length_ref` and `velocity_ref`, and `density` when used.
    @return `length_ref**a * velocity_ref**b * density**c`.
    """
    length, velocity, density = dimension
    factor = float(scales["length_ref"]) ** length * float(scales["velocity_ref"]) ** velocity
    if density:
        factor *= float(scales["density"]) ** density
    return factor
 
 

Here is the caller graph for this function:

input_reference_scale()

float picurv_cli.core.input_reference_scale	(	tuple	path,
		dict	scales
	)

Return the reference scale of one recorded input, for converting a whole payload.

File payloads (grids, inlet profiles) are converted element by element by their own readers; this gives them the one factor their recorded dimension implies, so they do not restate the dimension.

Parameters

[in]	path	Role and schema path of the input.
[in]	scales	Reference scales, as returned by resolve_reference_scales().

Returns

The reference scale of the input's recorded dimension.

Definition at line 9599 of file core.py.

def input_reference_scale(path: tuple, scales: dict) -> float:
    """!
    @brief Return the reference scale of one recorded input, for converting a whole payload.
    @details File payloads (grids, inlet profiles) are converted element by element by
             their own readers; this gives them the one factor their recorded dimension
             implies, so they do not restate the dimension.
    @param[in] path Role and schema path of the input.
    @param[in] scales Reference scales, as returned by `resolve_reference_scales()`.
    @return The reference scale of the input's recorded dimension.
    """
    dimension, _site = input_quantity(path)
    if dimension is None:
        raise ValueError(f"Input {'.'.join(map(str, path[1:]))} has no fixed dimension.")
    return reference_scale(dimension, scales)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

quantity_to_solver_units()

picurv_cli.core.quantity_to_solver_units	(		value,
		tuple	quantity,
		dict	scales,
		str	label
	)

Convert a physical value, or a list of them, by one recorded quantity entry.

Parameters

[in]	value	Physical value as written by the user.
[in]	quantity	(dimension, conversion site) entry from a dimension table.
[in]	scales	Reference scales, as returned by resolve_reference_scales().
[in]	label	Configuration path, for diagnostics.

Returns

The value divided by its dimension's reference scale.

Exceptions

ValueError

when the entry records no fixed dimension.

Definition at line 9615 of file core.py.

def quantity_to_solver_units(value, quantity: tuple, scales: dict, label: str):
    """!
    @brief Convert a physical value, or a list of them, by one recorded quantity entry.
    @param[in] value Physical value as written by the user.
    @param[in] quantity `(dimension, conversion site)` entry from a dimension table.
    @param[in] scales Reference scales, as returned by `resolve_reference_scales()`.
    @param[in] label Configuration path, for diagnostics.
    @return The value divided by its dimension's reference scale.
    @throws ValueError when the entry records no fixed dimension.
    """
    dimension, _site = quantity
    if dimension is None:
        raise ValueError(f"Input {label} has no fixed dimension to convert.")
    factor = reference_scale(dimension, scales)
    if isinstance(value, (list, tuple)):
        return [_to_finite_float(item, label) / factor for item in value]
    return _to_finite_float(value, label) / factor
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

to_solver_units()

picurv_cli.core.to_solver_units	(		value,
		tuple	path,
		dict	scales
	)

Convert one physical configuration value, or a list of them, to solver units.

Parameters

[in]	value	Physical value as written by the user.
[in]	path	Role and schema path whose recorded dimension governs the conversion.
[in]	scales	Reference scales, as returned by resolve_reference_scales().

Returns

The value divided by its dimension's reference scale.

Exceptions

ValueError

when the path records no fixed dimension.

Definition at line 9634 of file core.py.

def to_solver_units(value, path: tuple, scales: dict):
    """!
    @brief Convert one physical configuration value, or a list of them, to solver units.
    @param[in] value Physical value as written by the user.
    @param[in] path Role and schema path whose recorded dimension governs the conversion.
    @param[in] scales Reference scales, as returned by `resolve_reference_scales()`.
    @return The value divided by its dimension's reference scale.
    @throws ValueError when the path records no fixed dimension.
    """
    return quantity_to_solver_units(value, input_quantity(path), scales,
                                    ".".join(str(part) for part in path[1:]))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_reference_scales()

dict picurv_cli.core.resolve_reference_scales

(

dict

case_cfg

)

Resolve the reference length and velocity (and density, when given) of a case.

This is the part of the scaling contract every conversion needs. It does not require the fluid block, so boundary-condition preparation can use it before the full fluid contract is validated.

Parameters

[in]

case_cfg

Parsed case configuration.

Returns

Mapping with length_ref, velocity_ref, and optionally density.

Exceptions

ValueError

when a reference scale is missing, non-finite, or not positive.

Definition at line 9647 of file core.py.

def resolve_reference_scales(case_cfg: dict) -> dict:
    """!
    @brief Resolve the reference length and velocity (and density, when given) of a case.
    @details This is the part of the scaling contract every conversion needs. It does not
             require the fluid block, so boundary-condition preparation can use it before
             the full fluid contract is validated.
    @param[in] case_cfg Parsed case configuration.
    @return Mapping with `length_ref`, `velocity_ref`, and optionally `density`.
    @throws ValueError when a reference scale is missing, non-finite, or not positive.
    """
    scaling = ((case_cfg.get("properties") or {}).get("scaling") or {})
    length_ref = _to_finite_float(scaling.get("length_ref"), "properties.scaling.length_ref")
    velocity_ref = _to_finite_float(scaling.get("velocity_ref"), "properties.scaling.velocity_ref")
    if length_ref <= 0.0 or velocity_ref <= 0.0:
        raise ValueError("properties.scaling.length_ref and velocity_ref must be positive.")
    scales = {"length_ref": length_ref, "velocity_ref": velocity_ref}
    density = ((case_cfg.get("properties") or {}).get("fluid") or {}).get("density")
    if density is not None:
        scales["density"] = _to_finite_float(density, "properties.fluid.density")
    return scales
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

directory_value_charset_problem()

str picurv_cli.core.directory_value_charset_problem

(

str

value

)

Describe why a directory value cannot be written to a PETSc options line.

Parameters

[in]

value

Configured directory value.

Returns

Human-readable reason, or an empty string when the value is safe.

Definition at line 9702 of file core.py.

def directory_value_charset_problem(value: str) -> str:
    """!
    @brief Describe why a directory value cannot be written to a PETSc options line.
    @param[in] value Configured directory value.
    @return Human-readable reason, or an empty string when the value is safe.
    """
    if any(character.isspace() for character in value):
        return "contains whitespace"
    for character in UNSAFE_DIRECTORY_CHARACTERS:
        if character in value:
            label = {'"': "a double quote", "'": "a single quote", "#": "a comment marker"}.get(
                character, "a control character"
            )
            return f"contains {label}"
    return ""
 
 

Here is the caller graph for this function:

classify_run_directory_value()

str picurv_cli.core.classify_run_directory_value

(

value

)

Classify a configured run directory value.

Containment is judged lexically against the run directory, because the run directory does not exist yet at validation time. Beyond escaping, a value is rejected when it resolves to the run root itself: the log directory is recursively deleted on a fresh solve, so . or a/.. would delete the run.

Parameters

[in]

value

Configured directory value from monitor io.directories.

Returns

One of "contained", "escaping", "tilde", "run_root", or "invalid".

Definition at line 9719 of file core.py.

def classify_run_directory_value(value) -> str:
    """!
    @brief Classify a configured run directory value.
 
    @details Containment is judged lexically against the run directory, because the run
             directory does not exist yet at validation time. Beyond escaping, a value
             is rejected when it resolves to the run root itself: the log directory is
             recursively deleted on a fresh solve, so `.` or `a/..` would delete the run.
    @param[in] value Configured directory value from monitor `io.directories`.
    @return One of "contained", "escaping", "tilde", "run_root", or "invalid".
    """
    if not isinstance(value, str) or not value.strip():
        return "invalid"
    candidate = value.strip()
    # `~` is its own verdict because nothing expands it anywhere in the pipeline. The
    # control file is read by PETSc, not by a shell, and both the planner and the C
    # runtime treat a value not starting with `/` as relative to the run - so `~/logs`
    # names a literal `~` directory inside the run tree.
    #
    # It was worse before this verdict existed: physical containment classified `~` as
    # an authorizable external absolute location by expanding it, while every layer
    # that actually used the value treated it literally. The two disagreed about which
    # directory was being deleted. The fix is to refuse the value, not to expand it -
    # expanding it in one layer would only move the disagreement.
    if candidate.startswith("~"):
        return "tilde"
    if os.path.isabs(candidate):
        return "escaping"
    normalized = os.path.normpath(candidate)
    if normalized == os.pardir or normalized.startswith(os.pardir + os.sep):
        return "escaping"
    if normalized in (".", ""):
        return "run_root"
    return "contained"
 
 

Here is the caller graph for this function:

normalized_run_directory()

str picurv_cli.core.normalized_run_directory

(

str

value

)

Normalized, comparable form of a contained run directory value.

Parameters

[in]

value

Configured directory value.

Returns

Normalized relative path.

Definition at line 9755 of file core.py.

def normalized_run_directory(value: str) -> str:
    """!
    @brief Normalized, comparable form of a contained run directory value.
    @param[in] value Configured directory value.
    @return Normalized relative path.
    """
    return os.path.normpath(str(value).strip()).replace(os.sep, "/")
 
 

Here is the caller graph for this function:

paths_overlap()

bool picurv_cli.core.paths_overlap	(	str	first,
		str	second
	)

Whether two run-relative directories are the same or nested in one another.

Parameters

[in]	first	Normalized directory.
[in]	second	Normalized directory.

Returns

True when one contains the other.

Definition at line 9764 of file core.py.

def paths_overlap(first: str, second: str) -> bool:
    """!
    @brief Whether two run-relative directories are the same or nested in one another.
    @param[in] first Normalized directory.
    @param[in] second Normalized directory.
    @return True when one contains the other.
    """
    if first == second:
        return True
    return first.startswith(second + "/") or second.startswith(first + "/")
 
 

Here is the caller graph for this function:

resolve_unsafe_paths_override()

tuple picurv_cli.core.resolve_unsafe_paths_override	(	dict	dirs,
		str	monitor_path
	)

Resolve the unsafe-paths override, requiring a real YAML boolean.

A truthy string such as "false" must never enable an override that permits a destructive path. Only a genuine boolean true enables it; any other type is a configuration error rather than a silent interpretation.

Parameters

[in]	dirs	The io.directories mapping.
[in]	monitor_path	Path to the monitor file, for error messages.

Returns

Tuple of (enabled, errors).

Definition at line 9776 of file core.py.

def resolve_unsafe_paths_override(dirs: dict, monitor_path: str) -> tuple:
    """!
    @brief Resolve the unsafe-paths override, requiring a real YAML boolean.
 
    @details A truthy string such as "false" must never enable an override that permits
             a destructive path. Only a genuine boolean `true` enables it; any other
             type is a configuration error rather than a silent interpretation.
    @param[in] dirs The `io.directories` mapping.
    @param[in] monitor_path Path to the monitor file, for error messages.
    @return Tuple of (enabled, errors).
    """
    if UNSAFE_PATHS_OVERRIDE_KEY not in dirs:
        return False, []
    raw = dirs[UNSAFE_PATHS_OVERRIDE_KEY]
    if raw is True:
        return True, []
    if raw is False:
        return False, []
    return False, [
        f"  {monitor_path}: 'io.directories.{UNSAFE_PATHS_OVERRIDE_KEY}' must be a YAML boolean "
        f"(true or false), got {raw!r}. Quoted strings and numbers are rejected so a value like "
        f"\"false\" cannot silently enable an unsafe path."
    ]
 
 

Here is the caller graph for this function:

evaluate_run_directories()

tuple picurv_cli.core.evaluate_run_directories	(	dict	values,
		bool	override,
		set	explicit = None
	)

Apply every run-directory safety rule to a set of effective directory values.

Single source of truth for the rules, shared by configuration validation and submission preflight so the two cannot drift apart. Callers must pass effective values with defaults filled in.

Two classes of finding are distinguished. Waivable findings concern a deliberate external location; allow_unsafe_paths downgrades those to warnings. Non-waivable findings concern self-destruction or a value that cannot be written unambiguously - the run root itself, a reserved run directory, log/output overlap, and malformed characters. The override was granted for deliberate external storage, never for deleting the run's own config or emitting an ambiguous option line, so those stay errors.

Parameters

[in]	values	Effective mapping of directory key to configured value.
[in]	override	Whether the unsafe-paths override is enabled.
[in]	explicit	Keys the user actually configured; the rest are reported as defaults.

Returns

Tuple of (errors, warnings) as bare messages without a file prefix.

Definition at line 9801 of file core.py.

def evaluate_run_directories(values: dict, override: bool, explicit: set = None) -> tuple:
    """!
    @brief Apply every run-directory safety rule to a set of effective directory values.
 
    @details Single source of truth for the rules, shared by configuration validation and
             submission preflight so the two cannot drift apart. Callers must pass
             *effective* values with defaults filled in.
 
             Two classes of finding are distinguished. **Waivable** findings concern a
             deliberate external location; `allow_unsafe_paths` downgrades those to
             warnings. **Non-waivable** findings concern self-destruction or a value that
             cannot be written unambiguously - the run root itself, a reserved run
             directory, log/output overlap, and malformed characters. The override was
             granted for deliberate external storage, never for deleting the run's own
             config or emitting an ambiguous option line, so those stay errors.
    @param[in] values Effective mapping of directory key to configured value.
    @param[in] override Whether the unsafe-paths override is enabled.
    @param[in] explicit Keys the user actually configured; the rest are reported as defaults.
    @return Tuple of (errors, warnings) as bare messages without a file prefix.
    """
    errors: list = []
    warnings: list = []
    configured_keys = set(values) if explicit is None else set(explicit)
 
    def waivable(message: str) -> None:
        """!
        @brief Record a finding the unsafe-paths override may downgrade.
        @param[in] message Finding text.
        @return None.
        """
        if override:
            warnings.append(
                f"{message} Allowed only because '{UNSAFE_PATHS_OVERRIDE_KEY}: true' is set."
            )
        else:
            errors.append(
                f"{message} Use a directory inside the run tree, or set "
                f"'io.directories.{UNSAFE_PATHS_OVERRIDE_KEY}: true' to override deliberately."
            )
 
    def fatal(message: str) -> None:
        """!
        @brief Record a finding the override must never waive.
        @param[in] message Finding text.
        @return None.
        """
        errors.append(f"{message} This cannot be overridden.")
 
    destructive_note = (
        "On a fresh solve the runtime RECURSIVELY DELETES this directory before writing to it."
    )
    resolved: dict = {}
    for key in RUN_OWNED_DIRECTORY_KEYS:
        if key not in values:
            continue
        raw = values[key]
        detail = destructive_note if key == "log" else (
            "Run output must stay inside the run directory so it can be archived and restored."
        )
        if not isinstance(raw, str) or not raw.strip():
            fatal(f"'io.directories.{key}' must be a non-empty relative path (got {raw!r}).")
            continue
 
        # Both axes are reported. Escaping is the safety-critical property and leads,
        # but character problems are non-waivable, so a value that is both must not be
        # able to slip through by overriding only the escape.
        verdict = classify_run_directory_value(raw)
        charset_problem = directory_value_charset_problem(raw)
        if charset_problem:
            fatal(
                f"'io.directories.{key}' = {raw!r} {charset_problem}. Run directory names must be "
                f"writable to a PETSc options line without quoting; use a plain relative path such "
                f"as 'logs' or 'diagnostics/run1'."
            )
        if verdict == "tilde":
            fatal(
                f"'io.directories.{key}' = {raw!r} starts with '~', which nothing expands. "
                f"The control file is read by PETSc rather than by a shell, and the C "
                f"runtime resolves a value not starting with '/' relative to the run - so "
                f"this would be planned as one directory and deleted as another. Give a "
                f"real absolute path if an external location is intended. This cannot be "
                f"overridden."
            )
            continue
        if verdict == "escaping":
            if not (isinstance(raw, str) and raw.strip().startswith("/")):
                fatal(
                    f"'io.directories.{key}' = {raw!r} escapes the run directory by relative "
                    f"traversal. {detail} A relative escape lands among sibling runs and study "
                    f"members, so it is never authorizable; give an absolute path if an external "
                    f"location is genuinely intended."
                )
                continue
            # No `continue`: an authorized absolute path must still face the
            # non-waivable checks below, or it could target a run-owned directory such
            # as `/abs/run/config`.
            waivable(f"'io.directories.{key}' = {raw!r} escapes the run directory. {detail}")
        if verdict == "run_root":
            fatal(
                f"'io.directories.{key}' = {raw!r} resolves to the run directory itself. "
                + (destructive_note + " That would delete the entire run."
                   if key == "log" else "Run output must live in its own subdirectory.")
            )
            continue
        if charset_problem:
            continue
        normalized = normalized_run_directory(raw)
        resolved[key] = normalized
        # Every segment is checked, not just the first: `./config`, `output/sub`, and
        # `/abs/run/config` all target run-owned directories.
        segments = [s for s in normalized.split("/") if s not in ("", ".")]
        hit = next((s for s in segments if s in RESERVED_RUN_DIRECTORY_NAMES), None)
        if hit:
            fatal(
                f"'io.directories.{key}' = {raw!r} targets the reserved run directory "
                f"'{hit}'. " + (destructive_note if key == "log"
                                else "That directory is owned by the run tree.")
            )
 
    if "log" in resolved and "output" in resolved and paths_overlap(resolved["log"], resolved["output"]):
        log_source = "" if "log" in configured_keys else " (default)"
        out_source = "" if "output" in configured_keys else " (default)"
        fatal(
            f"'io.directories.log' ({resolved['log']!r}{log_source}) and 'io.directories.output' "
            f"({resolved['output']!r}{out_source}) overlap. {destructive_note} "
            f"That would delete solver output."
        )
    return errors, warnings
 
 
# Typed physical verdicts. Waivability is decided on the verdict, never on a substring
# of the message: a finding reading "resolves to the run directory itself" contains no
# word like "escapes", so message matching silently downgraded self-destruction to a
# warning. Message text is for humans; these constants are for the rule.

Here is the call graph for this function:

Here is the caller graph for this function:

classify_physical_containment()

list picurv_cli.core.classify_physical_containment	(	str	run_dir,
		dict	values
	)

Classify where each run-owned directory physically lands.

Lexical containment is not enough: a contained name can be a symlink to an external directory, and PetscRMTree follows symlinks. This resolves the real path - including any symlinked ancestor - and reports a typed verdict so the caller can apply the waiver rule structurally.

Parameters

[in]	run_dir	Run directory the values are relative to.
[in]	values	Effective directory mapping.

Returns

List of (key, verdict, message) for every value that is not contained.

Definition at line 9948 of file core.py.

def classify_physical_containment(run_dir: str, values: dict) -> list:
    """!
    @brief Classify where each run-owned directory physically lands.
 
    @details Lexical containment is not enough: a contained name can be a symlink to an
             external directory, and `PetscRMTree` follows symlinks. This resolves the
             real path - including any symlinked ancestor - and reports a typed verdict
             so the caller can apply the waiver rule structurally.
    @param[in] run_dir Run directory the values are relative to.
    @param[in] values Effective directory mapping.
    @return List of (key, verdict, message) for every value that is not contained.
    """
    findings: list = []
    try:
        root = os.path.realpath(run_dir)
    except OSError:
        return findings
    for key in RUN_OWNED_DIRECTORY_KEYS:
        raw = values.get(key)
        if not isinstance(raw, str) or not raw.strip():
            continue
        text = raw.strip()
        # Whether the *value* was given as an absolute location, which is the only form
        # an authorization can cover. A relative name that resolves outside the tree got
        # there through a symlink, and that is never what an operator asked for.
        # Only a real absolute path can be waived. `~` is refused before this point by
        # the lexical rules, and is not expanded here either: an earlier version did
        # expand it, which made this layer reason about a home directory no other layer
        # ever resolves.
        absolute = text.startswith("/")
        candidate = os.path.join(run_dir, text)
        real = os.path.realpath(candidate)
 
        if real == root:
            findings.append((key, PHYSICAL_VERDICT_RUN_ROOT,
                f"'io.directories.{key}' = {raw!r} resolves to the run directory itself "
                f"({real!r}); deleting it would destroy the run. This cannot be overridden."))
        elif real == os.sep or root.startswith(real.rstrip(os.sep) + os.sep):
            findings.append((key, PHYSICAL_VERDICT_ANCESTOR,
                f"'io.directories.{key}' = {raw!r} resolves to {real!r}, which CONTAINS the run "
                f"directory {root!r}. The runtime deletes this path recursively, so it would "
                f"destroy the run and everything beside it. This cannot be overridden."))
        elif real.startswith(root + os.sep):
            continue
        elif absolute:
            findings.append((key, PHYSICAL_VERDICT_EXTERNAL_ABSOLUTE,
                f"'io.directories.{key}' = {raw!r} resolves to {real!r}, which is outside the run "
                f"directory {root!r}. The runtime deletes its log directory recursively."))
        else:
            findings.append((key, PHYSICAL_VERDICT_RELATIVE_ESCAPE,
                f"'io.directories.{key}' = {raw!r} is a relative name that resolves to {real!r}, "
                f"outside the run directory {root!r} - a symlink leads out of the tree. A "
                f"relative escape is never authorizable; name an absolute path if an external "
                f"location is genuinely intended. This cannot be overridden."))
    return findings
 
 

Here is the caller graph for this function:

check_physical_containment()

list picurv_cli.core.check_physical_containment	(	str	run_dir,
		dict	values
	)

Human-readable physical containment violations.

Parameters

[in]	run_dir	Run directory the values are relative to.
[in]	values	Effective directory mapping.

Returns

Violation lines.

Definition at line 10005 of file core.py.

def check_physical_containment(run_dir: str, values: dict) -> list:
    """!
    @brief Human-readable physical containment violations.
    @param[in] run_dir Run directory the values are relative to.
    @param[in] values Effective directory mapping.
    @return Violation lines.
    """
    return [message for _, _, message in classify_physical_containment(run_dir, values)]
 
 

Here is the call graph for this function:

effective_run_directories()

dict picurv_cli.core.effective_run_directories

(

dict

configured

)

Fill in defaults for run-owned directories that were not configured.

An omitted key is not absent at runtime, it takes its default. Checking only explicit keys would miss log: output, which collides with the default output directory and would delete solver output.

Parameters

[in]

configured

Configured directory mapping, possibly partial.

Returns

Effective mapping with defaults applied.

Definition at line 10015 of file core.py.

def effective_run_directories(configured: dict) -> dict:
    """!
    @brief Fill in defaults for run-owned directories that were not configured.
 
    @details An omitted key is not absent at runtime, it takes its default. Checking
             only explicit keys would miss `log: output`, which collides with the
             default output directory and would delete solver output.
    @param[in] configured Configured directory mapping, possibly partial.
    @return Effective mapping with defaults applied.
    """
    effective = dict(RUN_DIRECTORY_DEFAULTS)
    for key in RUN_OWNED_DIRECTORY_KEYS:
        if key in configured:
            effective[key] = configured[key]
    return effective
 
 

Here is the caller graph for this function:

validate_run_directory_containment()

tuple picurv_cli.core.validate_run_directory_containment	(	dict	monitor_cfg,
		str	monitor_path
	)

Classify legacy directory values as defense-in-depth during validation.

The monitor schema rejects this removed surface. Keeping the stricter classifier here ensures malformed or manually constructed configurations still receive the safety findings that protect recursive log cleanup.

Parameters

[in]	monitor_cfg	Parsed monitor YAML dictionary.
[in]	monitor_path	Path to the monitor file, for error messages.

Returns

Tuple of (errors, warnings).

Definition at line 10032 of file core.py.

def validate_run_directory_containment(monitor_cfg: dict, monitor_path: str) -> tuple:
    """!
    @brief Classify legacy directory values as defense-in-depth during validation.
    @details The monitor schema rejects this removed surface. Keeping the stricter
             classifier here ensures malformed or manually constructed configurations
             still receive the safety findings that protect recursive log cleanup.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @param[in] monitor_path Path to the monitor file, for error messages.
    @return Tuple of (errors, warnings).
    """
    io_cfg = (monitor_cfg or {}).get("io") or {}
    dirs = io_cfg.get("directories")
    if not isinstance(dirs, dict):
        return [], []
    override, override_errors = resolve_unsafe_paths_override(dirs, monitor_path)
    errors, warnings = evaluate_run_directories(
        effective_run_directories(dirs), override, explicit=set(dirs)
    )
    return (
        override_errors + [f"  {monitor_path}: {message}" for message in errors],
        [f"  {monitor_path}: {message}" for message in warnings],
    )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

validate_reserved_directory_flags()

list picurv_cli.core.validate_reserved_directory_flags	(	dict	config,
		str	config_path,
		str	label
	)

Reject raw PETSc passthrough options that set run-owned directories.

Passthrough surfaces emit {flag: value} verbatim into the generated control file. Run-owned path flags are reserved for the fixed workspace topology and may only be emitted by the generator.

Parameters

[in]	config	Parsed configuration mapping to scan.
[in]	config_path	Path to the file, for error messages.
[in]	label	Human-readable description of the surface being scanned.

Returns

Violation lines.

Definition at line 10056 of file core.py.

def validate_reserved_directory_flags(config: dict, config_path: str, label: str) -> list:
    """!
    @brief Reject raw PETSc passthrough options that set run-owned directories.
 
    @details Passthrough surfaces emit `{flag: value}` verbatim into the generated
             control file. Run-owned path flags are reserved for the fixed workspace
             topology and may only be emitted by the generator.
    @param[in] config Parsed configuration mapping to scan.
    @param[in] config_path Path to the file, for error messages.
    @param[in] label Human-readable description of the surface being scanned.
    @return Violation lines.
    """
    violations: list = []
 
    def scan(node, trail: str) -> None:
        """!
        @brief Walk the mapping looking for reserved flags used as keys.
        @param[in] node Current mapping, list, or scalar node.
        @param[in] trail Dotted path to the current node, for error messages.
        @return None.
        """
        if isinstance(node, dict):
            for key, value in node.items():
                token = key.strip() if isinstance(key, str) else key
                if token in RESERVED_DIRECTORY_FLAGS:
                    violations.append(
                        f"  {config_path}: {label} sets the reserved flag '{token}' at "
                        f"{trail or '<root>'}. Run directories are fixed by the workspace "
                        "contract; raw passthrough cannot override them."
                    )
                elif token in RESERVED_INDIRECTION_FLAGS:
                    violations.append(
                        f"  {config_path}: {label} sets '{token}' at {trail or '<root>'}. PETSc "
                        f"evaluates that indirection itself, so its contents cannot be checked "
                        "here and could reintroduce a run-directory flag. Remove the indirection."
                    )
                scan(value, f"{trail}.{key}" if trail else str(key))
        elif isinstance(node, list):
            for index, item in enumerate(node):
                scan(item, f"{trail}[{index}]")
 
    scan(config, "")
    return violations
 
 

Here is the caller graph for this function:

physical_units_transition_notices()

list picurv_cli.core.physical_units_transition_notices	(	dict	case_cfg,
		dict	solver_cfg,
		dict	monitor_cfg
	)

Name the inputs whose meaning changed when every input became physical.

These inputs were once read in solver units. At unit reference scales the two readings coincide, so a notice is only needed when the scales differ from one; it says which values are now divided by a reference scale.

Parameters

[in]	case_cfg	Parsed case configuration.
[in]	solver_cfg	Parsed solver configuration.
[in]	monitor_cfg	Parsed monitor configuration.

Returns

Warning lines, empty when the case uses unit reference scales.

Definition at line 10101 of file core.py.

def physical_units_transition_notices(case_cfg: dict, solver_cfg: dict, monitor_cfg: dict) -> list:
    """!
    @brief Name the inputs whose meaning changed when every input became physical.
    @details These inputs were once read in solver units. At unit reference scales the
             two readings coincide, so a notice is only needed when the scales differ
             from one; it says which values are now divided by a reference scale.
    @param[in] case_cfg Parsed case configuration.
    @param[in] solver_cfg Parsed solver configuration.
    @param[in] monitor_cfg Parsed monitor configuration.
    @return Warning lines, empty when the case uses unit reference scales.
    """
    try:
        scales = resolve_reference_scales(case_cfg)
    except (ValueError, TypeError, AttributeError):
        return []
    if scales["length_ref"] == 1.0 and scales["velocity_ref"] == 1.0:
        return []
    physics = ((case_cfg.get("models") or {}).get("physics") or {})
    ic = ((case_cfg.get("properties") or {}).get("initial_conditions") or {})
    operation = (solver_cfg or {}).get("operation_mode") or {}
    windows = (((monitor_cfg or {}).get("field_statistics") or {}).get("windows") or [])
    changed = []
    if isinstance((physics.get("particles") or {}).get("point_source"), dict):
        changed.append("models.physics.particles.point_source")
    wall_cfg = (physics.get("turbulence") or {}).get("wall_function")
    if isinstance(wall_cfg, dict) and "roughness_height" in wall_cfg:
        changed.append("models.physics.turbulence.wall_function.roughness_height")
    if str(ic.get("mode", "")).strip().lower() == "file":
        changed.append("properties.initial_conditions (mode: file payload)")
    if str(ic.get("generator", "")).strip().lower().replace("-", "_") in _PYTHON_INITIAL_CONDITION_PROVIDERS:
        changed.append(f"properties.initial_conditions.params ({ic.get('generator')})")
    if isinstance(operation, dict) and operation.get("uniform_flow"):
        changed.append("operation_mode.uniform_flow")
    if ((solver_cfg or {}).get("verification") or {}).get("sources"):
        changed.append("verification.sources")
    if any(isinstance(window, dict) and ({"start_time", "end_time", "time_cadence"} & set(window))
           for window in windows):
        changed.append("field_statistics.windows[].{start_time,end_time,time_cadence}")
    if not changed:
        return []
    return [
        f"Physical units: with length_ref={scales['length_ref']:g} and "
        f"velocity_ref={scales['velocity_ref']:g}, these inputs are read as physical values and "
        f"converted to solver units: {', '.join(changed)}. Inputs written in solver units "
        f"before this rule must be converted; see docs/pages/19_Nondimensionalization.md."
    ]
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

validate_simulation_configs()

picurv_cli.core.validate_simulation_configs	(	dict	case_cfg,
		dict	solver_cfg,
		dict	monitor_cfg,
		str	case_path,
		str	solver_path,
		str	monitor_path,
		bool	restart_source_given = False
	)

Validates every configuration a simulation run consumes, before any work is done.

Covers the three roles the solver is launched with: the case, the solver, and the monitor. Only one of those is a solver configuration, which is why this is not named for the solver; the monitor in particular carries observation and field-statistics contracts that have nothing to do with the numerical scheme.

Checks required sections, required keys, physical sanity, and the cross-file combinations no single file can rule out. Post-processing configuration is validated separately by validate_post_config().

Parameters

[in]	case_cfg	Parsed case YAML dictionary.
[in]	solver_cfg	Parsed solver YAML dictionary.
[in]	monitor_cfg	Parsed monitor YAML dictionary.
[in]	case_path	Path to case file (for error messages).
[in]	solver_path	Path to solver file (for error messages).
[in]	monitor_path	Path to monitor file (for error messages).
[in]	restart_source_given	Whether the invocation names a restart source (–restart-from or –continue), which silences the reminder that the case needs one.

Exceptions

SystemExit

on validation failure.

Definition at line 10149 of file core.py.

                                restart_source_given: bool = False):
    """!
    @brief Validates every configuration a simulation run consumes, before any work is done.
    @details Covers the three roles the solver is launched with: the case, the solver,
             and the monitor. Only one of those is a solver configuration, which is
             why this is not named for the solver; the monitor in particular carries
             observation and field-statistics contracts that have nothing to do with
             the numerical scheme.
 
             Checks required sections, required keys, physical sanity, and the
             cross-file combinations no single file can rule out. Post-processing
             configuration is validated separately by `validate_post_config()`.
    @param[in] case_cfg    Parsed case YAML dictionary.
    @param[in] solver_cfg  Parsed solver YAML dictionary.
    @param[in] monitor_cfg Parsed monitor YAML dictionary.
    @param[in] case_path   Path to case file (for error messages).
    @param[in] solver_path Path to solver file (for error messages).
    @param[in] monitor_path Path to monitor file (for error messages).
    @param[in] restart_source_given Whether the invocation names a restart source
                                    (--restart-from or --continue), which silences the
                                    reminder that the case needs one.
    @throws SystemExit on validation failure.
    """
    errors = []
    warnings = []
    warnings.extend(physical_units_transition_notices(case_cfg, solver_cfg, monitor_cfg))
    errors.extend(validate_reserved_directory_flags(
        case_cfg, case_path, "case solver_parameters / passthrough"))
    errors.extend(validate_reserved_directory_flags(
        solver_cfg, solver_path, "solver petsc_passthrough_options"))
    eulerian_source_mode = "solve"
 
    legacy_models = case_cfg.get("models") if isinstance(case_cfg, dict) else None
    legacy_statistics = legacy_models.get("statistics") if isinstance(legacy_models, dict) else None
    if legacy_statistics is not None:
        errors.append(
            f"  {case_path}: 'models.statistics' was removed with the legacy averaging system. "
            "Use instantaneous output and offline postprocessing until the replacement "
            "field-statistics pipeline is available."
        )
    if isinstance(solver_cfg, dict) and "solution_convergence" in solver_cfg:
        errors.append(
            f"  {solver_path}: 'solution_convergence' moved to "
            "monitor.yml -> solution_monitoring.convergence."
        )
    if errors:
        _print_validation_errors(errors)
 
    _validate_yaml_schema_keys(case_cfg, _CASE_SCHEMA, case_path, errors)
    _validate_yaml_schema_keys(solver_cfg, _SOLVER_SCHEMA, solver_path, errors)
    _validate_yaml_schema_keys(monitor_cfg, _MONITOR_SCHEMA, monitor_path, errors)
 
    # --- case.yml: required top-level sections ---
    required_case_sections = ['properties', 'run_control', 'grid', 'models', 'boundary_conditions']
    for section in required_case_sections:
        if section not in case_cfg:
            errors.append(f"  {case_path}: missing required section '{section}'.")
 
    if errors:
        _print_validation_errors(errors)
 
    # --- case.yml: properties sub-keys ---
    props = case_cfg.get('properties', {})
    for group, keys in [('scaling', ['length_ref', 'velocity_ref']),
                        ('fluid', ['density', 'viscosity'])]:
        sub = props.get(group, {})
        if not sub:
            errors.append(f"  {case_path}: missing 'properties.{group}' section.")
        else:
            for k in keys:
                if k not in sub:
                    errors.append(f"  {case_path}: missing key 'properties.{group}.{k}'.")
 
    # --- case.yml: run_control sub-keys ---
    rc = case_cfg.get('run_control', {})
    for k in ['start_step', 'total_steps', 'dt_physical']:
        if k not in rc:
            errors.append(f"  {case_path}: missing key 'run_control.{k}'.")
 
    # --- Physical sanity checks ---
    # Each value is checked for its type here: later stages convert them with int()/float()
    # and would otherwise stop with a Python error instead of naming the key.
    for key, value, positive in (
        ('properties.fluid.density', props.get('fluid', {}).get('density', 0), True),
        ('properties.fluid.viscosity', props.get('fluid', {}).get('viscosity', 0), False),
        ('run_control.dt_physical', rc.get('dt_physical', 0), True),
    ):
        if not isinstance(value, (int, float)) or isinstance(value, bool):
            errors.append(f"  {case_path}: '{key}' must be a number (got {value!r}).")
        elif positive and value <= 0:
            errors.append(f"  {case_path}: '{key}' must be positive (got {value}).")
        elif value < 0:
            errors.append(f"  {case_path}: '{key}' must be non-negative (got {value}).")
    particles_count = (((case_cfg.get('models') or {}).get('physics') or {}).get('particles') or {}).get('count', 0)
    for key, value in (('run_control.start_step', rc.get('start_step', 0)),
                       ('run_control.total_steps', rc.get('total_steps', 0)),
                       ('models.physics.particles.count', particles_count)):
        if not isinstance(value, int) or isinstance(value, bool) or value < 0:
            errors.append(f"  {case_path}: '{key}' must be a non-negative integer (got {value!r}).")
    if errors:
        _print_validation_errors(errors)
 
    # --- case.yml: grid mode ---
    grid_cfg = case_cfg.get('grid', {})
    grid_mode = grid_cfg.get('mode')
    valid_grid_modes = list(GRID_MODES)
    if grid_mode not in valid_grid_modes:
        errors.append(f"  {case_path}: 'grid.mode' must be one of {valid_grid_modes} (got '{grid_mode}').")
    elif grid_mode == 'file':
        source_file = grid_cfg.get('source_file')
        if not source_file:
            errors.append(f"  {case_path}: 'grid.source_file' is required when grid.mode is 'file'.")
        else:
            try:
                source_abs = resolve_workspace_path(case_path, source_file)
            except ValueError as exc:
                errors.append(f"  {case_path}: {exc}")
            else:
                if not os.path.isfile(source_abs):
                    errors.append(f"  {case_path}: grid.source_file does not exist: {source_abs}")
    elif grid_mode == 'programmatic_c':
        grid_settings = grid_cfg.get('programmatic_settings')
        if not grid_settings:
            errors.append(f"  {case_path}: 'grid.programmatic_settings' is required when grid.mode is 'programmatic_c'.")
        elif not isinstance(grid_settings, dict):
            errors.append(f"  {case_path}: 'grid.programmatic_settings' must be a mapping.")
    elif grid_mode == 'grid_gen':
        gen_cfg = grid_cfg.get('generator')
        if not isinstance(gen_cfg, dict):
            errors.append(f"  {case_path}: 'grid.generator' must be a mapping when grid.mode is 'grid_gen'.")
        else:
            warn_on_grid_generator_hyphen_keys(gen_cfg, case_path, warnings)
            errors.extend(
                reject_generator_destination_keys(gen_cfg, case_path, "grid.generator")
            )
 
            config_file = gen_cfg.get('config_file')
            if not config_file:
                errors.append(f"  {case_path}: 'grid.generator.config_file' is required for grid.mode='grid_gen'.")
            else:
                try:
                    config_abs = resolve_workspace_path(case_path, config_file)
                except ValueError as exc:
                    errors.append(f"  {case_path}: {exc}")
                else:
                    if not os.path.isfile(config_abs):
                        errors.append(f"  {case_path}: grid.generator.config_file does not exist: {config_abs}")
 
            grid_type = gen_cfg.get('grid_type')
            if grid_type is not None and str(grid_type) not in GRID_GENERATOR_TYPES:
                errors.append(f"  {case_path}: grid.generator.grid_type must be one of "
                              f"{list(GRID_GENERATOR_TYPES)} (got '{grid_type}').")
 
            # cli_args is an opaque token list handed straight to the generator, so a bad
            # geometry selector inside it would otherwise surface as a nonzero subprocess
            # exit in the middle of a run rather than as a validation error before one.
            errors.extend(validate_grid_generator_cli_args(gen_cfg.get('cli_args'), case_path))
 
            cli_args = gen_cfg.get('cli_args', [])
            if cli_args is not None and not isinstance(cli_args, list):
                errors.append(f"  {case_path}: grid.generator.cli_args must be a list of CLI tokens.")
    try:
        resolve_grid_da_processor_layout(grid_cfg)
    except ValueError as e:
        errors.append(f"  {case_path}: {e}")
 
    # --- case.yml: boundary_conditions strict validation ---
    prepared_blocks = None
    try:
        prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    except ValueError as e:
        errors.append(f"  {case_path}: {e}")
 
    # --- case.yml: initial_conditions mode-aware validation ---
    ic = props.get('initial_conditions', {})
    resolved_ic = None
    try:
        ic_start_step = int((case_cfg.get("run_control", {}) or {}).get("start_step", 0) or 0)
    except (TypeError, ValueError):
        ic_start_step = 0
    try:
        ic_eulerian_source = normalize_eulerian_field_source(
            (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
        )
    except ValueError:
        # The solver-specific validation below reports an invalid source value.
        # Keep IC validation independent of that diagnostic.
        ic_eulerian_source = "solve"
    ic_is_authoritative = ic_eulerian_source == "solve" and ic_start_step == 0
    if not ic:
        errors.append(f"  {case_path}: missing 'properties.initial_conditions' section.")
    elif not isinstance(ic, dict):
        errors.append(f"  {case_path}: 'properties.initial_conditions' must be a mapping.")
    elif 'mode' not in ic:
        errors.append(
            f"  {case_path}: missing key 'properties.initial_conditions.mode'. "
            "Specify 'generated' or 'file' explicitly."
        )
    elif ic_is_authoritative:
        try:
            scaling_contract = resolve_fluid_scaling(case_cfg)
            resolved_ic = resolve_initial_condition_config(
                ic, prepared_blocks, scales=scaling_contract,
                provider_context={"kinematic_viscosity": scaling_contract["nondimensional_kinematic_viscosity"]},
            )
        except KeyError as e:
            errors.append(f"  {case_path}: missing key 'properties.initial_conditions.{e.args[0]}'.")
        except ValueError as e:
            errors.append(f"  {case_path}: {e}")
    if ic_is_authoritative and resolved_ic and resolved_ic.get("kind") == "stability_mode_velocity":
        dimensionality = str((((case_cfg.get("models", {}) or {}).get("physics", {}) or {})
                             .get("dimensionality", "3D"))).strip().upper()
        smv = resolved_ic["params"]
        if dimensionality == "2D" and ("i" in (smv["streamwise_axis"], smv["cross_axis"])
                                       or not (smv.get("noise") or {"planar": True})["planar"]):
            errors.append(f"  {case_path}: stability_mode_velocity in 2D mode needs i as the normal axis "
                          "(streamwise and cross axes j and k) and noise.planar: true.")
    if (ic_is_authoritative and resolved_ic and
            GENERATED_IC_PROVIDERS.get(resolved_ic.get("kind"), {}).get("requires_fresh_3d")):
        if resolved_ic["kind"] in ("channel_spectral_velocity", "duct_spectral_velocity"):
            if (case_cfg.get("models", {}).get("physics", {}).get("fsi", {}) or {}).get("immersed", False):
                errors.append(f"  {case_path}: wall spectral ICs do not support immersed geometry.")
        dimensionality = str((((case_cfg.get("models", {}) or {}).get("physics", {}) or {})
                             .get("dimensionality", "3D"))).strip().upper()
        if dimensionality != "3D":
            errors.append(f"  {case_path}: {resolved_ic['label']} requires models.physics.dimensionality: 3D.")
        if grid_mode == "programmatic_c":
            settings = grid_cfg.get("programmatic_settings", {}) or {}
            ratios = [settings.get(key, 1.0) for key in ("rxs", "rys", "rzs")]
            try:
                if any(abs(float(value) - 1.0) > 1.0e-12 for value in ratios):
                    errors.append(f"  {case_path}: {resolved_ic['label']} requires uniform programmatic spacing (rxs/rys/rzs: 1.0).")
            except (TypeError, ValueError):
                pass
    generated_profile = any(
        bc.get("handler") == "prescribed_flow"
        and ((bc.get("params") or {}).get("source") or {}).get("type") == "generated"
        for block in (prepared_blocks or []) for bc in block
    )
    if grid_mode == 'programmatic_c' and (
            generated_profile or (resolved_ic and is_generated_ic_provider(resolved_ic))):
        try:
            validate_programmatic_bridge_grid_settings(grid_cfg.get('programmatic_settings'))
        except ValueError as e:
            errors.append(f"  {case_path}: {e}")
 
    # --- case.yml: particle initialization validation ---
    particles_cfg = case_cfg.get('models', {}).get('physics', {}).get('particles', {})
    if particles_cfg and not isinstance(particles_cfg, dict):
        errors.append(f"  {case_path}: 'models.physics.particles' must be a mapping.")
    elif isinstance(particles_cfg, dict):
        init_mode_raw = particles_cfg.get('init_mode', 'Surface')
        try:
            pinit_code = normalize_particle_init_mode(init_mode_raw)
        except ValueError as e:
            errors.append(f"  {case_path}: {e}")
            pinit_code = None
 
        # One base seed drives every particle random stream - initial placement, inlet
        # re-placement, and Brownian motion - so identical inputs on the same rank count
        # reproduce. Omitted, the runtime uses 12345.
        random_seed = particles_cfg.get('random_seed')
        if random_seed is not None and (isinstance(random_seed, bool) or not isinstance(random_seed, int)
                                        or not 0 <= random_seed <= 2147483647):
            errors.append(
                f"  {case_path}: models.physics.particles.random_seed must be an integer from 0 to "
                f"2147483647 (got {random_seed!r})."
            )
 
        restart_mode = particles_cfg.get('restart_mode')
        if restart_mode is not None and str(restart_mode).lower() not in PARTICLE_RESTART_MODES:
            errors.append(
                f"  {case_path}: models.physics.particles.restart_mode must be 'init' or 'load' (got '{restart_mode}')."
            )
        elif 'restart_mode' not in particles_cfg:
            try:
                start_step = int(rc.get('start_step', 0))
                particle_count = int(particles_cfg.get('count', 0) or 0)
            except (TypeError, ValueError):
                start_step = 0
                particle_count = 0
            if start_step > 0 and particle_count > 0:
                warnings.append(
                    f"{case_path}: models.physics.particles.restart_mode is omitted for a particle restart "
                    "(run_control.start_step > 0, count > 0). C will default to 'load'."
                )
 
        if pinit_code == 2:
            point_cfg = particles_cfg.get('point_source', {})
            if not isinstance(point_cfg, dict):
                errors.append(f"  {case_path}: models.physics.particles.point_source must be a mapping when init_mode is PointSource.")
            else:
                for coord in ('x', 'y', 'z'):
                    if coord not in point_cfg:
                        errors.append(
                            f"  {case_path}: models.physics.particles.point_source.{coord} is required when init_mode is PointSource."
                        )
 
        if 'fields' in particles_cfg:
            try:
                particle_fields = normalize_particle_fields(particles_cfg['fields'])
            except ValueError as e:
                errors.append(f"  {case_path}: {e}")
                particle_fields = []
            if particle_fields and int(particles_cfg.get('count', 0) or 0) <= 0:
                errors.append(f"  {case_path}: models.physics.particles.fields needs particles (count > 0).")
            if particle_fields and ((solver_cfg.get('verification') or {}).get('sources') or {}).get('scalar'):
                errors.append(
                    f"  {case_path}: models.physics.particles.fields cannot be combined with "
                    f"{solver_path} verification.sources.scalar, which prescribes Psi at every step.")
            if pinit_code == 2:
                for entry in particle_fields:
                    if not any(re.search(r"\b(uniform|normal)\s*\‍(", e) for e in entry["expressions"]):
                        warnings.append(
                            f"{case_path}: models.physics.particles.fields.{entry['name']} has no random draw, "
                            "but init_mode is PointSource: every particle starts at one point and gets the "
                            "same value. Use a constant, or uniform()/normal() for per-particle values.")
            try:
                resumes = int(rc.get('start_step', 0)) > 0
            except (TypeError, ValueError):
                resumes = False
            if particle_fields and resumes and str(particles_cfg.get('restart_mode', 'load')).lower() == 'load':
                warnings.append(
                    f"{case_path}: models.physics.particles.fields is ignored when particles are restored "
                    "(restart_mode: load); their values come from the checkpoint.")
 
    # --- case.yml: domain and physics switches ---
    # Multi-block coupling, immersed boundaries and moving bodies are planned, not
    # implemented. The switches stay in the schema so that setting one fails here with a
    # reason, rather than as an unknown key or, worse, as a run that solves a different
    # problem: the solver would accept all three and silently ignore what they promise.
    models_cfg = case_cfg.get('models', {}) or {}
    domain_cfg = models_cfg.get('domain', {}) or {}
    physics_cfg = models_cfg.get('physics', {}) or {}
    try:
        block_count = int(domain_cfg.get('blocks', 1))
    except (TypeError, ValueError):
        block_count = None
    if block_count != 1:
        errors.append(
            f"  {case_path}: models.domain.blocks must be 1 (got {domain_cfg.get('blocks')!r}). "
            "Multi-block domains are planned, not implemented: no solver exchanges data across "
            "the faces blocks share, so each block would be solved as an isolated domain."
        )
    fsi_cfg = physics_cfg.get('fsi', {}) or {}
    if not isinstance(fsi_cfg, dict):
        errors.append(f"  {case_path}: 'models.physics.fsi' must be a mapping.")
    else:
        for key, feature in (('immersed', 'An immersed boundary'),
                             ('moving_fsi', 'Moving-body fluid-structure interaction')):
            if fsi_cfg.get(key):
                errors.append(
                    f"  {case_path}: models.physics.fsi.{key} must be false. {feature} is planned, "
                    "not implemented: no body geometry is loaded, and the interpolation that would "
                    "impose one on the flow was never ported."
                )
    dimensionality = str(physics_cfg.get('dimensionality', '3D')).strip()
    if dimensionality not in DOMAIN_DIMENSIONALITY_MODES:
        errors.append(
            f"  {case_path}: models.physics.dimensionality must be one of "
            f"{list(DOMAIN_DIMENSIONALITY_MODES)} (got '{dimensionality}')."
        )
 
    # --- case.yml: turbulence model validation ---
    turbulence_cfg = case_cfg.get('models', {}).get('physics', {}).get('turbulence', {})
    if turbulence_cfg is not None and not isinstance(turbulence_cfg, dict):
        errors.append(f"  {case_path}: 'models.physics.turbulence' must be a mapping.")
    elif isinstance(turbulence_cfg, dict) and turbulence_cfg:
        try:
            # Only the selectors are checked here and the flags are discarded, so unit
            # scales stand in for the case's, whose own validation runs separately.
            append_turbulence_flags(case_cfg.get('models', {}), [],
                                    {"length_ref": 1.0, "velocity_ref": 1.0})
        except ValueError as e:
            errors.append(f"  {case_path}: {e}")
 
        les_cfg = turbulence_cfg.get('les')
        rans_cfg = turbulence_cfg.get('rans')
        wall_cfg = turbulence_cfg.get('wall_function')
 
        if isinstance(les_cfg, dict):
            validate_les_configuration(case_cfg, les_cfg, case_path, errors, warnings)
 
        validate_wall_model_pairing(case_cfg, les_cfg, wall_cfg, case_path,
                                    errors, warnings)
 
        if rans_cfg is not None:
            errors.append(f"  {case_path}: {RANS_PLANNED_REFUSAL}")
 
        if isinstance(wall_cfg, dict):
            if 'enabled' in wall_cfg and not isinstance(wall_cfg['enabled'], bool):
                errors.append(f"  {case_path}: models.physics.turbulence.wall_function.enabled must be true or false.")
            if 'roughness_height' in wall_cfg:
                try:
                    value = float(wall_cfg['roughness_height'])
                    if value < 0.0:
                        errors.append(f"  {case_path}: models.physics.turbulence.wall_function.roughness_height must be nonnegative.")
                except (TypeError, ValueError):
                    errors.append(f"  {case_path}: models.physics.turbulence.wall_function.roughness_height must be numeric.")
                # Only the log law has a roughness formulation. Werner-Wengle has no
                # roughness term and Cabot discards the argument, so accepting the key
                # for either would silently ignore a value the user set deliberately.
                try:
                    wall_model = normalize_wall_function_model(wall_cfg.get('model'))
                except ValueError:
                    wall_model = None
                if wall_model in (2, 3):
                    errors.append(
                        f"  {case_path}: models.physics.turbulence.wall_function.roughness_height "
                        "applies only to model 'log_law'; 'werner' has no roughness formulation and "
                        "'cabot' ignores it. Remove the key or select 'log_law'.")
 
    # --- solver.yml: basic structure ---
    if not isinstance(solver_cfg, dict) or not solver_cfg:
        errors.append(f"  {solver_path}: solver config is empty or not a valid YAML mapping.")
    else:
        strategy_cfg = solver_cfg.get('strategy', {})
        if not isinstance(strategy_cfg, dict):
            errors.append(f"  {solver_path}: 'strategy' must be a mapping.")
        elif 'implicit' in strategy_cfg:
            errors.append(
                f"  {solver_path}: unsupported old key 'strategy.implicit' is not supported. "
                "Use 'strategy.momentum_solver' with named solver values."
            )
        if isinstance(strategy_cfg, dict) and 'momentum_solver' in strategy_cfg:
            try:
                normalize_momentum_solver_type(strategy_cfg['momentum_solver'])
            except ValueError as e:
                errors.append(f"  {solver_path}: {e}")
 
        op_mode_cfg = solver_cfg.get('operation_mode', {})
        if op_mode_cfg is not None and not isinstance(op_mode_cfg, dict):
            errors.append(f"  {solver_path}: 'operation_mode' must be a mapping when provided.")
        elif isinstance(op_mode_cfg, dict):
            eulerian_source_mode = None
            normalized_analytical_type = None
            if 'eulerian_field_source' in op_mode_cfg:
                try:
                    eulerian_source_mode = normalize_eulerian_field_source(op_mode_cfg.get('eulerian_field_source'))
                except ValueError as e:
                    errors.append(f"  {solver_path}: {e}")
 
            analytical_type = op_mode_cfg.get('analytical_type')
            if analytical_type is not None:
                try:
                    normalized_analytical_type = normalize_analytical_type(analytical_type)
                except ValueError as e:
                    errors.append(f"  {solver_path}: {e}")
                else:
                    uniform_flow_cfg = op_mode_cfg.get('uniform_flow')
                    if uniform_flow_cfg is not None and not isinstance(uniform_flow_cfg, dict):
                        errors.append(f"  {solver_path}: 'operation_mode.uniform_flow' must be a mapping when provided.")
                    elif normalized_analytical_type == "UNIFORM_FLOW":
                        if not isinstance(uniform_flow_cfg, dict):
                            errors.append(
                                f"  {solver_path}: operation_mode.uniform_flow is required when "
                                "operation_mode.analytical_type is 'UNIFORM_FLOW'."
                            )
                        else:
                            for coord in ("u", "v", "w"):
                                if coord not in uniform_flow_cfg:
                                    errors.append(
                                        f"  {solver_path}: operation_mode.uniform_flow.{coord} is required for UNIFORM_FLOW."
                                    )
                                else:
                                    try:
                                        float(uniform_flow_cfg[coord])
                                    except (TypeError, ValueError):
                                        errors.append(
                                            f"  {solver_path}: operation_mode.uniform_flow.{coord} must be numeric."
                                        )
                    elif uniform_flow_cfg is not None:
                        errors.append(
                            f"  {solver_path}: operation_mode.uniform_flow is only valid when "
                            "operation_mode.analytical_type is 'UNIFORM_FLOW'."
                        )
 
            if eulerian_source_mode == "analytical":
                effective_analytical_type = normalized_analytical_type or "TGV3D"
                if effective_analytical_type == "TGV3D":
                    # programmatic_c: the solver assigns the [0, 2*pi] TGV domain itself.
                    # file: the given grid is kept and the field is evaluated at its cell centres.
                    if grid_mode not in (GRID_MODES[1], GRID_MODES[0]):
                        errors.append(
                            f"  {case_path}: analytical type '{effective_analytical_type}' requires grid.mode "
                            "'programmatic_c' (solver-assigned TGV domain) or 'file' (a grid file the field "
                            "is evaluated on)."
                        )
                    elif grid_mode == 'programmatic_c' and isinstance(grid_cfg.get('programmatic_settings'), dict):
                        missing_dims = [key for key in ('im', 'jm', 'km') if key not in grid_cfg['programmatic_settings']]
                        if missing_dims:
                            errors.append(
                                f"  {case_path}: grid.programmatic_settings must include {missing_dims} when "
                                f"operation_mode.analytical_type resolves to '{effective_analytical_type}'."
                            )
                else:
                    if grid_mode not in (GRID_MODES[1], GRID_MODES[0]):
                        errors.append(
                            f"  {case_path}: grid.mode '{grid_mode}' is not supported when "
                            f"operation_mode.analytical_type is '{effective_analytical_type}'. "
                            "Use 'programmatic_c' or 'file'."
                        )
                    elif grid_mode == 'programmatic_c' and isinstance(grid_cfg.get('programmatic_settings'), dict):
                        missing_dims = [key for key in ('im', 'jm', 'km') if key not in grid_cfg['programmatic_settings']]
                        if missing_dims:
                            errors.append(
                                f"  {case_path}: grid.programmatic_settings must include {missing_dims} when "
                                f"operation_mode.analytical_type is '{effective_analytical_type}' and "
                                "grid.mode is 'programmatic_c'."
                            )
 
        verification_cfg = solver_cfg.get('verification', {})
        if verification_cfg is not None and not isinstance(verification_cfg, dict):
            errors.append(f"  {solver_path}: 'verification' must be a mapping when provided.")
        elif isinstance(verification_cfg, dict) and verification_cfg:
            sources_cfg = verification_cfg.get('sources', {})
            if sources_cfg is not None and not isinstance(sources_cfg, dict):
                errors.append(f"  {solver_path}: 'verification.sources' must be a mapping when provided.")
            elif isinstance(sources_cfg, dict) and sources_cfg:
                diff_cfg = sources_cfg.get('diffusivity')
                scalar_cfg = sources_cfg.get('scalar')
 
                if diff_cfg is not None:
                    if not isinstance(diff_cfg, dict):
                        errors.append(f"  {solver_path}: 'verification.sources.diffusivity' must be a mapping.")
                    else:
                        if eulerian_source_mode != "analytical":
                            errors.append(
                                f"  {solver_path}: verification.sources.diffusivity is only valid when "
                                "operation_mode.eulerian_field_source is 'analytical'."
                            )
                        mode = diff_cfg.get('mode')
                        profile = diff_cfg.get('profile')
                        if str(mode).strip().lower() != "analytical":
                            errors.append(
                                f"  {solver_path}: verification.sources.diffusivity.mode must be 'analytical'."
                            )
                        if str(profile).strip().upper() != "LINEAR_X":
                            errors.append(
                                f"  {solver_path}: verification.sources.diffusivity.profile must be 'LINEAR_X'."
                            )
                        for key in ("gamma0", "slope_x"):
                            if key not in diff_cfg:
                                errors.append(
                                    f"  {solver_path}: verification.sources.diffusivity.{key} is required."
                                )
                            else:
                                try:
                                    float(diff_cfg[key])
                                except (TypeError, ValueError):
                                    errors.append(
                                        f"  {solver_path}: verification.sources.diffusivity.{key} must be numeric."
                                    )
 
                if scalar_cfg is not None:
                    if not isinstance(scalar_cfg, dict):
                        errors.append(f"  {solver_path}: 'verification.sources.scalar' must be a mapping.")
                    else:
                        if eulerian_source_mode != "analytical":
                            errors.append(
                                f"  {solver_path}: verification.sources.scalar is only valid when "
                                "operation_mode.eulerian_field_source is 'analytical'."
                            )
                        mode = scalar_cfg.get('mode')
                        profile = str(scalar_cfg.get('profile', '')).strip().upper()
                        if str(mode).strip().lower() != "analytical":
                            errors.append(
                                f"  {solver_path}: verification.sources.scalar.mode must be 'analytical'."
                            )
                        if profile not in VERIFICATION_SCALAR_PROFILES:
                            errors.append(
                                f"  {solver_path}: verification.sources.scalar.profile must be one of CONSTANT, LINEAR_X, SIN_PRODUCT."
                            )
                        required_scalar_keys = {
                            "CONSTANT": ("value",),
                            "LINEAR_X": ("phi0", "slope_x"),
                            "SIN_PRODUCT": ("amplitude", "kx", "ky", "kz"),
                        }.get(profile, ())
                        for key in required_scalar_keys:
                            if key not in scalar_cfg:
                                errors.append(
                                    f"  {solver_path}: verification.sources.scalar.{key} is required for profile '{profile}'."
                                )
                            else:
                                try:
                                    float(scalar_cfg[key])
                                except (TypeError, ValueError):
                                    errors.append(
                                        f"  {solver_path}: verification.sources.scalar.{key} must be numeric."
                                    )
 
                unknown_source_keys = sorted(set(sources_cfg.keys()) - {"diffusivity", "scalar"})
                if unknown_source_keys:
                    errors.append(
                        f"  {solver_path}: unsupported verification.sources entries: {unknown_source_keys}. "
                        "Currently supported: 'diffusivity', 'scalar'."
                    )
            unknown_verification_keys = sorted(set(verification_cfg.keys()) - {"sources"})
            if unknown_verification_keys:
                errors.append(
                    f"  {solver_path}: unsupported verification keys: {unknown_verification_keys}. "
                    "Currently supported: 'sources'."
                )
 
        try:
            resolve_scalar_transport(case_cfg, solver_cfg, warn=True)
        except ValueError as exc:
            errors.append(f"  {solver_path}: {exc}")
        try:
            resolve_les_diagnostics(case_cfg, monitor_cfg, warn=True)
        except ValueError as exc:
            errors.append(f"  {monitor_path}: {exc}")
 
        tolerances_cfg = solver_cfg.get('tolerances', {})
        if tolerances_cfg is not None and not isinstance(tolerances_cfg, dict):
            errors.append(f"  {solver_path}: 'tolerances' must be a mapping when provided.")
        elif isinstance(tolerances_cfg, dict):
            for key in ("absolute_tol", "relative_tol", "residual_absolute_tol", "residual_relative_tol"):
                if key in tolerances_cfg:
                    try:
                        float(tolerances_cfg[key])
                    except (TypeError, ValueError):
                        errors.append(f"  {solver_path}: tolerances.{key} must be numeric.")
 
        ms_cfg = solver_cfg.get('momentum_solver', {})
        if ms_cfg is not None and not isinstance(ms_cfg, dict):
            errors.append(f"  {solver_path}: 'momentum_solver' must be a mapping when provided.")
        elif isinstance(ms_cfg, dict):
            unsupported_flat_keys = {
                'max_pseudo_steps', 'absolute_tol', 'relative_tol', 'step_tol',
                'pseudo_cfl', 'jameson_residual_noise_allowance_factor',
                'rk4_residual_noise_allowance_factor'
            }
            present_unsupported = sorted(unsupported_flat_keys.intersection(ms_cfg.keys()))
            if present_unsupported:
                errors.append(
                    f"  {solver_path}: unsupported flat keys in 'momentum_solver' are not supported: {present_unsupported}. "
                    "Use solver-specific sub-blocks (e.g., momentum_solver.dual_time_picard_jameson_rk)."
                )
 
            allowed_ms_keys = {'dual_time_picard_jameson_rk', 'dual_time_picard_rk4', 'newton_krylov'}
            unknown_ms_keys = sorted(set(ms_cfg.keys()) - allowed_ms_keys)
            if unknown_ms_keys:
                errors.append(
                    f"  {solver_path}: unsupported momentum_solver blocks/keys: {unknown_ms_keys}. "
                    "Currently supported: 'dual_time_picard_jameson_rk' and 'newton_krylov'."
                )
            if 'dual_time_picard_jameson_rk' in ms_cfg and 'dual_time_picard_rk4' in ms_cfg:
                errors.append(
                    f"  {solver_path}: use only momentum_solver.dual_time_picard_jameson_rk; "
                    "do not also set its deprecated dual_time_picard_rk4 alias."
                )
 
            selected_solver = None
            if isinstance(strategy_cfg, dict) and 'momentum_solver' in strategy_cfg:
                try:
                    selected_solver = normalize_momentum_solver_type(strategy_cfg['momentum_solver'])
                except ValueError:
                    pass
            if selected_solver is None:
                selected_solver = "DUALTIME_PICARD_JAMESON_RK"
 
            has_dualtime_block = (
                'dual_time_picard_jameson_rk' in ms_cfg or 'dual_time_picard_rk4' in ms_cfg
            )
            if selected_solver != "DUALTIME_PICARD_JAMESON_RK" and has_dualtime_block:
                errors.append(
                    f"  {solver_path}: momentum_solver.dual_time_picard_jameson_rk is set but selected solver is "
                    f"{selected_solver}. Solver-specific blocks must match the selected solver."
                )
 
            newton_cfg = ms_cfg.get('newton_krylov')
            if newton_cfg is not None:
                if selected_solver != "newton_krylov":
                    errors.append(
                        f"  {solver_path}: momentum_solver.newton_krylov is set but selected solver is "
                        f"{selected_solver}. Solver-specific blocks must match the selected solver."
                    )
                try:
                    validate_newton_krylov_config(newton_cfg)
                except ValueError as exc:
                    errors.append(f"  {solver_path}: {exc}")
 
            dt_picard_cfg = ms_cfg.get('dual_time_picard_jameson_rk', ms_cfg.get('dual_time_picard_rk4'))
            if dt_picard_cfg is not None:
                if not isinstance(dt_picard_cfg, dict):
                    errors.append(f"  {solver_path}: momentum_solver.dual_time_picard_jameson_rk must be a mapping.")
                else:
                    allowed_dt_keys = {
                        'max_pseudo_steps', 'absolute_tol', 'relative_tol', 'step_tol',
                        'pseudo_cfl', 'jameson_residual_noise_allowance_factor',
                        'rk4_residual_noise_allowance_factor', 'ratio_ema_alpha'
                    }
                    unknown_dt_keys = sorted(set(dt_picard_cfg.keys()) - allowed_dt_keys)
                    if unknown_dt_keys:
                        errors.append(
                            f"  {solver_path}: unsupported keys in momentum_solver.dual_time_picard_jameson_rk: {unknown_dt_keys}."
                        )
                    if ('jameson_residual_noise_allowance_factor' in dt_picard_cfg and
                            'rk4_residual_noise_allowance_factor' in dt_picard_cfg):
                        errors.append(
                            f"  {solver_path}: use only jameson_residual_noise_allowance_factor; "
                            "do not also set its deprecated rk4_residual_noise_allowance_factor alias."
                        )
                    if 'pseudo_cfl' in dt_picard_cfg:
                        pcfl_cfg = dt_picard_cfg['pseudo_cfl']
                        if not isinstance(pcfl_cfg, dict):
                            errors.append(f"  {solver_path}: momentum_solver.dual_time_picard_jameson_rk.pseudo_cfl must be a mapping.")
                        else:
                            allowed_pcfl_keys = {'initial', 'minimum', 'maximum', 'growth_factor', 'reduction_factor'}
                            unknown_pcfl_keys = sorted(set(pcfl_cfg.keys()) - allowed_pcfl_keys)
                            if unknown_pcfl_keys:
                                errors.append(
                                    f"  {solver_path}: unsupported keys in momentum_solver.dual_time_picard_jameson_rk.pseudo_cfl: {unknown_pcfl_keys}."
                                )
                            numeric_pcfl = {}
                            for key in allowed_pcfl_keys:
                                if key in pcfl_cfg:
                                    try:
                                        numeric_pcfl[key] = float(pcfl_cfg[key])
                                    except (TypeError, ValueError):
                                        errors.append(
                                            f"  {solver_path}: momentum_solver.dual_time_picard_jameson_rk.pseudo_cfl.{key} must be numeric."
                                        )
                            if numeric_pcfl.get('minimum', 1.0) <= 0.0:
                                errors.append(f"  {solver_path}: pseudo_cfl.minimum must be positive.")
                            if numeric_pcfl.get('growth_factor', 1.0) < 1.0:
                                errors.append(f"  {solver_path}: pseudo_cfl.growth_factor must be at least 1.")
                            reduction = numeric_pcfl.get('reduction_factor', 1.0)
                            if reduction <= 0.0 or reduction >= 1.0:
                                errors.append(f"  {solver_path}: pseudo_cfl.reduction_factor must be in (0, 1).")
                            if all(key in numeric_pcfl for key in ('minimum', 'initial', 'maximum')):
                                if not numeric_pcfl['minimum'] <= numeric_pcfl['initial'] <= numeric_pcfl['maximum']:
                                    errors.append(f"  {solver_path}: pseudo_cfl requires minimum <= initial <= maximum.")
                    noise_key = (
                        'jameson_residual_noise_allowance_factor'
                        if 'jameson_residual_noise_allowance_factor' in dt_picard_cfg
                        else 'rk4_residual_noise_allowance_factor'
                    )
                    if noise_key in dt_picard_cfg:
                        try:
                            if float(dt_picard_cfg[noise_key]) < 1.0:
                                errors.append(f"  {solver_path}: {noise_key} must be at least 1.")
                        except (TypeError, ValueError):
                            errors.append(f"  {solver_path}: {noise_key} must be numeric.")
                    if 'ratio_ema_alpha' in dt_picard_cfg:
                        try:
                            alpha_val = float(dt_picard_cfg['ratio_ema_alpha'])
                            if not 0.0 <= alpha_val <= 1.0:
                                errors.append(f"  {solver_path}: ratio_ema_alpha must be in [0, 1].")
                        except (TypeError, ValueError):
                            errors.append(f"  {solver_path}: ratio_ema_alpha must be numeric.")
 
    # --- solver.yml: interpolation section ---
    interp_cfg = solver_cfg.get('interpolation', {}) if isinstance(solver_cfg, dict) else {}
    if interp_cfg is not None and not isinstance(interp_cfg, dict):
        errors.append(f"  {solver_path}: 'interpolation' must be a mapping when provided.")
    elif isinstance(interp_cfg, dict) and 'method' in interp_cfg:
        try:
            interp_code = normalize_interpolation_method(interp_cfg['method'])
        except ValueError as e:
            errors.append(f"  {solver_path}: {e}")
        else:
            # FaceFlux reads the face fluxes; the analytical types other than UNIFORM_FLOW set Ucat only.
            op_mode = solver_cfg.get('operation_mode') if isinstance(solver_cfg.get('operation_mode'), dict) else {}
            if (interp_code == 2 and str(op_mode.get('eulerian_field_source', 'solve')).strip().lower() == 'analytical'
                    and str(op_mode.get('analytical_type', 'TGV3D')).strip().upper() != 'UNIFORM_FLOW'):
                errors.append(
                    f"  {solver_path}: interpolation.method 'FaceFlux' needs the face fluxes the flow is "
                    f"built from, which analytical type '{op_mode.get('analytical_type', 'TGV3D')}' does not set; "
                    "use 'Trilinear', or the UNIFORM_FLOW analytical type.")
 
    # --- monitor.yml: basic structure ---
    if not isinstance(monitor_cfg, dict) or not monitor_cfg:
        errors.append(f"  {monitor_path}: monitor config is empty or not a valid YAML mapping.")
    else:
        io_cfg = monitor_cfg.get('io', {})
        freq = io_cfg.get('data_output_frequency')
        if freq is not None and (not isinstance(freq, int) or freq <= 0):
            errors.append(f"  {monitor_path}: 'io.data_output_frequency' must be a positive integer (got {freq}).")
        for key in ('write_initial_checkpoint', 'write_final_checkpoint'):
            if key in io_cfg and not isinstance(io_cfg[key], bool):
                errors.append(f"  {monitor_path}: 'io.{key}' must be true or false (got {io_cfg[key]!r}).")
        try:
            physics_cfg = (case_cfg.get('models') or {}).get('physics') if isinstance(case_cfg, dict) and isinstance(case_cfg.get('models') or {}, dict) else None
            particles_cfg = physics_cfg.get('particles') if isinstance(physics_cfg, dict) else None
            particle_count = particles_cfg.get('count', 0) if isinstance(particles_cfg, dict) else 0
            if resolve_traced_particle_ids(monitor_cfg) and not particle_count:
                errors.append(f"  {monitor_path}: 'logging.trace_particles' needs particles; "
                              "models.physics.particles.count is 0.")
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        particle_console_freq = io_cfg.get('particle_console_output_frequency')
        if particle_console_freq is not None and (not isinstance(particle_console_freq, int) or particle_console_freq < 0):
            errors.append(
                f"  {monitor_path}: 'io.particle_console_output_frequency' must be a non-negative integer "
                f"(got {particle_console_freq})."
            )
        containment_errors, containment_warnings = validate_run_directory_containment(
            monitor_cfg, monitor_path
        )
        errors.extend(containment_errors)
        warnings.extend(containment_warnings)
        errors.extend(validate_reserved_directory_flags(
            monitor_cfg, monitor_path, "monitor passthrough"))
        try:
            resolve_profiling_config(monitor_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        try:
            resolve_diagnostics_config(monitor_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        try:
            resolve_solver_monitoring_flags(monitor_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        try:
            normalize_solution_monitoring_config(monitor_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
        statistics_console_freq = io_cfg.get('statistics_console_output_frequency')
        if statistics_console_freq is not None and (
                not isinstance(statistics_console_freq, int)
                or isinstance(statistics_console_freq, bool)
                or statistics_console_freq < 0):
            errors.append(
                f"  {monitor_path}: 'io.statistics_console_output_frequency' must be a non-negative "
                f"integer (got {statistics_console_freq})."
            )
        try:
            normalize_field_statistics_config(monitor_cfg, case_cfg)
        except ValueError as e:
            errors.append(f"  {monitor_path}: {e}")
 
    if not errors and not restart_source_given:
        if needs_restart_source(case_cfg, solver_cfg):
            warnings.append(
                f"{case_path}: This configuration requires restart data (start_step > 0, "
                "eulerian_field_source='load', or particle restart_mode='load'). "
                "Use --restart-from or --continue when running."
            )
 
    if errors:
        _print_validation_errors(errors)
    for warning in warnings:
        print(f"[WARNING] {warning}", file=sys.stderr)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

check_post_checkpoint_cadence_alignment()

"tuple[list, list]" picurv_cli.core.check_post_checkpoint_cadence_alignment	(	dict	post_cfg,
		dict	monitor_cfg,
		str	post_path,
		str	monitor_path = "monitor.yml"
	)

Report post step selections that cannot land on a committed checkpoint.

The post-processor reads committed bundles, and the solver commits one every io.data_output_frequency completed steps. A step_interval that is not a multiple of that cadence therefore asks for steps that were never written: those steps wait forever for a checkpoint, and far less than the recipe requested is processed. That is only discovered after a solve has already run, so it is caught here instead.

The solver also commits the initial and final states off cadence, which is why a misaligned start_step is a warning rather than an error: it may legitimately be the run's initial or final step. A bounded selection containing only one checkpoint has no stride to align; its interval must still be positive. Multi-checkpoint selections retain the cadence check.

Parameters

[in]	post_cfg	Parsed post-processing configuration.
[in]	monitor_cfg	Parsed monitor configuration governing the source run.
[in]	post_path	Path to the post file, for error messages.
[in]	monitor_path	Path to the monitor file, for error messages.

Returns

(errors, warnings), each a list of message strings. Both are empty when the comparison cannot be made, because the inputs that would make it meaningful are validated and reported elsewhere.

Definition at line 11000 of file core.py.

                                            monitor_path: str = "monitor.yml") -> "tuple[list, list]":
    """!
    @brief Report post step selections that cannot land on a committed checkpoint.
 
    @details The post-processor reads committed bundles, and the solver commits one
             every `io.data_output_frequency` completed steps. A `step_interval` that
             is not a multiple of that cadence therefore asks for steps that were
             never written: those steps wait forever for a checkpoint, and far less
             than the recipe requested is processed. That is only
             discovered after a solve has already run, so it is caught here instead.
 
             The solver also commits the initial and final states off cadence, which
             is why a misaligned `start_step` is a warning rather than an error: it
             may legitimately be the run's initial or final step. A bounded selection
             containing only one checkpoint has no stride to align; its interval must
             still be positive. Multi-checkpoint selections retain the cadence check.
 
    @param[in] post_cfg     Parsed post-processing configuration.
    @param[in] monitor_cfg  Parsed monitor configuration governing the source run.
    @param[in] post_path    Path to the post file, for error messages.
    @param[in] monitor_path Path to the monitor file, for error messages.
    @return `(errors, warnings)`, each a list of message strings. Both are empty when
            the comparison cannot be made, because the inputs that would make it
            meaningful are validated and reported elsewhere.
    """
    errors = []
    warnings = []
    if not isinstance(post_cfg, dict) or not isinstance(monitor_cfg, dict):
        return errors, warnings
 
    io_cfg = monitor_cfg.get("io") or {}
    if not isinstance(io_cfg, dict):
        return errors, warnings
    try:
        cadence = int(io_cfg["data_output_frequency"])
    except (KeyError, TypeError, ValueError):
        # A missing or malformed cadence is reported by the monitor's own checks.
        return errors, warnings
    # A disabled cadence commits only the initial and final states, so there is no
    # stride to align to.
    if cadence <= 0:
        return errors, warnings
 
    try:
        start_step, end_step, step_interval = resolve_post_requested_window(post_cfg)
    except (TypeError, ValueError):
        # Reported by the run_control checks, which run against the same values.
        return errors, warnings
 
    single_checkpoint = end_step >= start_step and end_step - start_step < step_interval
    if not single_checkpoint and step_interval % cadence != 0:
        suggestion = max(cadence, (step_interval // cadence) * cadence)
        errors.append(
            f"  {post_path}: 'run_control.step_interval' is {step_interval}, which is not a "
            f"multiple of 'io.data_output_frequency' ({cadence}) in {monitor_path}. The solver "
            f"only commits a checkpoint every {cadence} steps, so most requested steps were "
            f"never written and post-processing would stop at the first missing one. Use "
            f"{suggestion}, or another multiple of {cadence}, or lower the monitor cadence."
        )
 
    if start_step > 0 and start_step % cadence != 0:
        warnings.append(
            f"{post_path}: 'run_control.start_step' is {start_step}, which is not a multiple of "
            f"'io.data_output_frequency' ({cadence}) in {monitor_path}. That step only exists if "
            f"it is the run's initial or final step, which is committed off cadence."
        )
 
    return errors, warnings
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

validate_post_config()

picurv_cli.core.validate_post_config	(	dict	post_cfg,
		str	post_path,
		dict	monitor_cfg = None,
		dict	case_cfg = None
	)

Validates the post-processing config before running the post-processor.

Parameters

[in]	post_cfg	Parsed post-processing YAML dictionary.
[in]	post_path	Path to post file (for error messages).
[in]	monitor_cfg	Parsed monitor configuration, when available. Two checks span both files: field statistics, where post.yml names the windows and monitor.yml decides what each accumulates, and step cadence, where monitor.yml decides which steps exist to be read. Both run only when the monitor is known.
[in]	case_cfg	Parsed case configuration, when available. Spectra preconditions need the boundary conditions and block count, so they are checked only when the case is known; validating a recipe on its own still checks it on its own terms.

Exceptions

SystemExit

on validation failure.

Definition at line 11071 of file core.py.

def validate_post_config(post_cfg: dict, post_path: str, monitor_cfg: dict = None, case_cfg: dict = None):
    """!
    @brief Validates the post-processing config before running the post-processor.
    @param[in] post_cfg  Parsed post-processing YAML dictionary.
    @param[in] post_path Path to post file (for error messages).
    @param[in] monitor_cfg Parsed monitor configuration, when available. Two checks
                           span both files: field statistics, where post.yml names
                           the windows and monitor.yml decides what each accumulates,
                           and step cadence, where monitor.yml decides which steps
                           exist to be read. Both run only when the monitor is known.
    @param[in] case_cfg Parsed case configuration, when available. Spectra
                        preconditions need the boundary conditions and block count, so
                        they are checked only when the case is known; validating a
                        recipe on its own still checks it on its own terms.
    @throws SystemExit on validation failure.
    """
    errors = []
    warnings = []
 
    _validate_yaml_schema_keys(post_cfg, _POST_SCHEMA, post_path, errors)
 
    try:
        recipe = normalize_post_field_statistics_config(post_cfg)
    except ValueError as e:
        recipe = None
        errors.append(f"  {post_path}: {e}")
 
    try:
        spectra_recipe = normalize_post_spectra_config(post_cfg)
    except ValueError as e:
        spectra_recipe = None
        errors.append(f"  {post_path}: {e}")
    if recipe is not None:
        try:
            normalize_post_reducers_config(post_cfg)
        except ValueError as e:
            errors.append(f"  {post_path}: {e}")
    if spectra_recipe and spectra_recipe["tasks"] and case_cfg is not None:
        errors.extend(validate_post_spectra_preconditions(spectra_recipe, case_cfg, post_path))
    if recipe and recipe["windows"] and monitor_cfg is not None:
        try:
            configured = normalize_field_statistics_config(monitor_cfg)
        except ValueError:
            # The monitor file reports its own errors; do not repeat them here.
            configured = None
        if configured is not None:
            if not configured["enabled"]:
                errors.append(
                    f"  {post_path}: field statistics are requested, but "
                    "'field_statistics.enabled' is not set in the monitor configuration, so no "
                    "window is accumulated."
                )
            else:
                by_name = {window["name"]: window for window in configured["windows"]}
                for name in recipe["windows"]:
                    if name not in by_name:
                        errors.append(
                            f"  {post_path}: field-statistics window '{name}' is not defined in "
                            f"the monitor configuration. Defined windows: {sorted(by_name)}."
                        )
                    elif _post_window_derived_field_count(by_name[name], recipe["outputs"]) == 0:
                        errors.append(
                            f"  {post_path}: outputs {recipe['outputs']} produce no field for "
                            f"window '{name}'; it accumulates none of the state they need. Add "
                            "'second' to a field's moments for stresses, RMS, or turbulent "
                            "kinetic energy, or a covariance for a flux."
                        )
 
    for ensemble in (recipe or {}).get("ensembles", []):
        eligible = _ensemble_source_fields(ensemble["source"])
        if _post_window_derived_field_count(ensemble, recipe["outputs"], eligible) == 0:
            errors.append(
                f"  {post_path}: outputs {recipe['outputs']} produce no field for ensemble "
                f"'{ensemble['name']}'; add 'second' to a field's moments or a covariance."
            )
        if case_cfg is not None:
            requirements = {eligible[entry["field"]]["requires"] for entry in ensemble["fields"]}
            for requirement in sorted(r for r in requirements if r):
                if not _statistics_subsystem_available(case_cfg, requirement):
                    errors.append(
                        f"  {post_path}: ensemble '{ensemble['name']}' needs the '{requirement}' "
                        "subsystem, which is not enabled for this case."
                    )
 
    if not isinstance(post_cfg, dict) or not post_cfg:
        errors.append(f"  {post_path}: post-processing config is empty or not a valid YAML mapping.")
        _print_validation_errors(errors)
 
    # --- run_control ---
    if 'run_control' not in post_cfg:
        errors.append(f"  {post_path}: missing required section 'run_control'.")
    else:
        rc = post_cfg.get('run_control', {})
        if not isinstance(rc, dict):
            errors.append(f"  {post_path}: 'run_control' must be a mapping.")
        else:
            for canonical_key, aliases in POST_RUN_CONTROL_ALIASES.items():
                if not any(alias in rc for alias in aliases):
                    alias_list = "', '".join(aliases)
                    errors.append(
                        f"  {post_path}: missing required key 'run_control.{canonical_key}' "
                        f"(accepted aliases: '{alias_list}')."
                    )
                    continue
                raw_value = _mapping_value_with_aliases(rc, *aliases)
                try:
                    value = int(raw_value)
                    if canonical_key == "step_interval" and value <= 0:
                        errors.append(f"  {post_path}: 'run_control.step_interval' must be positive.")
                except (TypeError, ValueError):
                    alias_name = next((alias for alias in aliases if alias in rc), canonical_key)
                    errors.append(
                        f"  {post_path}: 'run_control.{alias_name}' must be an integer-compatible value."
                    )
 
    # --- io section ---
    io_cfg = post_cfg.get('io', {})
    source_cfg = post_cfg.get('source_data')
    if source_cfg is not None and not isinstance(source_cfg, dict):
        errors.append(f"  {post_path}: 'source_data' must be a mapping when provided.")
    global_ops = post_cfg.get('global_operations')
    if global_ops is not None:
        if not isinstance(global_ops, dict):
            errors.append(f"  {post_path}: 'global_operations' must be a mapping when provided.")
        elif 'dimensionalize' in global_ops and not isinstance(global_ops.get('dimensionalize'), bool):
            errors.append(f"  {post_path}: 'global_operations.dimensionalize' must be a boolean.")
    if not io_cfg:
        errors.append(f"  {post_path}: missing required section 'io'.")
    elif not isinstance(io_cfg, dict):
        errors.append(f"  {post_path}: 'io' must be a mapping.")
    else:
        for k in ['output_filename_prefix']:
            if k not in io_cfg:
                errors.append(f"  {post_path}: missing required key 'io.{k}'.")
        for key_name in ('output_directory', 'output_filename_prefix', 'particle_filename_prefix'):
            if key_name in io_cfg and not isinstance(io_cfg.get(key_name), str):
                errors.append(f"  {post_path}: 'io.{key_name}' must be a string when provided.")
        # The conductor files every post artifact by recipe identity, which excludes
        # this key, so two recipes differing only in it write over each other.
        if 'output_directory' in io_cfg:
            warnings.append(
                f"{post_path}: 'io.output_directory' is ignored; post output goes to the run's "
                "visualization and analysis directories under the recipe's identity, so recipes "
                "differing only in this key share one home and overwrite each other. Change "
                "'io.output_filename_prefix' to keep them apart."
            )
        if 'output_particles' in io_cfg and not isinstance(io_cfg.get('output_particles'), bool):
            errors.append(f"  {post_path}: 'io.output_particles' must be a boolean when provided.")
        try:
            normalize_post_paraview_series_config(post_cfg)
        except ValueError as exc:
            errors.append(f"  {post_path}: {exc}")
        particle_subsampling_frequency = io_cfg.get('particle_subsampling_frequency')
        if particle_subsampling_frequency is not None:
            if not isinstance(particle_subsampling_frequency, int) or particle_subsampling_frequency <= 0:
                errors.append(
                    f"  {post_path}: 'io.particle_subsampling_frequency' must be a positive integer when provided."
                )
        input_extensions = io_cfg.get('input_extensions')
        source_input_extensions = get_post_source_data(post_cfg).get('input_extensions')
        if input_extensions is not None:
            if not isinstance(input_extensions, dict):
                errors.append(f"  {post_path}: 'io.input_extensions' must be a mapping when provided.")
            else:
                for ext_key in ('eulerian', 'particle'):
                    ext_val = input_extensions.get(ext_key)
                    if ext_val is not None and not isinstance(ext_val, str):
                        errors.append(f"  {post_path}: 'io.input_extensions.{ext_key}' must be a string extension.")
                    elif ext_val is not None and str(ext_val).strip().lstrip('.').lower() != 'dat':
                        errors.append(
                            f"  {post_path}: 'io.input_extensions.{ext_key}' must be 'dat'; "
                            "committed checkpoint payload names are fixed."
                        )
        if source_input_extensions is not None:
            if not isinstance(source_input_extensions, dict):
                errors.append(f"  {post_path}: 'source_data.input_extensions' must be a mapping when provided.")
            else:
                for ext_key in ('eulerian', 'particle'):
                    ext_val = source_input_extensions.get(ext_key)
                    if ext_val is not None and not isinstance(ext_val, str):
                        errors.append(
                            f"  {post_path}: 'source_data.input_extensions.{ext_key}' must be a string extension."
                        )
                    elif ext_val is not None and str(ext_val).strip().lstrip('.').lower() != 'dat':
                        errors.append(
                            f"  {post_path}: 'source_data.input_extensions.{ext_key}' must be 'dat'; "
                            "committed checkpoint payload names are fixed."
                        )
 
        for list_key in ('eulerian_fields', 'particle_fields'):
            list_val = io_cfg.get(list_key)
            if list_val is not None and (not isinstance(list_val, list)
                                         or not all(isinstance(item, str) for item in list_val)):
                errors.append(f"  {post_path}: 'io.{list_key}' must be a list of field names when provided.")
        # The nodal_average inputs are computed at cell centres, and a .vts carries point data
        # only: the writer skips them, so a listed one would silently never reach the file.
        eulerian_fields = io_cfg.get('eulerian_fields')
        for cell_field in ('Ucat', 'P', 'Psi', 'Qcrit'):
            if isinstance(eulerian_fields, list) and cell_field in eulerian_fields:
                after = " after q_criterion" if cell_field == 'Qcrit' else ""
                errors.append(
                    f"  {post_path}: 'io.eulerian_fields' lists '{cell_field}', which is cell-centred and "
                    f"cannot be written as point data. Add a nodal_average task (input_field: {cell_field}, "
                    f"output_field: {cell_field}_nodal){after} and write '{cell_field}_nodal'."
                )
 
    # --- Check eulerian_pipeline entries have 'task' key ---
    eulerian_pipeline = post_cfg.get('eulerian_pipeline', [])
    if eulerian_pipeline is not None and not isinstance(eulerian_pipeline, list):
        errors.append(f"  {post_path}: 'eulerian_pipeline' must be a list when provided.")
        eulerian_pipeline = []
    for i, entry in enumerate(eulerian_pipeline):
        if not isinstance(entry, dict) or 'task' not in entry:
            errors.append(f"  {post_path}: 'eulerian_pipeline[{i}]' is missing the 'task' key. "
                          "Check YAML indentation (each entry needs '- task: ...' with proper spacing).")
            continue
        task_name = entry.get('task')
        if task_name == 'q_criterion':
            continue
        if task_name == 'nodal_average':
            in_field = entry.get('input_field')
            out_field = entry.get('output_field')
            if not isinstance(in_field, str) or not in_field.strip():
                errors.append(f"  {post_path}: 'eulerian_pipeline[{i}].input_field' must be a non-empty string.")
            if not isinstance(out_field, str) or not out_field.strip():
                errors.append(f"  {post_path}: 'eulerian_pipeline[{i}].output_field' must be a non-empty string.")
            if isinstance(in_field, str) and isinstance(out_field, str) and in_field == out_field:
                errors.append(
                    f"  {post_path}: 'eulerian_pipeline[{i}]' nodal_average input and output fields must differ."
                )
            continue
        if task_name == 'normalize_field':
            field = entry.get('field', 'P')
            if not isinstance(field, str) or not field.strip():
                errors.append(f"  {post_path}: 'eulerian_pipeline[{i}].field' must be a non-empty string.")
            elif field != 'P':
                errors.append(
                    f"  {post_path}: 'eulerian_pipeline[{i}].field' currently only supports 'P' "
                    f"(got '{field}')."
                )
            reference_point = entry.get('reference_point', [1, 1, 1])
            if not isinstance(reference_point, (list, tuple)) or len(reference_point) != 3:
                errors.append(
                    f"  {post_path}: 'eulerian_pipeline[{i}].reference_point' must be a 3-item list."
                )
            else:
                for rp_idx, coord in enumerate(reference_point):
                    try:
                        int(coord)
                    except (TypeError, ValueError):
                        errors.append(
                            f"  {post_path}: 'eulerian_pipeline[{i}].reference_point[{rp_idx}]' "
                            "must be integer-compatible."
                        )
            continue
        errors.append(
            f"  {post_path}: unsupported eulerian task '{task_name}' at eulerian_pipeline[{i}]. "
            f"Available tasks: {list(POST_EULERIAN_PIPELINE_TASKS)}."
        )
 
    # --- Check lagrangian_pipeline entries have 'task' key ---
    lagrangian_pipeline = post_cfg.get('lagrangian_pipeline', [])
    if lagrangian_pipeline is not None and not isinstance(lagrangian_pipeline, list):
        errors.append(f"  {post_path}: 'lagrangian_pipeline' must be a list when provided.")
        lagrangian_pipeline = []
    for i, entry in enumerate(lagrangian_pipeline):
        if not isinstance(entry, dict) or 'task' not in entry:
            errors.append(f"  {post_path}: 'lagrangian_pipeline[{i}]' is missing the 'task' key.")
            continue
        task_name = entry.get('task')
        if task_name == 'specific_ke':
            in_field = entry.get('input_field')
            out_field = entry.get('output_field')
            if not isinstance(in_field, str) or not in_field.strip():
                errors.append(f"  {post_path}: 'lagrangian_pipeline[{i}].input_field' must be a non-empty string.")
            if not isinstance(out_field, str) or not out_field.strip():
                errors.append(f"  {post_path}: 'lagrangian_pipeline[{i}].output_field' must be a non-empty string.")
            continue
        errors.append(
            f"  {post_path}: unsupported lagrangian task '{task_name}' at lagrangian_pipeline[{i}]."
        )
 
    # --- Check statistics pipeline entries ---
    stats_cfg = post_cfg.get('statistics_pipeline')
    stats_entries = []
    if stats_cfg is not None:
        if isinstance(stats_cfg, list):
            stats_entries = stats_cfg
        elif isinstance(stats_cfg, dict):
            stats_entries = stats_cfg.get('tasks', [])
            if not isinstance(stats_entries, list):
                errors.append(f"  {post_path}: 'statistics_pipeline.tasks' must be a list.")
            stats_output_prefix = stats_cfg.get('output_prefix')
            if stats_output_prefix is not None and not isinstance(stats_output_prefix, str):
                errors.append(f"  {post_path}: 'statistics_pipeline.output_prefix' must be a string.")
        else:
            errors.append(
                f"  {post_path}: 'statistics_pipeline' must be either a list of tasks or a mapping with a 'tasks' list."
            )
        for i, entry in enumerate(stats_entries):
            if isinstance(entry, str):
                task_name = entry
            elif isinstance(entry, dict) and 'task' in entry:
                task_name = entry.get('task')
            else:
                errors.append(
                    f"  {post_path}: statistics task entry {i} must be either a string or a mapping with key 'task'."
                )
                continue
            try:
                normalize_statistics_task(task_name)
            except ValueError as e:
                errors.append(f"  {post_path}: {e}")
 
    # MSD measures displacement from the configured point source, not from each
    # particle's own start. Any other seeding leaves that point unset - the coordinate
    # origin - and the statistic measures distance from the origin instead. With no
    # particles the task writes nothing, so only a seeded case is refused.
    if case_cfg is not None and "ComputeMSD" in get_post_statistics_task_tokens(post_cfg):
        particles_cfg = (((case_cfg.get('models') or {}).get('physics') or {}).get('particles') or {})
        try:
            particle_count = int(particles_cfg.get('count', 0) or 0)
        except (TypeError, ValueError):
            particle_count = 0
        init_mode = particles_cfg.get('init_mode', 'Surface')
        try:
            is_point_source = normalize_particle_init_mode(init_mode) == 2
        except ValueError:
            is_point_source = True  # the case file reports its own init_mode error
        if particle_count > 0 and not is_point_source:
            errors.append(
                f"  {post_path}: statistics task 'msd' measures displacement from "
                f"models.physics.particles.point_source, so it requires init_mode: PointSource "
                f"(the case seeds with '{init_mode}')."
            )
 
    legacy_stats_output_prefix = post_cfg.get('statistics_output_prefix')
    if legacy_stats_output_prefix is not None and not isinstance(legacy_stats_output_prefix, str):
        errors.append(f"  {post_path}: 'statistics_output_prefix' must be a string when provided.")
 
    # Runs last so it reports against values the run_control checks above have
    # already established are integers.
    cadence_errors, cadence_warnings = check_post_checkpoint_cadence_alignment(
        post_cfg, monitor_cfg, post_path)
    errors.extend(cadence_errors)
    warnings.extend(cadence_warnings)
 
    if errors:
        _print_validation_errors(errors)
    for warning in warnings:
        print(f"[WARNING] {warning}", file=sys.stderr)
 

Here is the call graph for this function:

Here is the caller graph for this function:

validate_cluster_config()

picurv_cli.core.validate_cluster_config	(	dict	cluster_cfg,
		str	cluster_path
	)

Validate Slurm scheduler configuration from cluster.yml.

Parameters

[in]	cluster_cfg	Argument passed to validate_cluster_config().
[in]	cluster_path	Argument passed to validate_cluster_config().

Definition at line 11423 of file core.py.

def validate_cluster_config(cluster_cfg: dict, cluster_path: str):
    """!
    @brief Validate Slurm scheduler configuration from cluster.yml.
    @param[in] cluster_cfg Argument passed to `validate_cluster_config()`.
    @param[in] cluster_path Argument passed to `validate_cluster_config()`.
    """
    errors = []
    warnings = []
    _validate_yaml_schema_keys(cluster_cfg, _CLUSTER_SCHEMA, cluster_path, errors)
    if not isinstance(cluster_cfg, dict) or not cluster_cfg:
        errors.append(f"  {cluster_path}: cluster config is empty or not a valid YAML mapping.")
        _print_validation_errors(errors)
 
    scheduler = cluster_cfg.get("scheduler", {})
    if not isinstance(scheduler, dict):
        errors.append(f"  {cluster_path}: 'scheduler' must be a mapping.")
    else:
        scheduler_type = scheduler.get("type", "slurm")
        if str(scheduler_type).lower() != "slurm":
            errors.append(f"  {cluster_path}: scheduler.type must be 'slurm' in v1 (got '{scheduler_type}').")
 
    resources = cluster_cfg.get("resources", {})
    if not isinstance(resources, dict):
        errors.append(f"  {cluster_path}: 'resources' must be a mapping.")
    else:
        for req in ("account", "nodes", "ntasks_per_node", "mem", "time"):
            if req not in resources:
                errors.append(f"  {cluster_path}: missing required key 'resources.{req}'.")
        for int_key in ("nodes", "ntasks_per_node"):
            if int_key in resources:
                val = resources.get(int_key)
                if not isinstance(val, int) or val <= 0:
                    errors.append(f"  {cluster_path}: resources.{int_key} must be a positive integer (got {val}).")
        for str_key in ("account", "mem", "time", "partition"):
            if str_key in resources and resources.get(str_key) is not None:
                if not isinstance(resources.get(str_key), str):
                    errors.append(f"  {cluster_path}: resources.{str_key} must be a string when provided.")
        if isinstance(resources.get("time"), str):
            try:
                parse_slurm_time_limit_to_seconds(resources["time"])
            except ValueError as exc:
                errors.append(
                    f"  {cluster_path}: resources.time must be a supported finite Slurm time string ({exc})."
                )
        account = resources.get("account")
        if account == CLUSTER_TEMPLATE_PLACEHOLDER_ACCOUNT:
            warnings.append(
                f"{cluster_path}: resources.account still uses the sample placeholder "
                f"'{CLUSTER_TEMPLATE_PLACEHOLDER_ACCOUNT}'. Edit the cluster profile before submission."
            )
 
    notifications = cluster_cfg.get("notifications", {})
    if notifications is not None and not isinstance(notifications, dict):
        errors.append(f"  {cluster_path}: 'notifications' must be a mapping when provided.")
    elif isinstance(notifications, dict):
        mail_user = notifications.get("mail_user")
        if mail_user is not None and not is_valid_email(mail_user):
            errors.append(f"  {cluster_path}: notifications.mail_user is not a valid email '{mail_user}'.")
        if mail_user == CLUSTER_TEMPLATE_PLACEHOLDER_MAIL:
            warnings.append(
                f"{cluster_path}: notifications.mail_user still uses the sample placeholder "
                f"'{CLUSTER_TEMPLATE_PLACEHOLDER_MAIL}'. Edit the cluster profile before submission."
            )
        mail_type = notifications.get("mail_type")
        if mail_type is not None and not isinstance(mail_type, str):
            errors.append(f"  {cluster_path}: notifications.mail_type must be a string when provided.")
 
    execution = cluster_cfg.get("execution", {})
    if execution is not None and not isinstance(execution, dict):
        errors.append(f"  {cluster_path}: 'execution' must be a mapping when provided.")
    elif isinstance(execution, dict):
        module_setup = execution.get("module_setup", [])
        if module_setup is not None and not isinstance(module_setup, list):
            errors.append(f"  {cluster_path}: execution.module_setup must be a list of shell lines.")
        elif isinstance(module_setup, list):
            for i, line in enumerate(module_setup):
                if not isinstance(line, str):
                    errors.append(f"  {cluster_path}: execution.module_setup[{i}] must be a string.")
 
        launcher = execution.get("launcher")
        if launcher is not None and not isinstance(launcher, str):
            errors.append(f"  {cluster_path}: execution.launcher must be a string when provided.")
        launcher_args = execution.get("launcher_args")
        if launcher_args is not None and not isinstance(launcher_args, list):
            errors.append(f"  {cluster_path}: execution.launcher_args must be a list of CLI tokens.")
        elif isinstance(launcher_args, list):
            for i, token in enumerate(launcher_args):
                if not isinstance(token, (str, int, float)):
                    errors.append(f"  {cluster_path}: execution.launcher_args[{i}] must be a scalar CLI token.")
                elif _launcher_arg_contains_whitespace(token):
                    errors.append(
                        f"  {cluster_path}: execution.launcher_args[{i}] must be a single CLI token; "
                        "split whitespace-separated arguments into separate list items."
                    )
        if (launcher is None or isinstance(launcher, str)) and (launcher_args is None or isinstance(launcher_args, list)):
            try:
                normalize_cluster_launcher(execution)
            except ValueError as exc:
                errors.append(f"  {cluster_path}: {exc}.")
 
        extra_sbatch = execution.get("extra_sbatch")
        if extra_sbatch is not None and not isinstance(extra_sbatch, (dict, list)):
            errors.append(f"  {cluster_path}: execution.extra_sbatch must be a mapping or list when provided.")
 
        walltime_guard = execution.get("walltime_guard")
        if walltime_guard is not None and not isinstance(walltime_guard, dict):
            errors.append(f"  {cluster_path}: execution.walltime_guard must be a mapping when provided.")
        elif isinstance(walltime_guard, dict):
            enabled = walltime_guard.get("enabled")
            if enabled is not None and not isinstance(enabled, bool):
                errors.append(f"  {cluster_path}: execution.walltime_guard.enabled must be boolean when provided.")
 
            warmup_steps = walltime_guard.get("warmup_steps")
            if warmup_steps is not None and (not isinstance(warmup_steps, int) or isinstance(warmup_steps, bool) or warmup_steps <= 0):
                errors.append(
                    f"  {cluster_path}: execution.walltime_guard.warmup_steps must be a positive integer when provided."
                )
 
            multiplier = walltime_guard.get("multiplier")
            if multiplier is not None:
                if isinstance(multiplier, bool) or not isinstance(multiplier, (int, float)) or multiplier <= 0.0:
                    errors.append(
                        f"  {cluster_path}: execution.walltime_guard.multiplier must be a positive number when provided."
                    )
                elif float(multiplier) > 5.0:
                    errors.append(
                        f"  {cluster_path}: execution.walltime_guard.multiplier must be <= 5.0 (got {multiplier})."
                    )
 
            min_seconds = walltime_guard.get("min_seconds")
            if min_seconds is not None and (
                isinstance(min_seconds, bool) or not isinstance(min_seconds, (int, float)) or float(min_seconds) <= 0.0
            ):
                errors.append(
                    f"  {cluster_path}: execution.walltime_guard.min_seconds must be a positive number when provided."
                )
 
            estimator_alpha = walltime_guard.get("estimator_alpha")
            if estimator_alpha is not None:
                if isinstance(estimator_alpha, bool) or not isinstance(estimator_alpha, (int, float)):
                    errors.append(
                        f"  {cluster_path}: execution.walltime_guard.estimator_alpha must be a number in (0, 1] when provided."
                    )
                elif float(estimator_alpha) <= 0.0 or float(estimator_alpha) > 1.0:
                    errors.append(
                        f"  {cluster_path}: execution.walltime_guard.estimator_alpha must be in (0, 1] (got {estimator_alpha})."
                    )
 
    if warnings:
        for warning in warnings:
            print(f"[WARNING] {warning}", file=sys.stderr)
 
    if errors:
        _print_validation_errors(errors)
 

Here is the call graph for this function:

Here is the caller graph for this function:

validate_study_config()

picurv_cli.core.validate_study_config	(	dict	study_cfg,
		str	study_path,
		bool	skip_base_file_check = False
	)

Validate sweep/study specification from study.yml.

Parameters

[in]	study_cfg	Argument passed to validate_study_config().
[in]	study_path	Argument passed to validate_study_config().
[in]	skip_base_file_check	When True, skip file-existence check for base_configs paths.

Definition at line 11578 of file core.py.

def validate_study_config(study_cfg: dict, study_path: str, skip_base_file_check: bool = False):
    """!
    @brief Validate sweep/study specification from study.yml.
    @param[in] study_cfg Argument passed to `validate_study_config()`.
    @param[in] study_path Argument passed to `validate_study_config()`.
    @param[in] skip_base_file_check When True, skip file-existence check for base_configs paths.
    """
    errors = []
    _validate_yaml_schema_keys(study_cfg, _STUDY_SCHEMA, study_path, errors)
    if not isinstance(study_cfg, dict) or not study_cfg:
        errors.append(f"  {study_path}: study config is empty or not a valid YAML mapping.")
        _print_validation_errors(errors)
 
    base_cfgs = study_cfg.get("base_configs")
    if not isinstance(base_cfgs, dict):
        errors.append(f"  {study_path}: missing required mapping 'base_configs'.")
    else:
        for req in ("case", "solver", "monitor", "post"):
            path_val = base_cfgs.get(req)
            if not path_val or not isinstance(path_val, str):
                errors.append(f"  {study_path}: base_configs.{req} must be a path string.")
            elif not skip_base_file_check:
                resolved = resolve_path(study_path, path_val)
                if not os.path.isfile(resolved):
                    errors.append(f"  {study_path}: base_configs.{req} does not exist: {resolved}")
 
    study_type = study_cfg.get("study_type")
    allowed_types = set(STUDY_TYPES)
    if study_type not in allowed_types:
        errors.append(
            f"  {study_path}: study_type must be one of {sorted(allowed_types)} (got '{study_type}')."
        )
 
    parameters = study_cfg.get("parameters")
    parameter_sets = study_cfg.get("parameter_sets")
    allowed_roots = {"case", "solver", "monitor", "post"}
    if bool(parameters) == bool(parameter_sets):
        errors.append(f"  {study_path}: provide exactly one of 'parameters' or 'parameter_sets'.")
    elif parameter_sets:
        if not isinstance(parameter_sets, list) or not parameter_sets:
            errors.append(f"  {study_path}: 'parameter_sets' must be a non-empty list of key->value mappings.")
        else:
            for set_index, param_set in enumerate(parameter_sets):
                if not isinstance(param_set, dict) or not param_set:
                    errors.append(
                        f"  {study_path}: parameter_sets[{set_index}] must be a non-empty mapping of key->value overrides."
                    )
                    continue
                for key, value in param_set.items():
                    if not isinstance(key, str) or "." not in key:
                        errors.append(
                            f"  {study_path}: parameter_sets[{set_index}] key '{key}' must use '<target>.<yaml.path>' format."
                        )
                        continue
                    root = key.split(".", 1)[0]
                    if root not in allowed_roots:
                        errors.append(
                            f"  {study_path}: parameter_sets[{set_index}] key '{key}' must start with one of {sorted(allowed_roots)}."
                        )
                    if isinstance(value, (dict, list)):
                        errors.append(
                            f"  {study_path}: parameter_sets[{set_index}] value for '{key}' must be a scalar, not {type(value).__name__}."
                        )
    else:
        if not isinstance(parameters, dict) or not parameters:
            errors.append(f"  {study_path}: 'parameters' must be a non-empty mapping of key->list.")
        else:
            for key, values in parameters.items():
                if not isinstance(key, str) or "." not in key:
                    errors.append(
                        f"  {study_path}: parameter key '{key}' must use '<target>.<yaml.path>' format."
                    )
                    continue
                root = key.split(".", 1)[0]
                if root not in allowed_roots:
                    errors.append(
                        f"  {study_path}: parameter key '{key}' must start with one of {sorted(allowed_roots)}."
                    )
                if not isinstance(values, list) or len(values) == 0:
                    errors.append(f"  {study_path}: parameters.{key} must be a non-empty list.")
 
    metrics = study_cfg.get("metrics", [])
    if metrics is not None and not isinstance(metrics, list):
        errors.append(f"  {study_path}: 'metrics' must be a list when provided.")
    elif isinstance(metrics, list):
        for i, metric in enumerate(metrics):
            if isinstance(metric, str):
                continue
            if not isinstance(metric, dict):
                errors.append(
                    f"  {study_path}: metrics[{i}] must be a string or mapping."
                )
                continue
            if "name" not in metric:
                errors.append(f"  {study_path}: metrics[{i}] missing required key 'name'.")
            if "source" not in metric:
                errors.append(f"  {study_path}: metrics[{i}] missing required key 'source'.")
            if str(metric.get("source", "")).strip().lower() in METRIC_SOURCE_KINDS[2:]:
                # extract_metric_from_log reads group(1); without it every case scores empty.
                regex = metric.get("regex")
                try:
                    has_group = isinstance(regex, str) and re.compile(regex).groups >= 1
                except re.error:
                    has_group = False
                if not has_group:
                    errors.append(
                        f"  {study_path}: metrics[{i}].regex must be a valid regular expression "
                        "with a capture group for the value when source is a log."
                    )
            for label_key in ("plot_label", "label", "units"):
                label_value = metric.get(label_key)
                if label_value is not None and (not isinstance(label_value, str) or not label_value.strip()):
                    errors.append(
                        f"  {study_path}: metrics[{i}].{label_key} must be a non-empty string when provided."
                    )
 
    plotting = study_cfg.get("plotting", {})
    if plotting is not None and not isinstance(plotting, dict):
        errors.append(f"  {study_path}: 'plotting' must be a mapping when provided.")
    elif isinstance(plotting, dict):
        enabled = plotting.get("enabled")
        if enabled is not None and not isinstance(enabled, bool):
            errors.append(f"  {study_path}: plotting.enabled must be boolean when provided.")
        output_format = plotting.get("output_format")
        if output_format is not None and output_format not in STUDY_PLOT_FORMATS:
            errors.append(f"  {study_path}: plotting.output_format must be one of ['png','pdf','svg'].")
 
    execution = study_cfg.get("execution", {})
    if execution is not None and not isinstance(execution, dict):
        errors.append(f"  {study_path}: 'execution' must be a mapping when provided.")
    elif isinstance(execution, dict):
        max_conc = execution.get("max_concurrent_array_tasks")
        if max_conc is not None and (not isinstance(max_conc, int) or max_conc <= 0):
            errors.append(
                f"  {study_path}: execution.max_concurrent_array_tasks must be a positive integer when provided."
            )
 
    if errors:
        _print_validation_errors(errors)
 

Here is the call graph for this function:

Here is the caller graph for this function:

_deep_set()

picurv_cli.core._deep_set ( dict  container, str  dotted_path,   value  )

protected

Set nested dictionary value, creating intermediate maps when needed.

Parameters

[in]	container	Argument passed to _deep_set().
[in]	dotted_path	Argument passed to _deep_set().
[in]	value	Argument passed to _deep_set().

Definition at line 11718 of file core.py.

def _deep_set(container: dict, dotted_path: str, value):
    """!
    @brief Set nested dictionary value, creating intermediate maps when needed.
    @param[in] container Argument passed to `_deep_set()`.
    @param[in] dotted_path Argument passed to `_deep_set()`.
    @param[in] value Argument passed to `_deep_set()`.
    """
    keys = dotted_path.split(".")
    current = container
    for key in keys[:-1]:
        if key not in current or not isinstance(current[key], dict):
            current[key] = {}
        current = current[key]
    current[keys[-1]] = value
 

Here is the caller graph for this function:

expand_parameter_matrix()

list picurv_cli.core.expand_parameter_matrix

(

dict

parameters

)

Expand study parameter lists into cartesian-product combinations.

Parameters

[in]

parameters

Argument passed to expand_parameter_matrix().

Returns

Value returned by expand_parameter_matrix().

Definition at line 11733 of file core.py.

def expand_parameter_matrix(parameters: dict) -> list:
    """!
    @brief Expand study parameter lists into cartesian-product combinations.
    @param[in] parameters Argument passed to `expand_parameter_matrix()`.
    @return Value returned by `expand_parameter_matrix()`.
    """
    param_keys = list(parameters.keys())
    all_values = [parameters[k] for k in param_keys]
    combos = []
    for combo in itertools.product(*all_values):
        combos.append(dict(zip(param_keys, combo)))
    return combos
 
 

Here is the caller graph for this function:

expand_study_parameter_combinations()

list picurv_cli.core.expand_study_parameter_combinations

(

dict

study_cfg

)

Expand either cartesian-study parameters or explicit parameter sets.

Parameters

[in]

study_cfg

Argument passed to expand_study_parameter_combinations().

Returns

Value returned by expand_study_parameter_combinations().

Definition at line 11747 of file core.py.

def expand_study_parameter_combinations(study_cfg: dict) -> list:
    """!
    @brief Expand either cartesian-study parameters or explicit parameter sets.
    @param[in] study_cfg Argument passed to `expand_study_parameter_combinations()`.
    @return Value returned by `expand_study_parameter_combinations()`.
    """
    parameter_sets = study_cfg.get("parameter_sets")
    if parameter_sets:
        return [dict(param_set) for param_set in parameter_sets]
    return expand_parameter_matrix(study_cfg.get("parameters") or {})
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

flatten_study_parameters()

dict picurv_cli.core.flatten_study_parameters

(

dict

parameters

)

Flatten grouped study overrides into scalar dotted-path columns.

A grouped override such as case.run_control: {dt_physical: ...} materializes correctly in case YAML but is not a useful CSV cell or plot coordinate. Flattening preserves the actual varied variables.

Parameters

[in]

parameters

One expanded study parameter combination.

Returns

Flat dotted-path-to-scalar mapping.

Definition at line 11759 of file core.py.

def flatten_study_parameters(parameters: dict) -> dict:
    """!
    @brief Flatten grouped study overrides into scalar dotted-path columns.
 
    @details A grouped override such as `case.run_control: {dt_physical: ...}`
             materializes correctly in case YAML but is not a useful CSV cell or
             plot coordinate. Flattening preserves the actual varied variables.
 
    @param[in] parameters One expanded study parameter combination.
    @return Flat dotted-path-to-scalar mapping.
    """
    flattened = {}
 
    def visit(prefix, value):
        """!
        @brief Recursively flatten one grouped override value.
        @param[in] prefix Current dotted parameter path.
        @param[in] value Scalar or nested mapping at the current path.
        """
        if isinstance(value, dict):
            for child, child_value in value.items():
                visit(f"{prefix}.{child}" if prefix else str(child), child_value)
        else:
            flattened[prefix] = value
 
    for key, value in (parameters or {}).items():
        visit(str(key), value)
    return flattened
 
 

Here is the caller graph for this function:

get_study_parameter_keys()

list picurv_cli.core.get_study_parameter_keys

(

dict

study_cfg

)

Collect ordered parameter keys from either cross-product parameter expansions or explicit parameter sets.

Parameters

[in]

study_cfg

Argument passed to get_study_parameter_keys().

Returns

Value returned by get_study_parameter_keys().

Definition at line 11789 of file core.py.

def get_study_parameter_keys(study_cfg: dict) -> list:
    """!
    @brief Collect ordered parameter keys from either cross-product parameter expansions or explicit parameter sets.
    @param[in] study_cfg Argument passed to `get_study_parameter_keys()`.
    @return Value returned by `get_study_parameter_keys()`.
    """
    parameters = study_cfg.get("parameters")
    if isinstance(parameters, dict) and parameters:
        keys = []
        for key, candidates in parameters.items():
            candidate_dicts = [value for value in candidates if isinstance(value, dict)] if isinstance(candidates, list) else []
            expanded = []
            for value in candidate_dicts:
                for flat_key in flatten_study_parameters({key: value}):
                    if flat_key not in expanded:
                        expanded.append(flat_key)
            for flat_key in expanded or [key]:
                if flat_key not in keys:
                    keys.append(flat_key)
        return keys
 
    keys = []
    parameter_sets = study_cfg.get("parameter_sets") or []
    for param_set in parameter_sets:
        if not isinstance(param_set, dict):
            continue
        for key in flatten_study_parameters(param_set):
            if key not in keys:
                keys.append(key)
    return keys
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

get_cluster_total_tasks()

int picurv_cli.core.get_cluster_total_tasks

(

dict

cluster_cfg

)

Return cluster total tasks.

Parameters

[in]

cluster_cfg

Argument passed to get_cluster_total_tasks().

Returns

Value returned by get_cluster_total_tasks().

Definition at line 11821 of file core.py.

def get_cluster_total_tasks(cluster_cfg: dict) -> int:
    """!
    @brief Return cluster total tasks.
    @param[in] cluster_cfg Argument passed to `get_cluster_total_tasks()`.
    @return Value returned by `get_cluster_total_tasks()`.
    """
    resources = cluster_cfg.get("resources", {})
    return int(resources.get("nodes", 1)) * int(resources.get("ntasks_per_node", 1))
 

Here is the caller graph for this function:

normalize_extension()

str picurv_cli.core.normalize_extension

(

str

ext

)

Canonicalize a user-supplied filename extension by trimming whitespace and leading dots.

Parameters

[in]

ext

Argument passed to normalize_extension().

Returns

Value returned by normalize_extension().

Definition at line 11830 of file core.py.

def normalize_extension(ext: str) -> str:
    """!
    @brief Canonicalize a user-supplied filename extension by trimming whitespace and leading dots.
    @param[in] ext Argument passed to `normalize_extension()`.
    @return Value returned by `normalize_extension()`.
    """
    if ext is None:
        return None
    return str(ext).strip().lstrip(".")
 

resolve_conductor_entry_point()

list picurv_cli.core.resolve_conductor_entry_point

(

)

Resolve how to invoke this conductor again from a batch script.

Prefers the bin/picurv wrapper, which selects the managed Python environment a cluster node needs, and falls back to the running interpreter with the package entry point when that wrapper is absent.

Returns

Argv prefix that re-invokes the conductor.

Definition at line 11840 of file core.py.

def resolve_conductor_entry_point() -> list:
    """!
    @brief Resolve how to invoke this conductor again from a batch script.
 
    @details Prefers the `bin/picurv` wrapper, which selects the managed Python
             environment a cluster node needs, and falls back to the running
             interpreter with the package entry point when that wrapper is absent.
 
    @return Argv prefix that re-invokes the conductor.
    """
    wrapper = os.path.join(PACKAGE_PROJECT_ROOT, "bin", "picurv")
    if os.path.isfile(wrapper) and os.access(wrapper, os.X_OK):
        return [wrapper]
    return [sys.executable, os.path.join(PACKAGE_PROJECT_ROOT, "picurv_cli", "picurv")]
 
 

Here is the caller graph for this function:

build_spectra_follow_command()

list picurv_cli.core.build_spectra_follow_command	(	str	run_dir,
		str	post_path,
		dict	post_cfg,
		bool	recompute = False
	)

Build the batch-script step that measures spectra after the field stage.

Spectra are a serial pass over committed checkpoints, so the command is returned bare rather than wrapped in the MPI launcher: run under srun with the post stage's task count it would become one identical copy per task, each writing the same files.

Parameters

[in]	run_dir	Run directory the batch job operates on.
[in]	post_path	Post recipe path, reachable from the compute node.
[in]	post_cfg	Effective post configuration.
[in]	recompute	Re-measure steps whose spectra are still valid.

Returns

Argv list, or an empty list when the recipe requests no spectra.

Definition at line 11856 of file core.py.

                                 recompute: bool = False) -> list:
    """!
    @brief Build the batch-script step that measures spectra after the field stage.
 
    @details Spectra are a serial pass over committed checkpoints, so the command is
             returned bare rather than wrapped in the MPI launcher: run under `srun`
             with the post stage's task count it would become one identical copy per
             task, each writing the same files.
 
    @param[in] run_dir Run directory the batch job operates on.
    @param[in] post_path Post recipe path, reachable from the compute node.
    @param[in] post_cfg Effective post configuration.
    @param[in] recompute Re-measure steps whose spectra are still valid.
    @return Argv list, or an empty list when the recipe requests no spectra.
    """
    try:
        spectra = normalize_post_spectra_config(post_cfg)
    except ValueError:
        # Validation reports recipe errors; do not raise a second time here.
        return []
    if not spectra["tasks"]:
        return []
    return resolve_conductor_entry_point() + [
        "run", "--post-process", "--only", "spectra",
        "--run-dir", os.path.abspath(run_dir),
        "--post", os.path.abspath(post_path),
    ] + (["--recompute"] if recompute else [])
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

executable_petsc_library_dir()

"str | None" picurv_cli.core.executable_petsc_library_dir

(

str

executable_path

)

The lib/ directory of the PETSc an executable was built against, from its stamp.

Both PETSc index widths name their library libpetsc.so.MAJOR.MINOR, so the loader takes whichever comes first on LD_LIBRARY_PATH; launching with this directory first gives each executable its own PETSc whatever modules the job loaded.

Parameters

[in]

executable_path

Path to simulator, postprocessor or their 64-bit pair.

Returns

Absolute directory, or None when the stamp does not name one.

Definition at line 11886 of file core.py.

def executable_petsc_library_dir(executable_path: str) -> "str | None":
    """!
    @brief The lib/ directory of the PETSc an executable was built against, from its stamp.
    @details Both PETSc index widths name their library libpetsc.so.MAJOR.MINOR, so the loader
             takes whichever comes first on LD_LIBRARY_PATH; launching with this directory first
             gives each executable its own PETSc whatever modules the job loaded.
    @param[in] executable_path Path to `simulator`, `postprocessor` or their 64-bit pair.
    @return Absolute directory, or None when the stamp does not name one.
    """
    petsc = read_binary_petsc_stamp(executable_path) if os.path.isfile(executable_path) else None
    if not petsc or not petsc.get("dir"):
        return None
    library_dir = os.path.join(petsc["dir"], petsc.get("arch") or "", "lib")
    return os.path.normpath(library_dir) if os.path.isdir(library_dir) else None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

petsc_library_path_lines()

list picurv_cli.core.petsc_library_path_lines

(

"str | None"

library_dir

)

Shell lines putting one PETSc's lib/ first on LD_LIBRARY_PATH, after module setup.

Parameters

[in]

library_dir

From executable_petsc_library_dir(), or None for no change.

Returns

Script lines.

Definition at line 11902 of file core.py.

def petsc_library_path_lines(library_dir: "str | None") -> list:
    """!
    @brief Shell lines putting one PETSc's lib/ first on LD_LIBRARY_PATH, after module setup.
    @param[in] library_dir From `executable_petsc_library_dir()`, or None for no change.
    @return Script lines.
    """
    if not library_dir:
        return []
    return [f'export LD_LIBRARY_PATH={shlex.quote(library_dir)}"${{LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}}"']
 
 

Here is the caller graph for this function:

executable_identity_check_lines()

list picurv_cli.core.executable_identity_check_lines	(	str	executable,
		"str | None"	expected_version_line,
		bool	pinned = False
	)

Shell lines that compare an executable's reported identity with the staged one.

A job resolves its executable when it starts, which can be long after it was staged. The installation's bin/ may have been rebuilt in between, and a job that silently runs the new build produces checkpoints that disagree with the run's manifest. The lines run after module setup, because --version still needs the executable's shared libraries, and before the launcher, so a mismatch stops the job before any rank starts. When staging could not read an identity there is nothing to compare, so the reported one is only logged.

Parameters

[in]	executable	Executable path, emitted verbatim when it is a shell variable.
[in]	expected_version_line	Exact --version output captured at staging, or None.
[in]	pinned	Whether the executable is the run's own pinned copy.

Returns

Script lines.

Definition at line 11913 of file core.py.

                                    pinned: bool = False) -> list:
    """!
    @brief Shell lines that compare an executable's reported identity with the staged one.
 
    @details A job resolves its executable when it starts, which can be long after it
             was staged. The installation's `bin/` may have been rebuilt in between, and
             a job that silently runs the new build produces checkpoints that disagree
             with the run's manifest. The lines run after module setup, because
             `--version` still needs the executable's shared libraries, and before the
             launcher, so a mismatch stops the job before any rank starts. When staging
             could not read an identity there is nothing to compare, so the reported one
             is only logged.
    @param[in] executable Executable path, emitted verbatim when it is a shell variable.
    @param[in] expected_version_line Exact `--version` output captured at staging, or None.
    @param[in] pinned Whether the executable is the run's own pinned copy.
    @return Script lines.
    """
    token = executable if executable.startswith("$") else shlex.quote(executable)
    lines = [
        f'PICURV_EXECUTABLE_IDENTITY=$({token} --version 2>&1) || {{ '
        f'echo "[FATAL] {executable} --version failed: ${{PICURV_EXECUTABLE_IDENTITY}}" >&2; exit 1; }}',
        'echo "[$(date)] Executable identity: ${PICURV_EXECUTABLE_IDENTITY}"',
    ]
    if not expected_version_line:
        lines.append('echo "[$(date)] No identity was readable at staging, so none is compared."')
        return lines
    remedy = (
        "The run's pinned copy was replaced after staging; restore it or re-pin the run."
        if pinned else
        "It was rebuilt after staging; restage the job, or stage with --pin-executables so "
        "the run keeps its own copy."
    )
    lines.extend([
        f"PICURV_STAGED_IDENTITY={shlex.quote(expected_version_line)}",
        'if [ "${PICURV_EXECUTABLE_IDENTITY}" != "${PICURV_STAGED_IDENTITY}" ]; then',
        f'  echo "[FATAL] {executable} reports ${{PICURV_EXECUTABLE_IDENTITY}}, but this job was '
        f'staged against ${{PICURV_STAGED_IDENTITY}}. {remedy}" >&2',
        "  exit 1",
        "fi",
    ])
    return lines
 
 

Here is the caller graph for this function:

render_slurm_script()

picurv_cli.core.render_slurm_script	(	str	script_path,
		str	job_name,
		dict	cluster_cfg,
		list	command,
		str	workdir,
		str	stdout_path,
		str	stderr_path = None,
		dict	env_vars = None,
		dict	shell_env_vars = None,
		str	array_spec = None,
		list	follow_commands = None,
		"tuple | None"	identity_check = None
	)

Render a Slurm batch script for a single command.

Parameters

[in]	script_path	Argument passed to render_slurm_script().
[in]	job_name	Argument passed to render_slurm_script().
[in]	cluster_cfg	Argument passed to render_slurm_script().
[in]	command	Argument passed to render_slurm_script().
[in]	workdir	Argument passed to render_slurm_script().
[in]	stdout_path	Argument passed to render_slurm_script().
[in]	stderr_path	Argument passed to render_slurm_script().
[in]	env_vars	Argument passed to render_slurm_script().
[in]	shell_env_vars	Argument passed to render_slurm_script().
[in]	array_spec	Argument passed to render_slurm_script().
[in]	follow_commands	Commands to run after the launched one, each an argv list. They run in the batch shell rather than under the MPI launcher, so a serial step does not become one copy per task. Supplying any of them drops the exec.
[in]	identity_check	(executable, expected --version line, pinned) checked before launch; see executable_identity_check_lines().

Definition at line 11957 of file core.py.

):
    """!
    @brief Render a Slurm batch script for a single command.
    @param[in] script_path Argument passed to `render_slurm_script()`.
    @param[in] job_name Argument passed to `render_slurm_script()`.
    @param[in] cluster_cfg Argument passed to `render_slurm_script()`.
    @param[in] command Argument passed to `render_slurm_script()`.
    @param[in] workdir Argument passed to `render_slurm_script()`.
    @param[in] stdout_path Argument passed to `render_slurm_script()`.
    @param[in] stderr_path Argument passed to `render_slurm_script()`.
    @param[in] env_vars Argument passed to `render_slurm_script()`.
    @param[in] shell_env_vars Argument passed to `render_slurm_script()`.
    @param[in] array_spec Argument passed to `render_slurm_script()`.
    @param[in] follow_commands Commands to run after the launched one, each an argv
                               list. They run in the batch shell rather than under the
                               MPI launcher, so a serial step does not become one copy
                               per task. Supplying any of them drops the `exec`.
    @param[in] identity_check `(executable, expected --version line, pinned)` checked
                              before launch; see `executable_identity_check_lines()`.
    """
    resources = cluster_cfg.get("resources", {})
    notifications = cluster_cfg.get("notifications", {}) or {}
    execution = cluster_cfg.get("execution", {}) or {}
    extra_sbatch = execution.get("extra_sbatch")
    module_setup = execution.get("module_setup", []) or []
 
    if stderr_path is None:
        stderr_path = stdout_path.replace(".out", ".err")
 
    lines = [
        "#!/bin/bash",
        f"#SBATCH --job-name={job_name}",
        f"#SBATCH --nodes={resources['nodes']}",
        f"#SBATCH --ntasks-per-node={resources['ntasks_per_node']}",
        f"#SBATCH --mem={resources['mem']}",
        f"#SBATCH --time={resources['time']}",
        f"#SBATCH --output={stdout_path}",
        f"#SBATCH --error={stderr_path}",
        f"#SBATCH --account={resources['account']}",
    ]
    partition = resources.get("partition")
    if partition:
        lines.append(f"#SBATCH --partition={partition}")
    if array_spec:
        lines.append(f"#SBATCH --array={array_spec}")
    mail_user = notifications.get("mail_user")
    mail_type = notifications.get("mail_type")
    if mail_user:
        lines.append(f"#SBATCH --mail-user={mail_user}")
    if mail_type:
        lines.append(f"#SBATCH --mail-type={mail_type}")
 
    if isinstance(extra_sbatch, dict):
        for key, value in extra_sbatch.items():
            flag = str(key)
            if not flag.startswith("--"):
                flag = f"--{flag}"
            if isinstance(value, bool):
                if value:
                    lines.append(f"#SBATCH {flag}")
            elif value is not None:
                lines.append(f"#SBATCH {flag}={value}")
    elif isinstance(extra_sbatch, list):
        for token in extra_sbatch:
            lines.append(f"#SBATCH {token}")
 
    lines.extend(
        [
            "",
            "set -euo pipefail",
            "",
            f"cd {shlex.quote(workdir)}",
            'echo "[$(date)] Starting job ${SLURM_JOB_NAME} (${SLURM_JOB_ID})"',
            'echo "[$(date)] Working directory: $PWD"',
        ]
    )
 
    if shell_env_vars:
        for key, value in shell_env_vars.items():
            lines.append(f"export {key}={value}")
 
    for setup_line in module_setup:
        lines.append(str(setup_line))
 
    if env_vars:
        for key, value in env_vars.items():
            lines.append(f"export {key}={shlex.quote(str(value))}")
 
    if identity_check:
        lines.extend(petsc_library_path_lines(executable_petsc_library_dir(identity_check[0])))
        lines.extend(executable_identity_check_lines(*identity_check))
 
    cmd = " ".join(shlex.quote(str(tok)) for tok in command)
    if follow_commands:
        # `exec` would replace the shell and the trailing commands would never run.
        # `set -e` is already in effect, so a failure in the launched command aborts
        # the job before anything downstream of it executes.
        lines.append(cmd)
        for follow in follow_commands:
            lines.append(" ".join(shlex.quote(str(tok)) for tok in follow))
    else:
        lines.append(f"exec {cmd}")
 
    os.makedirs(os.path.dirname(script_path), exist_ok=True)
    with open(script_path, "w") as f:
        f.write("\n".join(lines) + "\n")
    os.chmod(script_path, 0o755)
 

Here is the call graph for this function:

Here is the caller graph for this function:

split_launcher_tokens()

"tuple[str | None, list[str]]" picurv_cli.core.split_launcher_tokens	(	"str | None"	launcher,
		"list | None"	launcher_args = None,
		str	label = "launcher"
	)

Canonicalize launcher config into executable token plus argv-style flags.

Parameters

[in]	launcher	Argument passed to split_launcher_tokens().
[in]	launcher_args	Argument passed to split_launcher_tokens().
[in]	label	Argument passed to split_launcher_tokens().

Returns

Value returned by split_launcher_tokens().

Definition at line 12078 of file core.py.

) -> "tuple[str | None, list[str]]":
    """!
    @brief Canonicalize launcher config into executable token plus argv-style flags.
    @param[in] launcher Argument passed to `split_launcher_tokens()`.
    @param[in] launcher_args Argument passed to `split_launcher_tokens()`.
    @param[in] label Argument passed to `split_launcher_tokens()`.
    @return Value returned by `split_launcher_tokens()`.
    """
    normalized_args = [str(x) for x in (launcher_args or [])]
 
    if launcher is None:
        return None, normalized_args
 
    try:
        launcher_tokens = shlex.split(str(launcher))
    except ValueError as exc:
        raise ValueError(f"{label} is not shell-parseable: {exc}") from exc
 
    if not launcher_tokens:
        return None, normalized_args
 
    return launcher_tokens[0], launcher_tokens[1:] + normalized_args
 
 

Here is the caller graph for this function:

normalize_cluster_launcher()

"tuple[str | None, list[str]]" picurv_cli.core.normalize_cluster_launcher

(

dict

execution

)

Canonicalize cluster launcher config into executable token plus argv-style flags.

Parameters

[in]

execution

Argument passed to normalize_cluster_launcher().

Returns

Value returned by normalize_cluster_launcher().

Definition at line 12106 of file core.py.

def normalize_cluster_launcher(execution: dict) -> "tuple[str | None, list[str]]":
    """!
    @brief Canonicalize cluster launcher config into executable token plus argv-style flags.
    @param[in] execution Argument passed to `normalize_cluster_launcher()`.
    @return Value returned by `normalize_cluster_launcher()`.
    """
    return split_launcher_tokens(
        execution.get("launcher"),
        execution.get("launcher_args") or [],
        label="execution.launcher",
    )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

strip_launcher_size_flags()

"list[str]" picurv_cli.core.strip_launcher_size_flags	(	str	launcher_name,
		"list[str]"	launcher_args
	)

Remove explicit MPI task-count flags from known launchers.

Parameters

[in]	launcher_name	Basename-normalized launcher executable.
[in]	launcher_args	Launcher argument list.

Returns

Filtered launcher arguments with explicit size flags removed.

Definition at line 12119 of file core.py.

def strip_launcher_size_flags(launcher_name: str, launcher_args: "list[str]") -> "list[str]":
    """!
    @brief Remove explicit MPI task-count flags from known launchers.
    @param[in] launcher_name Basename-normalized launcher executable.
    @param[in] launcher_args Launcher argument list.
    @return Filtered launcher arguments with explicit size flags removed.
    """
    filtered = []
    idx = 0
    while idx < len(launcher_args):
        token = str(launcher_args[idx])
 
        if launcher_name == "srun":
            if token in {"-n", "--ntasks"}:
                idx += 2
                continue
            if token.startswith("--ntasks="):
                idx += 1
                continue
        elif launcher_name in {"mpiexec", "mpirun"}:
            if token in {"-n", "-np"}:
                idx += 2
                continue
            if token.startswith("-n=") or token.startswith("-np="):
                idx += 1
                continue
 
        filtered.append(token)
        idx += 1
 
    return filtered
 
 

Here is the caller graph for this function:

build_local_launch_command()

list picurv_cli.core.build_local_launch_command	(	str	executable,
		list	executable_args,
		int	num_procs,
		str	config_search_anchor = None,
		bool	allow_single_rank_launcher_override = False,
		"int | None"	force_num_procs = None
	)

Build local launcher command, allowing env or shared config overrides for login-node MPI quirks.

Parameters

[in]	executable	Argument passed to build_local_launch_command().
[in]	executable_args	Argument passed to build_local_launch_command().
[in]	num_procs	Argument passed to build_local_launch_command().
[in]	config_search_anchor	Argument passed to build_local_launch_command().
[in]	allow_single_rank_launcher_override	When true, explicit launcher overrides also apply to 1-rank commands.
[in]	force_num_procs	Optional explicit MPI rank count override applied after stripping conflicting launcher size flags.

Returns

Value returned by build_local_launch_command().

Definition at line 12152 of file core.py.

) -> list:
    """!
    @brief Build local launcher command, allowing env or shared config overrides for login-node MPI quirks.
    @param[in] executable Argument passed to `build_local_launch_command()`.
    @param[in] executable_args Argument passed to `build_local_launch_command()`.
    @param[in] num_procs Argument passed to `build_local_launch_command()`.
    @param[in] config_search_anchor Argument passed to `build_local_launch_command()`.
    @param[in] allow_single_rank_launcher_override When true, explicit launcher overrides also apply to 1-rank commands.
    @param[in] force_num_procs Optional explicit MPI rank count override applied after stripping conflicting launcher size flags.
    @return Value returned by `build_local_launch_command()`.
    """
    target_num_procs = force_num_procs if force_num_procs is not None else num_procs
    command = [executable] + executable_args
    if target_num_procs <= 1 and not allow_single_rank_launcher_override:
        return command
 
    launcher_override = os.environ.get("PICURV_MPI_LAUNCHER")
    if launcher_override is None:
        launcher_override = os.environ.get("MPI_LAUNCHER")
 
    try:
        if launcher_override is not None:
            explicit_launcher_config = True
            launcher, launcher_args = split_launcher_tokens(
                launcher_override,
                label="local MPI launcher override",
            )
        else:
            _, runtime_execution_cfg = load_runtime_execution_config(config_search_anchor)
            local_execution = resolve_runtime_execution_context(runtime_execution_cfg, "local")
            configured_launcher = local_execution.get("launcher")
            configured_args = local_execution.get("launcher_args") or []
            explicit_launcher_config = configured_launcher is not None or bool(configured_args)
            if target_num_procs <= 1 and not explicit_launcher_config:
                return command
            launcher, launcher_args = split_launcher_tokens(
                configured_launcher if configured_launcher is not None else "mpiexec",
                configured_args,
                label="local_execution.launcher",
            )
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    if not launcher:
        return command
 
    launcher_name = os.path.basename(launcher).lower()
    if force_num_procs is not None:
        launcher_args = strip_launcher_size_flags(launcher_name, launcher_args)
    prefix = [launcher] + launcher_args
 
    if launcher_name == "srun":
        has_n = any(token in {"-n", "--ntasks"} for token in launcher_args)
        if not has_n:
            prefix += ["-n", str(target_num_procs)]
    elif launcher_name in {"mpiexec", "mpirun"}:
        has_n = any(token in {"-n", "-np"} for token in launcher_args)
        if not has_n:
            prefix += ["-n", str(target_num_procs)]
 
    return prefix + command
 

Here is the call graph for this function:

Here is the caller graph for this function:

restart_grid_inputs()

dict picurv_cli.core.restart_grid_inputs	(	str	run_dir,
		dict	case_cfg
	)

The inputs a run's geometry is derived from, to compare across a restart.

The solver compares the checkpoint's geometry, which it hashes from the built grid, only after the job has started. These inputs determine that geometry within one build, so a difference is worth saying at staging: a staged inputs/grid/grid.run (file and generated grids, already non-dimensional) by content, otherwise the grid section without its rank layout and the length scale; and the periodic faces of every block.

Parameters

[in]	run_dir	Run whose staged grid is read.
[in]	case_cfg	That run's case configuration.

Returns

Mapping of input name to a comparable value.

Definition at line 12222 of file core.py.

def restart_grid_inputs(run_dir: str, case_cfg: dict) -> dict:
    """!
    @brief The inputs a run's geometry is derived from, to compare across a restart.
    @details The solver compares the checkpoint's geometry, which it hashes from the built
             grid, only after the job has started. These inputs determine that geometry
             within one build, so a difference is worth saying at staging: a staged
             `inputs/grid/grid.run` (file and generated grids, already non-dimensional)
             by content, otherwise the grid section without its rank layout and the
             length scale; and the periodic faces of every block.
    @param[in] run_dir Run whose staged grid is read.
    @param[in] case_cfg That run's case configuration.
    @return Mapping of input name to a comparable value.
    """
    staged = os.path.join(run_dir, "inputs", "grid", "grid.run")
    grid = {key: value for key, value in (case_cfg.get("grid") or {}).items()
            if not str(key).startswith("da_processors_")}
    try:
        periodic = [sorted(bc["face"] for bc in block if bc["type"] == "PERIODIC")
                    for block in validate_and_prepare_boundary_conditions(case_cfg)]
    except (ValueError, KeyError, TypeError):
        periodic = None
    inputs = {"periodic faces": periodic}
    if os.path.isfile(staged):
        inputs["grid file"] = _file_sha256(staged)
    else:
        inputs["grid"] = grid
        inputs["length_ref"] = ((case_cfg.get("properties") or {}).get("scaling") or {}).get("length_ref")
    return inputs
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

warn_on_restart_grid_change()

picurv_cli.core.warn_on_restart_grid_change	(	dict	source_inputs,
		dict	branch_inputs
	)

Warn at staging when a restart's grid inputs differ from its source run's.

Parameters

[in]	source_inputs	restart_grid_inputs() of the run that wrote the checkpoint.
[in]	branch_inputs	restart_grid_inputs() of the staged restart.

Returns

Names of the inputs that differ.

Definition at line 12252 of file core.py.

def warn_on_restart_grid_change(source_inputs: dict, branch_inputs: dict):
    """!
    @brief Warn at staging when a restart's grid inputs differ from its source run's.
    @param[in] source_inputs restart_grid_inputs() of the run that wrote the checkpoint.
    @param[in] branch_inputs restart_grid_inputs() of the staged restart.
    @return Names of the inputs that differ.
    """
    changed = sorted(name for name in set(source_inputs) | set(branch_inputs)
                     if source_inputs.get(name) != branch_inputs.get(name))
    if changed:
        print(f"[WARNING] This restart's grid inputs differ from the source run's ({', '.join(changed)}). "
              "The solver refuses a checkpoint whose geometry differs, but only once the job has "
              "started and built the grid.", file=sys.stderr)
    return changed
 
 

Here is the caller graph for this function:

check_restart_continuation()

picurv_cli.core.check_restart_continuation	(	str	solver_exe,
		list	solver_args,
		str	run_dir,
		str	config_search_anchor = None
	)

Ask the simulator whether a staged restart's carried statistics windows can continue.

Runs the simulator's restart check on one rank. It parses the run's control file and compares each window with the source checkpoint's manifest exactly as the restart will, but builds no grid, so it costs about a second and runs on a login node whatever the production rank count. Passing it does not replace the full check at solver start, which also compares geometry.

Parameters

[in]	solver_exe	Simulator executable the run will launch.
[in]	solver_args	Simulator arguments the run will launch with.
[in]	run_dir	Staged run directory, the simulator's working directory.
[in]	config_search_anchor	Path from which the local launcher configuration is found.

Returns

None when the windows can continue, else the simulator's own reason.

Definition at line 12268 of file core.py.

                               config_search_anchor: str = None):
    """!
    @brief Ask the simulator whether a staged restart's carried statistics windows can continue.
    @details Runs the simulator's restart check on one rank. It parses the run's control
             file and compares each window with the source checkpoint's manifest exactly
             as the restart will, but builds no grid, so it costs about a second and runs
             on a login node whatever the production rank count. Passing it does not
             replace the full check at solver start, which also compares geometry.
    @param[in] solver_exe Simulator executable the run will launch.
    @param[in] solver_args Simulator arguments the run will launch with.
    @param[in] run_dir Staged run directory, the simulator's working directory.
    @param[in] config_search_anchor Path from which the local launcher configuration is found.
    @return None when the windows can continue, else the simulator's own reason.
    """
    command = build_local_launch_command(
        solver_exe, solver_args + ["-restart_check_only", "true"], 1,
        config_search_anchor=config_search_anchor,
        allow_single_rank_launcher_override=True, force_num_procs=1,
    )
    result = _run_captured_command(command, run_dir)
    if result.returncode == 0:
        print("[INFO] Statistics continuation check passed.")
        return None
    # PETSc prints a banner, its generic error class, then the simulator's own message.
    messages = [line.split("PETSC ERROR:", 1)[1].strip()
                for line in (result.stdout + result.stderr).splitlines() if "PETSC ERROR:" in line]
    messages = [m for m in messages if m and not m.startswith("-")]
    return (messages[1] if len(messages) > 1 else messages[0] if messages
            else (result.stderr or result.stdout).strip() or f"exit status {result.returncode}")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_cluster_execution()

dict picurv_cli.core.resolve_cluster_execution	(	dict	cluster_cfg,
		str	config_search_anchor = None,
			extra_search_anchors = None
	)

Resolve cluster execution launcher settings from shared runtime config plus cluster.yml overrides.

Parameters

[in]	cluster_cfg	Argument passed to resolve_cluster_execution().
[in]	config_search_anchor	Argument passed to resolve_cluster_execution().
[in]	extra_search_anchors	Argument passed to resolve_cluster_execution().

Returns

Value returned by resolve_cluster_execution().

Definition at line 12300 of file core.py.

def resolve_cluster_execution(cluster_cfg: dict, config_search_anchor: str = None, extra_search_anchors=None) -> dict:
    """!
    @brief Resolve cluster execution launcher settings from shared runtime config plus cluster.yml overrides.
    @param[in] cluster_cfg Argument passed to `resolve_cluster_execution()`.
    @param[in] config_search_anchor Argument passed to `resolve_cluster_execution()`.
    @param[in] extra_search_anchors Argument passed to `resolve_cluster_execution()`.
    @return Value returned by `resolve_cluster_execution()`.
    """
    _, runtime_execution_cfg = load_runtime_execution_config(config_search_anchor, extra_search_anchors=extra_search_anchors)
    shared_cluster_execution = resolve_runtime_execution_context(runtime_execution_cfg, "cluster")
    execution = cluster_cfg.get("execution", {}) or {}
    cluster_override = {
        "launcher": execution.get("launcher") if "launcher" in execution else None,
        "launcher_args": execution.get("launcher_args") if "launcher_args" in execution else None,
    }
    return merge_execution_overrides(shared_cluster_execution, cluster_override)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

build_cluster_launch_command()

list picurv_cli.core.build_cluster_launch_command	(	dict	cluster_cfg,
		str	executable,
		list	executable_args,
		str	config_search_anchor = None,
			extra_search_anchors = None,
		"int | None"	force_num_procs = None
	)

Build scheduler launcher command from cluster config plus optional shared execution defaults.

Parameters

[in]	cluster_cfg	Argument passed to build_cluster_launch_command().
[in]	executable	Argument passed to build_cluster_launch_command().
[in]	executable_args	Argument passed to build_cluster_launch_command().
[in]	config_search_anchor	Argument passed to build_cluster_launch_command().
[in]	extra_search_anchors	Argument passed to build_cluster_launch_command().
[in]	force_num_procs	Optional explicit MPI rank count override applied after stripping conflicting launcher size flags.

Returns

Value returned by build_cluster_launch_command().

Definition at line 12318 of file core.py.

) -> list:
    """!
    @brief Build scheduler launcher command from cluster config plus optional shared execution defaults.
    @param[in] cluster_cfg Argument passed to `build_cluster_launch_command()`.
    @param[in] executable Argument passed to `build_cluster_launch_command()`.
    @param[in] executable_args Argument passed to `build_cluster_launch_command()`.
    @param[in] config_search_anchor Argument passed to `build_cluster_launch_command()`.
    @param[in] extra_search_anchors Argument passed to `build_cluster_launch_command()`.
    @param[in] force_num_procs Optional explicit MPI rank count override applied after stripping conflicting launcher size flags.
    @return Value returned by `build_cluster_launch_command()`.
    """
    try:
        execution = resolve_cluster_execution(
            cluster_cfg,
            config_search_anchor=config_search_anchor,
            extra_search_anchors=extra_search_anchors,
        )
        launcher, launcher_args = split_launcher_tokens(
            execution.get("launcher") if execution.get("launcher") is not None else "srun",
            execution.get("launcher_args") or [],
            label="cluster execution launcher",
        )
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    ntasks = int(force_num_procs) if force_num_procs is not None else get_cluster_total_tasks(cluster_cfg)
    launcher_name = launcher.lower() if launcher else ""
    if force_num_procs is not None:
        launcher_args = strip_launcher_size_flags(launcher_name, launcher_args)
 
    if launcher and launcher_name == "srun":
        has_n = any(token in {"-n", "--ntasks"} for token in launcher_args)
        cmd = ["srun"] + launcher_args
        if not has_n:
            cmd += ["-n", str(ntasks)]
        return cmd + [executable] + executable_args
 
    if launcher and launcher_name == "mpirun":
        has_np = any(token in {"-np", "-n"} for token in launcher_args)
        cmd = ["mpirun"] + launcher_args
        if not has_np:
            cmd += ["-np", str(ntasks)]
        return cmd + [executable] + executable_args
 
    if launcher and launcher_name == "mpiexec":
        has_np = any(token in {"-np", "-n"} for token in launcher_args)
        cmd = ["mpiexec"] + launcher_args
        if not has_np:
            cmd += ["-np", str(ntasks)]
        return cmd + [executable] + executable_args
 
    # Custom launcher or no launcher.
    cmd = []
    if launcher:
        cmd.append(str(launcher))
    cmd += launcher_args
    cmd += [executable] + executable_args
    return cmd
 

Here is the call graph for this function:

Here is the caller graph for this function:

parse_slurm_job_id()

str picurv_cli.core.parse_slurm_job_id

(

str

sbatch_output

)

Extract numeric job id from standard sbatch output.

Parameters

[in]

sbatch_output

Argument passed to parse_slurm_job_id().

Returns

Value returned by parse_slurm_job_id().

Definition at line 12385 of file core.py.

def parse_slurm_job_id(sbatch_output: str) -> str:
    """!
    @brief Extract numeric job id from standard sbatch output.
    @param[in] sbatch_output Argument passed to `parse_slurm_job_id()`.
    @return Value returned by `parse_slurm_job_id()`.
    """
    match = re.search(r"Submitted batch job\s+(\d+)", sbatch_output or "")
    return match.group(1) if match else None
 
#: Slurm end states after which an `afterok` dependency can never be satisfied.

Here is the caller graph for this function:

slurm_job_end_state()

"tuple[str, str | None]" picurv_cli.core.slurm_job_end_state

(

str

job_id

)

Whether a recorded Slurm job (or array) is still queued, and how it ended if not.

Slurm forgets a finished job after its MinJobAge, and a dependency on a job it no longer knows is rejected, so a stage submitted long after the job it waits for must not depend on it. squeue answers for live jobs; sacct for ended ones.

Parameters

[in]

job_id

Recorded job id; for an array, the array's id covers every task.

Returns

("active", state), ("completed", "COMPLETED"), ("failed", state), ("unknown", state-or-None) when the job is not queued but sacct cannot say how it ended, or ("unchecked", None) where squeue is unavailable.

Definition at line 12401 of file core.py.

def slurm_job_end_state(job_id: str) -> "tuple[str, str | None]":
    """!
    @brief Whether a recorded Slurm job (or array) is still queued, and how it ended if not.
    @details Slurm forgets a finished job after its MinJobAge, and a dependency on a job it
             no longer knows is rejected, so a stage submitted long after the job it waits
             for must not depend on it. `squeue` answers for live jobs; `sacct` for ended ones.
    @param[in] job_id Recorded job id; for an array, the array's id covers every task.
    @return `("active", state)`, `("completed", "COMPLETED")`, `("failed", state)`,
            `("unknown", state-or-None)` when the job is not queued but `sacct` cannot say how
            it ended, or `("unchecked", None)` where `squeue` is unavailable.
    """
    squeue = shutil.which("squeue")
    if not squeue:
        return "unchecked", None
    result = subprocess.run([squeue, "-h", "-j", str(job_id), "-o", "%T"],
                            text=True, capture_output=True, check=False)
    live = [line.strip() for line in (result.stdout or "").splitlines() if line.strip()]
    if result.returncode == 0 and live:
        return "active", live[0]
    sacct = shutil.which("sacct")
    if not sacct:
        return "unknown", None
    result = subprocess.run([sacct, "-n", "-X", "-P", "-j", str(job_id), "-o", "State"],
                            text=True, capture_output=True, check=False)
    # "CANCELLED by 123" carries the canceller; the state is the first word.
    states = [line.split()[0] for line in (result.stdout or "").splitlines() if line.strip()]
    if result.returncode != 0 or not states:
        return "unknown", None
    failed = [state for state in states if state in _SLURM_FAILED_END_STATES]
    if failed:
        return "failed", failed[0]
    if all(state == "COMPLETED" for state in states):
        return "completed", "COMPLETED"
    # A state sacct reports for a job squeue no longer lists, such as a transient one.
    return "unknown", states[0]
 
 

Here is the caller graph for this function:

submit_sbatch()

dict picurv_cli.core.submit_sbatch	(	str	script_path,
		str	dependency = None,
		str	dependency_type = "afterok"
	)

Submit sbatch script and return submission metadata.

Parameters

[in]	script_path	Argument passed to submit_sbatch().
[in]	dependency	Argument passed to submit_sbatch().
[in]	dependency_type	Slurm dependency type (default: afterok). Common values: afterok, afterany.

Returns

Value returned by submit_sbatch().

Definition at line 12438 of file core.py.

def submit_sbatch(script_path: str, dependency: str = None, dependency_type: str = "afterok") -> dict:
    """!
    @brief Submit sbatch script and return submission metadata.
    @param[in] script_path Argument passed to `submit_sbatch()`.
    @param[in] dependency Argument passed to `submit_sbatch()`.
    @param[in] dependency_type Slurm dependency type (default: afterok). Common values: afterok, afterany.
    @return Value returned by `submit_sbatch()`.
    """
    cmd = ["sbatch"]
    if dependency:
        cmd.append(f"--dependency={dependency_type}:{dependency}")
    cmd.append(script_path)
    result = subprocess.run(cmd, text=True, capture_output=True, check=False)
    metadata = {
        "command": cmd,
        "returncode": result.returncode,
        "stdout": (result.stdout or "").strip(),
        "stderr": (result.stderr or "").strip(),
        "script": script_path,
    }
    if result.returncode != 0:
        print(f"[FATAL] sbatch submission failed for {script_path}\n{metadata['stderr']}", file=sys.stderr)
        sys.exit(result.returncode)
    metadata["job_id"] = parse_slurm_job_id(metadata["stdout"])
    if not metadata["job_id"]:
        print(
            f"[FATAL] Could not parse Slurm job id from sbatch output: {metadata['stdout']}",
            file=sys.stderr
        )
        sys.exit(1)
    return metadata
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_print_validation_errors()

picurv_cli.core._print_validation_errors ( list  errors )

protected

Prints validation errors and exits.

Parameters

[in]

errors

List of error message strings.

Definition at line 12471 of file core.py.

def _print_validation_errors(errors: list):
    """!
    @brief Prints validation errors and exits.
    @param[in] errors List of error message strings.
    """
    print(f"\n[FATAL] Configuration validation failed with {len(errors)} issue(s):", file=sys.stderr)
    for raw_error in errors:
        file_path, message = _split_error_file_and_message(raw_error)
        key_path = _extract_key_path(message)
        code = _classify_error_code(message)
        emit_structured_error(code, key=key_path, file_path=file_path, message=message)
    print(
        "\nHint: See examples/master_template/ for valid config structure and "
        "docs/pages/14_Config_Contract.md for key-level contract details.",
        file=sys.stderr,
    )
    sys.exit(1)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

generate_header()

str picurv_cli.core.generate_header	(	str	run_id,
		dict	source_files
	)

Creates a standard header block for all generated files.

Parameters

[in]	run_id	The unique identifier for the current simulation run.
[in]	source_files	A dictionary of source profile files used.

Returns

A formatted string containing the header.

Definition at line 12490 of file core.py.

def generate_header(run_id: str, source_files: dict) -> str:
    """!
    @brief Creates a standard header block for all generated files.
    @param[in] run_id The unique identifier for the current simulation run.
    @param[in] source_files A dictionary of source profile files used.
    @return A formatted string containing the header.
    """
    header_parts = [
        "# ==============================================================================",
        "#                AUTO-GENERATED CONFIGURATION FILE",
        "# ------------------------------------------------------------------------------",
        f"#   Run ID:       {run_id}",
        f"#   Timestamp:    {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}",
        "#",
        "#   Source Configuration:"
    ]
    for name, path in source_files.items():
        header_parts.append(f"#     - {name:<12}: {os.path.basename(path)}")
    header_parts.extend([
        "#",
        "#   DO NOT EDIT THIS FILE MANUALLY. IT IS A MACHINE-READABLE ARTIFACT.",
        "# ==============================================================================\n"
    ])
    return "\n".join(header_parts)
 

Here is the caller graph for this function:

generate_simple_list_file()

str picurv_cli.core.generate_simple_list_file	(	str	run_dir,
		str	run_id,
		dict	cfg,
		str	section,
		str	key,
		str	filename,
		dict	header_sources,
		str	config_dir = None
	)

Generic function to create a file containing a simple list of strings.

Parameters

[in]	run_dir	The path to the main run directory.
[in]	run_id	The unique identifier for the run.
[in]	cfg	The dictionary containing the configuration data.
[in]	section	The top-level key in the cfg dictionary.
[in]	key	The second-level key whose value is the list of strings.
[in]	filename	The name of the file to generate (e.g., 'whitelist.run').
[in]	header_sources	A dictionary of source files for the header.
[in]	config_dir	Optional configuration revision directory.

Returns

The absolute path to the generated file.

Definition at line 12515 of file core.py.

                              config_dir: str = None) -> str:
    """!
    @brief Generic function to create a file containing a simple list of strings.
    @param[in] run_dir The path to the main run directory.
    @param[in] run_id The unique identifier for the run.
    @param[in] cfg The dictionary containing the configuration data.
    @param[in] section The top-level key in the cfg dictionary.
    @param[in] key The second-level key whose value is the list of strings.
    @param[in] filename The name of the file to generate (e.g., 'whitelist.run').
    @param[in] header_sources A dictionary of source files for the header.
    @param[in] config_dir Optional configuration revision directory.
    @return The absolute path to the generated file.
    """
    print(f"[INFO] Generating {filename}...")
    config_dir = config_dir or os.path.join(run_dir, "config")
    os.makedirs(config_dir, exist_ok=True)
    file_path = os.path.join(config_dir, filename)
    
    lines = [generate_header(run_id, header_sources)]
    items = cfg.get(section, {}).get(key, [])
    lines.extend(items)
 
    with open(file_path, "w") as f: f.write("\n".join(lines))
    print(f"[SUCCESS] Generated {filename}: {os.path.relpath(file_path)}")
    return os.path.abspath(file_path)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

normalize_monitor_function_names()

list picurv_cli.core.normalize_monitor_function_names	(	list	names,
		str	field_name
	)

Translate renamed solver functions in a monitor.yml function list.

Parameters

[in]	names	Function names as written in monitor.yml.
[in]	field_name	YAML path of the list, used in warnings.

Returns

The list with renamed functions replaced and removed ones dropped.

Logging and profiling select functions by exact name, so a stale name silently selects nothing. Renamed functions are mapped to their current names and removed ones dropped, each with a warning.

Definition at line 12544 of file core.py.

def normalize_monitor_function_names(names: list, field_name: str) -> list:
    """!
    @brief Translate renamed solver functions in a monitor.yml function list.
    @param[in] names Function names as written in monitor.yml.
    @param[in] field_name YAML path of the list, used in warnings.
    @return The list with renamed functions replaced and removed ones dropped.
    @details Logging and profiling select functions by exact name, so a stale name
             silently selects nothing. Renamed functions are mapped to their current
             names and removed ones dropped, each with a warning.
    """
    normalized = []
    for name in names or []:
        if name in RENAMED_MONITOR_FUNCTIONS:
            current = RENAMED_MONITOR_FUNCTIONS[name]
            print(f"[WARNING] {field_name}: '{name}' was renamed to '{current}'; using '{current}'.",
                  file=sys.stderr)
            name = current
        elif name in REMOVED_MONITOR_FUNCTIONS:
            print(f"[WARNING] {field_name}: '{name}' no longer exists (removed by the Poisson "
                  "rewrite, 0d34592); dropping it.", file=sys.stderr)
            continue
        if name not in normalized:
            normalized.append(name)
    return normalized
 
 

Here is the caller graph for this function:

has_explicit_monitor_whitelist()

bool picurv_cli.core.has_explicit_monitor_whitelist

(

dict

monitor_cfg

)

Return True when logging.enabled_functions contains at least one entry.

Parameters

[in]

monitor_cfg

Argument passed to has_explicit_monitor_whitelist().

Returns

Value returned by has_explicit_monitor_whitelist().

Definition at line 12570 of file core.py.

def has_explicit_monitor_whitelist(monitor_cfg: dict) -> bool:
    """!
    @brief Return True when logging.enabled_functions contains at least one entry.
    @param[in] monitor_cfg Argument passed to `has_explicit_monitor_whitelist()`.
    @return Value returned by `has_explicit_monitor_whitelist()`.
    """
    items = monitor_cfg.get("logging", {}).get("enabled_functions", [])
    return bool(items)
 
 
#: Fixed names of the solver records under a run's `logs/`.

Here is the caller graph for this function:

resolve_profiling_config()

dict picurv_cli.core.resolve_profiling_config

(

dict

monitor_cfg

)

Resolve profiling reporting config from monitor.yml.

Parameters

[in]

monitor_cfg

Argument passed to resolve_profiling_config().

Returns

Value returned by resolve_profiling_config().

Definition at line 12585 of file core.py.

def resolve_profiling_config(monitor_cfg: dict) -> dict:
    """!
    @brief Resolve profiling reporting config from monitor.yml.
    @param[in] monitor_cfg Argument passed to `resolve_profiling_config()`.
    @return Value returned by `resolve_profiling_config()`.
    """
    profiling_cfg = monitor_cfg.get("profiling", {}) or {}
    timestep_cfg = profiling_cfg.get("timestep_output")
    final_cfg = profiling_cfg.get("final_summary")
 
    if timestep_cfg is None:
        mode = "off"
        functions = []
    else:
        if not isinstance(timestep_cfg, dict):
            raise ValueError("monitor.profiling.timestep_output must be a mapping when provided.")
        mode = str(timestep_cfg.get("mode", "off")).lower()
        functions = timestep_cfg.get("functions", [])
 
    if mode not in PROFILING_TIMESTEP_MODES:
        raise ValueError("monitor.profiling.timestep_output.mode must be one of ['off', 'selected', 'all'].")
    if functions is None:
        functions = []
    if not isinstance(functions, list):
        raise ValueError("monitor.profiling.timestep_output.functions must be a list of function names.")
    if not all(isinstance(item, str) and item.strip() for item in functions):
        raise ValueError("monitor.profiling.timestep_output.functions entries must be non-empty strings.")
    if mode == "selected" and not functions:
        raise ValueError("monitor.profiling.timestep_output.functions must be non-empty when mode is 'selected'.")
    if mode != "selected" and functions:
        raise ValueError("monitor.profiling.timestep_output.functions is only valid when mode is 'selected'.")
    functions = normalize_monitor_function_names(functions, "monitor.profiling.timestep_output.functions")
    if mode == "selected" and not functions:
        raise ValueError("monitor.profiling.timestep_output.functions lists only functions that no longer exist.")
 
    if final_cfg is None:
        final_enabled = True
    elif isinstance(final_cfg, dict):
        final_enabled = bool(final_cfg.get("enabled", True))
    else:
        raise ValueError("monitor.profiling.final_summary must be a mapping when provided.")
 
    # Per-particle and per-cell helper timers are off unless named here, or 'all'.
    helpers = profiling_cfg.get("helpers", [])
    if helpers is None:
        helpers = []
    if isinstance(helpers, str):
        if helpers.strip().lower() != "all":
            raise ValueError("monitor.profiling.helpers must be 'all' or a list of function names.")
        helpers = ["all"]
    elif not isinstance(helpers, list) or not all(isinstance(item, str) and item.strip() for item in helpers):
        raise ValueError("monitor.profiling.helpers must be 'all' or a list of non-empty function names.")
    elif helpers != ["all"]:
        helpers = normalize_monitor_function_names(helpers, "monitor.profiling.helpers")
        if any("," in item or item.strip() != item for item in helpers):
            raise ValueError("monitor.profiling.helpers names must not contain commas or surrounding spaces.")
 
    return {
        "mode": mode,
        "functions": functions,
        "final_summary_enabled": final_enabled,
        "helpers": helpers,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_diagnostic_info()

dict picurv_cli.core._diagnostic_info (   value )

protected

Validate PETSc info logging configuration.

Parameters

[in]

value

Boolean or structured PETSc info configuration.

Returns

Normalized enabled/class-filter mapping.

Definition at line 12667 of file core.py.

def _diagnostic_info(value) -> dict:
    """!
    @brief Validate PETSc info logging configuration.
    @param[in] value Boolean or structured PETSc info configuration.
    @return Normalized enabled/class-filter mapping.
    """
    if isinstance(value, bool):
        return {"enabled": value, "classes": []}
    if value is None:
        return {"enabled": False, "classes": []}
    if not isinstance(value, dict):
        raise ValueError("monitor.diagnostics.petsc.info must be boolean, null, or a mapping.")
    unknown = sorted(set(value) - {"enabled", "classes"})
    if unknown:
        raise ValueError(f"monitor.diagnostics.petsc.info has unsupported key(s): {unknown}.")
    enabled = value.get("enabled", True)
    classes = value.get("classes", [])
    if not isinstance(enabled, bool):
        raise ValueError("monitor.diagnostics.petsc.info.enabled must be boolean.")
    if not isinstance(classes, list) or not all(
        isinstance(item, str) and item.strip() and "," not in item and ":" not in item
        for item in classes
    ):
        raise ValueError(
            "monitor.diagnostics.petsc.info.classes must be a list of non-empty PETSc class names."
        )
    return {"enabled": enabled, "classes": [item.strip() for item in classes]}
 
 

Here is the caller graph for this function:

_diagnostic_bool_or_path()

picurv_cli.core._diagnostic_bool_or_path (   value, str  key  )

protected

Validate a diagnostics value that can be false, true, or a path/viewer string.

Parameters

[in]	value	Candidate value.
[in]	key	Diagnostics key used in error messages.

Returns

Normalized value.

Definition at line 12696 of file core.py.

def _diagnostic_bool_or_path(value, key: str):
    """!
    @brief Validate a diagnostics value that can be false, true, or a path/viewer string.
    @param[in] value Candidate value.
    @param[in] key Diagnostics key used in error messages.
    @return Normalized value.
    """
    if isinstance(value, bool) or value is None:
        return value
    if isinstance(value, str) and value.strip():
        return value.strip()
    raise ValueError(f"monitor.diagnostics.petsc.{key} must be boolean, null, or a non-empty string.")
 
 

Here is the caller graph for this function:

_diagnostic_bool()

bool picurv_cli.core._diagnostic_bool (   value, str  key  )

protected

Validate a diagnostics boolean value.

Parameters

[in]	value	Candidate value.
[in]	key	Diagnostics key used in error messages.

Returns

Boolean value.

Definition at line 12710 of file core.py.

def _diagnostic_bool(value, key: str) -> bool:
    """!
    @brief Validate a diagnostics boolean value.
    @param[in] value Candidate value.
    @param[in] key Diagnostics key used in error messages.
    @return Boolean value.
    """
    if isinstance(value, bool):
        return value
    raise ValueError(f"monitor.diagnostics.petsc.{key} must be boolean.")
 
 

Here is the caller graph for this function:

_diagnostic_bool_or_all()

picurv_cli.core._diagnostic_bool_or_all (   value, str  key  )

protected

Validate a diagnostics value that can be false, true, or "all".

Parameters

[in]	value	Candidate value.
[in]	key	Diagnostics key used in error messages.

Returns

Normalized value.

Definition at line 12722 of file core.py.

def _diagnostic_bool_or_all(value, key: str):
    """!
    @brief Validate a diagnostics value that can be false, true, or "all".
    @param[in] value Candidate value.
    @param[in] key Diagnostics key used in error messages.
    @return Normalized value.
    """
    if isinstance(value, bool) or value is None:
        return value
    if isinstance(value, str) and value.strip().lower() == "all":
        return "all"
    raise ValueError(f"monitor.diagnostics.petsc.{key} must be boolean, null, or 'all'.")
 
 

Here is the caller graph for this function:

_diagnostic_default_file()

str picurv_cli.core._diagnostic_default_file ( str  run_dir, str  filename  )

protected

Return an absolute run-local diagnostics file path.

Parameters

[in]	run_dir	Run directory.
[in]	filename	Diagnostics filename.

Returns

Absolute diagnostics path under the run logs directory.

Definition at line 12736 of file core.py.

def _diagnostic_default_file(run_dir: str, filename: str) -> str:
    """!
    @brief Return an absolute run-local diagnostics file path.
    @param[in] run_dir Run directory.
    @param[in] filename Diagnostics filename.
    @return Absolute diagnostics path under the run logs directory.
    """
    return os.path.abspath(os.path.join(run_dir, CANONICAL_RUN_PATHS["logs"], filename))
 
 

Here is the caller graph for this function:

_diagnostic_resolve_path_or_default()

picurv_cli.core._diagnostic_resolve_path_or_default (   value, str  run_dir, str  default_filename  )

protected

Resolve true/string diagnostics values to a concrete file path.

Parameters

[in]	value	Boolean/string diagnostics value.
[in]	run_dir	Run directory.
[in]	default_filename	Default file name when value is true.

Returns

False, or an absolute/explicit path string.

Definition at line 12746 of file core.py.

def _diagnostic_resolve_path_or_default(value, run_dir: str, default_filename: str):
    """!
    @brief Resolve true/string diagnostics values to a concrete file path.
    @param[in] value Boolean/string diagnostics value.
    @param[in] run_dir Run directory.
    @param[in] default_filename Default file name when value is true.
    @return False, or an absolute/explicit path string.
    """
    if value is True:
        return _diagnostic_default_file(run_dir, default_filename)
    if isinstance(value, str):
        if os.path.isabs(value) or value.startswith(":"):
            return value
        return os.path.abspath(os.path.join(run_dir, "logs", value))
    return False
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_diagnostics_config()

dict picurv_cli.core.resolve_diagnostics_config	(	dict	monitor_cfg,
		"str | None"	run_dir = None,
		str	stage_label = "Solver"
	)

Resolve monitor diagnostics config and default run-local log paths.

Parameters

[in]	monitor_cfg	Parsed monitor.yml mapping.
[in]	run_dir	Optional run directory for default artifact paths.
[in]	stage_label	Solver/PostProcessor suffix used for PETSc output defaults.

Returns

Normalized diagnostics config.

Definition at line 12763 of file core.py.

def resolve_diagnostics_config(monitor_cfg: dict, run_dir: "str | None" = None, stage_label: str = "Solver") -> dict:
    """!
    @brief Resolve monitor diagnostics config and default run-local log paths.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @param[in] run_dir Optional run directory for default artifact paths.
    @param[in] stage_label Solver/PostProcessor suffix used for PETSc output defaults.
    @return Normalized diagnostics config.
    """
    diagnostics_cfg = (monitor_cfg.get("diagnostics", {}) or {}) if isinstance(monitor_cfg, dict) else {}
    if not isinstance(diagnostics_cfg, dict):
        raise ValueError("monitor.diagnostics must be a mapping when provided.")
 
    petsc_raw = diagnostics_cfg.get("petsc", {}) or {}
    if not isinstance(petsc_raw, dict):
        raise ValueError("monitor.diagnostics.petsc must be a mapping when provided.")
    unknown = sorted(set(petsc_raw.keys()) - DIAGNOSTICS_PETSC_KEYS)
    if unknown:
        raise ValueError(f"monitor.diagnostics.petsc has unsupported key(s): {unknown}.")
 
    petsc = {
        "info": _diagnostic_info(petsc_raw.get("info", False)),
        "malloc_debug": _diagnostic_bool(petsc_raw.get("malloc_debug", False), "malloc_debug"),
        "malloc_test": _diagnostic_bool(petsc_raw.get("malloc_test", False), "malloc_test"),
        "malloc_dump": _diagnostic_bool(petsc_raw.get("malloc_dump", False), "malloc_dump"),
        "malloc_view": _diagnostic_bool_or_path(petsc_raw.get("malloc_view", False), "malloc_view"),
        "malloc_view_threshold": petsc_raw.get("malloc_view_threshold"),
        "memory_view": _diagnostic_bool(petsc_raw.get("memory_view", False), "memory_view"),
        "log_view": _diagnostic_bool_or_path(petsc_raw.get("log_view", False), "log_view"),
        "log_view_memory": _diagnostic_bool(petsc_raw.get("log_view_memory", False), "log_view_memory"),
        "log_all": _diagnostic_bool(petsc_raw.get("log_all", False), "log_all"),
        "log_trace": _diagnostic_bool_or_path(petsc_raw.get("log_trace", False), "log_trace"),
        "objects_dump": _diagnostic_bool_or_all(petsc_raw.get("objects_dump", False), "objects_dump"),
        "options_left": petsc_raw.get("options_left"),
    }
    if petsc["malloc_view_threshold"] is not None and not isinstance(petsc["malloc_view_threshold"], (int, float)):
        raise ValueError("monitor.diagnostics.petsc.malloc_view_threshold must be numeric or null.")
    if petsc["options_left"] is not None and not isinstance(petsc["options_left"], bool):
        raise ValueError("monitor.diagnostics.petsc.options_left must be boolean or null.")
 
    memory_raw = diagnostics_cfg.get("runtime_memory_log", {}) or {}
    if not isinstance(memory_raw, dict):
        raise ValueError("monitor.diagnostics.runtime_memory_log must be a mapping when provided.")
    # `file` is refused by the monitor schema; a stored run's config may still carry it.
    memory_unknown = sorted(set(memory_raw.keys()) - {"enabled", "file"})
    if memory_unknown:
        raise ValueError(f"monitor.diagnostics.runtime_memory_log has unsupported key(s): {memory_unknown}.")
    memory_enabled = memory_raw.get("enabled", True)
    if not isinstance(memory_enabled, bool):
        raise ValueError("monitor.diagnostics.runtime_memory_log.enabled must be boolean.")
 
    resolved_petsc = dict(petsc)
    artifacts = []
    if run_dir:
        suffix = "PostProcessor" if stage_label == "PostProcessor" else "Solver"
        resolved_petsc["info"] = False
        defaults = {
            "malloc_view": f"PETSc_MallocView_{suffix}.log",
            "log_view": f"PETSc_LogView_{suffix}.log",
            "log_trace": f"PETSc_LogTrace_{suffix}.log",
        }
        if petsc["info"]["enabled"]:
            info_path = _diagnostic_default_file(run_dir, f"PETSc_Info_{suffix}.log")
            classes = petsc["info"]["classes"]
            resolved_petsc["info"] = info_path + (f":{','.join(classes)}" if classes else "")
            # PetscInfoSetFile appends the emitting MPI rank (for example `.0`).
            artifacts.append(f"{info_path}.*")
        for key, default_name in defaults.items():
            resolved_value = _diagnostic_resolve_path_or_default(petsc[key], run_dir, default_name)
            if key == "log_view" and resolved_value and isinstance(resolved_value, str) and not resolved_value.startswith(":"):
                resolved_value = f":{resolved_value}"
            resolved_petsc[key] = resolved_value
            if resolved_value and isinstance(resolved_value, str) and not resolved_value.startswith(":"):
                artifacts.append(resolved_value)
            elif resolved_value and isinstance(resolved_value, str) and resolved_value.startswith(":"):
                artifacts.append(resolved_value[1:])
        if memory_enabled:
            artifacts.append(
                os.path.abspath(os.path.join(
                    run_dir, CANONICAL_RUN_PATHS["logs"], RUNTIME_MEMORY_FILE
                ))
            )
 
    return {
        "petsc": resolved_petsc,
        "runtime_memory_log": {"enabled": memory_enabled},
        "artifacts": artifacts,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

build_petsc_diagnostics_args()

list picurv_cli.core.build_petsc_diagnostics_args	(	dict	monitor_cfg,
		str	run_dir,
		str	stage_label
	)

Build PETSc diagnostics command-line arguments for a run stage.

Parameters

[in]	monitor_cfg	Parsed monitor.yml mapping.
[in]	run_dir	Run directory used to resolve default diagnostics files.
[in]	stage_label	Stage label for default output names.

Returns

List of executable arguments.

Definition at line 12852 of file core.py.

def build_petsc_diagnostics_args(monitor_cfg: dict, run_dir: str, stage_label: str) -> list:
    """!
    @brief Build PETSc diagnostics command-line arguments for a run stage.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @param[in] run_dir Run directory used to resolve default diagnostics files.
    @param[in] stage_label Stage label for default output names.
    @return List of executable arguments.
    """
    diagnostics = resolve_diagnostics_config(monitor_cfg, run_dir, stage_label)
    petsc = diagnostics["petsc"]
    args = []
    if petsc["info"]:
        args.extend(["-info", str(petsc["info"])])
    if petsc["malloc_debug"]:
        args.append("-malloc_debug")
    if petsc["malloc_test"]:
        args.append("-malloc_test")
    for key, flag in (
        ("malloc_dump", "-malloc_dump"),
        ("malloc_view", "-malloc_view"),
        ("memory_view", "-memory_view"),
        ("log_view", "-log_view"),
        ("log_trace", "-log_trace"),
        ("objects_dump", "-objects_dump"),
    ):
        value = petsc.get(key)
        if value is True:
            args.append(flag)
        elif value:
            args.extend([flag, str(value)])
    if petsc["malloc_view_threshold"] is not None:
        args.extend(["-malloc_view_threshold", str(petsc["malloc_view_threshold"])])
    if petsc["log_view_memory"]:
        args.append("-log_view_memory")
    if petsc["log_all"]:
        args.append("-log_all")
    if petsc["options_left"] is not None:
        args.extend(["-options_left", "true" if petsc["options_left"] else "false"])
    elif stage_label == "PostProcessor":
        # The postprocessor reads the solver's control file, so every solver-only option
        # would be reported as unused on each run; left unset, the report is turned off.
        args.extend(["-options_left", "false"])
    return args
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_statistics_subsystem_available()

bool picurv_cli.core._statistics_subsystem_available ( dict  case_cfg,   requirement  )

protected

Report whether the subsystem a statistics field depends on is active.

Parameters

[in]	case_cfg	Parsed case configuration.
[in]	requirement	Subsystem key from STATISTICS_ELIGIBLE_FIELDS, or None.

Returns

Value returned by _statistics_subsystem_available().

Definition at line 12897 of file core.py.

def _statistics_subsystem_available(case_cfg: dict, requirement) -> bool:
    """!
    @brief Report whether the subsystem a statistics field depends on is active.
    @param[in] case_cfg Parsed case configuration.
    @param[in] requirement Subsystem key from `STATISTICS_ELIGIBLE_FIELDS`, or None.
    @return Value returned by `_statistics_subsystem_available()`.
    """
    if requirement is None:
        return True
    physics = ((case_cfg or {}).get("models", {}) or {}).get("physics", {}) or {}
    if requirement == "particles":
        particles = physics.get("particles", {}) or {}
        try:
            return int(particles.get("count", 0) or 0) > 0
        except (TypeError, ValueError):
            return False
    turbulence = physics.get("turbulence", {}) or {}
    les_on = bool((turbulence.get("les", {}) or {}).get("enabled", False))
    if requirement == "les":
        return les_on
    if requirement == "turbulence":
        return les_on
    return False
 
 

Here is the caller graph for this function:

normalize_field_statistics_config()

dict picurv_cli.core.normalize_field_statistics_config	(	dict	monitor_cfg,
		dict	case_cfg = None
	)

Validate and canonicalize the field-statistics block of monitor.yml.

Rejects every condition the field-statistics contract forbids, naming the offending window so a message points at one entry rather than the block. Returns a canonical form the flag resolver serializes without further interpretation, so validation and emission cannot disagree.

Parameters

[in]	monitor_cfg	Parsed monitor configuration.
[in]	case_cfg	Parsed case configuration, used to check that each field's subsystem is active. Subsystem checks are skipped when None.

Returns

Value returned by normalize_field_statistics_config().

Definition at line 12922 of file core.py.

def normalize_field_statistics_config(monitor_cfg: dict, case_cfg: dict = None) -> dict:
    """!
    @brief Validate and canonicalize the field-statistics block of monitor.yml.
 
    @details Rejects every condition the field-statistics contract forbids, naming the
             offending window so a message points at one entry rather than the block.
             Returns a canonical form the flag resolver serializes without further
             interpretation, so validation and emission cannot disagree.
 
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] case_cfg Parsed case configuration, used to check that each field's
                        subsystem is active. Subsystem checks are skipped when None.
    @return Value returned by `normalize_field_statistics_config()`.
    """
    raw = (monitor_cfg or {}).get("field_statistics")
    if raw is None:
        return {"enabled": False, "windows": []}
    if not isinstance(raw, dict):
        raise ValueError("'field_statistics' must be a mapping.")
 
    enabled = raw.get("enabled", False)
    if not isinstance(enabled, bool):
        raise ValueError("'field_statistics.enabled' must be true or false.")
    windows_raw = raw.get("windows", []) or []
    if not isinstance(windows_raw, list):
        raise ValueError("'field_statistics.windows' must be a list.")
    if enabled and not windows_raw:
        raise ValueError("'field_statistics.enabled' is true but no window is defined.")
 
    windows = []
    seen_names = set()
    for index, window in enumerate(windows_raw):
        if not isinstance(window, dict):
            raise ValueError(f"'field_statistics.windows[{index}]' must be a mapping.")
        name = window.get("name")
        if not isinstance(name, str) or not name.strip():
            raise ValueError(f"'field_statistics.windows[{index}]' needs a non-empty 'name'.")
        name = name.strip()
        # Window names identify saved state across a restart, so a duplicate would
        # make two windows indistinguishable in the checkpoint.
        if name in seen_names:
            raise ValueError(f"field statistics window '{name}' is defined more than once.")
        seen_names.add(name)
 
        start_time = window.get("start_time")
        if not isinstance(start_time, (int, float)) or isinstance(start_time, bool):
            raise ValueError(f"field statistics window '{name}': 'start_time' must be a number.")
        end_time = window.get("end_time")
        if end_time is not None:
            if not isinstance(end_time, (int, float)) or isinstance(end_time, bool):
                raise ValueError(f"field statistics window '{name}': 'end_time' must be a number.")
            if float(end_time) <= float(start_time):
                raise ValueError(
                    f"field statistics window '{name}': 'end_time' ({end_time}) must be greater "
                    f"than 'start_time' ({start_time})."
                )
 
        weighting = window.get("weighting")
        if weighting not in STATISTICS_WEIGHTING_MODES:
            raise ValueError(
                f"field statistics window '{name}': 'weighting' must be one of "
                f"{list(STATISTICS_WEIGHTING_MODES)} (got {weighting!r})."
            )
 
        has_step = "step_cadence" in window and window["step_cadence"] is not None
        has_time = "time_cadence" in window and window["time_cadence"] is not None
        if has_step == has_time:
            raise ValueError(
                f"field statistics window '{name}': set exactly one of 'step_cadence' and "
                "'time_cadence'."
            )
        step_cadence = None
        time_cadence = None
        if has_step:
            step_cadence = window["step_cadence"]
            if not isinstance(step_cadence, int) or isinstance(step_cadence, bool) or step_cadence <= 0:
                raise ValueError(
                    f"field statistics window '{name}': 'step_cadence' must be a positive integer "
                    f"(got {step_cadence!r})."
                )
        else:
            time_cadence = window["time_cadence"]
            if (not isinstance(time_cadence, (int, float)) or isinstance(time_cadence, bool)
                    or float(time_cadence) <= 0.0):
                raise ValueError(
                    f"field statistics window '{name}': 'time_cadence' must be a positive number "
                    f"(got {time_cadence!r})."
                )
 
        fields, covariances = _normalize_statistics_requests(
            f"field statistics window '{name}'", window.get("fields"), window.get("covariances"),
            STATISTICS_ELIGIBLE_FIELDS, case_cfg)
 
        windows.append({
            "name": name,
            "start_time": float(start_time),
            "end_time": None if end_time is None else float(end_time),
            "weighting": weighting,
            "step_cadence": step_cadence,
            "time_cadence": None if time_cadence is None else float(time_cadence),
            "fields": fields,
            "covariances": covariances,
        })
 
    return {"enabled": bool(enabled), "windows": windows}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_normalize_statistics_requests()

picurv_cli.core._normalize_statistics_requests ( str  label,   fields_raw,   covariances_raw, dict  eligible,   case_cfg = None  )

protected

Validate and canonicalize the fields and covariances one window or ensemble requests.

Parameters

[in]	label	Owner named in error messages, such as ‘field statistics window 'w’`.
[in]	fields_raw	The requested fields list of the owner.
[in]	covariances_raw	The requested covariance pairs of the owner, or None.
[in]	eligible	Fields the owner may name, with component counts and requirements.
[in]	case_cfg	Parsed case configuration for subsystem checks, or None to skip them.

Returns

Tuple of the canonical field entries and covariance pairs.

Definition at line 13029 of file core.py.

def _normalize_statistics_requests(label: str, fields_raw, covariances_raw, eligible: dict, case_cfg=None):
    """!
    @brief Validate and canonicalize the fields and covariances one window or ensemble requests.
    @param[in] label Owner named in error messages, such as `field statistics window 'w'`.
    @param[in] fields_raw The requested fields list of the owner.
    @param[in] covariances_raw The requested covariance pairs of the owner, or None.
    @param[in] eligible Fields the owner may name, with component counts and requirements.
    @param[in] case_cfg Parsed case configuration for subsystem checks, or None to skip them.
    @return Tuple of the canonical field entries and covariance pairs.
    """
    if not isinstance(fields_raw, list) or not fields_raw:
        raise ValueError(f"{label}: 'fields' must be a non-empty list.")
    fields = []
    for field_entry in fields_raw:
        if not isinstance(field_entry, dict):
            raise ValueError(f"{label}: each 'fields' entry must be a mapping.")
        field_name = field_entry.get("field")
        if not isinstance(field_name, str) or field_name not in eligible:
            raise ValueError(
                f"{label}: field {field_name!r} cannot be accumulated. "
                f"Available fields: {sorted(eligible)}."
            )
        requirement = eligible[field_name]["requires"]
        if case_cfg is not None and not _statistics_subsystem_available(case_cfg, requirement):
            raise ValueError(
                f"{label}: field '{field_name}' requires the "
                f"'{requirement}' subsystem, which is not enabled for this case."
            )
        if any(existing["field"] == field_name for existing in fields):
            raise ValueError(
                f"{label}: field '{field_name}' is listed more than once."
            )
        moments = field_entry.get("moments")
        if not isinstance(moments, list) or not moments:
            raise ValueError(
                f"{label}: field '{field_name}' needs a non-empty "
                "'moments' list."
            )
        unknown = [m for m in moments if m not in STATISTICS_MOMENT_NAMES]
        if unknown:
            raise ValueError(
                f"{label}: field '{field_name}' requests unknown "
                f"moments {unknown}. Available moments: {list(STATISTICS_MOMENT_NAMES)}."
            )
        # The first moment is always kept, because every centered product is
        # measured against it.
        fields.append({"field": field_name, "moments": ["first"] + (["second"] if "second" in moments else [])})
 
    covariances_raw = covariances_raw or []
    if not isinstance(covariances_raw, list):
        raise ValueError(f"{label}: 'covariances' must be a list.")
    requested = {entry["field"] for entry in fields}
    covariances = []
    for pair in covariances_raw:
        if not isinstance(pair, list) or len(pair) != 2:
            raise ValueError(
                f"{label}: each covariance must be a pair of field names."
            )
        first, second = pair
        for member in (first, second):
            if not isinstance(member, str) or member not in eligible:
                raise ValueError(
                    f"{label}: covariance member {member!r} cannot be "
                    f"accumulated. Available fields: {sorted(eligible)}."
                )
        if first == second:
            raise ValueError(
                f"{label}: covariance ['{first}', '{second}'] pairs a "
                "field with itself; request that through moments: [second] instead."
            )
        missing = sorted({first, second} - requested)
        if missing:
            raise ValueError(
                f"{label}: covariance ['{first}', '{second}'] needs "
                f"{missing} in 'fields' as well, because a co-moment is centered against their means."
            )
        # Two three-component fields would need a full nine-component tensor,
        # which nothing allocates.
        if (eligible[first]["components"] == 3
                and eligible[second]["components"] == 3):
            raise ValueError(
                f"{label}: covariance ['{first}', '{second}'] pairs two "
                "vector fields, which is not supported."
            )
        if sorted((first, second)) in [sorted(existing) for existing in covariances]:
            raise ValueError(
                f"{label}: covariance ['{first}', '{second}'] is "
                "requested more than once."
            )
        covariances.append([first, second])
 
    return fields, covariances
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_field_statistics_flags()

list picurv_cli.core.resolve_field_statistics_flags	(	dict	monitor_cfg,
		dict	case_cfg = None
	)

Serialize field-statistics configuration into control-file option lines.

A window list is variable arity, so its option names are constructed from the index. Each name belongs to a family declared in the ingress audit manifest.

Parameters

[in]	monitor_cfg	Parsed monitor configuration.
[in]	case_cfg	Parsed case configuration, for subsystem availability checks.

Returns

Value returned by resolve_field_statistics_flags().

Definition at line 13123 of file core.py.

def resolve_field_statistics_flags(monitor_cfg: dict, case_cfg: dict = None) -> list:
    """!
    @brief Serialize field-statistics configuration into control-file option lines.
    @details A window list is variable arity, so its option names are constructed from
             the index. Each name belongs to a family declared in the ingress audit
             manifest.
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] case_cfg Parsed case configuration, for subsystem availability checks.
    @return Value returned by `resolve_field_statistics_flags()`.
    """
    config = normalize_field_statistics_config(monitor_cfg, case_cfg)
    if not config["enabled"]:
        return []
 
    # Window times are physical; the runtime compares them against its own clock, which
    # is in solver time, so each is divided by the reference time L_ref / U_ref.
    scales = resolve_reference_scales(case_cfg or {})
    window_path = ("monitor", "field_statistics", "windows", "[]")
 
    def solver_time(key: str, value: float) -> float:
        """!
        @brief Convert one physical window time to solver time.
        @param[in] key Window key, for the recorded dimension.
        @param[in] value Physical time.
        @return Solver time.
        """
        return to_solver_units(value, window_path + (key,), scales)
 
    lines = ["-field_statistics_enabled true",
             f"-field_statistics_window_count {len(config['windows'])}"]
    for index, window in enumerate(config["windows"]):
        prefix = f"-field_statistics_window_{index}"
        lines.append(f"{prefix}_name {window['name']}")
        lines.append(f"{prefix}_start_time {solver_time('start_time', window['start_time'])!r}")
        # An absent end time is what makes a window open ended, so the option is
        # omitted rather than given a sentinel value.
        if window["end_time"] is not None:
            lines.append(f"{prefix}_end_time {solver_time('end_time', window['end_time'])!r}")
        lines.append(f"{prefix}_weighting {window['weighting']}")
        if window["step_cadence"] is not None:
            lines.append(f"{prefix}_step_cadence {window['step_cadence']}")
        else:
            lines.append(f"{prefix}_time_cadence {solver_time('time_cadence', window['time_cadence'])!r}")
        lines.append(f"{prefix}_field_count {len(window['fields'])}")
        for field_index, field_entry in enumerate(window["fields"]):
            lines.append(f"{prefix}_field_{field_index}_name {field_entry['field']}")
            lines.append(f"{prefix}_field_{field_index}_moments {','.join(field_entry['moments'])}")
        lines.append(f"{prefix}_covariance_count {len(window['covariances'])}")
        for pair_index, pair in enumerate(window["covariances"]):
            lines.append(f"{prefix}_covariance_{pair_index} {pair[0]},{pair[1]}")
    return lines
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_statistics_console_output_frequency()

"int | None" picurv_cli.core.resolve_statistics_console_output_frequency

(

dict

io_cfg

)

Resolve the statistics console cadence, mirroring the particle one.

Parameters

[in]

io_cfg

Parsed monitor io block.

Returns

Value returned by resolve_statistics_console_output_frequency().

Definition at line 13176 of file core.py.

def resolve_statistics_console_output_frequency(io_cfg: dict) -> "int | None":
    """!
    @brief Resolve the statistics console cadence, mirroring the particle one.
    @param[in] io_cfg Parsed monitor `io` block.
    @return Value returned by `resolve_statistics_console_output_frequency()`.
    """
    if 'statistics_console_output_frequency' in io_cfg:
        return io_cfg['statistics_console_output_frequency']
    return io_cfg.get('data_output_frequency')
 
 

Here is the caller graph for this function:

normalize_solution_monitoring_config()

dict picurv_cli.core.normalize_solution_monitoring_config

(

dict

monitor_cfg

)

Validate and canonicalize physical-solution convergence monitoring.

Parameters

[in]

monitor_cfg

Parsed monitor.yml mapping.

Returns

Canonical solution-monitoring configuration.

Exceptions

ValueError

when convergence settings are invalid.

Definition at line 13187 of file core.py.

def normalize_solution_monitoring_config(monitor_cfg: dict) -> dict:
    """!
    @brief Validate and canonicalize physical-solution convergence monitoring.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @return Canonical solution-monitoring configuration.
    @throws ValueError when convergence settings are invalid.
    """
    if not isinstance(monitor_cfg, dict):
        raise ValueError("monitor.yml must be a mapping before solution monitoring can be normalized.")
    monitoring = monitor_cfg.get("solution_monitoring", {}) or {}
    if not isinstance(monitoring, dict):
        raise ValueError("solution_monitoring must be a mapping when provided.")
    convergence = monitoring.get("convergence", {}) or {}
    if not isinstance(convergence, dict):
        raise ValueError("solution_monitoring.convergence must be a mapping when provided.")
    enabled = convergence.get("enabled", True)
    if not isinstance(enabled, bool):
        raise ValueError("solution_monitoring.convergence.enabled must be boolean.")
    mode = normalize_solution_convergence_mode(convergence.get("mode", "steady_deterministic"))
    normalized = {"enabled": enabled, "mode": mode.lower()}
    periodic_cfg = convergence.get("periodic_deterministic")
    statistical_cfg = convergence.get("statistical_steady")
    if mode == "PERIODIC_DETERMINISTIC":
        if not isinstance(periodic_cfg, dict):
            raise ValueError(
                "solution_monitoring.convergence.periodic_deterministic is required for periodic_deterministic mode."
            )
        period_steps = periodic_cfg.get("period_steps")
        if isinstance(period_steps, bool) or not isinstance(period_steps, int) or period_steps <= 0:
            raise ValueError(
                "solution_monitoring.convergence.periodic_deterministic.period_steps must be a positive integer."
            )
        normalized["periodic_deterministic"] = {"period_steps": period_steps}
    elif periodic_cfg is not None:
        raise ValueError(
            "solution_monitoring.convergence.periodic_deterministic is only valid for periodic_deterministic mode."
        )
    if mode == "STATISTICAL_STEADY":
        if not isinstance(statistical_cfg, dict):
            raise ValueError(
                "solution_monitoring.convergence.statistical_steady is required for statistical_steady mode."
            )
        window_steps = statistical_cfg.get("window_steps")
        if isinstance(window_steps, bool) or not isinstance(window_steps, int) or window_steps <= 0:
            raise ValueError(
                "solution_monitoring.convergence.statistical_steady.window_steps must be a positive integer."
            )
        normalized["statistical_steady"] = {"window_steps": window_steps}
    elif statistical_cfg is not None:
        raise ValueError(
            "solution_monitoring.convergence.statistical_steady is only valid for statistical_steady mode."
        )
    return {"convergence": normalized}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_solution_monitoring_flags()

dict picurv_cli.core.resolve_solution_monitoring_flags

(

dict

monitor_cfg

)

Translate solution-monitoring YAML into the existing C convergence flags.

Parameters

[in]

monitor_cfg

Parsed monitor.yml mapping.

Returns

Mapping of convergence options to explicit runtime values.

Definition at line 13242 of file core.py.

def resolve_solution_monitoring_flags(monitor_cfg: dict) -> dict:
    """!
    @brief Translate solution-monitoring YAML into the existing C convergence flags.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @return Mapping of convergence options to explicit runtime values.
    """
    convergence = normalize_solution_monitoring_config(monitor_cfg)["convergence"]
    flags = {
        "-solution_convergence_enabled": "true" if convergence["enabled"] else "false",
        "-solution_convergence_mode": f'"{normalize_solution_convergence_mode(convergence["mode"])}"',
    }
    if "periodic_deterministic" in convergence:
        flags["-solution_convergence_period_steps"] = convergence["periodic_deterministic"]["period_steps"]
    if "statistical_steady" in convergence:
        flags["-solution_convergence_window_steps"] = convergence["statistical_steady"]["window_steps"]
    return flags
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

prepare_monitor_files()

dict picurv_cli.core.prepare_monitor_files	(	str	run_dir,
		str	run_id,
		dict	monitor_cfg,
		dict	source_files,
		str	config_dir = None
	)

Generate monitor sidecar files and resolve profiling reporting behavior.

Parameters

[in]	run_dir	Argument passed to prepare_monitor_files().
[in]	run_id	Argument passed to prepare_monitor_files().
[in]	monitor_cfg	Argument passed to prepare_monitor_files().
[in]	source_files	Argument passed to prepare_monitor_files().
[in]	config_dir	Optional configuration revision directory.

Returns

Value returned by prepare_monitor_files().

Definition at line 13260 of file core.py.

                          config_dir: str = None) -> dict:
    """!
    @brief Generate monitor sidecar files and resolve profiling reporting behavior.
    @param[in] run_dir Argument passed to `prepare_monitor_files()`.
    @param[in] run_id Argument passed to `prepare_monitor_files()`.
    @param[in] monitor_cfg Argument passed to `prepare_monitor_files()`.
    @param[in] source_files Argument passed to `prepare_monitor_files()`.
    @param[in] config_dir Optional configuration revision directory.
    @return Value returned by `prepare_monitor_files()`.
    """
    print("[INFO] Generating monitoring files...")
 
    whitelist_path = None
    if has_explicit_monitor_whitelist(monitor_cfg):
        enabled = normalize_monitor_function_names(
            monitor_cfg["logging"]["enabled_functions"], "monitor.logging.enabled_functions")
        whitelist_path = generate_simple_list_file(
            run_dir, run_id, {"logging": {"enabled_functions": enabled}}, "logging", "enabled_functions",
            "whitelist.run", source_files, config_dir=config_dir,
        )
    else:
        print("[INFO] logging.enabled_functions is empty; omitting whitelist.run so the C runtime uses its default allow-list.")
 
    profiling_cfg = resolve_profiling_config(monitor_cfg)
 
    profile_path = None
    if profiling_cfg["mode"] == "selected":
        profile_path = generate_simple_list_file(
            run_dir,
            run_id,
            {"profiling": {"selected_functions": profiling_cfg["functions"]}},
            "profiling",
            "selected_functions",
            "profile.run",
            source_files,
            config_dir=config_dir,
        )
    else:
        print(f"[INFO] profiling.timestep_output.mode is '{profiling_cfg['mode']}'; no profile.run function list is needed.")
 
    return {
        "whitelist": whitelist_path,
        "profile": profile_path,
        "profiling": profiling_cfg,
    }
 

Here is the call graph for this function:

Here is the caller graph for this function:

generate_multi_block_bcs()

list picurv_cli.core.generate_multi_block_bcs	(	str	run_dir,
		str	run_id,
		dict	case_cfg,
		dict	source_files,
		str	config_dir = None
	)

Parses multi-block BCs from YAML, generates a .run file for each block, and returns a list of their absolute paths.

Handles both simple list format (for single-block cases) and a list-of-lists (for multi-block cases) for boundary conditions.

Parameters

[in]	run_dir	The path to the main run directory.
[in]	run_id	The unique identifier for the run.
[in]	case_cfg	The parsed case.yml configuration dictionary.
[in]	source_files	A dictionary of source files for the header.
[in]	config_dir	Optional configuration revision directory.

Returns

A list of absolute paths to the generated BC files.

Exceptions

ValueError

if the number of BC definitions does not match the number of blocks.

Definition at line 13307 of file core.py.

                             config_dir: str = None) -> list:
    """!
    @brief Parses multi-block BCs from YAML, generates a .run file for each block,
           and returns a list of their absolute paths.
    @details Handles both simple list format (for single-block cases) and a
             list-of-lists (for multi-block cases) for boundary conditions.
    @param[in] run_dir The path to the main run directory.
    @param[in] run_id The unique identifier for the run.
    @param[in] case_cfg The parsed case.yml configuration dictionary.
    @param[in] source_files A dictionary of source files for the header.
    @param[in] config_dir Optional configuration revision directory.
    @return A list of absolute paths to the generated BC files.
    @throws ValueError if the number of BC definitions does not match the number of blocks.
    """
    print("[INFO] Generating boundary condition files...")
    config_dir = config_dir or os.path.join(run_dir, "config")
    os.makedirs(config_dir, exist_ok=True)
    profile_dir = os.path.join(run_dir, "inputs", "inlet_profiles")
    os.makedirs(profile_dir, exist_ok=True)
    num_blocks = int(case_cfg.get('models', {}).get('domain', {}).get('blocks', 1))
    prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    case_path = source_files.get("Case") if source_files else None
    profile_grid_dims = None
    # Every profile source stages a physical velocity PICSLICE.
    profile_velocity_scale = reference_scale(BC_PARAM_QUANTITIES["source"][0], resolve_reference_scales(case_cfg))
 
    if any(bc.get("handler") == "prescribed_flow" for block in prepared_blocks for bc in block):
        profile_grid_dims = resolve_grid_block_dimensions_for_profiles(case_cfg, case_path, run_dir)
 
    generated_files = []
    generated_profile_summaries = []
    generated_target_grid = None
    field_slice_target_grid = None
    for i, block_bcs_list in enumerate(prepared_blocks):
        file_name = "bcs.run" if num_blocks == 1 else f"bcs_block{i}.run"
        bcs_file_path = os.path.join(config_dir, file_name)
        bcs_lines = [generate_header(run_id, source_files)]
 
        for bc in block_bcs_list:
            face, bc_type, handler = bc['face'], bc['type'], bc['handler']
            params = dict(bc.get('params') or {})
            if handler == "prescribed_flow":
                source = params.pop("source")
                expected_dims = _bc_profile_expected_dims(face, profile_grid_dims[i])
                staged_name = f"inlet_profile_block{i}_{face.replace('+', 'pos').replace('-', 'neg')}.picslice"
                staged_path = os.path.join(profile_dir, staged_name)
                if os.path.isfile(staged_path):
                    with open(staged_path, "r", encoding="utf-8") as stream:
                        header = [line.strip() for line in stream if line.strip() and not line.lstrip().startswith("#")]
                    if len(header) < 3 or header[0] != "PICSLICE":
                        raise ValueError(f"Locked inlet profile is not a PICSLICE file: {staged_path}")
                    try:
                        actual_dims = tuple(int(token) for token in header[2].split())
                    except ValueError as exc:
                        raise ValueError(f"Locked inlet profile has invalid dimensions: {staged_path}") from exc
                    if actual_dims != tuple(expected_dims):
                        raise ValueError(
                            f"Locked inlet profile {staged_path} has dimensions {actual_dims}; "
                            f"expected {tuple(expected_dims)}."
                        )
                    print(
                        f"[INFO] Reusing locked prescribed_flow profile for block {i}, "
                        f"face {face}: {os.path.relpath(staged_path)}"
                    )
                    params["source_file"] = os.path.abspath(staged_path)
                    source = None
                elif source["type"] == "file":
                    source_path = _resolve_case_relative_path(
                        source["path"], os.path.dirname(os.path.abspath(case_path))
                    )
                elif source["type"] == "generated":
                    source_path = os.path.join(
                        profile_dir,
                        f"inlet_profile_block{i}_{_face_artifact_token(face)}.generated.dimensional.picslice",
                    )
                    if os.path.abspath(source_path) == os.path.abspath(staged_path):
                        raise ValueError(
                            f"Generated profile output_file for block {i}, face {face} must differ from staged solver profile."
                        )
                    if source["generator"] == "square_duct_poiseuille":
                        if generated_target_grid is None:
                            generated_target_grid = resolve_target_grid_for_generated_profile(case_cfg, case_path, run_dir)
                        summary = generate_square_duct_poiseuille_picslice(
                            source_path,
                            expected_dims,
                            source["params"],
                            target_grid=generated_target_grid,
                            target_block=i,
                            target_face=face,
                            script=source.get("script"),
                            case_path=case_path,
                        )
                    else:
                        raise ValueError(f"Unsupported generated profile generator '{source['generator']}'.")
                    summary.update({"block": i, "face": face})
                    generated_profile_summaries.append(summary)
                elif source["type"] == "field_slice":
                    source_path = os.path.join(
                        profile_dir,
                        f"inlet_profile_block{i}_{_face_artifact_token(face)}.sliced.dimensional.picslice",
                    )
                    if os.path.abspath(source_path) == os.path.abspath(staged_path):
                        raise ValueError(
                            f"field_slice output_file for block {i}, face {face} must differ from staged solver profile."
                        )
                    if field_slice_target_grid is None:
                        field_slice_target_grid = resolve_target_grid_for_field_slice(case_cfg, case_path, run_dir)
                    summary = generate_field_slice_picslice(
                        source_path,
                        expected_dims,
                        source,
                        field_slice_target_grid,
                        face,
                        i,
                        case_path,
                    )
                    summary.update({"block": i, "face": face})
                    generated_profile_summaries.append(summary)
                elif source is not None:
                    raise ValueError(f"Unsupported prescribed_flow source type '{source.get('type')}'.")
                if source is not None:
                    summary = validate_and_nondimensionalize_picslice(source_path, staged_path, profile_velocity_scale, expected_dims)
                    print(
                        f"[SUCCESS] Staged prescribed_flow profile for block {i}, face {face}: "
                        f"{os.path.relpath(staged_path)} dims={summary['dims']}"
                    )
                    params["source_file"] = os.path.abspath(staged_path)
            params_str = ""
            if params:
                parts = []
                for k, v in params.items():
                    if isinstance(v, bool):
                        value_str = "true" if v else "false"
                    else:
                        value_str = str(v)
                    parts.append(f"{k}={value_str}")
                params_str = " ".join(parts)
            bcs_lines.append(f"{face:<20s} {bc_type:<12s} {handler:<20s} {params_str}")
        
        with open(bcs_file_path, "w") as f: f.write("\n".join(bcs_lines))
        
        print(f"[SUCCESS] Generated BCs for Block {i}: {os.path.relpath(bcs_file_path)}")
        generated_files.append(os.path.abspath(bcs_file_path))
 
    if generated_profile_summaries:
        info_path = write_profile_info(profile_dir, generated_profile_summaries)
        print(f"[SUCCESS] Wrote generated profile summary: {os.path.relpath(info_path)}")
        
    return generated_files
 

Here is the call graph for this function:

Here is the caller graph for this function:

format_flag_value()

picurv_cli.core.format_flag_value

(

value

)

Converts Python types to C-style command-line flag values.

Parameters

[in]

value

The Python object to convert (bool, list, or other).

Returns

A string representation suitable for a C command-line parser.

Definition at line 13458 of file core.py.

def format_flag_value(value):
    """!
    @brief Converts Python types to C-style command-line flag values.
    @param[in] value The Python object to convert (bool, list, or other).
    @return A string representation suitable for a C command-line parser.
    """
    if isinstance(value, bool):
        return "1" if value else "0"
    if isinstance(value, list):
        return ",".join(map(str, value))
    return str(value)
 

Here is the caller graph for this function:

translate_programmatic_grid_settings()

dict picurv_cli.core.translate_programmatic_grid_settings

(

dict

grid_settings

)

Return programmatic-grid settings translated to the C node-count contract.

Parameters

[in]

grid_settings

Argument passed to translate_programmatic_grid_settings().

Returns

Value returned by translate_programmatic_grid_settings().

Definition at line 13470 of file core.py.

def translate_programmatic_grid_settings(grid_settings: dict) -> dict:
    """!
    @brief Return programmatic-grid settings translated to the C node-count contract.
    @param[in] grid_settings Argument passed to `translate_programmatic_grid_settings()`.
    @return Value returned by `translate_programmatic_grid_settings()`.
    """
    translated = dict(grid_settings)
    for dim_key in ("im", "jm", "km"):
        if dim_key in translated:
            raw_val = translated[dim_key]
            if not isinstance(raw_val, int) or raw_val <= 0:
                raise ValueError(
                    f"grid.programmatic_settings.{dim_key} must be a positive integer cell count "
                    f"(got {raw_val!r})."
                )
            translated[dim_key] = raw_val + 1
    return translated
 
 

Here is the caller graph for this function:

validate_programmatic_bridge_grid_settings()

None picurv_cli.core.validate_programmatic_bridge_grid_settings

(

dict

raw_settings

)

Validate the scalar programmatic grid settings the bridge PICGRID is built from.

A Python generator - an initial condition or a generated inlet profile - runs as a separate process and reads the programmatic grid from that bridge, which supports one block with scalar settings.

Parameters

[in]

raw_settings

programmatic_settings dict from case.yml.

Exceptions

ValueError

when required scalar settings are missing or invalid.

Definition at line 13496 of file core.py.

def validate_programmatic_bridge_grid_settings(raw_settings: dict) -> None:
    """!
    @brief Validate the scalar programmatic grid settings the bridge PICGRID is built from.
    @details A Python generator - an initial condition or a generated inlet profile - runs
             as a separate process and reads the programmatic grid from that bridge, which
             supports one block with scalar settings.
    @param[in] raw_settings programmatic_settings dict from case.yml.
    @throws ValueError when required scalar settings are missing or invalid.
    """
    if not isinstance(raw_settings, dict):
        raise ValueError(
            "grid.programmatic_settings must be a mapping when a Python generator reads the grid."
        )
 
    missing = [key for key in PROGRAMMATIC_BRIDGE_GRID_KEYS if key not in raw_settings]
    if missing:
        raise ValueError(
            "grid.programmatic_settings must include "
            f"{missing} when grid.mode is 'programmatic_c' and a Python generator reads the grid."
        )
 
    for key in ("im", "jm", "km"):
        value = raw_settings[key]
        if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
            raise ValueError(
                f"grid.programmatic_settings.{key} must be a positive scalar integer cell count "
                "when a Python generator reads the programmatic_c grid."
            )
 
    for key in ("xMins", "xMaxs", "yMins", "yMaxs", "zMins", "zMaxs", "rxs", "rys", "rzs"):
        value = raw_settings[key]
        if isinstance(value, (list, tuple, dict, bool)):
            raise ValueError(
                f"grid.programmatic_settings.{key} must be a scalar numeric value "
                "when a Python generator reads the programmatic_c grid."
            )
        try:
            numeric = float(value)
        except (TypeError, ValueError):
            raise ValueError(
                f"grid.programmatic_settings.{key} must be a scalar numeric value "
                "when a Python generator reads the programmatic_c grid."
            )
        if not math.isfinite(numeric):
            raise ValueError(
                f"grid.programmatic_settings.{key} must be finite "
                "when a Python generator reads the programmatic_c grid."
            )
        if key in {"rxs", "rys", "rzs"} and numeric <= 0.0:
            raise ValueError(
                f"grid.programmatic_settings.{key} must be positive "
                "when a Python generator reads the programmatic_c grid."
            )
 
 

Here is the caller graph for this function:

generate_picgrid_from_programmatic_settings()

dict picurv_cli.core.generate_picgrid_from_programmatic_settings	(	dict	raw_settings,
		str	dest_path,
		float	L_ref
	)

Generate a canonical PICGRID file from programmatic Cartesian grid settings.

Implements the same coordinate formula as ComputeStretchedCoord in src/grid.c. im/jm/km in raw_settings are cell counts; node counts are im+1, jm+1, km+1.

Parameters

[in]	raw_settings	programmatic_settings dict from case.yml.
[in]	dest_path	Destination PICGRID file path.
[in]	L_ref	Reference length for nondimensionalization (must be non-zero).

Returns

Summary dict: nblk, dims [(IM, JM, KM)], total_nodes.

Definition at line 13551 of file core.py.

def generate_picgrid_from_programmatic_settings(raw_settings: dict, dest_path: str, L_ref: float) -> dict:
    """!
    @brief Generate a canonical PICGRID file from programmatic Cartesian grid settings.
    @details Implements the same coordinate formula as ComputeStretchedCoord in src/grid.c.
             im/jm/km in raw_settings are cell counts; node counts are im+1, jm+1, km+1.
    @param[in] raw_settings programmatic_settings dict from case.yml.
    @param[in] dest_path Destination PICGRID file path.
    @param[in] L_ref Reference length for nondimensionalization (must be non-zero).
    @return Summary dict: nblk, dims [(IM, JM, KM)], total_nodes.
    """
    validate_programmatic_bridge_grid_settings(raw_settings)
    if L_ref == 0.0:
        raise ValueError("length_ref must be non-zero for programmatic grid generation.")
    IM = int(raw_settings.get("im", 0)) + 1
    JM = int(raw_settings.get("jm", 0)) + 1
    KM = int(raw_settings.get("km", 0)) + 1
    if IM < 2 or JM < 2 or KM < 2:
        raise ValueError(
            f"programmatic_settings im/jm/km must each be >= 1 "
            f"(got im={IM-1}, jm={JM-1}, km={KM-1})."
        )
    x_min = float(raw_settings.get("xMins", 0.0))
    x_max = float(raw_settings.get("xMaxs", 1.0))
    y_min = float(raw_settings.get("yMins", 0.0))
    y_max = float(raw_settings.get("yMaxs", 1.0))
    z_min = float(raw_settings.get("zMins", 0.0))
    z_max = float(raw_settings.get("zMaxs", 1.0))
    rx = float(raw_settings.get("rxs", 1.0))
    ry = float(raw_settings.get("rys", 1.0))
    rz = float(raw_settings.get("rzs", 1.0))
 
    def _stretched(idx, N, length, r):
        """!
        @brief Mirror of ComputeStretchedCoord from src/grid.c.
        @param[in] idx Node index along the axis.
        @param[in] N Total node count along the axis.
        @param[in] length Physical length of the axis.
        @param[in] r Geometric stretching ratio.
        @return Coordinate offset from the axis minimum.
        """
        frac = idx / (N - 1.0)
        if abs(r - 1.0) < 1.0e-9:
            return length * frac
        return length * (r ** frac - 1.0) / (r - 1.0)
 
    Lx, Ly, Lz = x_max - x_min, y_max - y_min, z_max - z_min
    os.makedirs(os.path.dirname(dest_path), exist_ok=True)
    with open(dest_path, "w") as fout:
        fout.write("PICGRID\n1\n")
        fout.write(f"{IM} {JM} {KM}\n")
        for k in range(KM):
            z = (z_min + _stretched(k, KM, Lz, rz)) / L_ref
            for j in range(JM):
                y = (y_min + _stretched(j, JM, Ly, ry)) / L_ref
                for i in range(IM):
                    x = (x_min + _stretched(i, IM, Lx, rx)) / L_ref
                    fout.write(
                        f"{format_picgrid_coordinate(x)} {format_picgrid_coordinate(y)} "
                        f"{format_picgrid_coordinate(z)}\n"
                    )
    total_nodes = IM * JM * KM
    return {"nblk": 1, "dims": [(IM, JM, KM)], "total_nodes": total_nodes}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_grid_da_processor_layout()

dict picurv_cli.core.resolve_grid_da_processor_layout

(

dict

grid_cfg

)

Resolve optional global DMDA layout, preferring grid-level keys over legacy nested keys.

Parameters

[in]

grid_cfg

Argument passed to resolve_grid_da_processor_layout().

Returns

Value returned by resolve_grid_da_processor_layout().

Definition at line 13618 of file core.py.

def resolve_grid_da_processor_layout(grid_cfg: dict) -> dict:
    """!
    @brief Resolve optional global DMDA layout, preferring grid-level keys over legacy nested keys.
    @param[in] grid_cfg Argument passed to `resolve_grid_da_processor_layout()`.
    @return Value returned by `resolve_grid_da_processor_layout()`.
    """
    top_level = {}
    legacy = {}
 
    for key in GRID_DA_PROCESSOR_KEYS:
        value = grid_cfg.get(key)
        if isinstance(value, (list, tuple)):
            raise ValueError(
                f"grid.{key} must be a scalar integer. "
                "Per-block MPI decomposition is not implemented on the C side; DMDA layout is global."
            )
        if value is not None:
            if not isinstance(value, int) or value <= 0:
                raise ValueError(f"grid.{key} must be a positive integer when provided (got {value}).")
            top_level[key] = value
 
    legacy_settings = grid_cfg.get("programmatic_settings")
    if isinstance(legacy_settings, dict):
        for key in GRID_DA_PROCESSOR_KEYS:
            value = legacy_settings.get(key)
            if isinstance(value, (list, tuple)):
                raise ValueError(
                    f"grid.programmatic_settings.{key} must be a scalar integer. "
                    "Per-block MPI decomposition is not implemented on the C side; DMDA layout is global."
                )
            if value is not None:
                if not isinstance(value, int) or value <= 0:
                    raise ValueError(
                        f"grid.programmatic_settings.{key} must be a positive integer when provided (got {value})."
                    )
                legacy[key] = value
 
    resolved = {}
    for key in GRID_DA_PROCESSOR_KEYS:
        top_value = top_level.get(key)
        legacy_value = legacy.get(key)
        if top_value is not None and legacy_value is not None and top_value != legacy_value:
            raise ValueError(
                f"grid.{key} conflicts with legacy grid.programmatic_settings.{key}; "
                "define the processor layout in only one place."
            )
        if top_value is not None:
            resolved[key] = top_value
        elif legacy_value is not None:
            resolved[key] = legacy_value
 
    return resolved
 
 

Here is the caller graph for this function:

resolve_grid_node_dims()

"list | None" picurv_cli.core.resolve_grid_node_dims	(	dict	case_cfg,
		str	case_path,
		"str | None"	staged_grid = None
	)

Per-block (IM, JM, KM) node counts the solver will read, without building the grid.

A staged PICGRID, when one exists, is authoritative. Otherwise a file grid's header is read, a programmatic grid's cell counts are converted to nodes, and a grid_gen grid's cell counts are resolved by grid.gen's own parameter precedence without generating any coordinates.

Parameters

[in]	case_cfg	Parsed case configuration.
[in]	case_path	Path to case.yml, for case-relative paths.
[in]	staged_grid	Already staged inputs/grid/grid.run, if any.

Returns

List of node-count tuples, or None when the dimensions cannot be determined.

Definition at line 13672 of file core.py.

                           staged_grid: "str | None" = None) -> "list | None":
    """!
    @brief Per-block (IM, JM, KM) node counts the solver will read, without building the grid.
    @details A staged PICGRID, when one exists, is authoritative. Otherwise a file grid's
             header is read, a programmatic grid's cell counts are converted to nodes,
             and a `grid_gen` grid's cell counts are resolved by grid.gen's own
             parameter precedence without generating any coordinates.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Path to case.yml, for case-relative paths.
    @param[in] staged_grid Already staged `inputs/grid/grid.run`, if any.
    @return List of node-count tuples, or None when the dimensions cannot be determined.
    """
    grid_cfg = case_cfg.get("grid") or {}
    expected_nblk = int(((case_cfg.get("models") or {}).get("domain") or {}).get("blocks", 1))
    case_dir = os.path.dirname(os.path.abspath(case_path))
    mode = grid_cfg.get("mode")
    try:
        if staged_grid and os.path.isfile(staged_grid):
            return read_picgrid_header_dimensions(staged_grid, expected_nblk)
        if mode == "file":
            return read_picgrid_header_dimensions(
                _resolve_case_relative_path(grid_cfg["source_file"], case_dir), expected_nblk)
        if mode == "programmatic_c":
            settings = translate_programmatic_grid_settings(grid_cfg.get("programmatic_settings") or {})
            return [(settings["im"], settings["jm"], settings["km"])]
        if mode == "grid_gen":
            generator = grid_cfg.get("generator") or {}
            if generator.get("script"):
                return None
            tokens = ["-c", _resolve_case_relative_path(generator["config_file"], case_dir)]
            if generator.get("grid_type"):
                tokens.append(str(generator["grid_type"]))
            tokens.extend(str(token) for token in (generator.get("cli_args") or []))
            grid_gen = load_generator_module("grid.gen", "picurv_grid_generator")
            with contextlib.redirect_stdout(StringIO()), contextlib.redirect_stderr(StringIO()):
                _, params = grid_gen.resolve_grid_parameters(tokens)
            return [(params.ncells_i + 1, params.ncells_j + 1, params.ncells_k + 1)]
    except (SystemExit, Exception):
        # Staging reports a malformed grid in its own terms; this check only adds to it.
        return None
    return None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

case_declares_periodic_axis()

bool picurv_cli.core.case_declares_periodic_axis

(

dict

case_cfg

)

Whether any face of any block is PERIODIC, which sets the DMDA stencil width.

Parameters

[in]

case_cfg

Parsed case configuration.

Returns

True when grid setup will use stencil width 3 on every axis.

Definition at line 13716 of file core.py.

def case_declares_periodic_axis(case_cfg: dict) -> bool:
    """!
    @brief Whether any face of any block is PERIODIC, which sets the DMDA stencil width.
    @param[in] case_cfg Parsed case configuration.
    @return True when grid setup will use stencil width 3 on every axis.
    """
    try:
        blocks = validate_and_prepare_boundary_conditions(case_cfg)
    except ValueError:
        return False
    return any(entry.get("type") == "PERIODIC" for block in blocks for entry in block)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

da_processor_layout_problems()

list picurv_cli.core.da_processor_layout_problems	(	dict	grid_cfg,
		"int | None"	num_procs,
		"list | None"	block_dims = None,
		"dict | None"	solver_cfg = None,
		bool	any_periodic = False,
		"str | None"	source = None
	)

Problems with a user-set DMDA layout that would abort grid setup.

Mirrors InitializeAllGridDMs() in src/grid.c: each coarser level holds (IM + 1) / 2 nodes on an axis that is not semi-coarsened, the DMDA carries IM + 1 points, and PETSc's default split gives the smallest rank points // ranks of them. Grid setup requires that to reach the stencil width, which is 3 on every axis when any face is periodic and 2 otherwise. Only the coarsest level can fail, because every finer level is aligned to twice its widths.

Parameters

[in]	grid_cfg	The case's grid block.
[in]	num_procs	MPI processes the solve will launch, or None when unknown (validate without a cluster profile), which skips only the product check.
[in]	block_dims	Per-block node counts, or None to skip the multigrid check.
[in]	solver_cfg	Parsed solver.yml, for the multigrid levels and semi-coarsening.
[in]	any_periodic	Whether any face is PERIODIC.
[in]	source	Where the layout was given, as --ni/--nj/--nk or cluster.yml execution.decomposition; None for case.yml's own keys.

Returns

List of messages; empty when the layout is usable or not set.

Definition at line 13729 of file core.py.

                                 any_periodic: bool = False, source: "str | None" = None) -> list:
    """!
    @brief Problems with a user-set DMDA layout that would abort grid setup.
    @details Mirrors `InitializeAllGridDMs()` in src/grid.c: each coarser level holds
             (IM + 1) / 2 nodes on an axis that is not semi-coarsened, the DMDA carries
             IM + 1 points, and PETSc's default split gives the smallest rank
             points // ranks of them. Grid setup requires that to reach the stencil
             width, which is 3 on every axis when any face is periodic and 2 otherwise.
             Only the coarsest level can fail, because every finer level is aligned to
             twice its widths.
    @param[in] grid_cfg The case's grid block.
    @param[in] num_procs MPI processes the solve will launch, or None when unknown (validate
               without a cluster profile), which skips only the product check.
    @param[in] block_dims Per-block node counts, or None to skip the multigrid check.
    @param[in] solver_cfg Parsed solver.yml, for the multigrid levels and semi-coarsening.
    @param[in] any_periodic Whether any face is PERIODIC.
    @param[in] source Where the layout was given, as `--ni/--nj/--nk` or
               `cluster.yml execution.decomposition`; None for case.yml's own keys.
    @return List of messages; empty when the layout is usable or not set.
    """
    layout = resolve_grid_da_processor_layout(grid_cfg)
    if source == "--ni/--nj/--nk":
        names = dict(zip(GRID_DA_PROCESSOR_KEYS, ("--ni", "--nj", "--nk")))
        together = "--ni x --nj x --nk"
    elif source:
        names = {key: f"{source}.{axis}" for key, axis in zip(GRID_DA_PROCESSOR_KEYS, "ijk")}
        together = f"{source} (i, j, k)"
    else:
        names = {key: f"grid.{key}" for key in GRID_DA_PROCESSOR_KEYS}
        together = "grid.da_processors_x/y/z"
    if not layout or (num_procs is not None and num_procs <= 1):
        return []
    problems = []
    if num_procs is not None and all(layout.get(key) is not None for key in GRID_DA_PROCESSOR_KEYS):
        total_layout = 1
        for key in GRID_DA_PROCESSOR_KEYS:
            total_layout *= layout[key]
        if total_layout != num_procs:
            printable = " x ".join(str(layout[key]) for key in GRID_DA_PROCESSOR_KEYS)
            problems.append(
                "DMDA processor layout mismatch: "
                f"{together} is {printable} (product {total_layout}), "
                f"but this run requests {num_procs} MPI processes. "
                "Give values whose product equals the requested MPI process count, or "
                "remove all three settings to let PICurv choose the layout."
            )
    if not block_dims:
        return problems
    multigrid = (((solver_cfg or {}).get("poisson_solver") or {}).get("multigrid") or {})
    levels = int(multigrid.get("levels", 3))
    semi = multigrid.get("semi_coarsening") or {}
    stencil = 3 if any_periodic else 2
    for block, dims in enumerate(block_dims):
        for axis, key, nodes in zip("ijk", GRID_DA_PROCESSOR_KEYS, dims):
            ranks = layout.get(key)
            if ranks is None:
                continue
            coarse = nodes
            if str(semi.get(axis, False)).strip().lower() not in ("true", "1", "yes"):
                for _ in range(levels - 1):
                    coarse = (coarse + 1) // 2
            points = coarse + 1
            if points // ranks < stencil:
                problems.append(
                    f"{names[key]} = {ranks} is too many ranks for block {block}'s "
                    f"{axis} axis at {levels} multigrid levels: the coarsest level has "
                    f"{points} points there, so a rank gets {points // ranks}, below the "
                    f"stencil width {stencil}"
                    + (" (3 on every axis because a face is PERIODIC)" if any_periodic else "")
                    + f". Grid setup would abort with 'Local width ... is smaller than "
                    f"stencil width'. Use at most {max(points // stencil, 1)} rank(s) on "
                    "this axis, or lower poisson_solver.multigrid.levels."
                )
    return problems
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

normalize_decomposition_args()

None picurv_cli.core.normalize_decomposition_args

(

args

)

Resolve -n and the optional --ni/--nj/--nk of picurv run into one rank count.

The three counts go together. Given them, -n defaults to their product and must equal it when also given; without them, -n defaults to 1. Sets args.num_procs and args.decomposition (a tuple or None).

Parameters

[in,out]

args

Parsed picurv run arguments.

Definition at line 13807 of file core.py.

def normalize_decomposition_args(args) -> None:
    """!
    @brief Resolve `-n` and the optional `--ni/--nj/--nk` of `picurv run` into one rank count.
    @details The three counts go together. Given them, `-n` defaults to their product and
             must equal it when also given; without them, `-n` defaults to 1. Sets
             `args.num_procs` and `args.decomposition` (a tuple or None).
    @param[in,out] args Parsed `picurv run` arguments.
    """
    parts = [getattr(args, key, None) for key in ("ni", "nj", "nk")]
    args.decomposition = None
    if any(part is not None for part in parts):
        if any(part is None or part <= 0 for part in parts):
            fail_cli_usage("--ni, --nj and --nk are given together, as positive integers.")
        product = parts[0] * parts[1] * parts[2]
        if args.num_procs is None:
            args.num_procs = product
        elif args.num_procs != product:
            fail_cli_usage(f"--ni x --nj x --nk is {parts[0]} x {parts[1]} x {parts[2]} = {product} ranks, "
                           f"but -n is {args.num_procs}; give one or make them agree.")
        args.decomposition = tuple(parts)
    if args.num_procs is None:
        args.num_procs = 1
    if args.num_procs < 1:
        fail_cli_usage("-n must be a positive integer.")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_decomposition_layout()

dict picurv_cli.core._decomposition_layout (   layout )

protected

Express an (ni, nj, nk) tuple as the da_processors mapping the layout checks read.

Parameters

[in]

layout

Rank counts along i, j, k.

Returns

{"da_processors_x": ni, "da_processors_y": nj, "da_processors_z": nk}.

Definition at line 13833 of file core.py.

def _decomposition_layout(layout) -> dict:
    """!
    @brief Express an (ni, nj, nk) tuple as the da_processors mapping the layout checks read.
    @param[in] layout Rank counts along i, j, k.
    @return {"da_processors_x": ni, "da_processors_y": nj, "da_processors_z": nk}.
    """
    return dict(zip(GRID_DA_PROCESSOR_KEYS, layout))
 
 

Here is the caller graph for this function:

choose_decomposition()

picurv_cli.core.choose_decomposition	(	int	num_procs,
		list	block_dims,
		"dict | None"	solver_cfg,
		bool	any_periodic
	)

Choose the MPI decomposition of a structured grid for a rank count.

Every ordered (ni, nj, nk) with product num_procs that grid setup accepts at the multigrid levels in use (da_processor_layout_problems) is a candidate. The one cutting the least grid area between ranks wins, so a thin axis, such as the i axis of a 2D case, is not split while another can be; ties go to the most even split, then to more ranks on k, then on j.

Parameters

[in]	num_procs	MPI ranks.
[in]	block_dims	Per-block node counts.
[in]	solver_cfg	Parsed solver.yml, for the multigrid levels and semi-coarsening.
[in]	any_periodic	Whether any face is PERIODIC, which sets the stencil width.

Returns

(ni, nj, nk), or None when no decomposition is feasible.

Definition at line 13842 of file core.py.

                         any_periodic: bool):
    """!
    @brief Choose the MPI decomposition of a structured grid for a rank count.
    @details Every ordered (ni, nj, nk) with product `num_procs` that grid setup accepts at
             the multigrid levels in use (da_processor_layout_problems) is a candidate. The
             one cutting the least grid area between ranks wins, so a thin axis, such as the
             i axis of a 2D case, is not split while another can be; ties go to the most even
             split, then to more ranks on k, then on j.
    @param[in] num_procs MPI ranks.
    @param[in] block_dims Per-block node counts.
    @param[in] solver_cfg Parsed solver.yml, for the multigrid levels and semi-coarsening.
    @param[in] any_periodic Whether any face is PERIODIC, which sets the stencil width.
    @return (ni, nj, nk), or None when no decomposition is feasible.
    """
    best = None
    for ni in range(1, num_procs + 1):
        if num_procs % ni:
            continue
        for nj in range(1, num_procs // ni + 1):
            if (num_procs // ni) % nj:
                continue
            layout = (ni, nj, num_procs // ni // nj)
            if da_processor_layout_problems(_decomposition_layout(layout), num_procs, block_dims,
                                            solver_cfg, any_periodic):
                continue
            cut = imbalance = 0.0
            for dims in block_dims:
                cells = [max(d - 1, 1) for d in dims]
                cut += sum((layout[a] - 1) * cells[(a + 1) % 3] * cells[(a + 2) % 3] for a in range(3))
                largest = 1.0
                for a in range(3):
                    largest *= -(-cells[a] // layout[a])
                imbalance = max(imbalance, largest * num_procs / (cells[0] * cells[1] * cells[2]))
            key = (cut, imbalance, -layout[2], -layout[1])
            if best is None or key < best[0]:
                best = (key, layout)
    return best[1] if best else None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_decomposition()

dict picurv_cli.core.resolve_decomposition	(	int	num_procs,
		dict	grid_cfg,
		"list | None"	block_dims,
		"dict | None"	solver_cfg,
		bool	any_periodic,
			explicit = None,
		"dict | None"	cluster_cfg = None
	)

Resolve the MPI decomposition a stage launches with.

In order of precedence: --ni/--nj/--nk, cluster.yml execution.decomposition, the deprecated case.yml grid.da_processors_*, and otherwise choose_decomposition(). A set layout must multiply to the rank count and pass the multigrid check. When the grid's size cannot be known before the run, PETSc chooses.

Parameters

[in]	num_procs	MPI ranks of the stage.
[in]	grid_cfg	The case's grid block.
[in]	block_dims	Per-block node counts, or None when unknown.
[in]	solver_cfg	Parsed solver.yml.
[in]	any_periodic	Whether any face is PERIODIC.
[in]	explicit	(ni, nj, nk) from the command line, or None.
[in]	cluster_cfg	Parsed cluster.yml, or None.

Returns

{"layout": (ni, nj, nk) or None, "source": str, "problems": [str]}.

Definition at line 13882 of file core.py.

                          explicit=None, cluster_cfg: "dict | None" = None) -> dict:
    """!
    @brief Resolve the MPI decomposition a stage launches with.
    @details In order of precedence: `--ni/--nj/--nk`, cluster.yml
             `execution.decomposition`, the deprecated case.yml `grid.da_processors_*`, and
             otherwise choose_decomposition(). A set layout must multiply to the rank count
             and pass the multigrid check. When the grid's size cannot be known before the
             run, PETSc chooses.
    @param[in] num_procs MPI ranks of the stage.
    @param[in] grid_cfg The case's grid block.
    @param[in] block_dims Per-block node counts, or None when unknown.
    @param[in] solver_cfg Parsed solver.yml.
    @param[in] any_periodic Whether any face is PERIODIC.
    @param[in] explicit (ni, nj, nk) from the command line, or None.
    @param[in] cluster_cfg Parsed cluster.yml, or None.
    @return {"layout": (ni, nj, nk) or None, "source": str, "problems": [str]}.
    """
    if num_procs <= 1:
        return {"layout": (1, 1, 1), "source": "serial", "problems": []}
    layout, source = None, None
    if explicit:
        layout, source = tuple(explicit), "--ni/--nj/--nk"
    elif isinstance(((cluster_cfg or {}).get("execution") or {}).get("decomposition"), dict):
        spec = cluster_cfg["execution"]["decomposition"]
        if not all(isinstance(spec.get(axis), int) and spec.get(axis) > 0 for axis in "ijk"):
            return {"layout": None, "source": "cluster.yml",
                    "problems": ["cluster.yml execution.decomposition needs positive integers i, j and k."]}
        layout, source = (spec["i"], spec["j"], spec["k"]), "cluster.yml execution.decomposition"
    else:
        legacy = resolve_grid_da_processor_layout(grid_cfg or {})
        if legacy:
            print("[WARNING] case.yml grid.da_processors_x/y/z is deprecated; give the decomposition "
                  "with --ni/--nj/--nk or cluster.yml execution.decomposition.", file=sys.stderr)
            if len(legacy) == 3:
                layout, source = tuple(legacy[key] for key in GRID_DA_PROCESSOR_KEYS), "case.yml (deprecated)"
            else:
                problems = da_processor_layout_problems(grid_cfg, num_procs, block_dims, solver_cfg, any_periodic)
                return {"layout": None, "partial": legacy, "source": "case.yml (deprecated, partial)",
                        "problems": problems}
    if layout is not None:
        return {"layout": layout, "source": source,
                "problems": da_processor_layout_problems(
                    _decomposition_layout(layout), num_procs, block_dims, solver_cfg, any_periodic,
                    None if source.startswith("case.yml") else source)}
    if not block_dims:
        return {"layout": None, "source": "PETSc (grid size unknown before the run)", "problems": []}
    layout = choose_decomposition(num_procs, block_dims, solver_cfg, any_periodic)
    if layout is None:
        feasible = [n for n in range(max(num_procs - 16, 2), num_procs + 17)
                    if choose_decomposition(n, block_dims, solver_cfg, any_periodic)]
        nearest = sorted(feasible, key=lambda n: (abs(n - num_procs), n))[:3]
        return {"layout": None, "source": "auto", "problems": [
            f"No decomposition of {num_procs} ranks fits this grid at its multigrid levels "
            f"(each rank needs at least the stencil width of points on the coarsest level). "
            + (f"Rank counts that fit nearby: {', '.join(map(str, sorted(nearest)))}." if nearest
               else "Lower poisson_solver.multigrid.levels or refine the grid.")]}
    return {"layout": layout, "source": "auto", "problems": []}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_decomposition_record()

"dict | None" picurv_cli.core._decomposition_record ( "dict | None"  resolved )

protected

The JSON-serializable record of a resolved decomposition for run metadata.

Parameters

[in]

resolved

Result of resolve_decomposition(), or None.

Returns

{"layout": [ni, nj, nk] or None, "source": str}, or None.

Definition at line 13943 of file core.py.

def _decomposition_record(resolved: "dict | None") -> "dict | None":
    """!
    @brief The JSON-serializable record of a resolved decomposition for run metadata.
    @param[in] resolved Result of resolve_decomposition(), or None.
    @return {"layout": [ni, nj, nk] or None, "source": str}, or None.
    """
    if not resolved:
        return None
    return {"layout": list(resolved["layout"]) if resolved.get("layout") else None,
            "source": resolved["source"]}
 
 

Here is the caller graph for this function:

describe_decomposition()

str picurv_cli.core.describe_decomposition	(	dict	resolved,
		int	num_procs
	)

One line stating the decomposition a stage launches with.

Parameters

[in]	resolved	Result of resolve_decomposition().
[in]	num_procs	MPI ranks of the stage.

Returns

Human-readable description.

Definition at line 13955 of file core.py.

def describe_decomposition(resolved: dict, num_procs: int) -> str:
    """!
    @brief One line stating the decomposition a stage launches with.
    @param[in] resolved Result of resolve_decomposition().
    @param[in] num_procs MPI ranks of the stage.
    @return Human-readable description.
    """
    if resolved.get("problems"):
        return f"MPI decomposition: none usable for {num_procs} rank(s) ({resolved['source']})."
    if resolved.get("layout") is None:
        return f"MPI decomposition: chosen by PETSc for {num_procs} rank(s) ({resolved['source']})."
    ni, nj, nk = resolved["layout"]
    return f"MPI decomposition: {ni} x {nj} x {nk} (i x j x k) for {num_procs} rank(s), from {resolved['source']}."
 
 

Here is the caller graph for this function:

append_grid_da_processor_layout()

dict picurv_cli.core.append_grid_da_processor_layout	(	list	control_lines,
		dict	grid_cfg,
		int	num_procs,
		"list | None"	block_dims = None,
		"dict | None"	solver_cfg = None,
		bool	any_periodic = False,
			explicit = None,
		"dict | None"	cluster_cfg = None
	)

Resolve the solver's MPI decomposition, report it, and append its flags.

Parameters

[in]	control_lines	Control-file lines to extend.
[in]	grid_cfg	The case's grid block.
[in]	num_procs	MPI ranks of the solve.
[in]	block_dims	Per-block node counts, for the multigrid check and the choice.
[in]	solver_cfg	Parsed solver.yml, for the multigrid levels.
[in]	any_periodic	Whether any face is PERIODIC.
[in]	explicit	(ni, nj, nk) from the command line, or None.
[in]	cluster_cfg	Parsed cluster.yml, or None.

Returns

The resolved decomposition (resolve_decomposition()).

Exceptions

ValueError

when the decomposition would abort grid setup or none fits.

Definition at line 13970 of file core.py.

                                    explicit=None, cluster_cfg: "dict | None" = None) -> dict:
    """!
    @brief Resolve the solver's MPI decomposition, report it, and append its flags.
    @param[in] control_lines Control-file lines to extend.
    @param[in] grid_cfg The case's grid block.
    @param[in] num_procs MPI ranks of the solve.
    @param[in] block_dims Per-block node counts, for the multigrid check and the choice.
    @param[in] solver_cfg Parsed solver.yml, for the multigrid levels.
    @param[in] any_periodic Whether any face is PERIODIC.
    @param[in] explicit (ni, nj, nk) from the command line, or None.
    @param[in] cluster_cfg Parsed cluster.yml, or None.
    @return The resolved decomposition (resolve_decomposition()).
    @throws ValueError when the decomposition would abort grid setup or none fits.
    """
    resolved = resolve_decomposition(num_procs, grid_cfg, block_dims, solver_cfg, any_periodic,
                                     explicit, cluster_cfg)
    if resolved["problems"]:
        raise ValueError(" ".join(resolved["problems"]))
    print(f"[INFO] {describe_decomposition(resolved, num_procs)}")
    layout = resolved.get("layout")
    if num_procs > 1 and layout is not None:
        control_lines.extend(f"-{key} {value}" for key, value in zip(GRID_DA_PROCESSOR_KEYS, layout))
    elif num_procs > 1 and resolved.get("partial"):
        control_lines.extend(f"-{key} {value}" for key, value in resolved["partial"].items())
    return resolved
 

Here is the call graph for this function:

Here is the caller graph for this function:

normalize_momentum_solver_type()

str picurv_cli.core.normalize_momentum_solver_type

(

str

value

)

Maps canonical user-facing momentum solver names to C-enum CLI values.

Parameters

[in]

value

Canonical momentum solver string from YAML.

Returns

Canonical value accepted by -mom_solver_type.

Exceptions

ValueError

if the input cannot be mapped.

Definition at line 14000 of file core.py.

def normalize_momentum_solver_type(value: str) -> str:
    """!
    @brief Maps canonical user-facing momentum solver names to C-enum CLI values.
    @param[in] value Canonical momentum solver string from YAML.
    @return Canonical value accepted by -mom_solver_type.
    @throws ValueError if the input cannot be mapped.
    """
    # Only implemented YAML values belong here. Extend only with matching C enum/parser/dispatch support.
    if value is None:
        raise ValueError("momentum solver type cannot be None")
 
    raw = str(value).strip()
    mapped = {
        "Explicit RK4": "EXPLICIT_RK",
        "Dual Time Picard Jameson RK": "DUALTIME_PICARD_JAMESON_RK",
        "Dual Time Picard RK4": "DUALTIME_PICARD_JAMESON_RK",
        "Newton Krylov": "newton_krylov",
    }.get(raw)
    if mapped is None:
        raise ValueError(
            f"Unknown momentum solver '{value}'. Use one of: "
            "'Explicit RK4', 'Dual Time Picard Jameson RK', 'Newton Krylov'."
        )
    return mapped
 
 

Here is the caller graph for this function:

validate_newton_krylov_config()

dict picurv_cli.core.validate_newton_krylov_config

(

dict

cfg

)

Validate and normalize the structured Newton–Krylov solver block.

Parameters

[in]

cfg

Structured momentum_solver.newton_krylov mapping.

Returns

Normalized copy containing only supported structured fields.

Definition at line 14026 of file core.py.

def validate_newton_krylov_config(cfg: dict) -> dict:
    """!
    @brief Validate and normalize the structured Newton--Krylov solver block.
    @param[in] cfg Structured `momentum_solver.newton_krylov` mapping.
    @return Normalized copy containing only supported structured fields.
    """
    root = "momentum_solver.newton_krylov"
    if not isinstance(cfg, dict):
        raise ValueError(f"{root} must be a mapping.")
 
    unknown = sorted(set(cfg) - {
        "jacobian", "preconditioner", "nonlinear_solver", "linear_solver",
    })
    if unknown:
        raise ValueError(f"{root} has unsupported key(s): {unknown}.")
 
    normalized = {}
 
    def _mapping(parent: dict, key: str, path: str) -> dict:
        """!
        @brief Read and validate one optional nested Newton mapping.
        @param[in] parent Parent mapping.
        @param[in] key Nested key to read.
        @param[in] path User-facing YAML path for errors.
        @return Nested mapping, or an empty mapping when omitted.
        """
        value = parent.get(key, {})
        if value is None or not isinstance(value, dict):
            raise ValueError(f"{path} must be a mapping when provided.")
        return value
 
    def _method(value, path: str) -> str:
        """!
        @brief Normalize one nonempty PETSc solver/type token.
        @param[in] value YAML token value.
        @param[in] path User-facing YAML path for errors.
        @return Lowercase PETSc token.
        """
        if not isinstance(value, str) or not value.strip():
            raise ValueError(f"{path} must be a non-empty string.")
        return value.strip().lower()
 
    def _tolerance(value, path: str):
        """!
        @brief Validate one finite nonnegative tolerance.
        @param[in] value YAML tolerance value.
        @param[in] path User-facing YAML path for errors.
        @return Original validated value.
        """
        if isinstance(value, bool):
            raise ValueError(f"{path} must be numeric and nonnegative.")
        try:
            numeric = float(value)
        except (TypeError, ValueError) as exc:
            raise ValueError(f"{path} must be numeric and nonnegative.") from exc
        if not math.isfinite(numeric) or numeric < 0.0:
            raise ValueError(f"{path} must be numeric and nonnegative.")
        return value
 
    def _positive_integer(value, path: str):
        """!
        @brief Validate one positive integer count.
        @param[in] value YAML count value.
        @param[in] path User-facing YAML path for errors.
        @return Original validated integer.
        """
        if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
            raise ValueError(f"{path} must be a positive integer.")
        return value
 
    jacobian_path = f"{root}.jacobian"
    if "jacobian" not in cfg:
        normalized["jacobian"] = {
            "type": "finite_difference",
            "finite_difference": {"mode": "matrix_free"},
        }
    else:
        jacobian = _mapping(cfg, "jacobian", jacobian_path)
        unknown = sorted(set(jacobian) - {"type", "finite_difference"})
        if unknown:
            raise ValueError(f"{jacobian_path} has unsupported key(s): {unknown}.")
        if "type" not in jacobian:
            raise ValueError(f"{jacobian_path}.type is required when {jacobian_path} is provided.")
        jacobian_type = _method(jacobian["type"], f"{jacobian_path}.type")
        if jacobian_type == "frozen_momentum_approximation":
            raise ValueError(
                f"{jacobian_path}.type 'frozen_momentum_approximation' is not implemented."
            )
        if jacobian_type != "finite_difference":
            raise ValueError(
                f"{jacobian_path}.type currently supports only 'finite_difference' "
                f"(got '{jacobian_type}')."
            )
        finite_difference_path = f"{jacobian_path}.finite_difference"
        if "finite_difference" not in jacobian:
            raise ValueError(
                f"{finite_difference_path} is required when {jacobian_path}.type is "
                "'finite_difference'."
            )
        finite_difference = _mapping(
            jacobian, "finite_difference", finite_difference_path
        )
        unknown = sorted(set(finite_difference) - {"mode"})
        if unknown:
            raise ValueError(f"{finite_difference_path} has unsupported key(s): {unknown}.")
        if "mode" not in finite_difference:
            raise ValueError(f"{finite_difference_path}.mode is required.")
        finite_difference_mode = _method(
            finite_difference["mode"], f"{finite_difference_path}.mode"
        )
        if finite_difference_mode == "colored_sparse":
            raise ValueError(
                f"{finite_difference_path}.mode 'colored_sparse' is not implemented."
            )
        if finite_difference_mode != "matrix_free":
            raise ValueError(
                f"{finite_difference_path}.mode currently supports only 'matrix_free' "
                f"(got '{finite_difference_mode}')."
            )
        normalized["jacobian"] = {
            "type": jacobian_type,
            "finite_difference": {"mode": finite_difference_mode},
        }
 
    preconditioner = _mapping(
        cfg, "preconditioner", f"{root}.preconditioner"
    ) if "preconditioner" in cfg else {}
    preconditioner_path = f"{root}.preconditioner"
    unknown = sorted(set(preconditioner) - {"model", "structure"})
    if unknown:
        raise ValueError(f"{preconditioner_path} has unsupported key(s): {unknown}.")
    if "preconditioner" in cfg and "model" not in preconditioner:
        raise ValueError(
            f"{preconditioner_path}.model is required when {preconditioner_path} is provided."
        )
    model = _method(preconditioner.get("model", "none"), f"{preconditioner_path}.model")
    if model not in NEWTON_KRYLOV_PRECONDITIONER_MODELS:
        raise ValueError(
            f"{preconditioner_path}.model supports only 'none' or 'frozen_momentum_jacobian'."
        )
    structure = _mapping(
        preconditioner, "structure", f"{preconditioner_path}.structure"
    ) if "structure" in preconditioner else {}
    unknown = sorted(set(structure) - {"type"})
    if unknown:
        raise ValueError(f"{preconditioner_path}.structure has unsupported key(s): {unknown}.")
    structure_type = _method(
        structure.get("type", "none"), f"{preconditioner_path}.structure.type"
    )
    if structure_type not in NEWTON_KRYLOV_PRECONDITIONER_STRUCTURES:
        raise ValueError(
            f"{preconditioner_path}.structure.type supports only 'none' or 'point_block'."
        )
    if model == "none" and structure:
        raise ValueError(f"{preconditioner_path}.model 'none' does not accept a matrix structure.")
    if model == "frozen_momentum_jacobian" and structure_type != "point_block":
        raise ValueError(
            f"{preconditioner_path}.model 'frozen_momentum_jacobian' requires "
            f"{preconditioner_path}.structure.type 'point_block'."
        )
    normalized["preconditioner"] = {
        "model": model,
        "structure": {"type": structure_type},
    }
 
    nonlinear = _mapping(cfg, "nonlinear_solver", f"{root}.nonlinear_solver")
    nonlinear_path = f"{root}.nonlinear_solver"
    unknown = sorted(set(nonlinear) - {
        "method", "absolute_tolerance", "relative_tolerance", "step_tolerance",
        "max_iterations", "line_search", "eisenstat_walker",
    })
    if unknown:
        raise ValueError(f"{nonlinear_path} has unsupported key(s): {unknown}.")
    nonlinear_out = {}
    if "method" in nonlinear:
        nonlinear_out["method"] = _method(nonlinear["method"], f"{nonlinear_path}.method")
    for key in ("absolute_tolerance", "relative_tolerance", "step_tolerance"):
        if key in nonlinear:
            nonlinear_out[key] = _tolerance(nonlinear[key], f"{nonlinear_path}.{key}")
    if "max_iterations" in nonlinear:
        nonlinear_out["max_iterations"] = _positive_integer(
            nonlinear["max_iterations"], f"{nonlinear_path}.max_iterations"
        )
    if "line_search" in nonlinear:
        line_search = _mapping(nonlinear, "line_search", f"{nonlinear_path}.line_search")
        unknown = sorted(set(line_search) - {"type"})
        if unknown:
            raise ValueError(f"{nonlinear_path}.line_search has unsupported key(s): {unknown}.")
        nonlinear_out["line_search"] = {}
        if "type" in line_search:
            nonlinear_out["line_search"]["type"] = _method(
                line_search["type"], f"{nonlinear_path}.line_search.type"
            )
    if "eisenstat_walker" in nonlinear:
        ew_path = f"{nonlinear_path}.eisenstat_walker"
        ew = _mapping(nonlinear, "eisenstat_walker", ew_path)
        ew_keys = {
            "enabled", "version", "initial_relative_tolerance",
            "maximum_relative_tolerance", "gamma", "exponent",
            "safeguard_exponent", "safeguard_threshold",
        }
        unknown = sorted(set(ew) - ew_keys)
        if unknown:
            raise ValueError(f"{ew_path} has unsupported key(s): {unknown}.")
        enabled = ew.get("enabled", True)
        if not isinstance(enabled, bool):
            raise ValueError(f"{ew_path}.enabled must be boolean.")
        if not enabled and set(ew) - {"enabled"}:
            raise ValueError(f"{ew_path} parameters require enabled: true.")
        ew_out = {"enabled": enabled}
        if "version" in ew:
            version = ew["version"]
            if isinstance(version, bool) or not isinstance(version, int) or version not in {1, 2, 3, 4}:
                raise ValueError(f"{ew_path}.version must be one of 1, 2, 3, or 4.")
            ew_out["version"] = version
        bounds = {
            "initial_relative_tolerance": (0.0, 1.0, False, True),
            "maximum_relative_tolerance": (0.0, 1.0, False, True),
            "gamma": (0.0, 1.0, False, False),
            "exponent": (1.0, 2.0, True, False),
            "safeguard_threshold": (0.0, 1.0, True, True),
        }
        for key, (lower, upper, lower_open, upper_open) in bounds.items():
            if key not in ew:
                continue
            value = _tolerance(ew[key], f"{ew_path}.{key}")
            numeric = float(value)
            valid_lower = numeric > lower if lower_open else numeric >= lower
            valid_upper = numeric < upper if upper_open else numeric <= upper
            if not (valid_lower and valid_upper):
                brackets = ("(" if lower_open else "[") + f"{lower}, {upper}" + (")" if upper_open else "]")
                raise ValueError(f"{ew_path}.{key} must be in {brackets}.")
            ew_out[key] = value
        if "safeguard_exponent" in ew:
            ew_out["safeguard_exponent"] = _tolerance(
                ew["safeguard_exponent"], f"{ew_path}.safeguard_exponent"
            )
        nonlinear_out["eisenstat_walker"] = ew_out
    normalized["nonlinear_solver"] = nonlinear_out
 
    linear = _mapping(cfg, "linear_solver", f"{root}.linear_solver")
    linear_path = f"{root}.linear_solver"
    unknown = sorted(set(linear) - {
        "method", "absolute_tolerance", "relative_tolerance", "max_iterations",
        "gmres", "preconditioner",
    })
    if unknown:
        raise ValueError(f"{linear_path} has unsupported key(s): {unknown}.")
    linear_out = {}
    method = "gmres"
    if "method" in linear:
        method = _method(linear["method"], f"{linear_path}.method")
        linear_out["method"] = method
    for key in ("absolute_tolerance", "relative_tolerance"):
        if key in linear:
            linear_out[key] = _tolerance(linear[key], f"{linear_path}.{key}")
    if "max_iterations" in linear:
        linear_out["max_iterations"] = _positive_integer(
            linear["max_iterations"], f"{linear_path}.max_iterations"
        )
    if "gmres" in linear:
        gmres = _mapping(linear, "gmres", f"{linear_path}.gmres")
        unknown = sorted(set(gmres) - {"restart"})
        if unknown:
            raise ValueError(f"{linear_path}.gmres has unsupported key(s): {unknown}.")
        linear_out["gmres"] = {}
        if "restart" in gmres:
            if method not in GMRES_RESTART_METHODS:
                raise ValueError(
                    f"{linear_path}.gmres.restart is valid only when {linear_path}.method "
                    "is one of 'gmres', 'fgmres', or 'lgmres'."
                )
            linear_out["gmres"]["restart"] = _positive_integer(
                gmres["restart"], f"{linear_path}.gmres.restart"
            )
    if "preconditioner" in linear:
        compatibility_pc = _mapping(linear, "preconditioner", f"{linear_path}.preconditioner")
        unknown = sorted(set(compatibility_pc) - {"type"})
        if unknown:
            raise ValueError(f"{linear_path}.preconditioner has unsupported key(s): {unknown}.")
        if "type" in compatibility_pc:
            pc_type = _method(compatibility_pc["type"], f"{linear_path}.preconditioner.type")
            if pc_type != "none":
                raise ValueError(
                    f"{linear_path}.preconditioner.type is a deprecated compatibility alias "
                    "and supports only 'none'."
                )
            if "preconditioner" in cfg and model != "none":
                raise ValueError(
                    f"{linear_path}.preconditioner.type 'none' conflicts with "
                    f"{preconditioner_path}.model '{model}'."
                )
            warnings.warn(
                f"{linear_path}.preconditioner.type is deprecated; use "
                f"{preconditioner_path}.model: none.",
                FutureWarning,
                stacklevel=3,
            )
    normalized["linear_solver"] = linear_out
    return normalized
 

Here is the caller graph for this function:

normalize_solution_convergence_mode()

str picurv_cli.core.normalize_solution_convergence_mode

(

str

value

)

Normalizes the solution-convergence mode selector to the C-side canonical string.

Parameters

[in]

value

Human-readable solution-convergence mode selector.

Returns

Canonical string accepted by -solution_convergence_mode.

Exceptions

ValueError

if the input cannot be mapped.

Definition at line 14327 of file core.py.

def normalize_solution_convergence_mode(value: str) -> str:
    """!
    @brief Normalizes the solution-convergence mode selector to the C-side canonical string.
    @param[in] value Human-readable solution-convergence mode selector.
    @return Canonical string accepted by `-solution_convergence_mode`.
    @throws ValueError if the input cannot be mapped.
    """
    if value is None:
        raise ValueError("solution_convergence.mode cannot be None")
 
    normalized = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    aliases = {
        "steady_deterministic": "STEADY_DETERMINISTIC",
        "periodic_deterministic": "PERIODIC_DETERMINISTIC",
        "statistical_steady": "STATISTICAL_STEADY",
        "transient": "TRANSIENT",
    }
    mapped = aliases.get(normalized)
    if mapped is None:
        raise ValueError(
            f"Unknown solution_convergence.mode '{value}'. Use one of: "
            "'steady_deterministic', 'periodic_deterministic', 'statistical_steady', 'transient'."
        )
    return mapped
 

Here is the caller graph for this function:

normalize_field_init_mode()

int picurv_cli.core.normalize_field_init_mode

(

str

value

)

Maps canonical field init mode names to C enum/int codes (-finit).

Parameters

[in]

value

Canonical field initialization mode.

Returns

Canonical integer code accepted by -finit.

Exceptions

ValueError

if the input cannot be mapped.

Definition at line 14352 of file core.py.

def normalize_field_init_mode(value: str) -> int:
    """!
    @brief Maps canonical field init mode names to C enum/int codes (-finit).
    @param[in] value Canonical field initialization mode.
    @return Canonical integer code accepted by -finit.
    @throws ValueError if the input cannot be mapped.
    """
    # Canonical selector map for field initialization modes.
    if value is None:
        raise ValueError("field initialization mode cannot be None")
 
    mapped = {
        "Zero": 0,
        "Constant": 1,
        "Poiseuille": 2,
    }.get(str(value).strip())
    if mapped is None:
        raise ValueError(
            f"Unknown initial_conditions mode '{value}'. Use one of: 'Zero', 'Constant', 'Poiseuille'."
        )
    return mapped
 

Here is the caller graph for this function:

normalize_initial_condition_field()

"tuple[str, int]" picurv_cli.core.normalize_initial_condition_field

(

str

value

)

Normalize a file IC field selector to its staged basename and C enum value.

Parameters

[in]

value

User-facing Ucat or Ucont selector.

Returns

Tuple of staged field basename and C enum value.

Definition at line 14374 of file core.py.

def normalize_initial_condition_field(value: str) -> "tuple[str, int]":
    """!
    @brief Normalize a file IC field selector to its staged basename and C enum value.
    @param[in] value User-facing Ucat or Ucont selector.
    @return Tuple of staged field basename and C enum value.
    """
    normalized = str(value or "").strip().lower()
    if normalized == "ucat":
        return "ufield", 0
    if normalized == "ucont":
        return "vfield", 1
    raise ValueError("initial_conditions.field must be 'Ucat' or 'Ucont'.")
 
 
#: Physical dimension of a staged initial-condition payload, by C field code.

Here is the caller graph for this function:

resolve_ic_payload_provenance()

dict picurv_cli.core.resolve_ic_payload_provenance	(	dict	ic,
		int	field_code
	)

Resolve which scales a file-backed initial condition was written in.

A payload is physical unless it declares otherwise. A field saved by an earlier run is in that run's solver units, so it names the case that wrote it (source_case) or gives its scales directly, the same way a field_slice inlet profile does.

Parameters

[in]	ic	Initial-condition YAML mapping.
[in]	field_code	C field code: 0 for Ucat, 1 for Ucont.

Returns

Mapping with source_case, or velocity_scale and length_scale, or empty.

Exceptions

ValueError

on a conflicting, incomplete, or invalid declaration.

Definition at line 14392 of file core.py.

def resolve_ic_payload_provenance(ic: dict, field_code: int) -> dict:
    """!
    @brief Resolve which scales a file-backed initial condition was written in.
    @details A payload is physical unless it declares otherwise. A field saved by an
             earlier run is in that run's solver units, so it names the case that wrote
             it (`source_case`) or gives its scales directly, the same way a
             `field_slice` inlet profile does.
    @param[in] ic Initial-condition YAML mapping.
    @param[in] field_code C field code: 0 for Ucat, 1 for Ucont.
    @return Mapping with `source_case`, or `velocity_scale` and `length_scale`, or empty.
    @throws ValueError on a conflicting, incomplete, or invalid declaration.
    """
    source_case = ic.get("source_case")
    has_scale = any(key in ic for key in ("velocity_scale", "length_scale"))
    if source_case is not None:
        if has_scale:
            raise ValueError("initial_conditions: give source_case or velocity_scale/length_scale, not both.")
        if not isinstance(source_case, str) or not source_case.strip():
            raise ValueError("initial_conditions.source_case must be a non-empty path.")
        return {"source_case": source_case.strip()}
    if not has_scale:
        return {}
    if "velocity_scale" not in ic:
        raise ValueError("initial_conditions.length_scale requires velocity_scale.")
    provenance = {"velocity_scale": _to_finite_float(ic["velocity_scale"], "initial_conditions.velocity_scale"),
                  "length_scale": 1.0}
    if field_code == 1:
        if "length_scale" not in ic:
            raise ValueError("initial_conditions.length_scale is required for a Ucont payload in solver units.")
        provenance["length_scale"] = _to_finite_float(ic["length_scale"], "initial_conditions.length_scale")
    elif "length_scale" in ic:
        raise ValueError("initial_conditions.length_scale applies only to a Ucont payload.")
    if provenance["velocity_scale"] <= 0.0 or provenance["length_scale"] <= 0.0:
        raise ValueError("initial_conditions.velocity_scale and length_scale must be positive.")
    return provenance
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

ic_payload_divisor()

float picurv_cli.core.ic_payload_divisor	(	dict	resolved_ic,
		str	case_dir
	)

Return the factor a file-backed initial condition is divided by when staged.

A physical payload is divided by its dimension's reference scale. A payload in another run's solver units is first returned to physical units by that run's scale, so the two factors combine into one ratio.

Parameters

[in]	resolved_ic	Resolved mode: file initial condition.
[in]	case_dir	Directory that relative source_case paths resolve against.

Returns

Positive divisor; 1.0 when the payload already matches this case's solver units.

Definition at line 14429 of file core.py.

def ic_payload_divisor(resolved_ic: dict, case_dir: str) -> float:
    """!
    @brief Return the factor a file-backed initial condition is divided by when staged.
    @details A physical payload is divided by its dimension's reference scale. A payload in
             another run's solver units is first returned to physical units by that run's
             scale, so the two factors combine into one ratio.
    @param[in] resolved_ic Resolved `mode: file` initial condition.
    @param[in] case_dir Directory that relative `source_case` paths resolve against.
    @return Positive divisor; 1.0 when the payload already matches this case's solver units.
    """
    dimension = IC_PAYLOAD_DIMENSIONS[resolved_ic["field_code"]]
    provenance = resolved_ic.get("payload_provenance") or {}
    source_scales = {"length_ref": 1.0, "velocity_ref": 1.0}
    if "source_case" in provenance:
        source_path = _resolve_case_relative_path(provenance["source_case"], case_dir)
        source_scales = resolve_reference_scales(read_yaml_file(source_path))
    elif provenance:
        source_scales = {"length_ref": provenance["length_scale"], "velocity_ref": provenance["velocity_scale"]}
    return reference_scale(dimension, resolved_ic["scales"]) / reference_scale(dimension, source_scales)
 

Here is the call graph for this function:

Here is the caller graph for this function:

is_generated_ic_provider()

bool picurv_cli.core.is_generated_ic_provider

(

dict

resolved_ic

)

Return whether a resolved IC is backed by a registered file generator.

Parameters

[in]

resolved_ic

Resolved initial-condition contract.

Returns

True for a registered generated-file provider.

Definition at line 14470 of file core.py.

def is_generated_ic_provider(resolved_ic: dict) -> bool:
    """!
    @brief Return whether a resolved IC is backed by a registered file generator.
    @param[in] resolved_ic Resolved initial-condition contract.
    @return True for a registered generated-file provider.
    """
    return resolved_ic.get("kind") in GENERATED_IC_PROVIDERS
 
 

Here is the caller graph for this function:

resolve_fluid_scaling()

dict picurv_cli.core.resolve_fluid_scaling

(

dict

case_cfg

)

Resolve the shared physical and nondimensional fluid scaling contract.

Parameters

[in]

case_cfg

Parsed case configuration.

Returns

Resolved scaling, viscosity, and Reynolds-number quantities.

Definition at line 14479 of file core.py.

def resolve_fluid_scaling(case_cfg: dict) -> dict:
    """!
    @brief Resolve the shared physical and nondimensional fluid scaling contract.
    @param[in] case_cfg Parsed case configuration.
    @return Resolved scaling, viscosity, and Reynolds-number quantities.
    """
    properties = case_cfg["properties"]
    scaling = properties["scaling"]
    fluid = properties["fluid"]
    length_ref = _to_finite_float(scaling["length_ref"], "properties.scaling.length_ref")
    velocity_ref = _to_finite_float(scaling["velocity_ref"], "properties.scaling.velocity_ref")
    density = _to_finite_float(fluid["density"], "properties.fluid.density")
    dynamic_viscosity = _to_finite_float(fluid["viscosity"], "properties.fluid.viscosity")
    if length_ref <= 0.0 or velocity_ref <= 0.0 or density <= 0.0 or dynamic_viscosity < 0.0:
        raise ValueError("length_ref, velocity_ref, and density must be positive; viscosity must be non-negative.")
    reynolds = density*velocity_ref*length_ref/dynamic_viscosity if dynamic_viscosity else float("inf")
    return {
        "length_ref": length_ref, "velocity_ref": velocity_ref, "density": density,
        "dynamic_viscosity": dynamic_viscosity, "reynolds": reynolds,
        "physical_kinematic_viscosity": dynamic_viscosity/density,
        "nondimensional_kinematic_viscosity": dynamic_viscosity/(density*velocity_ref*length_ref),
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

load_generator_module()

picurv_cli.core.load_generator_module	(	str	script_name,
		str	module_name
	)

Load one of the extensionless scripts under generators/ as a module.

Parameters

[in]	script_name	File name under generators/, e.g. ic.gen.
[in]	module_name	Name to register the loaded module under.

Returns

Loaded module.

Definition at line 14503 of file core.py.

def load_generator_module(script_name: str, module_name: str):
    """!
    @brief Load one of the extensionless scripts under `generators/` as a module.
    @param[in] script_name File name under `generators/`, e.g. `ic.gen`.
    @param[in] module_name Name to register the loaded module under.
    @return Loaded module.
    """
    from importlib.machinery import SourceFileLoader
    loader = SourceFileLoader(module_name, os.path.join(GENERATORS_PATH, script_name))
    spec = importlib.util.spec_from_loader(loader.name, loader)
    module = importlib.util.module_from_spec(spec)
    loader.exec_module(module)
    return module
 
 

Here is the caller graph for this function:

load_ic_generator_module()

picurv_cli.core.load_ic_generator_module

(

)

Load generators/ic.gen, which owns the expression language and the IC providers.

Returns

Loaded module.

Definition at line 14518 of file core.py.

def load_ic_generator_module():
    """!
    @brief Load `generators/ic.gen`, which owns the expression language and the IC providers.
    @return Loaded module.
    """
    return load_generator_module("ic.gen", "picurv_ic_generator")
 
 
#: Particle fields a case may give an initial value, with their component counts: the
#: fields the particle carries (catalog capability `USER_INITIALIZE`). Every other particle
#: field is re-derived from the Eulerian fields or from particle location, so a configured
#: value would not survive. `tests/test_particle_fields.py` checks this against the catalog.

Here is the call graph for this function:

Here is the caller graph for this function:

normalize_particle_fields()

list picurv_cli.core.normalize_particle_fields

(

fields_cfg

)

Validate models.physics.particles.fields and lower each value to expressions.

A value is a number, an expression, or a mapping with params and either value or background with regions; a field with several components takes a list of values, one per component. Expressions use physical coordinates x y z, domain-normalized xn yn zn, pid, and physical time t, and may draw with uniform()/normal().

Parameters

[in]

fields_cfg

The fields mapping.

Returns

List of {"name", "expressions"} in configuration order.

Exceptions

ValueError

on an unknown field, a wrong component count, or an invalid value.

Definition at line 14533 of file core.py.

def normalize_particle_fields(fields_cfg) -> list:
    """!
    @brief Validate `models.physics.particles.fields` and lower each value to expressions.
    @details A value is a number, an expression, or a mapping with `params` and either
             `value` or `background` with `regions`; a field with several components takes a
             list of values, one per component. Expressions use physical coordinates
             `x y z`, domain-normalized `xn yn zn`, `pid`, and physical time `t`, and may
             draw with `uniform()`/`normal()`.
    @param[in] fields_cfg The `fields` mapping.
    @return List of `{"name", "expressions"}` in configuration order.
    @throws ValueError on an unknown field, a wrong component count, or an invalid value.
    """
    if not isinstance(fields_cfg, dict) or not fields_cfg:
        raise ValueError("models.physics.particles.fields must be a non-empty mapping of field names to values.")
    ic_gen = load_ic_generator_module()
    normalized = []
    for name, spec in fields_cfg.items():
        if name not in PARTICLE_SETTABLE_FIELDS:
            raise ValueError(
                f"models.physics.particles.fields.{name}: not a field a case can set; the runtime "
                f"re-derives it. Settable fields: {sorted(PARTICLE_SETTABLE_FIELDS)}.")
        components = PARTICLE_SETTABLE_FIELDS[name]
        specs = spec if components > 1 else [spec]
        if not isinstance(specs, list) or len(specs) != components:
            raise ValueError(f"models.physics.particles.fields.{name} takes {components} component values.")
        expressions = [
            ic_gen.lower_value(item, ic_gen.PARTICLE_EXPRESSION_NAMES, random=True,
                               where=f"models.physics.particles.fields.{name}")
            for item in specs
        ]
        normalized.append({"name": name, "expressions": expressions})
    return normalized
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

ic_provider_params_to_solver_units()

dict picurv_cli.core.ic_provider_params_to_solver_units	(	str	generator,
		dict	params,
		dict	scales
	)

Convert a provider's validated physical parameters to solver units.

Providers work on the staged nondimensional grid, so every dimensional parameter recorded in IC_PARAM_QUANTITIES is converted before the provider runs. Nested mappings are addressed by dotted name.

Parameters

[in]	generator	Provider identifier.
[in]	params	Validated parameter mapping in physical units.
[in]	scales	Reference scales, as returned by resolve_reference_scales().

Returns

A copy of the mapping with dimensional values in solver units.

Definition at line 14567 of file core.py.

def ic_provider_params_to_solver_units(generator: str, params: dict, scales: dict) -> dict:
    """!
    @brief Convert a provider's validated physical parameters to solver units.
    @details Providers work on the staged nondimensional grid, so every dimensional
             parameter recorded in `IC_PARAM_QUANTITIES` is converted before the provider
             runs. Nested mappings are addressed by dotted name.
    @param[in] generator Provider identifier.
    @param[in] params Validated parameter mapping in physical units.
    @param[in] scales Reference scales, as returned by `resolve_reference_scales()`.
    @return A copy of the mapping with dimensional values in solver units.
    """
    converted = copy.deepcopy(params)
    for name, quantity in IC_PARAM_QUANTITIES[generator].items():
        if quantity[1] != "cli":
            continue
        *parents, leaf = name.split(".")
        holder = converted
        for parent in parents:
            holder = holder.get(parent) if isinstance(holder, dict) else None
        if isinstance(holder, dict) and leaf in holder:
            holder[leaf] = quantity_to_solver_units(
                holder[leaf], quantity, scales, f"initial_conditions.params.{name}")
    return converted
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_resampled_velocity_params()

dict picurv_cli.core.resolve_resampled_velocity_params	(	dict	params,
			prepared_blocks,
		dict	scales,
			provider_context = None
	)

Validate resampled_velocity parameters and convert them to the provider contract.

The provider brings an external triply periodic velocity field onto the case's grid. Its box must be the case's box; the source's container, layout, and sample positions are declared because no standard format records them all.

Parameters

[in]	params	Raw provider parameters, physical units.
[in]	prepared_blocks	Normalized boundary-condition blocks.
[in]	scales	Reference scales.
[in]	provider_context	Optional conductor-derived provider context.

Returns

Resolved initial-condition contract; source_file stays as written and is resolved against the workspace when the provider runs.

Definition at line 14592 of file core.py.

def resolve_resampled_velocity_params(params: dict, prepared_blocks, scales: dict, provider_context=None) -> dict:
    """!
    @brief Validate `resampled_velocity` parameters and convert them to the provider contract.
    @details The provider brings an external triply periodic velocity field onto the case's
             grid. Its box must be the case's box; the source's container, layout, and sample
             positions are declared because no standard format records them all.
    @param[in] params Raw provider parameters, physical units.
    @param[in] prepared_blocks Normalized boundary-condition blocks.
    @param[in] scales Reference scales.
    @param[in] provider_context Optional conductor-derived provider context.
    @return Resolved initial-condition contract; `source_file` stays as written and is
            resolved against the workspace when the provider runs.
    """
    name = "resampled_velocity"
    if prepared_blocks and len(prepared_blocks) != 1:
        raise ValueError(f"{name} requires exactly one grid block.")
    if not prepared_blocks or len(prepared_blocks[0]) != 6 or any(
        bc.get("type") != "PERIODIC" or bc.get("handler") != "geometric" for bc in prepared_blocks[0]
    ):
        raise ValueError(f"{name} requires PERIODIC/geometric boundaries on all six faces; "
                         "wall-bounded sources are not supported yet.")
    unknown = sorted(set(params) - RESAMPLED_VELOCITY_PARAMS)
    if unknown:
        raise ValueError(f"{name} has unsupported params: {unknown}.")
    # Ucont is the default: face-centre samples projected with PICurv's face-difference
    # operator keep the most energy through the runtime's reconstruction and need the
    # smallest projection; Ucat stages cell centres like the synthetic providers do.
    field_name, field_code = normalize_initial_condition_field(params.get("field", "Ucont"))
    source_file = params.get("source_file")
    if not isinstance(source_file, str) or not source_file.strip():
        raise ValueError(f"{name} requires params.source_file, the field to import.")
    fmt = str(params.get("format", "")).lower()
    if fmt not in RESAMPLED_VELOCITY_LAYOUT_KEYS:
        raise ValueError(f"{name} params.format must be one of {sorted(RESAMPLED_VELOCITY_LAYOUT_KEYS)}.")
    cells = params.get("cells")
    if cells is not None:
        if (not isinstance(cells, list) or len(cells) != 3
                or any(isinstance(c, bool) or not isinstance(c, int) or c < 4 for c in cells)):
            raise ValueError(f"{name} params.cells must list the source's sample counts along x, y, z, "
                             "each an integer of at least 4.")
    elif fmt == "raw":
        raise ValueError(f"{name} with format: raw requires params.cells, the sample counts along x, y, z.")
    box = params.get("box_length")
    if not isinstance(box, list) or len(box) != 3:
        raise ValueError(f"{name} requires params.box_length: the source's periods along x, y, z, "
                         "in physical length.")
    box = [_to_finite_float(value, f"initial_conditions.params.box_length[{index}]")
           for index, value in enumerate(box)]
    if any(value <= 0 for value in box):
        raise ValueError(f"{name} params.box_length values must be positive.")
    offset = params.get("sample_offset", 0.0)
    offset = offset if isinstance(offset, list) else [offset, offset, offset]
    if len(offset) != 3:
        raise ValueError(f"{name} params.sample_offset is one number or three, along x, y, z.")
    offset = [_to_finite_float(value, f"initial_conditions.params.sample_offset[{index}]")
              for index, value in enumerate(offset)]
    if any(value < 0.0 or value >= 1.0 for value in offset):
        raise ValueError(f"{name} params.sample_offset is a fraction of the source spacing in [0, 1): "
                         "0 for samples on the box origin, 0.5 for cell centres.")
    layout = params.get("layout", {})
    if not isinstance(layout, dict):
        raise ValueError(f"{name} params.layout must be a mapping.")
    extra = sorted(set(layout) - RESAMPLED_VELOCITY_LAYOUT_KEYS[fmt])
    if extra:
        raise ValueError(f"{name} layout keys {extra} do not apply to format: {fmt}; "
                         f"it accepts {sorted(RESAMPLED_VELOCITY_LAYOUT_KEYS[fmt])}.")
    normalized_layout = {"fastest_axis": str(layout.get("fastest_axis", "x")).lower(),
                         "components": str(layout.get("components", "interleaved")).lower()}
    if normalized_layout["fastest_axis"] not in RESAMPLED_VELOCITY_FASTEST_AXES:
        raise ValueError(f"{name} layout.fastest_axis must be x (x varies fastest) or z.")
    if normalized_layout["components"] not in RESAMPLED_VELOCITY_COMPONENT_LAYOUTS:
        raise ValueError(f"{name} layout.components must be interleaved (u, v, w at each point) "
                         "or separate (all u, then all v, then all w).")
    if fmt == "raw":
        dtype = str(layout.get("dtype", "")).lower()
        if dtype not in RESAMPLED_VELOCITY_RAW_DTYPES:
            raise ValueError(f"{name} format: raw requires layout.dtype: float32 or float64.")
        byte_order = str(layout.get("byte_order", "native")).lower()
        if byte_order not in RESAMPLED_VELOCITY_BYTE_ORDERS:
            raise ValueError(f"{name} layout.byte_order must be little, big, or native.")
        header = layout.get("header_bytes", 0)
        if isinstance(header, bool) or not isinstance(header, int) or header < 0:
            raise ValueError(f"{name} layout.header_bytes must be a non-negative integer.")
        normalized_layout.update({"dtype": dtype, "byte_order": byte_order, "header_bytes": header})
    elif "datasets" in RESAMPLED_VELOCITY_LAYOUT_KEYS[fmt]:
        datasets = layout.get("datasets")
        if (not isinstance(datasets, list) or len(datasets) not in (1, 3)
                or any(not isinstance(item, str) or not item for item in datasets)):
            raise ValueError(f"{name} format: {fmt} requires layout.datasets: one array name, "
                             "or three for u, v, w.")
        normalized_layout["datasets"] = list(datasets)
    filter_cfg = params.get("filter", {"type": "none"})
    if not isinstance(filter_cfg, dict):
        raise ValueError(f"{name} params.filter must be a mapping.")
    filter_type = str(filter_cfg.get("type", "none")).lower()
    expected = {"none": set(), "sharp": {"cutoff"}, "gaussian": {"width"}, "box": {"width"}}
    if filter_type not in expected:
        raise ValueError(f"{name} filter.type must be one of {sorted(expected)}.")
    if set(filter_cfg) - {"type"} != expected[filter_type]:
        raise ValueError(f"{name} filter.type: {filter_type} takes exactly "
                         f"{sorted(expected[filter_type]) or 'no parameters'}.")
    normalized_filter = {"type": filter_type}
    for key in expected[filter_type]:
        value = _to_finite_float(filter_cfg[key], f"initial_conditions.params.filter.{key}")
        if value <= 0:
            raise ValueError(f"{name} filter.{key} must be positive.")
        normalized_filter[key] = value
    projection = str(params.get("projection", "picurv_discrete")).lower()
    if projection not in RESAMPLED_VELOCITY_PROJECTIONS:
        raise ValueError(f"{name} params.projection must be picurv_discrete, continuum, or none.")
    remove_mean = params.get("remove_mean", True)
    if not isinstance(remove_mean, bool):
        raise ValueError(f"{name} params.remove_mean must be boolean.")
    normalized = {"field": "Ucont" if field_code == 1 else "Ucat", "source_file": source_file,
                  "format": fmt, "box_length": box,
                  "sample_offset": offset, "layout": normalized_layout, "filter": normalized_filter,
                  "projection": projection, "remove_mean": remove_mean}
    if cells is not None:
        normalized["cells"] = list(cells)
    resolved = ic_provider_params_to_solver_units(name, normalized, scales)
    resolved["velocity_divisor"] = float(scales["velocity_ref"])
    return {"finit": 4, "cli_params": {}, "kind": name, "label": name,
            "field_name": field_name, "field_code": field_code,
            "provider_context": dict(provider_context or {}), "params": resolved}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

normalize_ic_initial_spectra()

picurv_cli.core.normalize_ic_initial_spectra	(		requested,
			excluded_axes,
			generator,
			required
	)

Validate the spectra a structured IC provider measures on its own output.

Parameters

[in]	requested	params.initial_spectra as written, or None.
[in]	excluded_axes	Axes the spectra must not transform (walls, cross-stream).
[in]	generator	Provider identifier, for messages.
[in]	required	Whether a nonempty list is mandatory.

Returns

Normalized spectrum tasks (an empty list when optional and absent).

Exceptions

ValueError

on an absent required list or an unsupported task.

Definition at line 14718 of file core.py.

def normalize_ic_initial_spectra(requested, excluded_axes, generator, required):
    """!
    @brief Validate the spectra a structured IC provider measures on its own output.
    @param[in] requested `params.initial_spectra` as written, or None.
    @param[in] excluded_axes Axes the spectra must not transform (walls, cross-stream).
    @param[in] generator Provider identifier, for messages.
    @param[in] required Whether a nonempty list is mandatory.
    @return Normalized spectrum tasks (an empty list when optional and absent).
    @throws ValueError on an absent required list or an unsupported task.
    """
    if requested is None and not required:
        return []
    if not isinstance(requested, list) or not requested:
        raise ValueError(f"{generator} requires params.initial_spectra: a nonempty list of "
                         "plane_spectrum or line_spectrum tasks over the periodic axes.")
    spectra = normalize_post_spectra_config({"spectra": {"tasks": requested}})
    for task in spectra["tasks"]:
        if task["task"] == "shell_spectrum" or set(task["axes"]) & set(excluded_axes):
            raise ValueError(f"initial spectra must transform only periodic axes of the {generator} IC.")
        if task["block"] != 0 or task["subtract_mean"].startswith("window:") or task["reference"]:
            raise ValueError("initial spectra require block 0, no window mean, and no reference.")
    return spectra["tasks"]
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_initial_condition_config()

dict picurv_cli.core.resolve_initial_condition_config	(	dict	ic,
			prepared_blocks,
		dict	scales,
			provider_context = None
	)

Resolve legacy and structured initial-condition YAML into one launcher contract.

Every value the user writes is physical; the resolved contract carries solver units, or the scales a provider or the staging step needs to reach them.

Parameters

[in]	ic	Initial-condition YAML mapping.
[in]	prepared_blocks	Normalized boundary-condition blocks.
[in]	scales	Reference scales, as returned by resolve_reference_scales().
[in]	provider_context	Optional conductor-derived provider context.

Returns

Normalized launcher initial-condition contract.

Definition at line 14742 of file core.py.

def resolve_initial_condition_config(ic: dict, prepared_blocks, scales: dict, provider_context=None) -> dict:
    """!
    @brief Resolve legacy and structured initial-condition YAML into one launcher contract.
    @details Every value the user writes is physical; the resolved contract carries solver
             units, or the scales a provider or the staging step needs to reach them.
    @param[in] ic Initial-condition YAML mapping.
    @param[in] prepared_blocks Normalized boundary-condition blocks.
    @param[in] scales Reference scales, as returned by `resolve_reference_scales()`.
    @param[in] provider_context Optional conductor-derived provider context.
    @return Normalized launcher initial-condition contract.
    """
    if not isinstance(ic, dict):
        raise ValueError("properties.initial_conditions must be a mapping.")
    mode = str(ic.get("mode", "")).strip()
 
    # Backward-compatible legacy spelling.
    if mode in LEGACY_FIELD_INIT_SPELLINGS:
        finit_code = normalize_field_init_mode(mode)
        params = resolve_ic_cli_params(ic, finit_code, prepared_blocks, scales)
        if finit_code == 1 and params.pop("ic_coordinate_system", 0) == 1:
            finit_code = 3
        return {"finit": finit_code, "cli_params": params, "kind": "builtin", "label": mode}
 
    normalized_mode = mode.lower().replace("-", "_").replace(" ", "_")
    if normalized_mode == "file":
        if prepared_blocks and len(prepared_blocks) > 1:
            raise ValueError("File-backed initial conditions currently support single-block cases only.")
        source_file = ic.get("source_file")
        if not isinstance(source_file, str) or not source_file.strip():
            raise ValueError("initial_conditions.source_file is required when mode is 'file'.")
        field_name, field_code = normalize_initial_condition_field(ic.get("field"))
        return {
            "finit": 4, "cli_params": {}, "kind": "file", "label": "file",
            "source_file": source_file.strip(), "field_name": field_name, "field_code": field_code,
            "payload_provenance": resolve_ic_payload_provenance(ic, field_code),
            "scales": dict(scales),
        }
    if normalized_mode != "generated":
        raise ValueError("initial_conditions.mode must be 'generated' or 'file'.")
 
    generator = str(ic.get("generator", "")).strip().lower().replace("-", "_").replace(" ", "_")
    params = ic.get("params", {})
    if not isinstance(params, dict):
        raise ValueError("initial_conditions.params must be a mapping.")
    for key in RETIRED_INITIAL_CONDITION_DESTINATION_KEYS:
        if key in params:
            raise ValueError(retired_destination_message("initial_conditions.params", key))
    if generator == "ic_gen":
        if prepared_blocks and len(prepared_blocks) > 1:
            raise ValueError("File-backed initial conditions currently support single-block cases only.")
        script = params.get("script")
        if script is not None and (not isinstance(script, str) or not script.strip()):
            raise ValueError("initial_conditions.params.script must be a non-empty path when provided.")
        field_name, field_code = normalize_initial_condition_field(params.get("field"))
        config_file = params.get("config_file")
        if not isinstance(config_file, str) or not config_file.strip():
            raise ValueError("initial_conditions.params.config_file is required for generator 'ic_gen'.")
        cli_args = params.get("cli_args", [])
        if cli_args is None:
            cli_args = []
        if not isinstance(cli_args, list):
            raise ValueError("initial_conditions.params.cli_args must be a list.")
        return {
            "finit": 4, "cli_params": {}, "kind": "ic_gen", "label": "ic_gen",
            "field_name": field_name, "field_code": field_code,
            "config_file": config_file.strip(),
            "script": script.strip() if script is not None else None,
            "cli_args": cli_args,
            "scales": dict(scales),
        }
 
    if generator in ("channel_spectral_velocity", "duct_spectral_velocity"):
        normalized = load_ic_generator_module().validate_wall_spectral_params(params, generator)
        if not prepared_blocks or len(prepared_blocks) != 1:
            raise ValueError("wall spectral IC requires exactly one block with resolved boundaries.")
        face_axes = {"Xi": "i", "Eta": "j", "Zeta": "k"}
        faces = prepared_blocks[0]
        if len(faces) != 6:
            raise ValueError("wall spectral IC requires all six boundary faces.")
        for bc in faces:
            axis = face_axes[bc["face"][1:]]
            if axis in normalized["wall_axes"]:
                # The perturbation vanishes at the wall, which every wall handler admits.
                valid = bc["type"] == "WALL" and "WALL" in BC_HANDLER_SPECS.get(bc["handler"], {}).get("types", ())
            else:
                valid = bc["type"] == "PERIODIC" and bc["handler"] in ("geometric", "constant_flux", "initial_flux")
                if axis != normalized["streamwise_axis"]:
                    valid = valid and bc["handler"] == "geometric"
            if not valid:
                raise ValueError("wall spectral IC requires wall pairs (no-slip or free-slip) and periodic remaining axes, driven only streamwise.")
        normalized["initial_spectra"] = normalize_ic_initial_spectra(
            normalized.get("initial_spectra"), normalized["wall_axes"], generator, required=True)
        return {"finit": 4, "cli_params": {}, "kind": generator, "label": generator,
                "field_name": "ufield", "field_code": 0,
                "params": ic_provider_params_to_solver_units(generator, normalized, scales),
                "provider_context": dict(provider_context or {})}
 
    if generator == "stability_mode_velocity":
        normalized = load_ic_generator_module().validate_stability_mode_params(params)
        if not prepared_blocks or len(prepared_blocks) != 1:
            raise ValueError("stability_mode_velocity requires exactly one block with resolved boundaries.")
        face_axes = {"Xi": "i", "Eta": "j", "Zeta": "k"}
        faces = prepared_blocks[0]
        if len(faces) != 6:
            raise ValueError("stability_mode_velocity requires all six boundary faces.")
        for bc in faces:
            cross = face_axes[bc["face"][1:]] == normalized["cross_axis"]
            if cross == (bc["type"] == "PERIODIC") or (not cross and bc["handler"] != "geometric"):
                raise ValueError("stability_mode_velocity requires geometric periodic streamwise and normal axes "
                                 "and non-periodic cross-stream faces.")
        if "initial_spectra" in normalized:
            normalized["initial_spectra"] = normalize_ic_initial_spectra(
                normalized["initial_spectra"], [normalized["cross_axis"]], generator, required=False)
        context = dict(provider_context or {})
        # The base profile is an expression of physical quantities; the provider applies these.
        context.update({"length_ref": scales["length_ref"], "velocity_ref": scales["velocity_ref"]})
        return {"finit": 4, "cli_params": {}, "kind": generator, "label": generator,
                "field_name": "ufield", "field_code": 0,
                "params": ic_provider_params_to_solver_units(generator, normalized, scales),
                "provider_context": context}
 
    if generator == "resampled_velocity":
        return resolve_resampled_velocity_params(params, prepared_blocks, scales, provider_context)
 
    if generator == "spectral_random_velocity":
        if prepared_blocks and len(prepared_blocks) != 1:
            raise ValueError("spectral_random_velocity requires exactly one grid block.")
        if not prepared_blocks or len(prepared_blocks[0]) != 6 or any(
            bc.get("type") != "PERIODIC" or bc.get("handler") != "geometric"
            for bc in prepared_blocks[0]
        ):
            raise ValueError("spectral_random_velocity requires PERIODIC/geometric boundaries on all six faces.")
        unknown = sorted(set(params) - SPECTRAL_RANDOM_VELOCITY_PARAMS)
        if unknown:
            raise ValueError(f"spectral_random_velocity has unsupported params: {unknown}.")
        field_name, field_code = normalize_initial_condition_field(params.get("field", "Ucat"))
        if field_code != 0:
            raise ValueError("spectral_random_velocity supports only params.field: Ucat.")
        seed = params.get("seed", 12345)
        if isinstance(seed, bool) or not isinstance(seed, int):
            raise ValueError("spectral_random_velocity params.seed must be an integer.")
        random_cfg = params.get("random", {})
        if not isinstance(random_cfg, dict) or set(random_cfg) - {"distribution", "mean"}:
            raise ValueError("spectral_random_velocity params.random supports only distribution and mean.")
        distribution = str(random_cfg.get("distribution", "gaussian")).lower()
        if distribution != "gaussian":
            raise ValueError("spectral_random_velocity supports only random.distribution: gaussian.")
        mean = random_cfg.get("mean", [0.0, 0.0, 0.0])
        if not isinstance(mean, list) or len(mean) != 3:
            raise ValueError("spectral_random_velocity random.mean must be a three-component list.")
        mean = [_to_finite_float(value, f"initial_conditions.params.random.mean[{index}]")
                for index, value in enumerate(mean)]
        spectrum = params.get("spectrum", {})
        if not isinstance(spectrum, dict):
            raise ValueError("spectral_random_velocity params.spectrum must be a mapping.")
        spectrum_type = str(spectrum.get("type", "white")).lower()
        if spectrum_type == "white":
            if set(spectrum) - {"type"}:
                raise ValueError("white spectrum supports only type.")
            normalized_spectrum = {"type": "white"}
        elif spectrum_type == "k4_exponential":
            if set(spectrum) - {"type", "k0", "k_cut"} or "k0" not in spectrum or "k_cut" not in spectrum:
                raise ValueError("k4_exponential spectrum requires only type, k0, and k_cut.")
            normalized_spectrum = {"type": "k4_exponential",
                                   "k0": _to_finite_float(spectrum["k0"], "initial_conditions.params.spectrum.k0"),
                                   "k_cut": _to_finite_float(spectrum["k_cut"], "initial_conditions.params.spectrum.k_cut")}
        else:
            raise ValueError("spectrum.type must be 'white' or 'k4_exponential'.")
        if any(value <= 0 for key, value in normalized_spectrum.items() if key != "type"):
            raise ValueError("spectrum k0 and k_cut values must be positive.")
        projection = params.get("projection", {"type": "none"})
        if not isinstance(projection, dict) or set(projection) - {"type", "operator"}:
            raise ValueError("projection supports only type and operator.")
        projection_type = str(projection.get("type", "none")).lower()
        if projection_type == "none" and "operator" not in projection:
            normalized_projection = {"type": "none"}
        elif projection_type == "solenoidal" and str(projection.get("operator", "")).lower() in PROJECTION_OPERATORS:
            normalized_projection = {"type": "solenoidal", "operator": str(projection["operator"]).lower()}
        else:
            raise ValueError("projection must be none, or solenoidal with continuum/picurv_discrete operator.")
        normalization = params.get("normalization", {"type": "none"})
        if not isinstance(normalization, dict) or set(normalization) - {"type", "target"}:
            raise ValueError("normalization supports only type and target.")
        normalization_type = str(normalization.get("type", "none")).lower()
        if normalization_type == "none" and "target" not in normalization:
            normalized_normalization = {"type": "none"}
        elif normalization_type == "component_rms" and "target" in normalization:
            target = _to_finite_float(normalization["target"], "initial_conditions.params.normalization.target")
            if target <= 0:
                raise ValueError("component_rms normalization.target must be positive.")
            normalized_normalization = {"type": "component_rms", "target": target}
        else:
            raise ValueError("normalization must be none or component_rms with target.")
        remove_mean = params.get("remove_mean", True)
        if not isinstance(remove_mean, bool):
            raise ValueError("spectral_random_velocity remove_mean must be boolean.")
        context = dict(provider_context or {})
        return {
            "finit": 4, "cli_params": {}, "kind": "spectral_random_velocity", "label": "spectral_random_velocity",
            "field_name": field_name, "field_code": field_code, "provider_context": context,
            "params": ic_provider_params_to_solver_units(
                "spectral_random_velocity",
                {"field": "Ucat", "seed": seed,
                 "random": {"distribution": distribution, "mean": mean},
                 "spectrum": normalized_spectrum, "projection": normalized_projection,
                 "normalization": normalized_normalization, "remove_mean": remove_mean},
                scales),
        }
 
    generator_modes = {
        "zero": (0, "Zero"),
        "constant": (1, "Constant"),
        "streamwise_constant": (3, "Constant"),
        "poiseuille": (2, "Poiseuille"),
    }
    if generator not in generator_modes:
        raise ValueError(
            "initial_conditions.generator must be one of: zero, constant, "
            "streamwise_constant, poiseuille, ic_gen, spectral_random_velocity, resampled_velocity, "
            "channel_spectral_velocity, duct_spectral_velocity, stability_mode_velocity."
        )
    finit_code, legacy_mode = generator_modes[generator]
    legacy_ic = dict(params)
    legacy_ic["mode"] = legacy_mode
    cli_params = resolve_ic_cli_params(
        legacy_ic,
        1 if finit_code == 3 else finit_code,
        prepared_blocks,
        scales,
    )
    cli_params.pop("ic_coordinate_system", None)
    return {"finit": finit_code, "cli_params": cli_params, "kind": "builtin", "label": generator}
 

Here is the call graph for this function:

Here is the caller graph for this function:

runtime_petsc_index_bytes()

int picurv_cli.core.runtime_petsc_index_bytes

(

)

Bytes of a PetscInt in the PETSc the solver this conductor drives was built on.

PETSc binary files store their sizes as PetscInt and do not record the width, so a file staged for the solver must use the solver's (PETSc's own PetscBinaryIO reads it from the build configuration the same way). An unbuilt or unstamped solver counts as 32-bit, PETSc's default.

Returns

4 or 8.

Definition at line 14975 of file core.py.

def runtime_petsc_index_bytes() -> int:
    """!
    @brief Bytes of a PetscInt in the PETSc the solver this conductor drives was built on.
    @details PETSc binary files store their sizes as PetscInt and do not record the width, so
             a file staged for the solver must use the solver's (PETSc's own PetscBinaryIO
             reads it from the build configuration the same way). An unbuilt or unstamped
             solver counts as 32-bit, PETSc's default.
    @return 4 or 8.
    """
    if _SELECTED_PETSC_INDEX_BYTES is not None:
        return _SELECTED_PETSC_INDEX_BYTES
    petsc = read_binary_petsc_stamp(resolve_runtime_executable("simulator")) or {}
    return PETSC_INDEX_BYTES.get(petsc.get("indices", "int32"), 4)
 
 
#: PetscInt widths, in bits, a PICurv build can use (`make INDEX_BITS=...`, `--petsc-index-bits`).

Here is the call graph for this function:

Here is the caller graph for this function:

requested_petsc_index_bytes()

"int | None" picurv_cli.core.requested_petsc_index_bytes

(

args = None

)

The index width a command was told to use: --petsc-index-bits, else PICURV_PETSC_INDEX_BITS.

Parameters

[in]

args

Parsed command arguments, or None.

Returns

4, 8, or None when neither names one.

Definition at line 15001 of file core.py.

def requested_petsc_index_bytes(args=None) -> "int | None":
    """!
    @brief The index width a command was told to use: `--petsc-index-bits`, else `PICURV_PETSC_INDEX_BITS`.
    @param[in] args Parsed command arguments, or None.
    @return 4, 8, or None when neither names one.
    """
    bits = getattr(args, "petsc_index_bits", None) if args is not None else None
    bits = bits or os.environ.get("PICURV_PETSC_INDEX_BITS") or None
    if bits is None:
        return None
    if str(bits).strip() not in PETSC_INDEX_BITS_CHOICES:
        raise ValueError(f"PETSc index bits must be 32 or 64, not {bits!r}.")
    return 4 if str(bits).strip() == "32" else 8
 
 

Here is the caller graph for this function:

required_petsc_index_bytes()

"tuple[int, str]" picurv_cli.core.required_petsc_index_bytes	(	dict	case_cfg,
		str	case_path,
		"dict | None"	monitor_cfg,
		"str | None"	staged_grid = None
	)

The PetscInt width a new run needs, from its particle count and grid size.

One PETSc object of more than PETSC_MAX_INT_32BIT entries needs 64-bit indices: a particle field (particles x 3) or a grid field (DA nodes x 3, or x 6 with field statistics). The solver checks the same limits when it creates them, so an underestimate here is refused at setup rather than run.

Parameters

[in]	case_cfg	Parsed case configuration.
[in]	case_path	Path to case.yml.
[in]	monitor_cfg	Parsed monitor configuration, for field statistics.
[in]	staged_grid	Staged PICGRID, if any.

Returns

(4 or 8, reason).

Definition at line 15016 of file core.py.

                               staged_grid: "str | None" = None) -> "tuple[int, str]":
    """!
    @brief The PetscInt width a new run needs, from its particle count and grid size.
    @details One PETSc object of more than PETSC_MAX_INT_32BIT entries needs 64-bit indices:
             a particle field (particles x 3) or a grid field (DA nodes x 3, or x 6 with field
             statistics). The solver checks the same limits when it creates them, so an
             underestimate here is refused at setup rather than run.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Path to case.yml.
    @param[in] monitor_cfg Parsed monitor configuration, for field statistics.
    @param[in] staged_grid Staged PICGRID, if any.
    @return (4 or 8, reason).
    """
    particles = (((case_cfg.get("models") or {}).get("physics") or {}).get("particles") or {})
    particle_entries = int(particles.get("count", 0) or 0) * PARTICLE_FIELD_MAX_COMPONENTS
    statistics = bool(monitor_cfg) and normalize_field_statistics_config(monitor_cfg, case_cfg)["enabled"]
    components = STATISTICS_FIELD_COMPONENTS if statistics else GRID_FIELD_MAX_COMPONENTS
    grid_entries = max([(im + 1) * (jm + 1) * (km + 1) * components
                        for im, jm, km in resolve_grid_node_dims(case_cfg, case_path, staged_grid) or []] or [0])
    if particle_entries > PETSC_MAX_INT_32BIT:
        return 8, f"{particle_entries:,} particle-field entries exceed the 32-bit limit {PETSC_MAX_INT_32BIT:,}"
    if grid_entries > PETSC_MAX_INT_32BIT:
        return 8, f"{grid_entries:,} grid-field entries exceed the 32-bit limit {PETSC_MAX_INT_32BIT:,}"
    return 4, "particle and grid fields fit 32-bit indices"
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

checkpoint_source_petsc_index_bytes()

"int | None" picurv_cli.core.checkpoint_source_petsc_index_bytes

(

str

source_dir

)

PetscInt width the committed checkpoints under a run output root were written with.

Every checkpoint of a run shares its build's width; one written before the width was recorded is 32-bit.

Parameters

[in]

source_dir

Run output root holding checkpoints/.

Returns

4 or 8, or None when it holds no committed checkpoint.

Definition at line 15043 of file core.py.

def checkpoint_source_petsc_index_bytes(source_dir: str) -> "int | None":
    """!
    @brief PetscInt width the committed checkpoints under a run output root were written with.
    @details Every checkpoint of a run shares its build's width; one written before the width
             was recorded is 32-bit.
    @param[in] source_dir Run output root holding `checkpoints/`.
    @return 4 or 8, or None when it holds no committed checkpoint.
    """
    root = os.path.join(os.path.abspath(source_dir), "checkpoints")
    for name in sorted(os.listdir(root), reverse=True) if os.path.isdir(root) else []:
        metadata = os.path.join(root, name, "checkpoint.meta")
        if os.path.isfile(os.path.join(root, name, "COMMITTED")) and os.path.isfile(metadata):
            return int(_read_checkpoint_options(metadata).get("checkpoint_petsc_index_bytes", "4"))
    return None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

select_petsc_index_bytes()

int picurv_cli.core.select_petsc_index_bytes	(	int	index_bytes,
		str	reason
	)

Make the current command drive the build of one PetscInt width.

resolve_runtime_executable() and runtime_petsc_index_bytes() follow it, so the executables staged, pinned and launched, and every PETSc file the conductor writes or validates for them, agree. Refuses a width whose executables are not built.

Parameters

[in]	index_bytes	4 or 8.
[in]	reason	Why, for the message.

Returns

index_bytes.

Definition at line 15059 of file core.py.

def select_petsc_index_bytes(index_bytes: int, reason: str) -> int:
    """!
    @brief Make the current command drive the build of one PetscInt width.
    @details `resolve_runtime_executable()` and `runtime_petsc_index_bytes()` follow it, so the
             executables staged, pinned and launched, and every PETSc file the conductor writes
             or validates for them, agree. Refuses a width whose executables are not built.
    @param[in] index_bytes 4 or 8.
    @param[in] reason Why, for the message.
    @return index_bytes.
    """
    global _SELECTED_PETSC_INDEX_BYTES
    _SELECTED_PETSC_INDEX_BYTES = index_bytes
    if index_bytes == 8:
        missing = [path for path in (resolve_runtime_executable(name) for name in RUN_EXECUTABLE_NAMES)
                   if not os.path.isfile(path)]
        if missing:
            raise ValueError(
                f"This run needs the 64-bit-index build ({reason}), which is not built: missing "
                f"{', '.join(missing)}. Build it with `make INDEX_BITS=64 PETSC_DIR=<64-bit-index PETSc> "
                f"[PETSC_ARCH=...] all`.")
        # stderr, so a dry-run's JSON plan on stdout stays parseable.
        print(f"[INFO] Using the 64-bit-index build: {reason}.", file=sys.stderr)
    return index_bytes
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

select_run_petsc_index_bytes()

int picurv_cli.core.select_run_petsc_index_bytes	(		args,
		dict	case_cfg,
		str	case_path,
		"dict | None"	monitor_cfg,
		"str | None"	restart_source_dir = None
	)

Choose and select the PetscInt width a run's solve stage needs.

A restart or continuation keeps the width its source checkpoint was written with; a new run uses 32-bit unless a particle or grid field outgrows it. An explicit --petsc-index-bits or PICURV_PETSC_INDEX_BITS wins, except against a checkpoint.

Parameters

[in]	args	Parsed command arguments.
[in]	case_cfg	Parsed case configuration.
[in]	case_path	Path to case.yml.
[in]	monitor_cfg	Parsed monitor configuration.
[in]	restart_source_dir	Restart source output root, if any.

Returns

4 or 8.

Definition at line 15084 of file core.py.

                                 restart_source_dir: "str | None" = None) -> int:
    """!
    @brief Choose and select the PetscInt width a run's solve stage needs.
    @details A restart or continuation keeps the width its source checkpoint was written with;
             a new run uses 32-bit unless a particle or grid field outgrows it. An explicit
             `--petsc-index-bits` or `PICURV_PETSC_INDEX_BITS` wins, except against a checkpoint.
    @param[in] args Parsed command arguments.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Path to case.yml.
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] restart_source_dir Restart source output root, if any.
    @return 4 or 8.
    """
    requested = requested_petsc_index_bytes(args)
    if restart_source_dir:
        recorded = checkpoint_source_petsc_index_bytes(restart_source_dir)
        if recorded is not None:
            if requested is not None and requested != recorded:
                raise ValueError(
                    f"--petsc-index-bits {8 * requested} conflicts with the restart source {restart_source_dir}, "
                    f"whose checkpoints were written with {8 * recorded}-bit indices.")
            return select_petsc_index_bytes(recorded, f"its restart source was written with {8 * recorded}-bit indices")
    needed, reason = required_petsc_index_bytes(case_cfg, case_path, monitor_cfg)
    if requested == 4 and needed == 8:
        raise ValueError(f"--petsc-index-bits 32 cannot run this case: {reason}.")
    if requested is not None:
        return select_petsc_index_bytes(requested, f"{8 * requested}-bit indices were requested")
    return select_petsc_index_bytes(needed, reason)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

select_existing_run_petsc_index_bytes()

int picurv_cli.core.select_existing_run_petsc_index_bytes	(	str	run_dir,
			args = None
	)

Select the PetscInt width an existing run was staged with, for its later stages.

The width staging recorded in config/active.json, else its checkpoints' width, else 32-bit. A conflicting explicit request is refused.

Parameters

[in]	run_dir	Run directory.
[in]	args	Parsed command arguments, or None.

Returns

4 or 8.

Definition at line 15115 of file core.py.

def select_existing_run_petsc_index_bytes(run_dir: str, args=None) -> int:
    """!
    @brief Select the PetscInt width an existing run was staged with, for its later stages.
    @details The width staging recorded in `config/active.json`, else its checkpoints' width,
             else 32-bit. A conflicting explicit request is refused.
    @param[in] run_dir Run directory.
    @param[in] args Parsed command arguments, or None.
    @return 4 or 8.
    """
    active = _read_json_if_exists(os.path.join(os.path.abspath(run_dir), "config", "active.json")) or {}
    recorded = active.get("petsc_index_bytes")
    if recorded is None:
        recorded = checkpoint_source_petsc_index_bytes(os.path.join(run_dir, CANONICAL_RUN_PATHS["output"]))
    requested = requested_petsc_index_bytes(args)
    if recorded is not None and requested is not None and requested != int(recorded):
        raise ValueError(f"--petsc-index-bits {8 * requested} conflicts with {run_dir}, staged with "
                         f"{8 * int(recorded)}-bit indices.")
    width = int(recorded) if recorded is not None else (requested or 4)
    return select_petsc_index_bytes(width, f"{run_dir} was staged with {8 * width}-bit indices")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

record_run_petsc_index_bytes()

None picurv_cli.core.record_run_petsc_index_bytes

(

str

run_dir

)

Record in config/active.json the PetscInt width the current command selected.

Parameters

[in]

run_dir

Run directory.

Returns

None.

Definition at line 15136 of file core.py.

def record_run_petsc_index_bytes(run_dir: str) -> None:
    """!
    @brief Record in `config/active.json` the PetscInt width the current command selected.
    @param[in] run_dir Run directory.
    @return None.
    """
    active_path = os.path.join(os.path.abspath(run_dir), "config", "active.json")
    active = _read_json_if_exists(active_path)
    if isinstance(active, dict):
        active["petsc_index_bytes"] = _SELECTED_PETSC_INDEX_BYTES or 4
        write_json_file(active_path, active)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

payload_petsc_index_bytes()

int picurv_cli.core.payload_petsc_index_bytes

(

str

path

)

PetscInt width of a PETSc payload: as its checkpoint recorded it, else the driven solver's.

A committed checkpoint's checkpoint.meta records the width it was written with (-checkpoint_petsc_index_bytes; absent in checkpoints written before it existed, which are 32-bit). A payload outside any checkpoint is read as the driven solver would read it.

Parameters

[in]

path

Payload path.

Returns

4 or 8.

Definition at line 15149 of file core.py.

def payload_petsc_index_bytes(path: str) -> int:
    """!
    @brief PetscInt width of a PETSc payload: as its checkpoint recorded it, else the driven solver's.
    @details A committed checkpoint's `checkpoint.meta` records the width it was written with
             (`-checkpoint_petsc_index_bytes`; absent in checkpoints written before it existed,
             which are 32-bit). A payload outside any checkpoint is read as the driven solver
             would read it.
    @param[in] path Payload path.
    @return 4 or 8.
    """
    directory = os.path.dirname(os.path.abspath(path))
    for _ in range(4):
        metadata = os.path.join(directory, "checkpoint.meta")
        if os.path.isfile(metadata):
            return int(_read_checkpoint_options(metadata).get("checkpoint_petsc_index_bytes", "4"))
        directory = os.path.dirname(directory)
    return runtime_petsc_index_bytes()
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

petsc_index_arguments()

list picurv_cli.core.petsc_index_arguments

(

int

index_bytes

)

Generator arguments naming a PetscInt width; none for PETSc's default 32-bit.

Kept empty at 4 bytes so a user's replacement generator script that predates the option keeps working for every 32-bit build.

Parameters

[in]

index_bytes

4 or 8.

Returns

Argument list.

Definition at line 15168 of file core.py.

def petsc_index_arguments(index_bytes: int) -> list:
    """!
    @brief Generator arguments naming a PetscInt width; none for PETSc's default 32-bit.
    @details Kept empty at 4 bytes so a user's replacement generator script that predates the
             option keeps working for every 32-bit build.
    @param[in] index_bytes 4 or 8.
    @return Argument list.
    """
    return [] if index_bytes == 4 else ["--petsc-index-bytes", str(index_bytes)]
 
 

Here is the caller graph for this function:

validate_petsc_vec_binary()

dict picurv_cli.core.validate_petsc_vec_binary	(	str	path,
		"int | None"	index_bytes = None
	)

Validate the basic PETSc binary VecView envelope used by ReadFieldData.

Parameters

[in]	path	PETSc binary vector path.
[in]	index_bytes	PetscInt width of the reading build; the driven solver's when None.

Returns

Summary containing the absolute path, scalar count and index width.

Definition at line 15179 of file core.py.

def validate_petsc_vec_binary(path: str, index_bytes: "int | None" = None) -> dict:
    """!
    @brief Validate the basic PETSc binary VecView envelope used by ReadFieldData.
    @param[in] path PETSc binary vector path.
    @param[in] index_bytes PetscInt width of the reading build; the driven solver's when None.
    @return Summary containing the absolute path, scalar count and index width.
    """
    import struct
    index_bytes = index_bytes or runtime_petsc_index_bytes()
    header_bytes = 2 * index_bytes
    with open(path, "rb") as fin:
        header = fin.read(header_bytes)
        if len(header) != header_bytes:
            raise ValueError(f"PETSc Vec file is too short: {path}")
        class_id, scalar_count = struct.unpack(">ii" if index_bytes == 4 else ">qq", header)
        payload = fin.read()
    if class_id != 1211214 or scalar_count < 0 or len(payload) != scalar_count * 8:
        raise ValueError(
            f"Invalid PETSc Vec file {path} for a PETSc with {index_bytes}-byte indices; a file "
            f"written for the other index width (or truncated) does not fit its header.")
    return {"path": os.path.abspath(path), "scalar_count": scalar_count, "index_bytes": index_bytes}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

write_scaled_petsc_vec_binary()

dict picurv_cli.core.write_scaled_petsc_vec_binary	(	str	source,
		str	destination,
		float	divisor
	)

Copy a PETSc binary Vec, dividing every scalar by one factor.

Used to stage a physical payload in solver units. The envelope is the one validate_petsc_vec_binary() accepts: a big-endian class id and count of the solver's index width, followed by big-endian doubles.

Parameters

[in]	source	Validated PETSc binary vector path.
[in]	destination	Path to write the scaled vector to.
[in]	divisor	Reference scale the payload is divided by.

Returns

Summary of the destination, as validate_petsc_vec_binary() reports it.

Definition at line 15202 of file core.py.

def write_scaled_petsc_vec_binary(source: str, destination: str, divisor: float) -> dict:
    """!
    @brief Copy a PETSc binary Vec, dividing every scalar by one factor.
    @details Used to stage a physical payload in solver units. The envelope is the one
             `validate_petsc_vec_binary()` accepts: a big-endian class id and count of the
             solver's index width, followed by big-endian doubles.
    @param[in] source Validated PETSc binary vector path.
    @param[in] destination Path to write the scaled vector to.
    @param[in] divisor Reference scale the payload is divided by.
    @return Summary of the destination, as `validate_petsc_vec_binary()` reports it.
    """
    from array import array
    index_bytes = validate_petsc_vec_binary(source)["index_bytes"]
    with open(source, "rb") as fin:
        header = fin.read(2 * index_bytes)
        values = array("d")
        values.frombytes(fin.read())
    if sys.byteorder == "little":
        values.byteswap()
    for index, value in enumerate(values):
        values[index] = value / divisor
    if sys.byteorder == "little":
        values.byteswap()
    with open(destination, "wb") as fout:
        fout.write(header)
        fout.write(values.tobytes())
    return validate_petsc_vec_binary(destination, index_bytes)
 

Here is the call graph for this function:

Here is the caller graph for this function:

initial_condition_diagnostic_paths()

picurv_cli.core.initial_condition_diagnostic_paths	(		run_dir,
			resolved_ic
	)

Resolve spectral IC artifacts through the canonical run layout, also for dry runs.

Parameters

[in]	run_dir	Run or asset-build root.
[in]	resolved_ic	Normalized file-backed IC provider.

Returns

Canonical diagnostic artifact paths, including each sample CSV and JSON.

Definition at line 15230 of file core.py.

def initial_condition_diagnostic_paths(run_dir, resolved_ic):
    """!
    @brief Resolve spectral IC artifacts through the canonical run layout, also for dry runs.
    @param[in] run_dir Run or asset-build root.
    @param[in] resolved_ic Normalized file-backed IC provider.
    @return Canonical diagnostic artifact paths, including each sample CSV and JSON.
    """
    if resolved_ic["kind"] not in SPECTRAL_IC_PROVIDERS:
        return []
    paths = [os.path.join(run_dir, CANONICAL_RUN_PATHS["metrics"], "initial_condition_summary.json")]
    if resolved_ic["kind"] in SHELL_SPECTRUM_IC_PROVIDERS:
        return paths + [os.path.join(run_dir, INITIAL_CONDITION_SPECTRUM_RELPATH)]
    for task in resolved_ic["params"].get("initial_spectra", []):
        base = post_spectra_task_basename(task, "initial_condition")
        paths.extend([os.path.join(run_dir, CANONICAL_RUN_PATHS["spectra"], base+suffix) for suffix in (".csv", ".json")])
    return paths
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

run_initial_spectrum_generator()

str picurv_cli.core.run_initial_spectrum_generator	(	str	field_path,
		str	staged_grid,
		str	spectrum_path,
		str	case_dir,
			task_cfg = None
	)

Measure the shell-averaged spectrum of a staged initial condition.

The spectrum has a single implementation in generators/spectra.gen, so the conductor measures the generated field rather than asking the initial-condition generator to report a spectrum it would have to bin itself.

Parameters

[in]	field_path	Generated PETSc binary Ucat path.
[in]	staged_grid	Staged canonical PICGRID path.
[in]	spectrum_path	Destination k,energy CSV path.
[in]	case_dir	Working directory for the subprocess.
[in]	task_cfg	Optional normalized plane/line task; None retains DIT shell measurement.

Returns

Absolute path to the written spectrum CSV.

Exceptions

ValueError

when the generator is missing or fails.

Definition at line 15248 of file core.py.

                                   spectrum_path: str, case_dir: str, task_cfg=None) -> str:
    """!
    @brief Measure the shell-averaged spectrum of a staged initial condition.
 
    The spectrum has a single implementation in `generators/spectra.gen`, so the
    conductor measures the generated field rather than asking the initial-condition
    generator to report a spectrum it would have to bin itself.
 
    @param[in] field_path    Generated PETSc binary Ucat path.
    @param[in] staged_grid   Staged canonical PICGRID path.
    @param[in] spectrum_path Destination `k,energy` CSV path.
    @param[in] case_dir      Working directory for the subprocess.
    @param[in] task_cfg Optional normalized plane/line task; None retains DIT shell measurement.
    @return Absolute path to the written spectrum CSV.
    @throws ValueError when the generator is missing or fails.
    """
    script = os.path.join(GENERATORS_PATH, "spectra.gen")
    if not os.path.isfile(script):
        raise ValueError(f"spectra.gen script not found: {script}")
    command = task_cfg["task"].replace("_", "-") if task_cfg else "shell-spectrum"
    cmd = [sys.executable, script, command,
           "--field-file", field_path, "--source-grid", staged_grid,
           "--spectrum-csv", spectrum_path, *petsc_index_arguments(runtime_petsc_index_bytes())]
    if task_cfg:
        cmd.extend(["--axes", *task_cfg["axes"], "--fixed-indices", json.dumps(task_cfg["fixed_indices"]),
                    "--subtract-mean", task_cfg["subtract_mean"], "--summary-json", os.path.splitext(spectrum_path)[0]+".json"])
    result = subprocess.run(cmd, cwd=case_dir, text=True, capture_output=True)
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "").strip()
        raise ValueError(
            f"initial-condition spectrum failed with exit code {result.returncode}. Details:\n{details}"
        )
    return os.path.abspath(spectrum_path)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

run_initial_condition_generator()

str picurv_cli.core.run_initial_condition_generator	(	str	case_path,
		str	run_dir,
		dict	resolved_ic
	)

Run the repository IC generator.

Parameters

[in]	case_path	Source case YAML path.
[in]	run_dir	Run or precompute output directory.
[in]	resolved_ic	Normalized external-generator contract.

Returns

Generated PETSc vector path.

Definition at line 15284 of file core.py.

def run_initial_condition_generator(case_path: str, run_dir: str, resolved_ic: dict) -> str:
    """!
    @brief Run the repository IC generator.
    @param[in] case_path Source case YAML path.
    @param[in] run_dir Run or precompute output directory.
    @param[in] resolved_ic Normalized external-generator contract.
    @return Generated PETSc vector path.
    """
    case_dir = os.path.dirname(os.path.abspath(case_path))
    if resolved_ic["kind"] in SPECTRAL_IC_PROVIDERS:
        script = os.path.join(GENERATORS_PATH, "ic.gen")
        output_path = os.path.join(run_dir, "inputs", "initial_condition", "initial_condition.generated.dat")
        os.makedirs(os.path.dirname(output_path), exist_ok=True)
        staged_grid = os.path.join(run_dir, "inputs", "grid", "grid.run")
        if not os.path.isfile(staged_grid):
            raise ValueError(f"{resolved_ic['kind']} requires a staged PICGRID at inputs/grid/grid.run.")
        summary_path = os.path.join(run_dir, "output", "analysis", "metrics", "initial_condition_summary.json")
        spectrum_path = os.path.join(run_dir, INITIAL_CONDITION_SPECTRUM_RELPATH)
        os.makedirs(os.path.dirname(summary_path), exist_ok=True)
        os.makedirs(os.path.dirname(spectrum_path), exist_ok=True)
        provider_params = resolved_ic["params"]
        provider_context = dict(resolved_ic.get("provider_context", {}))
        measured_field = output_path
        if resolved_ic["kind"] == "resampled_velocity" and provider_params.get("field") == "Ucont":
            # Staged fluxes are not a velocity; the spectrum is measured on the velocity the
            # runtime reconstructs from them, written beside the output and removed after.
            measured_field = os.path.join(os.path.dirname(output_path), ".runtime_ucat_for_spectrum.dat")
            provider_context["runtime_ucat_output"] = measured_field
        if resolved_ic["kind"] == "resampled_velocity":
            # The source is a workspace input, resolved here so the provider is handed one
            # absolute path; a reference-mode import resolves to its external target.
            provider_params = dict(provider_params)
            provider_params["source_file"] = resolve_workspace_path(case_path, provider_params["source_file"])
            if not os.path.isfile(provider_params["source_file"]):
                raise ValueError(f"resampled_velocity source file not found: {provider_params['source_file']}")
        cmd = [sys.executable, script, "--generator", resolved_ic["kind"],
               "--grid", staged_grid, "--output", output_path,
               "--params-json", json.dumps(provider_params, sort_keys=True),
               "--context-json", json.dumps(provider_context, sort_keys=True),
               "--summary-json", summary_path, *petsc_index_arguments(runtime_petsc_index_bytes())]
        result = subprocess.run(cmd, cwd=case_dir, text=True, capture_output=True)
        if result.returncode != 0:
            details = (result.stderr or result.stdout or "").strip()
            raise ValueError(f"{resolved_ic['kind']} failed with exit code {result.returncode}. Details:\n{details}")
        validate_petsc_vec_binary(output_path)
        if resolved_ic["kind"] in SHELL_SPECTRUM_IC_PROVIDERS:
            try:
                run_initial_spectrum_generator(measured_field, staged_grid, spectrum_path, case_dir)
            finally:
                if measured_field != output_path and os.path.exists(measured_field):
                    os.remove(measured_field)
        else:
            paths = initial_condition_diagnostic_paths(run_dir, resolved_ic)
            for task, path in zip(resolved_ic["params"].get("initial_spectra", []), paths[1::2]):
                run_initial_spectrum_generator(output_path, staged_grid, path, case_dir, task)
        return output_path
    script = _resolve_generator_script(resolved_ic.get("script"), case_path, "ic.gen")
    config_file = resolved_ic["config_file"]
    config_file = _resolve_case_relative_path(config_file, case_dir)
    if not os.path.isfile(script):
        raise ValueError(f"ic.gen script not found: {script}")
    if not os.path.isfile(config_file):
        raise ValueError(f"initial-condition generator config file not found: {config_file}")
    output_path = os.path.join(run_dir, "inputs", "initial_condition", "initial_condition.generated.dat")
    os.makedirs(os.path.dirname(output_path), exist_ok=True)
    cmd = [sys.executable, script, "-c", config_file, "--field",
           "Ucat" if resolved_ic["field_code"] == 0 else "Ucont",
           "--output", output_path, *petsc_index_arguments(runtime_petsc_index_bytes())]
    staged_grid = os.path.join(run_dir, "inputs", "grid", "grid.run")
    if os.path.isfile(staged_grid):
        cmd.extend(["--grid", staged_grid])
    # Expressions are written in physical units; the generator is given the scales and
    # writes solver units, like every other initial-condition provider.
    cmd.extend(["--length-ref", repr(float(resolved_ic["scales"]["length_ref"])),
                "--velocity-ref", repr(float(resolved_ic["scales"]["velocity_ref"]))])
    cmd.extend(str(token) for token in resolved_ic.get("cli_args", []))
    result = subprocess.run(cmd, cwd=case_dir, text=True, capture_output=True)
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "").strip()
        raise ValueError(f"ic.gen failed with exit code {result.returncode}. Details:\n{details}")
    validate_petsc_vec_binary(output_path)
    return output_path
 

Here is the call graph for this function:

Here is the caller graph for this function:

_check_file_ic_matches_grid()

None picurv_cli.core._check_file_ic_matches_grid ( dict  payload, str  staged_grid, dict  resolved_ic  )

protected

Refuse a mode: file payload sized for another grid, and say what imports one.

mode: file reads its vector verbatim, so it must already be laid out for this grid: one value per component per cell including one dummy layer. The runtime would refuse a mismatch at startup; staging refuses it first and names resampled_velocity, which brings a field from another grid onto this one. Programmatic grids are not staged here, so they keep the runtime check.

Parameters

[in]	payload	Header summary from validate_petsc_vec_binary().
[in]	staged_grid	Staged PICGRID path, if the grid is file-backed.
[in]	resolved_ic	Normalized file-backed IC contract.

Definition at line 15367 of file core.py.

def _check_file_ic_matches_grid(payload: dict, staged_grid: str, resolved_ic: dict) -> None:
    """!
    @brief Refuse a `mode: file` payload sized for another grid, and say what imports one.
    @details `mode: file` reads its vector verbatim, so it must already be laid out for this
             grid: one value per component per cell including one dummy layer. The runtime
             would refuse a mismatch at startup; staging refuses it first and names
             `resampled_velocity`, which brings a field from another grid onto this one.
             Programmatic grids are not staged here, so they keep the runtime check.
    @param[in] payload Header summary from `validate_petsc_vec_binary()`.
    @param[in] staged_grid Staged PICGRID path, if the grid is file-backed.
    @param[in] resolved_ic Normalized file-backed IC contract.
    """
    if not os.path.isfile(staged_grid):
        return
    dims = read_picgrid_header_dimensions(staged_grid)
    if len(dims) != 1:
        return
    im, jm, km = dims[0]
    expected = (im + 1) * (jm + 1) * (km + 1) * 3
    if payload["scalar_count"] != expected:
        raise ValueError(
            f"Initial-condition file {payload['path']} holds {payload['scalar_count']} values; this grid "
            f"({im - 1}x{jm - 1}x{km - 1} cells) needs {expected} for {resolved_ic.get('field_name', 'the field')}. "
            "mode: file reads a field already laid out for this grid. To bring in a field from another "
            "grid or format, use generator: resampled_velocity."
        )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

stage_initial_condition_file()

dict picurv_cli.core.stage_initial_condition_file	(	str	run_dir,
		str	case_path,
		dict	resolved_ic
	)

Materialize and stage one file-backed IC in ReadFieldData's expected layout.

Parameters

[in]	run_dir	Run or precompute output directory.
[in]	case_path	Source case YAML path.
[in]	resolved_ic	Normalized file-backed IC contract.

Returns

Source, staged path, and staging-directory summary.

Definition at line 15395 of file core.py.

def stage_initial_condition_file(run_dir: str, case_path: str, resolved_ic: dict) -> dict:
    """!
    @brief Materialize and stage one file-backed IC in ReadFieldData's expected layout.
    @param[in] run_dir Run or precompute output directory.
    @param[in] case_path Source case YAML path.
    @param[in] resolved_ic Normalized file-backed IC contract.
    @return Source, staged path, and staging-directory summary.
    """
    stage_dir = os.path.join(run_dir, "inputs", "initial_condition")
    os.makedirs(stage_dir, exist_ok=True)
    staged_path = os.path.join(stage_dir, f"{resolved_ic['field_name']}00000_0.dat")
    if os.path.isfile(staged_path):
        validate_petsc_vec_binary(staged_path)
        summary = {
            "source": os.path.abspath(staged_path),
            "staged": os.path.abspath(staged_path),
            "directory": os.path.abspath(stage_dir),
            "reused": True,
        }
        if resolved_ic["kind"] in SPECTRAL_IC_PROVIDERS:
            summary["diagnostics"] = initial_condition_diagnostic_paths(run_dir, resolved_ic)
        return summary
    divisor = 1.0
    if is_generated_ic_provider(resolved_ic):
        # Providers are handed the scales they need and write solver units.
        source_path = run_initial_condition_generator(case_path, run_dir, resolved_ic)
    else:
        case_dir = os.path.dirname(os.path.abspath(case_path))
        source_path = _resolve_case_relative_path(resolved_ic["source_file"], case_dir)
        if not os.path.isfile(source_path):
            raise ValueError(f"Initial-condition source file not found: {source_path}")
        payload = validate_petsc_vec_binary(source_path)
        _check_file_ic_matches_grid(payload, os.path.join(run_dir, "inputs", "grid", "grid.run"), resolved_ic)
        divisor = ic_payload_divisor(resolved_ic, case_dir)
    if divisor != 1.0:
        write_scaled_petsc_vec_binary(source_path, staged_path, divisor)
    elif os.path.abspath(source_path) != os.path.abspath(staged_path):
        shutil.copy2(source_path, staged_path)
    summary = {"source": os.path.abspath(source_path), "staged": os.path.abspath(staged_path),
               "directory": os.path.abspath(stage_dir), "payload_divisor": divisor}
    if resolved_ic["kind"] in SPECTRAL_IC_PROVIDERS:
        summary["diagnostics"] = initial_condition_diagnostic_paths(run_dir, resolved_ic)
    return summary
 

Here is the call graph for this function:

Here is the caller graph for this function:

normalize_flow_direction_token()

int picurv_cli.core.normalize_flow_direction_token

(

str

value

)

Maps a face-token flow direction string to the C FlowDirection enum integer.

Parameters

[in]

value

One of '+Xi', '-Xi', '+Eta', '-Eta', '+Zeta', '-Zeta'.

Returns

Integer 0-5 matching the FlowDirection enum.

Exceptions

ValueError

on unknown value.

Definition at line 15439 of file core.py.

def normalize_flow_direction_token(value: str) -> int:
    """!
    @brief Maps a face-token flow direction string to the C FlowDirection enum integer.
    @param[in] value One of '+Xi', '-Xi', '+Eta', '-Eta', '+Zeta', '-Zeta'.
    @return Integer 0-5 matching the FlowDirection enum.
    @throws ValueError on unknown value.
    """
    mapped = {
        "+Xi": 0, "-Xi": 1,
        "+Eta": 2, "-Eta": 3,
        "+Zeta": 4, "-Zeta": 5,
    }.get(str(value).strip())
    if mapped is None:
        raise ValueError(
            f"Unknown initial_conditions.flow_direction '{value}'. "
            "Use one of: '+Xi', '-Xi', '+Eta', '-Eta', '+Zeta', '-Zeta'."
        )
    return mapped
 

Here is the caller graph for this function:

_ic_has_inlet()

bool picurv_cli.core._ic_has_inlet (   prepared_blocks )

protected

Return True if any prepared BC block contains an INLET face.

Parameters

[in]

prepared_blocks

List of prepared BC lists (one per domain block).

Returns

True if at least one INLET entry exists across all blocks.

Definition at line 15458 of file core.py.

def _ic_has_inlet(prepared_blocks) -> bool:
    """!
    @brief Return True if any prepared BC block contains an INLET face.
    @param[in] prepared_blocks List of prepared BC lists (one per domain block).
    @return True if at least one INLET entry exists across all blocks.
    """
    if not prepared_blocks:
        return False
    for block_bcs in prepared_blocks:
        for entry in block_bcs:
            if entry.get("type") == "INLET":
                return True
    return False
 

Here is the caller graph for this function:

resolve_ic_cli_params()

dict picurv_cli.core.resolve_ic_cli_params	(	dict	ic,
		int	finit_code,
			prepared_blocks,
		dict	scales
	)

Resolve all IC parameters and return a dict of PETSc option values.

Parameters

[in]	ic	The properties.initial_conditions mapping.
[in]	finit_code	Normalized -finit integer code.
[in]	prepared_blocks	Normalized BC blocks (may be None).
[in]	scales	Reference scales, as returned by resolve_reference_scales().

Returns

Dict with keys matching PETSc option names (without leading dash).

Exceptions

KeyError	if a required key is absent.
ValueError	on invalid combinations or values.

Definition at line 15472 of file core.py.

def resolve_ic_cli_params(ic: dict, finit_code: int, prepared_blocks, scales: dict) -> dict:
    """!
    @brief Resolve all IC parameters and return a dict of PETSc option values.
    @param[in] ic The properties.initial_conditions mapping.
    @param[in] finit_code Normalized -finit integer code.
    @param[in] prepared_blocks Normalized BC blocks (may be None).
    @param[in] scales Reference scales, as returned by `resolve_reference_scales()`.
    @return Dict with keys matching PETSc option names (without leading dash).
    @throws KeyError if a required key is absent.
    @throws ValueError on invalid combinations or values.
    """
    result = {}
 
    if finit_code == 0:
        return result
 
    if finit_code == 1:  # Constant
        has_cartesian   = any(k in ic for k in ("u_physical", "v_physical", "w_physical"))
        has_curvilinear = "velocity_physical" in ic
 
        if has_cartesian and has_curvilinear:
            raise ValueError(
                "initial_conditions: cannot mix u/v/w_physical (cartesian) and "
                "velocity_physical (curvilinear) — use one or the other."
            )
 
        if has_curvilinear:  # curvilinear: scalar speed along flow_direction axis
            cs_code = 1
            result["ic_coordinate_system"] = cs_code
            try:
                vel_phys = float(ic["velocity_physical"])
            except (TypeError, ValueError) as exc:
                raise ValueError(
                    f"Invalid value for initial_conditions.velocity_physical: {ic['velocity_physical']!r}. "
                    "Expected a numeric value."
                ) from exc
            result["ic_velocity_physical"] = to_solver_units(
                vel_phys, ("case", "properties", "initial_conditions", "velocity_physical"), scales)
 
            if "flow_direction" in ic:
                result["flow_direction"] = normalize_flow_direction_token(ic["flow_direction"])
            elif not _ic_has_inlet(prepared_blocks):
                raise ValueError(
                    "initial_conditions.flow_direction is required for curvilinear Constant IC "
                    "when no INLET face exists."
                )
 
        else:  # cartesian: u/v/w_physical → Cart2Contra (default when no velocity_physical)
            if "flow_direction" in ic:
                raise ValueError(
                    "initial_conditions.flow_direction is not valid for cartesian Constant IC. "
                    "Use velocity_physical + flow_direction for curvilinear mode."
                )
            cs_code = 0
            result["ic_coordinate_system"] = cs_code
            u, v, w = parse_initial_velocity_components(ic, finit_code, require_explicit=True)
            ic_path = ("case", "properties", "initial_conditions")
            result["ucont_x"] = to_solver_units(u, ic_path + ("u_physical",), scales)
            result["ucont_y"] = to_solver_units(v, ic_path + ("v_physical",), scales)
            result["ucont_z"] = to_solver_units(w, ic_path + ("w_physical",), scales)
 
    elif finit_code == 2:  # Poiseuille
        if any(k in ic for k in ("u_physical", "v_physical", "w_physical")):
            raise ValueError(
                "For Poiseuille mode, use peak_velocity_physical, not u_physical/v_physical/w_physical."
            )
        if "velocity_physical" in ic:
            raise ValueError(
                "For Poiseuille mode, use peak_velocity_physical, not velocity_physical."
            )
        if "peak_velocity_physical" not in ic:
            raise KeyError("peak_velocity_physical")
        try:
            peak = float(ic["peak_velocity_physical"])
        except (TypeError, ValueError) as exc:
            raise ValueError(
                f"Invalid value for initial_conditions.peak_velocity_physical: "
                f"{ic['peak_velocity_physical']!r}. Expected a numeric value."
            ) from exc
        result["ic_velocity_physical"] = to_solver_units(
            peak, ("case", "properties", "initial_conditions", "peak_velocity_physical"), scales)
 
        if "flow_direction" in ic:
            fd_int = normalize_flow_direction_token(ic["flow_direction"])
            # Cross-check: explicit flow_direction must align with INLET face if one exists
            if _ic_has_inlet(prepared_blocks):
                inlet_axis = infer_unique_inlet_axis_from_prepared_bcs(prepared_blocks)
                fd_axis_name = {0: "x", 1: "y", 2: "z"}.get(fd_int // 2, "?")
                if inlet_axis and fd_axis_name != inlet_axis:
                    token = ic["flow_direction"]
                    raise ValueError(
                        f"initial_conditions.flow_direction '{token}' (axis '{fd_axis_name}') "
                        f"does not match INLET face axis '{inlet_axis}'."
                    )
            result["flow_direction"] = fd_int
        elif not _ic_has_inlet(prepared_blocks):
            raise ValueError(
                "initial_conditions.flow_direction is required for Poiseuille IC "
                "when no INLET face exists."
            )
 
    return result
 

Here is the call graph for this function:

Here is the caller graph for this function:

normalize_eulerian_field_source()

str picurv_cli.core.normalize_eulerian_field_source

(

str

value

)

Normalizes the Eulerian field source selector to the C-side canonical string.

Parameters

[in]

value

Human-readable or enum-like Eulerian field source.

Returns

Canonical string accepted by -euler_field_source.

Exceptions

ValueError

if the input cannot be mapped.

Definition at line 15575 of file core.py.

def normalize_eulerian_field_source(value: str) -> str:
    """!
    @brief Normalizes the Eulerian field source selector to the C-side canonical string.
    @param[in] value Human-readable or enum-like Eulerian field source.
    @return Canonical string accepted by `-euler_field_source`.
    @throws ValueError if the input cannot be mapped.
    """
    if value is None:
        raise ValueError("eulerian_field_source cannot be None")
 
    normalized = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    aliases = {
        "solve": "solve",
        "load": "load",
        "analytical": "analytical",
    }
    mapped = aliases.get(normalized)
    if mapped is None:
        raise ValueError(
            f"Unknown operation_mode.eulerian_field_source '{value}'. "
            "Use one of: 'solve', 'load', 'analytical'."
        )
    return mapped
 
 

Here is the caller graph for this function:

initial_condition_is_authoritative()

bool picurv_cli.core.initial_condition_is_authoritative	(	dict	case_cfg,
		dict	solver_cfg
	)

Whether the configured initial condition is the field the solver starts from.

A restart (start_step > 0) starts from saved state, and the load and analytical Eulerian sources supply their own field, so in each of those the configured initial condition is never read.

Parameters

[in]	case_cfg	Parsed case configuration.
[in]	solver_cfg	Parsed solver configuration.

Returns

True only for a fresh solve.

Definition at line 15600 of file core.py.

def initial_condition_is_authoritative(case_cfg: dict, solver_cfg: dict) -> bool:
    """!
    @brief Whether the configured initial condition is the field the solver starts from.
    @details A restart (start_step > 0) starts from saved state, and the load and
             analytical Eulerian sources supply their own field, so in each of those the
             configured initial condition is never read.
    @param[in] case_cfg Parsed case configuration.
    @param[in] solver_cfg Parsed solver configuration.
    @return True only for a fresh solve.
    """
    source = normalize_eulerian_field_source(
        ((solver_cfg or {}).get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
    )
    start_step = int(((case_cfg or {}).get("run_control", {}) or {}).get("start_step", 0) or 0)
    return source == "solve" and start_step == 0
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

unused_asset_kinds()

tuple picurv_cli.core.unused_asset_kinds	(	dict	case_cfg,
		dict	solver_cfg
	)

Asset kinds a run with these configurations would build but never read.

Parameters

[in]	case_cfg	Parsed case configuration.
[in]	solver_cfg	Parsed solver configuration.

Returns

Kinds to leave out of the run's asset materialization.

Definition at line 15617 of file core.py.

def unused_asset_kinds(case_cfg: dict, solver_cfg: dict) -> tuple:
    """!
    @brief Asset kinds a run with these configurations would build but never read.
    @param[in] case_cfg Parsed case configuration.
    @param[in] solver_cfg Parsed solver configuration.
    @return Kinds to leave out of the run's asset materialization.
    """
    return () if initial_condition_is_authoritative(case_cfg, solver_cfg) else ("initial-condition",)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

normalize_analytical_type()

str picurv_cli.core.normalize_analytical_type

(

str

value

)

Normalizes the analytical solution selector to the C-side canonical string.

Parameters

[in]

value

Human-readable analytical solution selector.

Returns

Canonical string accepted by -analytical_type.

Exceptions

ValueError

if the input cannot be mapped.

Definition at line 15627 of file core.py.

def normalize_analytical_type(value: str) -> str:
    """!
    @brief Normalizes the analytical solution selector to the C-side canonical string.
    @param[in] value Human-readable analytical solution selector.
    @return Canonical string accepted by `-analytical_type`.
    @throws ValueError if the input cannot be mapped.
    """
    # Canonical selector map for analytical solution selectors.
    if value is None:
        raise ValueError("analytical_type cannot be None")
 
    normalized = str(value).strip().upper().replace("-", "_").replace(" ", "_")
    if normalized not in ANALYTICAL_SOLUTION_TYPES:
        raise ValueError(
            f"Unknown operation_mode.analytical_type '{value}'. "
            "Use one of: 'TGV3D', 'ZERO_FLOW', 'UNIFORM_FLOW'."
        )
    return normalized
 

Here is the caller graph for this function:

parse_initial_velocity_components()

"tuple[float, float, float]" picurv_cli.core.parse_initial_velocity_components	(	dict	initial_conditions,
		int	finit_code,
		*bool	require_explicit
	)

Parse initial-condition velocity components with mode-aware defaults.

Parameters

[in]	initial_conditions	The properties.initial_conditions mapping from case.yml.
[in]	finit_code	Normalized -finit integer code.
[in]	require_explicit	If True, all three component keys must be present.

Returns

Tuple (u, v, w) in physical units.

Exceptions

KeyError	if a required component key is missing.
ValueError	if a component cannot be converted to float.

Definition at line 15646 of file core.py.

def parse_initial_velocity_components(initial_conditions: dict, finit_code: int, *, require_explicit: bool) -> "tuple[float, float, float]":
    """!
    @brief Parse initial-condition velocity components with mode-aware defaults.
    @param[in] initial_conditions The `properties.initial_conditions` mapping from case.yml.
    @param[in] finit_code Normalized `-finit` integer code.
    @param[in] require_explicit If True, all three component keys must be present.
    @return Tuple `(u, v, w)` in physical units.
    @throws KeyError if a required component key is missing.
    @throws ValueError if a component cannot be converted to float.
    """
    component_keys = ("u_physical", "v_physical", "w_physical")
    components = []
    for key in component_keys:
        if key not in initial_conditions:
            if require_explicit:
                raise KeyError(key)
            raw_value = 0.0
        else:
            raw_value = initial_conditions[key]
        try:
            components.append(float(raw_value))
        except (TypeError, ValueError) as exc:
            raise ValueError(
                f"Invalid value for properties.initial_conditions.{key}: {raw_value!r}. Expected a numeric value."
            ) from exc
    return tuple(components)
 

Here is the caller graph for this function:

infer_unique_inlet_axis_from_prepared_bcs()

"str | None" picurv_cli.core.infer_unique_inlet_axis_from_prepared_bcs

(

list

prepared_blocks

)

Infer the unique inlet axis across all blocks using C-side "primary inlet" ordering.

Parameters

[in]

prepared_blocks

Normalized BC blocks from validate_and_prepare_boundary_conditions.

Returns

One of "x", "y", "z" if unique, None if no inlet exists.

Exceptions

ValueError

if different blocks imply different inlet axes.

Definition at line 15673 of file core.py.

def infer_unique_inlet_axis_from_prepared_bcs(prepared_blocks: list) -> "str | None":
    """!
    @brief Infer the unique inlet axis across all blocks using C-side "primary inlet" ordering.
    @param[in] prepared_blocks Normalized BC blocks from `validate_and_prepare_boundary_conditions`.
    @return One of `"x"`, `"y"`, `"z"` if unique, `None` if no inlet exists.
    @throws ValueError if different blocks imply different inlet axes.
    """
    face_order = ("-Xi", "+Xi", "-Eta", "+Eta", "-Zeta", "+Zeta")
    face_axis = {
        "-Xi": "x", "+Xi": "x",
        "-Eta": "y", "+Eta": "y",
        "-Zeta": "z", "+Zeta": "z",
    }
 
    inlet_axes = set()
    for block_bcs in prepared_blocks:
        face_map = {entry["face"]: entry for entry in block_bcs}
        for face in face_order:
            entry = face_map.get(face)
            if entry and entry["type"] == "INLET":
                inlet_axes.add(face_axis[face])
                break
 
    if not inlet_axes:
        return None
    if len(inlet_axes) != 1:
        raise ValueError(
            "properties.initial_conditions.peak_velocity_physical requires all blocks to have a primary INLET "
            f"on the same axis. Found axes: {sorted(inlet_axes)}. Use u_physical/v_physical/w_physical instead."
        )
    return next(iter(inlet_axes))
 

Here is the caller graph for this function:

normalize_particle_init_mode()

int picurv_cli.core.normalize_particle_init_mode

(

str

value

)

Maps canonical particle init mode names to C enum/int codes (-pinit).

Parameters

[in]

value

Canonical particle initialization mode.

Returns

Canonical integer code accepted by -pinit.

Exceptions

ValueError

if the input cannot be mapped.

Definition at line 15705 of file core.py.

def normalize_particle_init_mode(value: str) -> int:
    """!
    @brief Maps canonical particle init mode names to C enum/int codes (-pinit).
    @param[in] value Canonical particle initialization mode.
    @return Canonical integer code accepted by -pinit.
    @throws ValueError if the input cannot be mapped.
    """
    # Canonical selector map for particle initialization modes.
    if value is None:
        raise ValueError("particle init mode cannot be None")
 
    name = str(value).strip()
    # SurfaceEdges was a diagnostic pattern whose placement depended on the rank layout.
    if name == "SurfaceEdges":
        raise ValueError(
            "particle init_mode 'SurfaceEdges' is retired: use 'Surface' for inlet seeding, "
            "or 'PointSource' to place particles at a chosen point."
        )
    mapped = {
        "Surface": 0,
        "Volume": 1,
        "PointSource": 2,
    }.get(name)
    if mapped is None:
        raise ValueError(
            f"Unknown particle init_mode '{value}'. Use one of: "
            "'Surface', 'Volume', 'PointSource'."
        )
    return mapped
 

Here is the caller graph for this function:

normalize_interpolation_method()

int picurv_cli.core.normalize_interpolation_method

(

str

value

)

Maps interpolation method names to C enum/int codes (-interpolation_method).

Parameters

[in]

value

Canonical interpolation method name.

Returns

Integer code accepted by -interpolation_method.

Exceptions

ValueError

if the input cannot be mapped.

Definition at line 15735 of file core.py.

def normalize_interpolation_method(value: str) -> int:
    """!
    @brief Maps interpolation method names to C enum/int codes (-interpolation_method).
    @param[in] value Canonical interpolation method name.
    @return Integer code accepted by -interpolation_method.
    @throws ValueError if the input cannot be mapped.
    """
    if value is None:
        raise ValueError("interpolation method cannot be None")
 
    mapped = {
        "Trilinear": 0,
        "CornerAveraged": 1,
        "FaceFlux": 2,
    }.get(str(value).strip())
    if mapped is None:
        raise ValueError(
            f"Unknown interpolation_method '{value}'. Use one of: "
            "'Trilinear', 'CornerAveraged', 'FaceFlux'."
        )
    return mapped
 
#: Canonical spelling of each LES model code, for diagnostics.

Here is the caller graph for this function:

normalize_les_model()

int picurv_cli.core.normalize_les_model

(

value

)

Maps LES model selectors to C enum/int codes (-les).

Parameters

[in]

value

LES selector name or legacy integer/bool value.

Returns

Integer code accepted by -les.

Exceptions

ValueError

if the input cannot be mapped.

Definition at line 15777 of file core.py.

def normalize_les_model(value) -> int:
    """!
    @brief Maps LES model selectors to C enum/int codes (-les).
    @param[in] value LES selector name or legacy integer/bool value.
    @return Integer code accepted by -les.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        return 1 if value else 0
    if isinstance(value, int):
        if value in (0, 1, 2, 3, 4):
            return value
        raise ValueError("models.physics.turbulence.les must be 0-4, false/true, or a supported model block.")
    if value is None:
        raise ValueError("LES model cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "none": 0,
        "off": 0,
        "disabled": 0,
        "no_les": 0,
        "constant": 1,
        "constant_smagorinsky": 1,
        "smagorinsky": 1,
        "dynamic": 2,
        "dynamic_smagorinsky": 2,
        "vreman": 3,
        "wale": 4,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES model '{value}'. Use one of: 'none', "
            "'constant_smagorinsky', 'dynamic_smagorinsky', 'vreman', 'wale'."
        )
    return mapped
 

Here is the caller graph for this function:

normalize_les_test_filter()

int picurv_cli.core.normalize_les_test_filter

(

value

)

Maps LES test-filter kernel names to the C -les_test_filter_kernel flag.

Parameters

[in]

value

Test-filter selector name or integer code.

Returns

0 for the volume-weighted box filter, 1 for the i/k Simpson filter.

Exceptions

ValueError

if the input cannot be mapped.

Definition at line 15814 of file core.py.

def normalize_les_test_filter(value) -> int:
    """!
    @brief Maps LES test-filter kernel names to the C -les_test_filter_kernel flag.
    @param[in] value Test-filter selector name or integer code.
    @return 0 for the volume-weighted box filter, 1 for the i/k Simpson filter.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.les.test_filter.kernel must name a filter, not a boolean.")
    if isinstance(value, int):
        if value in (0, 1):
            return value
        raise ValueError("models.physics.turbulence.les.test_filter.kernel must be 0, 1, or a supported filter name.")
    if value is None:
        raise ValueError("LES test_filter.kernel cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "volume_weighted_box": 0,
        "box": 0,
        "simpson_ik": 1,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES test filter kernel '{value}'. Use one of: "
            "'volume_weighted_box', 'simpson_ik'."
        )
    return mapped
 

Here is the caller graph for this function:

normalize_les_filter_width()

int picurv_cli.core.normalize_les_filter_width

(

value

)

Maps LES grid-filter-width model names to the C -les_filter_width flag.

Parameters

[in]

value

Filter-width model name or integer code.

Returns

0 for cube-root volume, 1 for the geometric mean of the cell extents, 2 for the longest cell extent, 3 for the Scotti aspect-ratio correction.

Exceptions

ValueError

if the input cannot be mapped.

Definition at line 15843 of file core.py.

def normalize_les_filter_width(value) -> int:
    """!
    @brief Maps LES grid-filter-width model names to the C -les_filter_width flag.
    @param[in] value Filter-width model name or integer code.
    @return 0 for cube-root volume, 1 for the geometric mean of the cell extents,
            2 for the longest cell extent, 3 for the Scotti aspect-ratio correction.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.les.filter_width must name a model, not a boolean.")
    if isinstance(value, int):
        if value in (0, 1, 2, 3):
            return value
        raise ValueError("models.physics.turbulence.les.filter_width must be 0, 1, 2, 3, or a supported model name.")
    if value is None:
        raise ValueError("LES filter_width cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "cube_root_volume": 0,
        "geometric_mean": 1,
        "max_edge": 2,
        "scotti": 3,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES filter width model '{value}'. Use one of: "
            "'cube_root_volume', 'geometric_mean', 'max_edge', 'scotti'."
        )
    return mapped
 

normalize_les_averaging_mode()

int picurv_cli.core.normalize_les_averaging_mode

(

value

)

Maps LES coefficient-averaging mode names to the C -les_averaging_mode flag.

Parameters

[in]

value

Averaging mode name or integer code.

Returns

0 for pointwise local averaging, 1 for homogeneous directions, 2 for the whole block.

Exceptions

ValueError

if the input cannot be mapped.

Definition at line 15874 of file core.py.

def normalize_les_averaging_mode(value) -> int:
    """!
    @brief Maps LES coefficient-averaging mode names to the C -les_averaging_mode flag.
    @param[in] value Averaging mode name or integer code.
    @return 0 for pointwise local averaging, 1 for homogeneous directions, 2 for the
            whole block.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.les.averaging.mode must name a mode, not a boolean.")
    if isinstance(value, int):
        if value in (0, 1, 2):
            return value
        raise ValueError("models.physics.turbulence.les.averaging.mode must be 0, 1, 2, or a supported mode name.")
    if value is None:
        raise ValueError("LES averaging.mode cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "local": 0,
        "homogeneous": 1,
        "global": 2,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES averaging mode '{value}'. Use one of: "
            "'local', 'homogeneous', 'global'."
        )
    return mapped
 

Here is the caller graph for this function:

normalize_les_clip_mode()

int picurv_cli.core.normalize_les_clip_mode

(

value

)

Maps LES coefficient-limiting mode names to the C -les_clip_mode flag.

Parameters

[in]

value

Clipping mode name or integer code.

Returns

0 to clamp into [0, max_cs^2], 1 to discard negatives only, 2 to keep the signed coefficient so backscatter survives.

Exceptions

ValueError

if the input cannot be mapped.

Definition at line 15904 of file core.py.

def normalize_les_clip_mode(value) -> int:
    """!
    @brief Maps LES coefficient-limiting mode names to the C -les_clip_mode flag.
    @param[in] value Clipping mode name or integer code.
    @return 0 to clamp into [0, max_cs^2], 1 to discard negatives only, 2 to keep the
            signed coefficient so backscatter survives.
    @throws ValueError if the input cannot be mapped.
    """
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.les.clipping.mode must name a mode, not a boolean.")
    if isinstance(value, int):
        if value in (0, 1, 2):
            return value
        raise ValueError("models.physics.turbulence.les.clipping.mode must be 0, 1, 2, or a supported mode name.")
    if value is None:
        raise ValueError("LES clipping.mode cannot be None")
 
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "clamp": 0,
        "clip_negative": 1,
        "none": 2,
    }.get(key)
    if mapped is None:
        raise ValueError(
            f"Unknown LES clipping mode '{value}'. Use one of: "
            "'clamp', 'clip_negative', 'none'."
        )
    return mapped
 
#: The logical grid directions an LES averaging set may span, in canonical order.

Here is the caller graph for this function:

normalize_les_averaging_directions()

str picurv_cli.core.normalize_les_averaging_directions

(

value

)

Maps a list of homogeneous logical directions to the C flag's string form.

Parameters

[in]

value

List or string naming a subset of the i, j, and k directions.

Returns

The selected directions as a canonically ordered subset of "ijk".

Exceptions

ValueError

if a direction is unknown or repeated.

Definition at line 15937 of file core.py.

def normalize_les_averaging_directions(value) -> str:
    """!
    @brief Maps a list of homogeneous logical directions to the C flag's string form.
    @param[in] value List or string naming a subset of the i, j, and k directions.
    @return The selected directions as a canonically ordered subset of "ijk".
    @throws ValueError if a direction is unknown or repeated.
    """
    if value is None:
        return ""
    if isinstance(value, str):
        tokens = [token for token in value.strip().lower()]
    elif isinstance(value, (list, tuple)):
        tokens = [str(token).strip().lower() for token in value]
    else:
        raise ValueError(
            "models.physics.turbulence.les.averaging.directions must be a list such as [i, k]."
        )
 
    selected = []
    for token in tokens:
        if token not in LES_AVERAGING_DIRECTION_AXES:
            raise ValueError(
                f"Unknown LES averaging direction '{token}'. Use a subset of ['i', 'j', 'k']."
            )
        if token in selected:
            raise ValueError(
                f"LES averaging direction '{token}' is repeated; list each direction once."
            )
        selected.append(token)
    return "".join(axis for axis in LES_AVERAGING_DIRECTION_AXES if axis in selected)
 

Here is the caller graph for this function:

normalize_wall_function_model()

int picurv_cli.core.normalize_wall_function_model

(

value

)

Maps wall-function model selectors to the C -wallfunction flag.

Parameters

[in]

value

Wall-function selector name, or None for the default.

Returns

Integer code accepted by -wallfunction; 1 log law, 2 Werner-Wengle, 3 Cabot.

Exceptions

ValueError

if the input cannot be mapped.

Definition at line 15968 of file core.py.

def normalize_wall_function_model(value) -> int:
    """!
    @brief Maps wall-function model selectors to the C -wallfunction flag.
    @param[in] value Wall-function selector name, or None for the default.
    @return Integer code accepted by -wallfunction; 1 log law, 2 Werner-Wengle, 3 Cabot.
    @throws ValueError if the input cannot be mapped.
    """
    if value is None:
        return 1
    if isinstance(value, bool):
        raise ValueError("models.physics.turbulence.wall_function.model must name a model, not a boolean.")
    if isinstance(value, int):
        if value in (1, 2, 3):
            return value
        raise ValueError("models.physics.turbulence.wall_function.model must be 1, 2, 3, or a supported model name.")
    key = str(value).strip().lower().replace("-", "_").replace(" ", "_")
    mapped = {
        "log_law": 1,
        "loglaw": 1,
        "werner": 2,
        "werner_wengle": 2,
        "cabot": 3,
    }.get(key)
    if mapped is None:
        raise ValueError(
            "Unknown wall_function model '%s'. Use one of: 'log_law', 'werner', 'cabot'." % value)
    return mapped
 

Here is the caller graph for this function:

resolve_enabled_flag()

bool picurv_cli.core.resolve_enabled_flag	(	dict	cfg,
		str	path,
		bool	default = True
	)

Resolves a structured enabled flag and rejects non-boolean values.

Parameters

[in]	cfg	Mapping that may contain enabled.
[in]	path	Human-readable config path for diagnostics.
[in]	default	Value used when enabled is omitted.

Returns

Boolean enabled state.

Exceptions

ValueError

if enabled is not a YAML boolean.

Definition at line 15996 of file core.py.

def resolve_enabled_flag(cfg: dict, path: str, default: bool = True) -> bool:
    """!
    @brief Resolves a structured `enabled` flag and rejects non-boolean values.
    @param[in] cfg Mapping that may contain `enabled`.
    @param[in] path Human-readable config path for diagnostics.
    @param[in] default Value used when `enabled` is omitted.
    @return Boolean enabled state.
    @throws ValueError if `enabled` is not a YAML boolean.
    """
    if 'enabled' not in cfg:
        return default
    if not isinstance(cfg['enabled'], bool):
        raise ValueError(f"{path}.enabled must be true or false.")
    return cfg['enabled']
 

Here is the caller graph for this function:

append_les_parameter_flags()

picurv_cli.core.append_les_parameter_flags	(	dict	les_cfg,
		list	control_lines
	)

Appends the LES closure parameter flags from a structured les block.

Parameters

[in]	les_cfg	Parsed models.physics.turbulence.les mapping.
[out]	control_lines	A list of strings to which C-flags will be appended.

Exceptions

ValueError

if a selector name or nested block shape is unsupported.

Definition at line 16011 of file core.py.

def append_les_parameter_flags(les_cfg: dict, control_lines: list):
    """!
    @brief Appends the LES closure parameter flags from a structured les block.
    @param[in] les_cfg Parsed `models.physics.turbulence.les` mapping.
    @param[out] control_lines A list of strings to which C-flags will be appended.
    @throws ValueError if a selector name or nested block shape is unsupported.
    """
    if 'constant_cs' in les_cfg:
        control_lines.append(f"-les_constant_cs {format_flag_value(les_cfg['constant_cs'])}")
    if 'vreman_coefficient' in les_cfg:
        control_lines.append(f"-les_vreman_coefficient {format_flag_value(les_cfg['vreman_coefficient'])}")
    if 'wale_coefficient' in les_cfg:
        control_lines.append(f"-les_wale_coefficient {format_flag_value(les_cfg['wale_coefficient'])}")
    if 'dynamic_frequency' in les_cfg:
        control_lines.append(f"-les_dynamic_frequency {format_flag_value(les_cfg['dynamic_frequency'])}")
    if 'filter_width' in les_cfg:
        control_lines.append(f"-les_filter_width {normalize_les_filter_width(les_cfg['filter_width'])}")
 
    # A bare string is accepted as shorthand for naming only the kernel, matching the
    # way the les block itself accepts either a scalar or a mapping.
    test_filter = les_cfg.get('test_filter')
    if test_filter is not None:
        if not isinstance(test_filter, dict):
            test_filter = {'kernel': test_filter}
        if 'kernel' in test_filter:
            control_lines.append(
                f"-les_test_filter_kernel {normalize_les_test_filter(test_filter['kernel'])}")
        if 'width_ratio' in test_filter:
            control_lines.append(
                f"-les_test_filter_width_ratio {format_flag_value(test_filter['width_ratio'])}")
 
    averaging = les_cfg.get('averaging')
    if averaging is not None:
        if not isinstance(averaging, dict):
            averaging = {'mode': averaging}
        if 'mode' in averaging:
            control_lines.append(
                f"-les_averaging_mode {normalize_les_averaging_mode(averaging['mode'])}")
        if 'directions' in averaging:
            directions = normalize_les_averaging_directions(averaging['directions'])
            if directions:
                control_lines.append(f"-les_averaging_directions {directions}")
 
    clipping = les_cfg.get('clipping')
    if clipping is not None:
        if not isinstance(clipping, dict):
            clipping = {'mode': clipping}
        if 'mode' in clipping:
            control_lines.append(f"-les_clip_mode {normalize_les_clip_mode(clipping['mode'])}")
        if 'max_cs' in clipping:
            control_lines.append(f"-les_clip_max_cs {format_flag_value(clipping['max_cs'])}")
        if 'min_viscosity_ratio' in clipping:
            control_lines.append(
                f"-les_min_viscosity_ratio {format_flag_value(clipping['min_viscosity_ratio'])}")
 
    gradient_model = les_cfg.get('gradient_model')
    if gradient_model is not None:
        if not isinstance(gradient_model, dict):
            gradient_model = {'enabled': gradient_model}
        enabled = resolve_enabled_flag(gradient_model,
                                       "models.physics.turbulence.les.gradient_model")
        control_lines.append(f"-les_gradient_model {1 if enabled else 0}")
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_les_diagnostics()

"dict | None" picurv_cli.core.resolve_les_diagnostics	(	dict	case_cfg,
		dict	monitor_cfg,
		bool	warn = False
	)

Resolve the LES diagnostic log settings from monitor.yml or their deprecated location.

The log is observation, not physics, so it is configured in monitor.yml diagnostics.les; case.yml models.physics.turbulence.les.diagnostics is read as a deprecated alias. Setting both is refused. yoshizawa_ci only scales the subgrid kinetic energy the log reports, so it belongs with the log.

Parameters

[in]	case_cfg	Parsed case configuration.
[in]	monitor_cfg	Parsed monitor configuration.
[in]	warn	Print a deprecation warning when the case.yml location is used.

Returns

{"enabled", optional "cadence", optional "yoshizawa_ci"}, or None when unset.

Exceptions

ValueError

for a duplicated, malformed, or out-of-range setting.

Definition at line 16074 of file core.py.

def resolve_les_diagnostics(case_cfg: dict, monitor_cfg: dict, warn: bool = False) -> "dict | None":
    """!
    @brief Resolve the LES diagnostic log settings from monitor.yml or their deprecated location.
    @details The log is observation, not physics, so it is configured in monitor.yml
             `diagnostics.les`; case.yml `models.physics.turbulence.les.diagnostics` is read as a
             deprecated alias. Setting both is refused. `yoshizawa_ci` only scales the subgrid
             kinetic energy the log reports, so it belongs with the log.
    @param[in] case_cfg Parsed case configuration.
    @param[in] monitor_cfg Parsed monitor configuration.
    @param[in] warn Print a deprecation warning when the case.yml location is used.
    @return {"enabled", optional "cadence", optional "yoshizawa_ci"}, or None when unset.
    @throws ValueError for a duplicated, malformed, or out-of-range setting.
    """
    monitor_value = (((monitor_cfg or {}).get("diagnostics") or {}).get("les")
                     if isinstance((monitor_cfg or {}).get("diagnostics"), dict) else None)
    les_cfg = ((((case_cfg or {}).get("models") or {}).get("physics") or {}).get("turbulence") or {}).get("les")
    case_value = les_cfg.get("diagnostics") if isinstance(les_cfg, dict) else None
    if monitor_value is not None and case_value is not None:
        raise ValueError("LES diagnostics are set in monitor.yml (diagnostics.les) and in their deprecated "
                         "case.yml location (models.physics.turbulence.les.diagnostics); keep only monitor.yml.")
    value, label = ((monitor_value, "monitor.yml diagnostics.les") if monitor_value is not None
                    else (case_value, "case.yml models.physics.turbulence.les.diagnostics"))
    if value is None:
        return None
    if not isinstance(value, dict):
        value = {"enabled": value}
    unknown = sorted(set(value) - {"enabled", "cadence", "yoshizawa_ci"})
    if unknown:
        raise ValueError(f"{label} has unsupported key(s): {unknown}. Use enabled, cadence, yoshizawa_ci.")
    resolved = {"enabled": resolve_enabled_flag(value, label)}
    if "cadence" in value:
        if isinstance(value["cadence"], bool) or not isinstance(value["cadence"], int) or value["cadence"] <= 0:
            raise ValueError(f"{label}.cadence must be a positive integer.")
        resolved["cadence"] = value["cadence"]
    if "yoshizawa_ci" in value:
        try:
            ci = _to_finite_float(value["yoshizawa_ci"], f"{label}.yoshizawa_ci")
        except (TypeError, ValueError) as exc:
            raise ValueError(f"{label}.yoshizawa_ci must be numeric.") from exc
        if ci < 0.0:
            raise ValueError(f"{label}.yoshizawa_ci must be non-negative.")
        resolved["yoshizawa_ci"] = ci
    if monitor_value is None and warn:
        print("[WARNING] case.yml models.physics.turbulence.les.diagnostics is deprecated; "
              "set it in monitor.yml as diagnostics.les.", file=sys.stderr)
    return resolved
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

append_les_diagnostics_flags()

picurv_cli.core.append_les_diagnostics_flags	(	"dict | None"	diagnostics,
		list	control_lines
	)

Append the LES diagnostic log flags resolved by resolve_les_diagnostics().

Parameters

[in]	diagnostics	Resolved settings, or None to append nothing.
[out]	control_lines	A list of strings to which C-flags will be appended.

Definition at line 16122 of file core.py.

def append_les_diagnostics_flags(diagnostics: "dict | None", control_lines: list):
    """!
    @brief Append the LES diagnostic log flags resolved by resolve_les_diagnostics().
    @param[in] diagnostics Resolved settings, or None to append nothing.
    @param[out] control_lines A list of strings to which C-flags will be appended.
    """
    if diagnostics is None:
        return
    control_lines.append(f"-les_diagnostics {'true' if diagnostics['enabled'] else 'false'}")
    if "cadence" in diagnostics:
        control_lines.append(f"-les_diagnostics_cadence {format_flag_value(diagnostics['cadence'])}")
    if "yoshizawa_ci" in diagnostics:
        control_lines.append(f"-les_yoshizawa_ci {format_flag_value(diagnostics['yoshizawa_ci'])}")
 

Here is the caller graph for this function:

append_turbulence_flags()

picurv_cli.core.append_turbulence_flags	(	dict	models,
		list	control_lines,
		dict	scales = None
	)

Appends turbulence model flags from legacy or structured case.yml blocks.

Parameters

[in]	models	Parsed case.yml models mapping.
[out]	control_lines	A list of strings to which C-flags will be appended.
[in]	scales	The case's reference scales. Required only when a physical roughness height is set.

Exceptions

RuntimeError

when a roughness height is set and no scales were supplied.

Definition at line 16136 of file core.py.

def append_turbulence_flags(models: dict, control_lines: list, scales: dict = None):
    """!
    @brief Appends turbulence model flags from legacy or structured case.yml blocks.
    @param[in] models Parsed case.yml `models` mapping.
    @param[out] control_lines A list of strings to which C-flags will be appended.
    @param[in] scales The case's reference scales. Required only when a physical
               roughness height is set.
    @throws RuntimeError when a roughness height is set and no scales were supplied.
    """
    turbulence_cfg = models.get('physics', {}).get('turbulence', {})
    if not turbulence_cfg:
        return
    if not isinstance(turbulence_cfg, dict):
        raise ValueError("models.physics.turbulence must be a mapping.")
 
    les_cfg = turbulence_cfg.get('les')
    rans_cfg = turbulence_cfg.get('rans')
    wall_cfg = turbulence_cfg.get('wall_function')
    les_code = None
 
    if isinstance(les_cfg, dict):
        enabled = resolve_enabled_flag(les_cfg, "models.physics.turbulence.les")
        model_value = les_cfg.get('model', 'constant_smagorinsky')
        les_code = normalize_les_model(model_value) if enabled else 0
        control_lines.append(f"-les {les_code}")
        append_les_parameter_flags(les_cfg, control_lines)
    elif les_cfg is not None:
        les_code = normalize_les_model(les_cfg)
        control_lines.append(f"-les {les_code}")
 
    if rans_cfg is not None:
        raise ValueError(RANS_PLANNED_REFUSAL)
 
    if isinstance(wall_cfg, dict):
        enabled = resolve_enabled_flag(wall_cfg, "models.physics.turbulence.wall_function")
        # The flag carries the model, with zero meaning disabled, so a selector change
        # reaches the runtime instead of being validated and dropped.
        wall_model = normalize_wall_function_model(wall_cfg.get('model'))
        control_lines.append(f"-wallfunction {wall_model if enabled else 0}")
        if 'roughness_height' in wall_cfg:
            if scales is None:
                raise RuntimeError("wall_function.roughness_height is a physical length and needs the case reference scales.")
            roughness = to_solver_units(
                wall_cfg['roughness_height'],
                ("case", "models", "physics", "turbulence", "wall_function", "roughness_height"), scales)
            control_lines.append(f"-wall_roughness {format_flag_value(roughness)}")
    elif wall_cfg is not None:
        control_lines.append(f"-wallfunction {format_flag_value(wall_cfg)}")
 

Here is the call graph for this function:

Here is the caller graph for this function:

control_value()

picurv_cli.core.control_value	(		value,
		str	context
	)

Guard a value that is written verbatim into the generated control file.

PETSc reads the control file line by line, so a value containing a newline writes additional option lines - which defeats every key-based check by smuggling a whole new flag. Rejecting the value is the only safe handling; there is no quoting that makes a multi-line option meaningful.

Parameters

[in]	value	Configured value destined for a control line.
[in]	context	YAML path, for the error message.

Returns

The value unchanged when it is safe to emit.

Exceptions

SystemExit

when the value would inject an option line.

Definition at line 16185 of file core.py.

def control_value(value, context: str):
    """!
    @brief Guard a value that is written verbatim into the generated control file.
 
    @details PETSc reads the control file line by line, so a value containing a newline
             writes additional option lines - which defeats every key-based check by
             smuggling a whole new flag. Rejecting the value is the only safe handling;
             there is no quoting that makes a multi-line option meaningful.
    @param[in] value Configured value destined for a control line.
    @param[in] context YAML path, for the error message.
    @return The value unchanged when it is safe to emit.
    @throws SystemExit when the value would inject an option line.
    """
    text = str(value)
    if any(character in text for character in ("\n", "\r")):
        print(
            f"[FATAL] {context} contains a newline. Values written to the generated control "
            f"file must occupy a single line; a multi-line value would inject additional "
            f"PETSc options.",
            file=sys.stderr,
        )
        sys.exit(1)
    return value
 
 

Here is the caller graph for this function:

append_passthrough_flags()

picurv_cli.core.append_passthrough_flags	(	list	control_lines,
		dict	options
	)

Appends raw CLI flags to the control list from a {flag: value} dict.

Boolean true is emitted as a switch with no value. Boolean false is skipped. All other values are emitted as "<flag> <value>".

Parameters

[out]	control_lines	The destination list of control-file lines.
[in]	options	Mapping of raw CLI flags to values.

Definition at line 16210 of file core.py.

def append_passthrough_flags(control_lines: list, options: dict):
    """!
    @brief Appends raw CLI flags to the control list from a {flag: value} dict.
    @details Boolean `true` is emitted as a switch with no value. Boolean `false`
             is skipped. All other values are emitted as "<flag> <value>".
    @param[out] control_lines The destination list of control-file lines.
    @param[in] options Mapping of raw CLI flags to values.
    """
    if not options:
        return
    for flag, value in options.items():
        if isinstance(flag, str) and flag.strip() in RESERVED_DIRECTORY_FLAGS:
            # Defense in depth: validation rejects these, but the emitter must never
            # write a run-directory flag from an unvalidated passthrough surface.
            raise ValueError(
                f"Refusing to emit reserved directory flag '{flag.strip()}' from passthrough "
                "options; run directories are fixed by the workspace contract."
            )
        if isinstance(value, bool):
            if value:
                control_lines.append(str(flag))
            continue
        control_lines.append(
            f"{flag} {control_value(format_flag_value(value), f'passthrough option {flag}')}"
        )
 
 

Here is the caller graph for this function:

resolve_solver_monitoring_flags()

dict picurv_cli.core.resolve_solver_monitoring_flags

(

dict

monitor_cfg

)

Resolve human-readable solver monitoring YAML to raw control flags.

Parameters

[in]

monitor_cfg

Parsed monitor.yml mapping.

Returns

Mapping of raw C/PETSc flags to values.

Definition at line 16253 of file core.py.

def resolve_solver_monitoring_flags(monitor_cfg: dict) -> dict:
    """!
    @brief Resolve human-readable solver monitoring YAML to raw control flags.
    @param[in] monitor_cfg Parsed monitor.yml mapping.
    @return Mapping of raw C/PETSc flags to values.
    """
    solver_mon_cfg = monitor_cfg.get("solver_monitoring", {}) if isinstance(monitor_cfg, dict) else {}
    if solver_mon_cfg is None:
        return {}
    if not isinstance(solver_mon_cfg, dict):
        raise ValueError("monitor.solver_monitoring must be a mapping when provided.")
 
    flags = {}
 
    momentum_cfg = solver_mon_cfg.get("momentum", {})
    if momentum_cfg is None:
        momentum_cfg = {}
    if not isinstance(momentum_cfg, dict):
        raise ValueError("monitor.solver_monitoring.momentum must be a mapping when provided.")
    unknown_momentum = sorted(set(momentum_cfg.keys()) - set(SOLVER_MONITORING_MOMENTUM_FLAG_MAP.keys()))
    if unknown_momentum:
        raise ValueError(f"monitor.solver_monitoring.momentum has unsupported key(s): {unknown_momentum}.")
    for key, flag in SOLVER_MONITORING_MOMENTUM_FLAG_MAP.items():
        if key in momentum_cfg:
            value = momentum_cfg[key]
            if not isinstance(value, bool):
                raise ValueError(f"monitor.solver_monitoring.momentum.{key} must be boolean.")
            flags[flag] = value
 
    poisson_cfg = solver_mon_cfg.get("poisson", {})
    if poisson_cfg is None:
        poisson_cfg = {}
    if not isinstance(poisson_cfg, dict):
        raise ValueError("monitor.solver_monitoring.poisson must be a mapping when provided.")
    unknown_poisson = sorted(set(poisson_cfg.keys()) - set(SOLVER_MONITORING_POISSON_FLAG_MAP.keys()))
    if unknown_poisson:
        raise ValueError(f"monitor.solver_monitoring.poisson has unsupported key(s): {unknown_poisson}.")
    for key, flag in SOLVER_MONITORING_POISSON_FLAG_MAP.items():
        if key in poisson_cfg:
            value = poisson_cfg[key]
            if not isinstance(value, bool):
                raise ValueError(f"monitor.solver_monitoring.poisson.{key} must be boolean.")
            flags[flag] = value
 
    passthrough = solver_mon_cfg.get("petsc_passthrough_options", {})
    if passthrough is None:
        passthrough = {}
    if not isinstance(passthrough, dict):
        raise ValueError("monitor.solver_monitoring.petsc_passthrough_options must be a mapping when provided.")
    flags.update(passthrough)
 
    legacy_raw = {
        key: value
        for key, value in solver_mon_cfg.items()
        if isinstance(key, str) and key.startswith("-")
    }
    flags.update(legacy_raw)
 
    unknown_top = sorted(
        key
        for key in solver_mon_cfg.keys()
        if key not in {"momentum", "poisson", "petsc_passthrough_options"} and not (isinstance(key, str) and key.startswith("-"))
    )
    if unknown_top:
        raise ValueError(
            "monitor.solver_monitoring has unsupported key(s): "
            f"{unknown_top}. Use 'momentum'/'poisson' for structured monitors or "
            "'petsc_passthrough_options' for raw PETSc flags."
        )
 
    return flags
 
 

Here is the caller graph for this function:

resolve_traced_particle_ids()

list picurv_cli.core.resolve_traced_particle_ids

(

dict

monitor_cfg

)

Return the sorted, distinct particle IDs of logging.trace_particles.

Parameters

[in]

monitor_cfg

Parsed monitor configuration.

Returns

Sorted list of non-negative integer IDs; empty when tracing is off.

Exceptions

ValueError

When the value is not a list of at most 64 non-negative integers.

Definition at line 16329 of file core.py.

def resolve_traced_particle_ids(monitor_cfg: dict) -> list:
    """!
    @brief Return the sorted, distinct particle IDs of `logging.trace_particles`.
    @param[in] monitor_cfg Parsed monitor configuration.
    @return Sorted list of non-negative integer IDs; empty when tracing is off.
    @throws ValueError When the value is not a list of at most 64 non-negative integers.
    """
    logging_cfg = monitor_cfg.get('logging') if isinstance(monitor_cfg, dict) else None
    if not isinstance(logging_cfg, dict) or logging_cfg.get('trace_particles') is None:
        return []
    raw = logging_cfg['trace_particles']
    if not isinstance(raw, list) or any(isinstance(pid, bool) or not isinstance(pid, int) or pid < 0 for pid in raw):
        raise ValueError("'logging.trace_particles' must be a list of non-negative integer particle IDs "
                         f"(got {raw!r}).")
    traced = sorted(set(raw))
    if len(traced) > MAX_TRACED_PARTICLES:
        raise ValueError(f"'logging.trace_particles' accepts at most {MAX_TRACED_PARTICLES} particle IDs "
                         f"(got {len(traced)}).")
    return traced
 
 

Here is the caller graph for this function:

resolve_particle_console_output_frequency()

"int | None" picurv_cli.core.resolve_particle_console_output_frequency

(

dict

io_cfg

)

Return the effective particle-console snapshot cadence from monitor.yml.

Parameters

[in]

io_cfg

Argument passed to resolve_particle_console_output_frequency().

Returns

Value returned by resolve_particle_console_output_frequency().

Definition at line 16350 of file core.py.

def resolve_particle_console_output_frequency(io_cfg: dict) -> "int | None":
    """!
    @brief Return the effective particle-console snapshot cadence from monitor.yml.
    @param[in] io_cfg Argument passed to `resolve_particle_console_output_frequency()`.
    @return Value returned by `resolve_particle_console_output_frequency()`.
    """
    if 'particle_console_output_frequency' in io_cfg:
        return io_cfg['particle_console_output_frequency']
    return io_cfg.get('data_output_frequency')
 

Here is the caller graph for this function:

parse_and_add_model_flags()

picurv_cli.core.parse_and_add_model_flags	(	dict	case_cfg,
		list	control_lines
	)

Parses the 'models' section of case.yml and adds corresponding C-solver flags.

Parameters

[in]	case_cfg	The parsed case.yml configuration dictionary.
[out]	control_lines	A list of strings to which C-flags will be appended.

Definition at line 16360 of file core.py.

def parse_and_add_model_flags(case_cfg: dict, control_lines: list):
    """!
    @brief Parses the 'models' section of case.yml and adds corresponding C-solver flags.
    @param[in] case_cfg The parsed case.yml configuration dictionary.
    @param[out] control_lines A list of strings to which C-flags will be appended.
    """
    models = case_cfg.get('models', {})
    FLAG_MAP = {
        'domain': {'blocks': '-nblk'},
        'physics.fsi': {'immersed': '-imm', 'moving_fsi': '-fsi'},
        'physics.particles': {'count': '-numParticles', 'random_seed': '-particle_random_seed'},
    }
    for section_path, flags in FLAG_MAP.items():
        current_level = models
        try:
            for key in section_path.split('.'): current_level = current_level[key]
            for yaml_key, flag in flags.items():
                if yaml_key in current_level:
                    control_lines.append(f"{flag} {format_flag_value(current_level[yaml_key])}")
        except KeyError: continue
 
    wall_cfg = (((models.get('physics') or {}).get('turbulence') or {}).get('wall_function'))
    needs_scales = isinstance(wall_cfg, dict) and 'roughness_height' in wall_cfg
    append_turbulence_flags(models, control_lines,
                            resolve_reference_scales(case_cfg) if needs_scales else None)
 
    if models.get('physics', {}).get('dimensionality') == '2D':
        control_lines.append("-TwoD 1")
    
    particles_cfg = models.get('physics', {}).get('particles', {})
    p_init_mode_str = particles_cfg.get('init_mode', 'Surface')
    pinit_code = normalize_particle_init_mode(p_init_mode_str)
    control_lines.append(f"-pinit {pinit_code}")
    print(f"  - Particle Initialization Mode: {p_init_mode_str} (Code: {pinit_code})")
 
    if pinit_code == 2:
        point_cfg = particles_cfg.get('point_source', {})
        if not isinstance(point_cfg, dict):
            raise ValueError("models.physics.particles.point_source must be a mapping when init_mode is PointSource.")
        scales = resolve_reference_scales(case_cfg)
        point_path = ("case", "models", "physics", "particles", "point_source")
        try:
            psrc = [to_solver_units(point_cfg[axis], point_path + (axis,), scales) for axis in ("x", "y", "z")]
        except (KeyError, TypeError, ValueError):
            raise ValueError("PointSource init_mode requires numeric point_source.{x,y,z} values.")
        for axis, value in zip(("x", "y", "z"), psrc):
            control_lines.append(f"-psrc_{axis} {value}")
        print(f"  - Particle Point Source: ({point_cfg['x']}, {point_cfg['y']}, {point_cfg['z']}) "
              f"-> solver units ({psrc[0]}, {psrc[1]}, {psrc[2]})")
 
    if particles_cfg.get('fields'):
        particle_fields = normalize_particle_fields(particles_cfg['fields'])
        control_lines.append(f"-particle_fields_count {len(particle_fields)}")
        for index, entry in enumerate(particle_fields):
            control_lines.append(f"-particle_fields_{index}_name {entry['name']}")
            for component, expression in enumerate(entry["expressions"]):
                text = control_value(expression, f"models.physics.particles.fields.{entry['name']}")
                control_lines.append(f"-particle_fields_{index}_expr_{component} \"{text}\"")
            print(f"  - Particle Field Initial Value: {entry['name']} = {' ; '.join(entry['expressions'])}")
 
    p_restart_mode = particles_cfg.get('restart_mode')
    if p_restart_mode:
        p_restart_mode_normalized = str(p_restart_mode).lower()
        if p_restart_mode_normalized not in PARTICLE_RESTART_MODES:
            raise ValueError(f"Unknown particle restart_mode '{p_restart_mode}'. Options are 'init' or 'load'.")
        control_lines.append(f"-particle_restart_mode \"{p_restart_mode}\"")
 
# PETSc KSP types whose iteration adapts to the input vector. Any of these used as
# the multigrid coarse solve (level_0) makes the MG preconditioner a nonlinear
# operator; see docs/pages/25_Pressure_Poisson_GMRES_Multigrid.md.

Here is the call graph for this function:

Here is the caller graph for this function:

parse_solver_config()

dict picurv_cli.core.parse_solver_config	(	dict	solver_cfg,
		dict	scales = None,
		dict	case_cfg = None
	)

Parses the structured solver.yml into a flat dictionary of {flag: value}.

Parameters

[in]	solver_cfg	The parsed solver.yml configuration dictionary.
[in]	scales	The case's reference scales. Required only when solver.yml sets a dimensional value, which is physical and is converted here.
[in]	case_cfg	The parsed case.yml, which holds the scalar-transport parameters.

Returns

A dictionary where keys are C-solver flags and values are the corresponding settings.

Definition at line 16436 of file core.py.

def parse_solver_config(solver_cfg: dict, scales: dict = None, case_cfg: dict = None) -> dict:
    """!
    @brief Parses the structured solver.yml into a flat dictionary of {flag: value}.
    @param[in] solver_cfg The parsed solver.yml configuration dictionary.
    @param[in] scales The case's reference scales. Required only when solver.yml sets a
               dimensional value, which is physical and is converted here.
    @param[in] case_cfg The parsed case.yml, which holds the scalar-transport parameters.
    @return A dictionary where keys are C-solver flags and values are the corresponding settings.
    """
    flags = {}
 
    def solver_value(path: tuple, value) -> float:
        """!
        @brief Convert one solver.yml value by its recorded dimension.
        @param[in] path Schema path under solver.yml.
        @param[in] value Value as written.
        @return The value in solver units.
        @throws RuntimeError when the value is dimensional and no scales were supplied; that
                is a caller error, kept distinct from the ValueError of an invalid value.
        """
        full_path = ("solver",) + path
        if input_quantity(full_path)[0] == DIMENSIONLESS:
            return _to_finite_float(value, ".".join(path))
        if scales is None:
            raise RuntimeError(f"{'.'.join(path)} is a physical value and needs the case reference scales.")
        return to_solver_units(value, full_path, scales)
    if 'operation_mode' in solver_cfg and isinstance(solver_cfg['operation_mode'], dict):
        op_mode = solver_cfg['operation_mode']
        if 'eulerian_field_source' in op_mode:
            normalized_source = normalize_eulerian_field_source(op_mode.get('eulerian_field_source'))
            flags['-euler_field_source'] = f"\"{normalized_source}\""
        if 'analytical_type' in op_mode and op_mode.get('analytical_type') is not None:
            normalized_analytical_type = normalize_analytical_type(op_mode.get('analytical_type'))
            flags['-analytical_type'] = f"\"{normalized_analytical_type}\""
            if normalized_analytical_type == "UNIFORM_FLOW":
                uniform_flow_cfg = op_mode.get('uniform_flow', {})
                if not isinstance(uniform_flow_cfg, dict):
                    raise ValueError("operation_mode.uniform_flow must be a mapping when analytical_type is 'UNIFORM_FLOW'.")
                try:
                    for component in ("u", "v", "w"):
                        flags[f'-analytical_uniform_{component}'] = solver_value(
                            ("operation_mode", "uniform_flow", component), uniform_flow_cfg[component])
                except KeyError as exc:
                    raise ValueError(f"operation_mode.uniform_flow.{exc.args[0]} is required when analytical_type is 'UNIFORM_FLOW'.") from exc
                except (TypeError, ValueError) as exc:
                    raise ValueError("operation_mode.uniform_flow.{u,v,w} must be numeric when analytical_type is 'UNIFORM_FLOW'.") from exc
 
    verification_cfg = solver_cfg.get('verification', {})
    if verification_cfg:
        if not isinstance(verification_cfg, dict):
            raise ValueError("verification must be a mapping when provided.")
        sources_cfg = verification_cfg.get('sources', {})
        if not isinstance(sources_cfg, dict):
            raise ValueError("verification.sources must be a mapping when provided.")
        diff_cfg = sources_cfg.get('diffusivity')
        if diff_cfg is not None:
            if not isinstance(diff_cfg, dict):
                raise ValueError("verification.sources.diffusivity must be a mapping.")
            try:
                flags['-verification_diffusivity_mode'] = f"\"{str(diff_cfg['mode']).strip().lower()}\""
                flags['-verification_diffusivity_profile'] = f"\"{str(diff_cfg['profile']).strip().upper()}\""
                for key in ("gamma0", "slope_x"):
                    flags[f'-verification_diffusivity_{key}'] = solver_value(
                        ("verification", "sources", "diffusivity", key), diff_cfg[key])
            except KeyError as exc:
                raise ValueError(f"verification.sources.diffusivity.{exc.args[0]} is required.") from exc
            except (TypeError, ValueError) as exc:
                raise ValueError("verification.sources.diffusivity.{gamma0,slope_x} must be numeric and mode/profile must be scalar strings.") from exc
 
        scalar_cfg = sources_cfg.get('scalar')
        if scalar_cfg is not None:
            if not isinstance(scalar_cfg, dict):
                raise ValueError("verification.sources.scalar must be a mapping.")
            try:
                flags['-verification_scalar_mode'] = f"\"{str(scalar_cfg['mode']).strip().lower()}\""
                flags['-verification_scalar_profile'] = f"\"{str(scalar_cfg['profile']).strip().upper()}\""
            except KeyError as exc:
                raise ValueError(f"verification.sources.scalar.{exc.args[0]} is required.") from exc
 
            scalar_numeric_keys = {
                'CONSTANT': ('value',),
                'LINEAR_X': ('phi0', 'slope_x'),
                'SIN_PRODUCT': ('amplitude', 'kx', 'ky', 'kz'),
            }
            profile = str(scalar_cfg.get('profile', '')).strip().upper()
            for key in scalar_numeric_keys.get(profile, ()):
                try:
                    flags[f'-verification_scalar_{key}'] = solver_value(
                        ("verification", "sources", "scalar", key), scalar_cfg[key])
                except KeyError as exc:
                    raise ValueError(f"verification.sources.scalar.{exc.args[0]} is required.") from exc
                except (TypeError, ValueError) as exc:
                    raise ValueError(f"verification.sources.scalar.{key} must be numeric.") from exc
 
    for key, value in resolve_scalar_transport(case_cfg, solver_cfg).items():
        flags[SCALAR_TRANSPORT_FLAGS[key]] = value
 
    selected_solver = None
    if 'strategy' in solver_cfg:
        s = solver_cfg['strategy']
        if 'central_diff' in s:
            flags['-central'] = format_flag_value(s['central_diff'])
        # Preferred selector.
        if 'momentum_solver' in s:
            selected_solver = normalize_momentum_solver_type(s['momentum_solver'])
        elif 'implicit' in s:
            raise ValueError("Legacy key 'strategy.implicit' is not supported. Use 'strategy.momentum_solver'.")
 
    def _warn_inactive_absolute_tol(cfg: dict, where: str):
        """!
        @brief Warn when absolute_tol is set but cannot affect convergence.
 
        absolute_tol bounds the velocity update. Since |dU| ~ dtau*|R|, bounding it
        absolutely is a disguised, step-size-dependent residual bound, so it takes no
        part once a residual tolerance is active -- which is now the default. Setting it
        therefore has no effect, and silently ineffective knobs are what this warning
        exists to prevent. See docs/pages/24_Dual_Time_Picard_Jameson_RK.md.
        @param[in] cfg Tolerance mapping to inspect for `absolute_tol` and the residual keys.
        @param[in] where Config path used to locate the offending key in the warning text.
        @return None; emits a warning on stderr when `absolute_tol` cannot take effect.
        """
        if 'absolute_tol' not in cfg:
            return
        # Residual convergence is enabled unless BOTH residual tolerances are explicitly
        # non-positive; their defaults (1e-8 / 1e-3) are positive.
        def _off(key):
            """!
            @brief Report whether a residual tolerance is explicitly disabled.
            @param[in] key Residual tolerance key to inspect.
            @return True when the key is present and non-positive.
            """
            v = cfg.get(key, None)
            try:
                return v is not None and float(v) <= 0.0
            except (TypeError, ValueError):
                return False
        if _off('residual_absolute_tol') and _off('residual_relative_tol'):
            return
        print(
            f"[WARNING] {where}.absolute_tol is set but takes no part in convergence while a "
            "residual tolerance is active (the default). It is retained only for the legacy "
            "update-only branch, which can converge falsely when dtau collapses. To control "
            "accuracy use residual_relative_tol / residual_absolute_tol. See "
            "docs/pages/24_Dual_Time_Picard_Jameson_RK.md.",
            file=sys.stderr,
        )
 
    ms = solver_cfg.get('momentum_solver', {})
    if selected_solver is None:
        selected_solver = "DUALTIME_PICARD_JAMESON_RK"
    flags['-mom_solver_type'] = f"\"{selected_solver}\""
 
    if 'tolerances' in solver_cfg:
        t = solver_cfg['tolerances']
        tol_map = {
            'max_iterations': '-mom_max_pseudo_steps',
            'absolute_tol': '-mom_atol',
            'relative_tol': '-mom_rtol',
            'residual_absolute_tol': '-mom_resid_atol',
            'residual_relative_tol': '-mom_resid_rtol',
            'step_tol': '-imp_stol'
        }
        for key, flag in tol_map.items():
            if key in t:
                flags[flag] = t[key]
        _warn_inactive_absolute_tol(t, "tolerances")
 
    def _append_dualtime_options(cfg: dict):
        """!
        @brief Append dualtime options.
        @param[in] cfg Argument passed to `_append_dualtime_options()`.
        """
        if 'max_pseudo_steps' in cfg:
            flags['-mom_max_pseudo_steps'] = cfg['max_pseudo_steps']
        if 'absolute_tol' in cfg:
            flags['-mom_atol'] = cfg['absolute_tol']
            _warn_inactive_absolute_tol(
                {**solver_cfg.get('tolerances', {}), **cfg},
                "momentum_solver.dual_time_picard_jameson_rk")
        if 'relative_tol' in cfg:
            flags['-mom_rtol'] = cfg['relative_tol']
        if 'step_tol' in cfg:
            flags['-imp_stol'] = cfg['step_tol']
        if 'pseudo_cfl' in cfg:
            pcfl = cfg['pseudo_cfl']
            if 'initial' in pcfl:
                flags['-pseudo_cfl'] = pcfl['initial']
            if 'minimum' in pcfl:
                flags['-min_pseudo_cfl'] = pcfl['minimum']
            if 'maximum' in pcfl:
                flags['-max_pseudo_cfl'] = pcfl['maximum']
            if 'growth_factor' in pcfl:
                flags['-pseudo_cfl_growth_factor'] = pcfl['growth_factor']
            if 'reduction_factor' in pcfl:
                flags['-pseudo_cfl_reduction_factor'] = pcfl['reduction_factor']
        if 'jameson_residual_noise_allowance_factor' in cfg:
            flags['-mom_dt_jameson_residual_norm_noise_allowance_factor'] = cfg['jameson_residual_noise_allowance_factor']
        elif 'rk4_residual_noise_allowance_factor' in cfg:
            flags['-mom_dt_jameson_residual_norm_noise_allowance_factor'] = cfg['rk4_residual_noise_allowance_factor']
        if 'ratio_ema_alpha' in cfg:
            flags['-mom_ratio_ema_alpha'] = cfg['ratio_ema_alpha']
 
    def _append_newton_krylov_options(cfg: dict):
        """!
        @brief Append validated structured Newton--Krylov PETSc options.
        @param[in] cfg Structured Newton--Krylov mapping.
        """
        cfg = validate_newton_krylov_config(cfg)
        jacobian = cfg["jacobian"]
        flags["-mom_nk_jacobian_type"] = jacobian["type"]
        flags["-mom_nk_jacobian_fd_mode"] = jacobian["finite_difference"]["mode"]
        preconditioner = cfg["preconditioner"]
        flags["-mom_nk_preconditioner_model"] = preconditioner["model"]
        flags["-mom_nk_preconditioner_structure"] = preconditioner["structure"]["type"]
        nonlinear = cfg["nonlinear_solver"]
        nonlinear_map = {
            "method": "-mom_nk_snes_type",
            "absolute_tolerance": "-mom_nk_snes_atol",
            "relative_tolerance": "-mom_nk_snes_rtol",
            "step_tolerance": "-mom_nk_snes_stol",
            "max_iterations": "-mom_nk_snes_max_it",
        }
        for key, flag in nonlinear_map.items():
            if key in nonlinear:
                flags[flag] = nonlinear[key]
        line_search = nonlinear.get("line_search", {})
        if "type" in line_search:
            flags["-mom_nk_snes_linesearch_type"] = line_search["type"]
        ew = nonlinear.get("eisenstat_walker")
        if ew:
            flags["-mom_nk_snes_ksp_ew"] = ew["enabled"]
            if ew["enabled"]:
                ew_map = {
                    "version": "-mom_nk_snes_ksp_ew_version",
                    "initial_relative_tolerance": "-mom_nk_snes_ksp_ew_rtol0",
                    "maximum_relative_tolerance": "-mom_nk_snes_ksp_ew_rtolmax",
                    "gamma": "-mom_nk_snes_ksp_ew_gamma",
                    "exponent": "-mom_nk_snes_ksp_ew_alpha",
                    "safeguard_exponent": "-mom_nk_snes_ksp_ew_alpha2",
                    "safeguard_threshold": "-mom_nk_snes_ksp_ew_threshold",
                }
                for key, flag in ew_map.items():
                    if key in ew:
                        flags[flag] = ew[key]
 
        linear = cfg["linear_solver"]
        linear_map = {
            "method": "-mom_nk_ksp_type",
            "absolute_tolerance": "-mom_nk_ksp_atol",
            "relative_tolerance": "-mom_nk_ksp_rtol",
            "max_iterations": "-mom_nk_ksp_max_it",
        }
        for key, flag in linear_map.items():
            if key in linear:
                flags[flag] = linear[key]
        gmres = linear.get("gmres", {})
        if "restart" in gmres:
            flags["-mom_nk_ksp_gmres_restart"] = gmres["restart"]
 
    if isinstance(ms, dict):
        allowed_ms_keys = {'type', 'dual_time_picard_jameson_rk', 'dual_time_picard_rk4', 'newton_krylov'}
        unknown_ms_keys = sorted(set(ms.keys()) - allowed_ms_keys)
        if unknown_ms_keys:
            raise ValueError(
                f"Unsupported momentum_solver keys/blocks: {unknown_ms_keys}. "
                "Currently supported blocks: 'dual_time_picard_jameson_rk' and 'newton_krylov'."
            )
 
        if 'dual_time_picard_jameson_rk' in ms and 'dual_time_picard_rk4' in ms:
            raise ValueError(
                "Use only momentum_solver.dual_time_picard_jameson_rk; "
                "do not also set its deprecated dual_time_picard_rk4 alias."
            )
        dt_picard_cfg = ms.get('dual_time_picard_jameson_rk', ms.get('dual_time_picard_rk4'))
        if dt_picard_cfg is not None:
            if selected_solver != "DUALTIME_PICARD_JAMESON_RK":
                raise ValueError(
                    f"momentum_solver.dual_time_picard_jameson_rk is set but selected solver is {selected_solver}."
                )
            if not isinstance(dt_picard_cfg, dict):
                raise ValueError("momentum_solver.dual_time_picard_jameson_rk must be a mapping.")
            if ('jameson_residual_noise_allowance_factor' in dt_picard_cfg and
                    'rk4_residual_noise_allowance_factor' in dt_picard_cfg):
                raise ValueError(
                    "Use only jameson_residual_noise_allowance_factor; "
                    "do not also set its deprecated rk4_residual_noise_allowance_factor alias."
                )
            _append_dualtime_options(dt_picard_cfg)
        newton_cfg = ms.get('newton_krylov')
        if newton_cfg is not None:
            if selected_solver != "newton_krylov":
                raise ValueError(
                    f"momentum_solver.newton_krylov is set but selected solver is {selected_solver}."
                )
            _append_newton_krylov_options(newton_cfg)
    def _normalize_poisson_method(value) -> str:
        """!
        @brief Normalize a user-facing Poisson linear-solver method name.
        @param[in] value Method value from the solver YAML.
        @return Lowercase PETSc KSP method token.
        """
        method = str(value).strip().lower()
        if not method:
            raise ValueError("poisson_solver.method cannot be empty.")
        if method in POISSON_KSP_REFUSED:
            raise ValueError(
                f"poisson_solver.method '{method}' {POISSON_KSP_REFUSED[method]}: PICurv's "
                "multigrid preconditioner is not a single fixed linear operator, and with it "
                f"'{method}' reports convergence while the true residual stalls, so the "
                "projection uses the wrong pressure. Use 'fgmres' (default) or 'cg'."
            )
        if method not in POISSON_KSP_METHODS:
            raise ValueError(
                f"poisson_solver.method '{method}' is not one of {sorted(POISSON_KSP_METHODS)}, "
                "the methods verified with the multigrid preconditioner. Another PETSc KSP type "
                "can still be set through petsc_passthrough_options (-ps_ksp_type), unverified."
            )
        return method
 
    def _normalize_poisson_preconditioner(value) -> str:
        """!
        @brief Normalize and validate the outer Poisson preconditioner name.
        @param[in] value Preconditioner value from the solver YAML.
        @return PETSc PC token for the supported outer preconditioner.
        """
        pc = str(value).strip().lower()
        pc = POISSON_PRECONDITIONER_SPELLINGS.get(pc, pc)
        if pc not in POISSON_PRECONDITIONER_TYPES:
            raise ValueError(
                "poisson_solver.preconditioner.type currently supports only 'multigrid'. "
                "The runtime Poisson solver still assumes PETSc PCMG setup."
            )
        return "mg"
 
    def _warn_if_krylov_coarse_solver(ksp_type, source_key: str):
        """!
        @brief Warn when the coarsest multigrid level is given a Krylov solver.
        @param[in] ksp_type PETSc KSP token configured for `level_0`.
        @param[in] source_key Name of the source YAML block, used in the message.
        @details level_0 is the coarse solve at the base of the V-cycle, not a
                 smoother. A Krylov method there makes the multigrid
                 preconditioner a nonlinear operator, which decouples the outer
                 KSP's tracked residual from the true residual b-Ax. This stays a
                 warning rather than an error because it remains legitimate at
                 large scale when tolerances are set against the true residual.
        """
        if str(ksp_type).strip().lower() not in KRYLOV_KSP_TYPES:
            return
        print(
            f"[WARNING] {source_key}.multigrid.level_solvers.level_0.method = '{ksp_type}' "
            "is a Krylov method. level_0 is the multigrid COARSE SOLVE, not a smoother, "
            "so a Krylov method there makes the preconditioner nonlinear and the outer "
            "KSP's tracked residual can stop matching the true residual b-Ax. "
            "Prefer {method: preonly, preconditioner: redundant}. If this is deliberate, "
            "enable solver_monitoring.poisson.pic_true_residual and set tolerances against "
            "the true residual. See docs/pages/25_Pressure_Poisson_GMRES_Multigrid.md.",
            file=sys.stderr,
        )
 
    def _poisson_level_number(level_name) -> int:
        """!
        @brief Extract the numeric suffix from a `level_N` multigrid level key.
        @param[in] level_name YAML level key supplied by the user.
        @return Numeric level suffix.
        """
        text = str(level_name).strip()
        match = re.fullmatch(r"level_(\d+)", text)
        if not match:
            raise ValueError(f"Invalid Poisson multigrid level name '{level_name}'. Expected 'level_N'.")
        return int(match.group(1))
 
    def _append_poisson_solver_flags(ps: dict, source_key: str):
        """!
        @brief Append structured Poisson solver options to the flat PETSc flag map.
        @param[in] ps The `poisson_solver` or legacy `pressure_solver` mapping.
        @param[in] source_key Name of the source YAML block, used in error messages.
        """
        if not isinstance(ps, dict):
            raise ValueError(f"{source_key} must be a mapping when provided.")
 
        method = None
        if 'method' in ps:
            method = _normalize_poisson_method(ps['method'])
            flags['-ps_ksp_type'] = method
            flags.update(POISSON_KSP_METHODS[method])
        if 'absolute_tolerance' in ps:
            flags['-ps_ksp_atol'] = ps['absolute_tolerance']
        if 'relative_tolerance' in ps:
            flags['-ps_ksp_rtol'] = ps['relative_tolerance']
        if 'max_iterations' in ps:
            flags['-ps_ksp_max_it'] = ps['max_iterations']
        if 'tolerance' in ps:
            raise ValueError(
                f"{source_key}.tolerance is not a solver control: the runtime read it and never "
                "used it. Use absolute_tolerance (-> -ps_ksp_atol) and relative_tolerance "
                "(-> -ps_ksp_rtol), which the Poisson KSP applies."
            )
 
        gmres_cfg = ps.get('gmres', {})
        if gmres_cfg is not None:
            if not isinstance(gmres_cfg, dict):
                raise ValueError(f"{source_key}.gmres must be a mapping when provided.")
            if 'restart' in gmres_cfg:
                if method is None:
                    method = _normalize_poisson_method(ps.get('method', 'fgmres'))
                    flags.setdefault('-ps_ksp_type', method)
                if method not in GMRES_RESTART_METHODS:
                    raise ValueError(
                        f"{source_key}.gmres.restart is valid only when {source_key}.method "
                        "is one of 'gmres', 'fgmres', or 'lgmres'."
                    )
                flags['-ps_ksp_gmres_restart'] = gmres_cfg['restart']
 
        preconditioner_cfg = ps.get('preconditioner', {})
        if preconditioner_cfg:
            if not isinstance(preconditioner_cfg, dict):
                raise ValueError(f"{source_key}.preconditioner must be a mapping when provided.")
            if 'type' in preconditioner_cfg:
                flags['-ps_pc_type'] = _normalize_poisson_preconditioner(preconditioner_cfg['type'])
 
        if 'multigrid' in ps:
            mg = ps['multigrid']
            if not isinstance(mg, dict):
                raise ValueError(f"{source_key}.multigrid must be a mapping when provided.")
            mg_map = {'levels': '-mg_level', 'pre_sweeps': '-mg_pre_it', 'post_sweeps': '-mg_post_it'}
            for key, flag in mg_map.items():
                if key in mg: flags[flag] = mg[key]
            if 'cycle' in mg:
                cycle = str(mg['cycle']).strip().lower()
                if cycle not in {"v"}:
                    raise ValueError(f"{source_key}.multigrid.cycle currently supports only 'v'.")
            if 'mode' in mg:
                mode = str(mg['mode']).strip().lower()
                if mode not in {"multiplicative"}:
                    raise ValueError(f"{source_key}.multigrid.mode currently supports only 'multiplicative'.")
            if 'semi_coarsening' in mg:
                sc = mg['semi_coarsening']
                if not isinstance(sc, dict):
                    raise ValueError(f"{source_key}.multigrid.semi_coarsening must be a mapping when provided.")
                if 'i' in sc: flags['-mg_i_semi'] = format_flag_value(sc['i'])
                if 'j' in sc: flags['-mg_j_semi'] = format_flag_value(sc['j'])
                if 'k' in sc: flags['-mg_k_semi'] = format_flag_value(sc['k'])
            if 'level_solvers' in mg:
                level_solvers = mg['level_solvers']
                if not isinstance(level_solvers, dict):
                    raise ValueError(f"{source_key}.multigrid.level_solvers must be a mapping when provided.")
                for level_name, settings in level_solvers.items():
                    if not isinstance(settings, dict):
                        raise ValueError(f"{source_key}.multigrid.level_solvers.{level_name} must be a mapping.")
                    level_num = _poisson_level_number(level_name)
                    for key, value in settings.items():
                        # PETSc prefixes every per-level KSP control with ksp_; emitted
                        # bare, max_it/rtol/atol were left unused and silently ignored.
                        mapped_key = {
                            'method': 'ksp_type', 'preconditioner': 'pc_type',
                            'max_it': 'ksp_max_it', 'rtol': 'ksp_rtol', 'atol': 'ksp_atol',
                        }.get(key, key)
                        # PETSc names the coarsest solver separately from positive levels.
                        if level_num == 0:
                            prefix = "-ps_mg_coarse_"
                            if mapped_key == 'ksp_type':
                                _warn_if_krylov_coarse_solver(value, source_key)
                        else:
                            prefix = f"-ps_mg_levels_{level_num}_"
                        flags[f"{prefix}{mapped_key}"] = format_flag_value(value)
 
    if 'poisson_solver' in solver_cfg and 'pressure_solver' in solver_cfg:
        if solver_cfg['poisson_solver'] != solver_cfg['pressure_solver']:
            raise ValueError(
                "Both 'poisson_solver' and legacy 'pressure_solver' are present with different values. "
                "Use 'poisson_solver' only, or make the legacy alias identical."
            )
    poisson_cfg = solver_cfg.get('poisson_solver', solver_cfg.get('pressure_solver'))
    if poisson_cfg is not None:
        source_key = 'poisson_solver' if 'poisson_solver' in solver_cfg else 'pressure_solver'
        _append_poisson_solver_flags(poisson_cfg, source_key)
    interp_cfg = solver_cfg.get('interpolation', {})
    if isinstance(interp_cfg, dict):
        interp_method_str = interp_cfg.get('method', 'Trilinear')
    else:
        interp_method_str = 'Trilinear'
    interp_code = normalize_interpolation_method(interp_method_str)
    flags['-interpolation_method'] = interp_code
    print(f"  - Interpolation Method: {interp_method_str} (Code: {interp_code})")
 
    if 'petsc_passthrough_options' in solver_cfg:
        passthrough = solver_cfg['petsc_passthrough_options']
        if passthrough is None:
            passthrough = {}
        if not isinstance(passthrough, dict):
            raise ValueError("petsc_passthrough_options must be a mapping when provided.")
        if passthrough:
            for key, value in passthrough.items():
                if str(key).strip() == "-ps_mg_coarse_ksp_type":
                    _warn_if_krylov_coarse_solver(value, "petsc_passthrough_options")
                flags[key] = value if isinstance(value, bool) else format_flag_value(value)
    summary_bits = []
    if '-ps_ksp_type' in flags:
        summary_bits.append(f"method={flags['-ps_ksp_type']}")
    if '-ps_ksp_atol' in flags:
        summary_bits.append(f"atol={flags['-ps_ksp_atol']}")
    if '-ps_ksp_rtol' in flags:
        summary_bits.append(f"rtol={flags['-ps_ksp_rtol']}")
    if '-ps_ksp_max_it' in flags:
        summary_bits.append(f"max_it={flags['-ps_ksp_max_it']}")
    if '-mg_level' in flags:
        summary_bits.append(f"mg_levels={flags['-mg_level']}")
    if summary_bits:
        print(f"  - Poisson Solver: {', '.join(summary_bits)}")
    if selected_solver == "DUALTIME_PICARD_JAMESON_RK":
        dualtime_bits = []
        for label, flag in (
            ("initial_pseudo_cfl", "-pseudo_cfl"),
            ("pseudo_cfl_range", None),
            ("max_pseudo_steps", "-mom_max_pseudo_steps"),
        ):
            if flag and flag in flags:
                dualtime_bits.append(f"{label}={flags[flag]}")
            elif label == "pseudo_cfl_range" and "-min_pseudo_cfl" in flags and "-max_pseudo_cfl" in flags:
                dualtime_bits.append(f"pseudo_cfl_range=[{flags['-min_pseudo_cfl']}, {flags['-max_pseudo_cfl']}]")
        print("  - Momentum Solver: Dual Time Picard Jameson RK" +
              (f" ({', '.join(dualtime_bits)})" if dualtime_bits else ""))
    elif selected_solver == "newton_krylov":
        newton_bits = []
        for label, flag in (
            ("jacobian", "-mom_nk_jacobian_type"),
            ("nonlinear", "-mom_nk_snes_type"),
            ("linear", "-mom_nk_ksp_type"),
            ("preconditioner", "-mom_nk_preconditioner_model"),
        ):
            if flag in flags:
                newton_bits.append(f"{label}={flags[flag]}")
        print("  - Momentum Solver: Newton Krylov" +
              (f" ({', '.join(newton_bits)})" if newton_bits else " (PETSc defaults)"))
    else:
        print("  - Momentum Solver: Explicit RK (no pseudo-time controller)")
    return flags
 

Here is the call graph for this function:

Here is the caller graph for this function:

generate_solver_control_file()

picurv_cli.core.generate_solver_control_file	(		run_dir,
			run_id,
			configs,
			num_procs,
			monitor_files,
			restart_source_dir = None,
			continue_mode = False,
		str	config_dir = None
	)

Generates the main .control file for the C-solver.

Orchestrates the conversion of all YAML configurations (case, solver, monitor) into a single, machine-readable file of command-line flags.

Parameters

[in]	run_dir	Argument passed to generate_solver_control_file().
[in]	run_id	Argument passed to generate_solver_control_file().
[in]	configs	Argument passed to generate_solver_control_file().
[in]	num_procs	Argument passed to generate_solver_control_file().
[in]	monitor_files	Argument passed to generate_solver_control_file().
[in]	restart_source_dir	Argument passed to generate_solver_control_file().
[in]	continue_mode	If True, appends -continue_mode flag for the C solver.
[in]	config_dir	Optional configuration revision directory.

Returns

Value returned by generate_solver_control_file().

Definition at line 16974 of file core.py.

                                 config_dir: str = None):
    """!
    @brief Generates the main .control file for the C-solver.
    @details Orchestrates the conversion of all YAML configurations (case, solver, monitor)
    into a single, machine-readable file of command-line flags.
    @param[in] run_dir Argument passed to `generate_solver_control_file()`.
    @param[in] run_id Argument passed to `generate_solver_control_file()`.
    @param[in] configs Argument passed to `generate_solver_control_file()`.
    @param[in] num_procs Argument passed to `generate_solver_control_file()`.
    @param[in] monitor_files Argument passed to `generate_solver_control_file()`.
    @param[in] restart_source_dir Argument passed to `generate_solver_control_file()`.
    @param[in] continue_mode If True, appends -continue_mode flag for the C solver.
    @param[in] config_dir Optional configuration revision directory.
    @return Value returned by `generate_solver_control_file()`.
    """
    print("[INFO] Generating master solver control file...")
    case_cfg, solver_cfg, monitor_cfg = configs['case'], configs['solver'], configs['monitor']
    source_files = {'Case': configs['case_path'], 'Solver': configs['solver_path'], 'Monitor': configs['monitor_path']}
    
    control_lines = []
    try:
        props, run_ctrl = case_cfg['properties'], case_cfg['run_control']
        scales, fluid, ic = props['scaling'], props['fluid'], props['initial_conditions']
        prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
        fluid_scaling = resolve_fluid_scaling(case_cfg)
        L_ref = fluid_scaling["length_ref"]
        U_ref = fluid_scaling["velocity_ref"]
        rho = fluid_scaling["density"]
        reynolds = fluid_scaling["reynolds"]
        dt_nondim = to_solver_units(run_ctrl['dt_physical'], ("case", "run_control", "dt_physical"), fluid_scaling)
        grid_length_scale = input_reference_scale(("case", "grid", "source_file"), fluid_scaling)
        print(f"  - Reynolds Number (Re) = {reynolds:.4f}")
        print(f"  - Non-Dimensional dt*  = {dt_nondim:.6f}")
        eulerian_source = normalize_eulerian_field_source(
            (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
        )
        start_step = int(run_ctrl.get("start_step", 0) or 0)
        ic_is_authoritative = eulerian_source == "solve" and start_step == 0
        ic_cli = []
        if ic_is_authoritative:
            resolved_ic = resolve_initial_condition_config(
                ic, prepared_blocks, fluid_scaling,
                provider_context={"kinematic_viscosity": fluid_scaling["nondimensional_kinematic_viscosity"]},
            )
            finit_mode_str = resolved_ic["label"]
            finit_code = resolved_ic["finit"]
            ic_params = resolved_ic["cli_params"]
            print(f"  - Initial Condition: {finit_mode_str} (Code: {finit_code})")
            if "ucont_x" in ic_params:
                ic_cli.extend([
                    f"-ucont_x {ic_params['ucont_x']}",
                    f"-ucont_y {ic_params['ucont_y']}",
                    f"-ucont_z {ic_params['ucont_z']}",
                ])
            if "ic_velocity_physical" in ic_params:
                ic_cli.append(f"-ic_velocity_physical {ic_params['ic_velocity_physical']}")
            if "flow_direction" in ic_params:
                ic_cli.append(f"-flow_direction {ic_params['flow_direction']}")
        else:
            source = (f"the run starts from the checkpoint at step {start_step}" if start_step > 0
                      else f"eulerian_field_source={eulerian_source!r} reads stored fields")
            print(f"[INFO] Initial condition not applied: {source}.")
            finit_code = 0
            resolved_ic = None
        control_lines.extend([
            f"-start_step {run_ctrl['start_step']}", f"-totalsteps {run_ctrl['total_steps']}",
            f"-ren {reynolds}", f"-dt {dt_nondim}", f"-finit {finit_code}",
            *ic_cli,
            f"-scaling_L_ref {L_ref}", f"-scaling_U_ref {U_ref}", f"-scaling_rho_ref {rho}"
        ])
    except (KeyError, TypeError, ZeroDivisionError, ValueError) as e:
        print(f"[FATAL] Error processing case.yml: {e}", file=sys.stderr)
        sys.exit(1)
        
    # --- CORRECTED: Add paths for whitelist and profile files ---
    if monitor_files.get("whitelist"):
        control_lines.append(f"-whitelist_config_file {monitor_files['whitelist']}")
    if monitor_files.get("profile"):
        control_lines.append(f"-profile_config_file {monitor_files['profile']}")
    append_passthrough_flags(control_lines, resolve_solution_monitoring_flags(monitor_cfg))
    control_lines.extend(resolve_field_statistics_flags(monitor_cfg, case_cfg))
    profiling_cfg = monitor_files.get("profiling", {})
    control_lines.append(f"-profiling_timestep_mode {profiling_cfg.get('mode', 'off')}")
    control_lines.append(f"-profiling_final_summary {str(bool(profiling_cfg.get('final_summary_enabled', True))).lower()}")
    if profiling_cfg.get("helpers"):
        control_lines.append(f"-profiling_helpers {','.join(profiling_cfg['helpers'])}")
    diagnostics_cfg = resolve_diagnostics_config(monitor_cfg)
    memory_log_cfg = diagnostics_cfg["runtime_memory_log"]
    control_lines.append(f"-runtime_memory_log_enabled {str(bool(memory_log_cfg.get('enabled', True))).lower()}")
 
    walltime_guard_policy = configs.get("walltime_guard_policy")
    if walltime_guard_policy is not None:
        control_lines.extend(
            [
                f"-walltime_guard_enabled {str(bool(walltime_guard_policy.get('enabled', False))).lower()}",
                f"-walltime_guard_warmup_steps {int(walltime_guard_policy.get('warmup_steps', DEFAULT_WALLTIME_GUARD_POLICY['warmup_steps']))}",
                f"-walltime_guard_multiplier {float(walltime_guard_policy.get('multiplier', DEFAULT_WALLTIME_GUARD_POLICY['multiplier']))}",
                f"-walltime_guard_min_seconds {float(walltime_guard_policy.get('min_seconds', DEFAULT_WALLTIME_GUARD_POLICY['min_seconds']))}",
                f"-walltime_guard_estimator_alpha {float(walltime_guard_policy.get('estimator_alpha', DEFAULT_WALLTIME_GUARD_POLICY['estimator_alpha']))}",
            ]
        )
    
    grid_cfg = case_cfg.get('grid', {})
    grid_mode = grid_cfg.get('mode')
    expected_nblk = int(case_cfg.get('models', {}).get('domain', {}).get('blocks', 1))
 
    if grid_mode == 'file':
        print("[INFO] Grid Mode: Using external file...")
        case_file_dir = os.path.dirname(configs['case_path'])
        nondim_grid_path = os.path.join(run_dir, "inputs", "grid", "grid.run")
        if os.path.isfile(nondim_grid_path):
            print(f"[INFO] Reusing locked grid asset: {os.path.relpath(nondim_grid_path)}")
            control_lines.append(f"-grid_file {nondim_grid_path}")
        else:
            source_grid = _resolve_case_relative_path(grid_cfg['source_file'], case_file_dir)
            grid_for_validation = source_grid
            try:
                summary = validate_and_nondimensionalize_picgrid(
                    grid_for_validation, nondim_grid_path, grid_length_scale, expected_nblk=expected_nblk
                )
                print(
                    f"[SUCCESS] Validated and non-dimensionalized grid: {os.path.relpath(nondim_grid_path)} "
                    f"(nblk={summary['nblk']}, total_nodes={summary['total_nodes']})"
                )
                control_lines.append(f"-grid_file {nondim_grid_path}")
            except Exception as e:
                print(f"[FATAL] Failed to process grid file '{source_grid}': {e}", file=sys.stderr)
                sys.exit(1)
    elif grid_mode == 'grid_gen':
        nondim_grid_path = os.path.join(run_dir, "inputs", "grid", "grid.run")
        if os.path.isfile(nondim_grid_path):
            print(f"[INFO] Grid Mode: grid.gen, reusing locked grid asset: {os.path.relpath(nondim_grid_path)}")
            control_lines.append(f"-grid_file {nondim_grid_path}")
        else:
            print("[INFO] Grid Mode: Generating external grid via grid.gen...")
            try:
                # grid.gen already converts ncells_* inputs into node-count PICGRID dims.
                generated_grid = run_grid_generator(
                    configs['case_path'], run_dir, grid_cfg, case_cfg=case_cfg)
                summary = validate_and_nondimensionalize_picgrid(
                    generated_grid, nondim_grid_path, grid_length_scale, expected_nblk=expected_nblk
                )
                print(
                    f"[SUCCESS] grid.gen output validated and non-dimensionalized: {os.path.relpath(nondim_grid_path)} "
                    f"(nblk={summary['nblk']}, total_nodes={summary['total_nodes']})"
                )
                control_lines.append(f"-grid_file {nondim_grid_path}")
            except Exception as e:
                print(f"[FATAL] Grid generation failed: {e}", file=sys.stderr)
                sys.exit(1)
    elif grid_mode == 'programmatic_c':
        print("[INFO] Grid Mode: Programmatic C...")
        grid_settings = translate_programmatic_grid_settings(grid_cfg.get('programmatic_settings', {}))
        control_lines.append("-grid")
        for p_key in GRID_DA_PROCESSOR_KEYS:
            grid_settings.pop(p_key, None)
        for key, value in grid_settings.items(): control_lines.append(f"-{key} {format_flag_value(value)}")
        if resolved_ic and is_generated_ic_provider(resolved_ic) and ic_is_authoritative:
            # The simulator builds this grid itself and never reads a file for it; this
            # bridge exists only so the Python IC generator (a separate process) can see
            # the same node coordinates. generate_picgrid_from_programmatic_settings uses
            # the identical formula as ComputeStretchedCoord in src/grid.c, so the two are
            # guaranteed to agree. Nothing above is changed: -grid_file is never emitted,
            # so the solver still builds its own grid exactly as before.
            nondim_grid_path = os.path.join(run_dir, "inputs", "grid", "grid.run")
            if not os.path.isfile(nondim_grid_path):
                try:
                    generate_picgrid_from_programmatic_settings(
                        grid_cfg.get('programmatic_settings', {}), nondim_grid_path,
                        input_reference_scale(("case", "grid", "programmatic_settings", "xMins"), fluid_scaling),
                    )
                    print(
                        "[SUCCESS] Materialized a bridge grid for the Python initial-condition "
                        f"provider: {os.path.relpath(nondim_grid_path)}"
                    )
                except Exception as e:
                    print(f"[FATAL] Failed to materialize bridge grid for initial-condition generator: {e}",
                          file=sys.stderr)
                    sys.exit(1)
    else:
        raise ValueError(f"Unknown or missing grid mode '{grid_mode}' in case.yml.")
 
    if resolved_ic and (resolved_ic["kind"] == "file" or is_generated_ic_provider(resolved_ic)):
        try:
            staged_ic = stage_initial_condition_file(run_dir, configs["case_path"], resolved_ic)
        except Exception as e:
            print(f"[FATAL] Failed to stage initial condition: {e}", file=sys.stderr)
            sys.exit(1)
        control_lines.extend([
            f"-ic_field {resolved_ic['field_code']}",
            f"-ic_dir {staged_ic['directory']}",
        ])
        print(f"  - Staged initial condition: {os.path.relpath(staged_ic['staged'])}")
 
    try:
        bcs_files = generate_multi_block_bcs(
            run_dir, run_id, case_cfg, source_files, config_dir=config_dir
        )
    except ValueError as e:
        print(f"[FATAL] Invalid boundary_conditions in case.yml: {e}", file=sys.stderr)
        sys.exit(1)
    control_lines.append(f"-bcs_files \"{','.join(bcs_files)}\"")
 
    configs["decomposition_resolved"] = append_grid_da_processor_layout(
        control_lines, grid_cfg, num_procs,
        block_dims=resolve_grid_node_dims(
            case_cfg, configs["case_path"], os.path.join(run_dir, "inputs", "grid", "grid.run")),
        solver_cfg=solver_cfg, any_periodic=case_declares_periodic_axis(case_cfg),
        explicit=configs.get("decomposition"), cluster_cfg=configs.get("cluster_cfg"))
    
    parse_and_add_model_flags(case_cfg, control_lines)
    append_les_diagnostics_flags(resolve_les_diagnostics(case_cfg, configs.get('monitor') or {}), control_lines)
    
    if 'solver_parameters' in case_cfg:
        params = case_cfg['solver_parameters']
        if params:
            for key, value in params.items():
                control_lines.append(f"{key} {format_flag_value(value)}")
 
    try:
        solver_flags = parse_solver_config(solver_cfg, resolve_reference_scales(case_cfg), case_cfg)
    except ValueError as e:
        print(f"[FATAL] Invalid solver.yml settings: {e}", file=sys.stderr)
        sys.exit(1)
    append_passthrough_flags(control_lines, solver_flags)
 
    try:
        solver_monitoring_flags = resolve_solver_monitoring_flags(monitor_cfg)
    except ValueError as e:
        print(f"[FATAL] Invalid monitor.yml solver_monitoring settings: {e}", file=sys.stderr)
        sys.exit(1)
    # Monitors for a solver that does not run would hand PETSc options nothing reads: the
    # momentum ones are Newton-Krylov's, and neither momentum nor Poisson solves when the
    # Eulerian field is loaded or analytical.
    solves_flow = solver_flags.get('-euler_field_source', '"solve"') == '"solve"'
    if not solves_flow:
        inactive = [flag for flag in (*SOLVER_MONITORING_MOMENTUM_FLAG_MAP.values(),
                                      *SOLVER_MONITORING_POISSON_FLAG_MAP.values())
                    if solver_monitoring_flags.pop(flag, None) is not None]
        if inactive:
            print("[INFO] monitor.yml solver_monitoring applies to solved flow only; not passed "
                  "with a loaded or analytical Eulerian field.")
    elif solver_flags.get('-mom_solver_type') != '"newton_krylov"':
        inactive = [flag for flag in SOLVER_MONITORING_MOMENTUM_FLAG_MAP.values()
                    if solver_monitoring_flags.pop(flag, None) is not None]
        if inactive:
            print("[INFO] monitor.yml solver_monitoring.momentum applies to Newton-Krylov only; "
                  "not passed to this momentum solver.")
    append_passthrough_flags(control_lines, solver_monitoring_flags)
    
    io_cfg = monitor_cfg.get('io', {})
    particle_console_output_freq = resolve_particle_console_output_frequency(io_cfg)
    if 'data_output_frequency' in io_cfg: control_lines.append(f"-tio {io_cfg['data_output_frequency']}")
    # The run's first and last states are checkpointed unless turned off; cadence and
    # signal checkpoints do not depend on these.
    for key in ('write_initial_checkpoint', 'write_final_checkpoint'):
        if key in io_cfg:
            control_lines.append(f"-{key} {str(bool(io_cfg[key])).lower()}")
    if particle_console_output_freq is not None:
        control_lines.append(f"-particle_console_output_freq {particle_console_output_freq}")
    statistics_console_output_freq = resolve_statistics_console_output_frequency(io_cfg)
    if statistics_console_output_freq is not None:
        control_lines.append(f"-statistics_console_output_freq {statistics_console_output_freq}")
    if 'particle_log_interval' in io_cfg: control_lines.append(f"-logfreq {io_cfg['particle_log_interval']}")
    traced = resolve_traced_particle_ids(monitor_cfg)
    if traced:
        control_lines.append(f"-picurv_trace_particles {','.join(str(pid) for pid in traced)}")
    if restart_source_dir:
        expected_restart = os.path.abspath(
            os.path.join(run_dir, CANONICAL_RUN_PATHS["restart"])
        )
        if os.path.abspath(restart_source_dir) != expected_restart:
            raise ValueError(
                "Restart data was not materialized in the canonical run input: "
                f"expected {expected_restart}, got {restart_source_dir}."
            )
    if continue_mode:
        control_lines.append("-continue_mode true")
    elif str(configs.get("statistics_state", "reset")).lower() == "carry":
        control_lines.append("-field_statistics_continue true")
 
    # Emitted last, and always: PETSc takes the final occurrence of an option, so a
    # validated directory written here wins over anything earlier in the file. Writing
    # them unconditionally also removes the "omitted default" gap, where an absent flag
    # let an environment variable or PETSc configuration choose the directory instead.
    control_lines.append("")
    control_lines.append("# Canonical run-owned directories are fixed by the workspace contract.")
    control_lines.append(f"-output_dir {CANONICAL_RUN_PATHS['output']}")
    control_lines.append(f"-restart_dir {CANONICAL_RUN_PATHS['restart']}")
    control_lines.append(f"-log_dir {CANONICAL_RUN_PATHS['logs']}")
    control_lines.append(f"-analysis_dir {CANONICAL_RUN_PATHS['metrics']}")
 
    final_content = generate_header(run_id, source_files) + "\n".join(control_lines)
    config_dir = config_dir or os.path.join(run_dir, "config")
    os.makedirs(config_dir, exist_ok=True)
    control_file_path = os.path.join(config_dir, f"{run_id}.control")
    with open(control_file_path, "w") as f: f.write(final_content)
    print(f"[SUCCESS] Generated solver control file: {os.path.relpath(control_file_path)}")
    return os.path.abspath(control_file_path)
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_post_decomposition()

dict picurv_cli.core.resolve_post_decomposition	(	str	run_dir,
		int	num_procs,
			explicit = None,
		"dict | None"	cluster_cfg = None
	)

Resolve the postprocessor's MPI decomposition from the run's staged configuration.

The postprocessor builds the same grid hierarchy as the solve, from the run's active case and solver files and its staged grid, so its decomposition is resolved like the solve's, for its own rank count.

Parameters

[in]	run_dir	Run directory.
[in]	num_procs	MPI ranks of the post-processing stage.
[in]	explicit	(ni, nj, nk) from the command line, or None.
[in]	cluster_cfg	Parsed cluster.yml, or None.

Returns

The resolved decomposition (resolve_decomposition()).

Definition at line 17276 of file core.py.

                               cluster_cfg: "dict | None" = None) -> dict:
    """!
    @brief Resolve the postprocessor's MPI decomposition from the run's staged configuration.
    @details The postprocessor builds the same grid hierarchy as the solve, from the run's
             active case and solver files and its staged grid, so its decomposition is
             resolved like the solve's, for its own rank count.
    @param[in] run_dir Run directory.
    @param[in] num_procs MPI ranks of the post-processing stage.
    @param[in] explicit (ni, nj, nk) from the command line, or None.
    @param[in] cluster_cfg Parsed cluster.yml, or None.
    @return The resolved decomposition (resolve_decomposition()).
    """
    active = load_active_run_configuration(run_dir)
    case_cfg = read_yaml_file(active["case"]) if active.get("case") and os.path.isfile(active["case"]) else {}
    solver_cfg = read_yaml_file(active["solver"]) if active.get("solver") and os.path.isfile(active["solver"]) else {}
    block_dims = resolve_grid_node_dims(case_cfg, active.get("case") or os.path.join(run_dir, "config", "case.yml"),
                                        os.path.join(run_dir, "inputs", "grid", "grid.run"))
    return resolve_decomposition(num_procs, case_cfg.get("grid") or {}, block_dims, solver_cfg,
                                 case_declares_periodic_axis(case_cfg), explicit, cluster_cfg)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

generate_post_recipe_file()

str picurv_cli.core.generate_post_recipe_file	(	str	run_dir,
		str	run_id,
		dict	post_cfg,
		dict	source_files,
			monitor_cfg = None,
		"dict | None"	decomposition = None
	)

Generates a key=value config file (post.run) for the C post-processor.

Translates the structured post-processing YAML into the specific flat key-value format required by the C executable, including complex, semicolon-separated pipeline strings.

Parameters

[in]	run_dir	The path to the main run directory.
[in]	run_id	The unique identifier for the run.
[in]	post_cfg	The parsed post-profile YAML configuration dictionary.
[in]	source_files	A dictionary of source files for the header.
[in]	monitor_cfg	Optional parsed monitor YAML configuration dictionary.
[in]	decomposition	The postprocessor's resolved decomposition (resolve_post_decomposition()), or None to let PETSc decide.

Returns

The absolute path to the generated post.run recipe file.

Definition at line 17298 of file core.py.

                              decomposition: "dict | None" = None) -> str:
    """!
    @brief Generates a key=value config file (post.run) for the C post-processor.
    @details Translates the structured post-processing YAML into the specific flat
             key-value format required by the C executable, including complex,
             semicolon-separated pipeline strings.
    @param[in] run_dir The path to the main run directory.
    @param[in] run_id The unique identifier for the run.
    @param[in] post_cfg The parsed post-profile YAML configuration dictionary.
    @param[in] source_files A dictionary of source files for the header.
    @param[in] monitor_cfg Optional parsed monitor YAML configuration dictionary.
    @param[in] decomposition The postprocessor's resolved decomposition (resolve_post_decomposition()),
               or None to let PETSc decide.
    @return The absolute path to the generated post.run recipe file.
    """
    print("[INFO] Generating post-processor recipe file (post.run)...")
    if not isinstance((post_cfg or {}).get("_picurv_paths"), dict):
        post_cfg, _ = apply_canonical_post_paths(post_cfg, run_dir)
    config_dir = get_post_recipe_root(run_dir, post_cfg)
    os.makedirs(config_dir, exist_ok=True)
    post_recipe_path = os.path.join(config_dir, "post.run")
 
    lines = [generate_header(run_id, source_files)]
    c_config = build_post_recipe_config(post_cfg, monitor_cfg)
 
    for key, value in c_config.items():
        if value is not None and str(value) != "":
            lines.append(f"{key} = {value}")
    # The steps themselves are decided when the job starts (prepare_post_job()).
    lines.append(f"step_list_file = {get_post_step_list_path(run_dir, post_cfg)}")
    if decomposition and decomposition.get("layout") and decomposition["layout"] != (1, 1, 1):
        lines.append("da_processors = " + " ".join(str(v) for v in decomposition["layout"]))
 
    with open(post_recipe_path, "w") as f:
        f.write("\n".join(lines))
    print(f"[SUCCESS] Generated post-processor recipe: {os.path.relpath(post_recipe_path)}")
    return os.path.abspath(post_recipe_path)
 

Here is the call graph for this function:

Here is the caller graph for this function:

execute_command()

picurv_cli.core.execute_command	(	list	command,
		str	run_dir,
		str	log_filename,
		dict	monitor_cfg = None
	)

Executes a command, streaming its output to the console and a log file.

... If None, the process inherits the parent's environment directly.

Parameters

[in]	command	Argument passed to execute_command().
[in]	run_dir	Argument passed to execute_command().
[in]	log_filename	Argument passed to execute_command().
[in]	monitor_cfg	Argument passed to execute_command().

Definition at line 17337 of file core.py.

def execute_command(command: list, run_dir: str, log_filename: str, monitor_cfg: dict = None):
    """!
    @brief Executes a command, streaming its output to the console and a log file.
    @details ...
    If None, the process inherits the parent's environment directly.
    @param[in] command Argument passed to `execute_command()`.
    @param[in] run_dir Argument passed to `execute_command()`.
    @param[in] log_filename Argument passed to `execute_command()`.
    @param[in] monitor_cfg Argument passed to `execute_command()`.
    """
    log_path = resolve_command_log_path(run_dir, log_filename)
    os.makedirs(os.path.dirname(log_path), exist_ok=True)
 
    print(f"[INFO] Launching Command...\n  > {format_command_for_display(command)}")
    print(f"       Log file: {os.path.relpath(log_path)}")
    print("-" * 60)
 
    # --- Environment Handling ---
    popen_kwargs = {
        "stdout": subprocess.PIPE, "stderr": subprocess.STDOUT,
        "cwd": run_dir, "bufsize": 1, "universal_newlines": True,
        "encoding": 'utf-8', "errors": 'replace'
    }
 
    run_env = os.environ.copy()
    if monitor_cfg:
        verbosity = monitor_cfg.get('logging', {}).get('verbosity', 'INFO').upper()
        run_env['LOG_LEVEL'] = verbosity
        print(f"[INFO] Log level: {verbosity}")
    # The launched executable's own PETSc first, as job scripts do (petsc_library_path_lines()).
    for token in command:
        library_dir = executable_petsc_library_dir(str(token)) if os.path.isabs(str(token)) else None
        if library_dir:
            run_env["LD_LIBRARY_PATH"] = library_dir + (":" + run_env["LD_LIBRARY_PATH"]
                                                        if run_env.get("LD_LIBRARY_PATH") else "")
            break
    popen_kwargs['env'] = run_env
 
    print("-" * 60)
    try:
        # Pass the constructed keyword arguments dictionary to Popen
        process = subprocess.Popen(command, **popen_kwargs)
 
        with open(log_path, "w") as log_file:
            for line in process.stdout:
                sys.stdout.write(line)
                log_file.write(line)
        process.wait()
        return_code = process.returncode
        print("-" * 60)
        if return_code == 0:
            print(f"[SUCCESS] Execution finished successfully.")
        else:
            print(f"[FATAL] Execution failed with exit code {return_code}. Check log: {os.path.relpath(log_path)}", file=sys.stderr)
            sys.exit(return_code)
    except FileNotFoundError:
        print(f"[FATAL] Command not found or is not executable: '{command[0]}'", file=sys.stderr)
        print("        Please check that the path is correct and the file has execute permissions.", file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        print(f"[FATAL] An unexpected error occurred during execution: {e}", file=sys.stderr)
        sys.exit(1)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

format_command_for_display()

str picurv_cli.core.format_command_for_display

(

list

command

)

Render a shell-safe command string for console and log output.

Parameters

[in]

command

Argument passed to format_command_for_display().

Returns

Value returned by format_command_for_display().

Definition at line 17401 of file core.py.

def format_command_for_display(command: list) -> str:
    """!
    @brief Render a shell-safe command string for console and log output.
    @param[in] command Argument passed to `format_command_for_display()`.
    @return Value returned by `format_command_for_display()`.
    """
    return " ".join(shlex.quote(str(part)) for part in command)
 
 

Here is the caller graph for this function:

resolve_command_log_path()

str picurv_cli.core.resolve_command_log_path	(	str	run_dir,
		str	log_filename
	)

Resolve a command log filename relative to the run directory.

Parameters

[in]	run_dir	Argument passed to resolve_command_log_path().
[in]	log_filename	Argument passed to resolve_command_log_path().

Returns

Value returned by resolve_command_log_path().

Definition at line 17410 of file core.py.

def resolve_command_log_path(run_dir: str, log_filename: str) -> str:
    """!
    @brief Resolve a command log filename relative to the run directory.
    @param[in] run_dir Argument passed to `resolve_command_log_path()`.
    @param[in] log_filename Argument passed to `resolve_command_log_path()`.
    @return Value returned by `resolve_command_log_path()`.
    """
    if os.path.dirname(log_filename):
        return os.path.join(run_dir, log_filename)
    return os.path.join(run_dir, "logs", log_filename)
 
 

Here is the caller graph for this function:

_run_captured_command()

subprocess.CompletedProcess picurv_cli.core._run_captured_command ( list  command, str  run_dir  )

protected

Run a command and capture combined stdout/stderr details for later inspection.

Parameters

[in]	command	Argument passed to _run_captured_command().
[in]	run_dir	Argument passed to _run_captured_command().

Returns

Value returned by _run_captured_command().

Definition at line 17449 of file core.py.

def _run_captured_command(command: list, run_dir: str) -> subprocess.CompletedProcess:
    """!
    @brief Run a command and capture combined stdout/stderr details for later inspection.
    @param[in] command Argument passed to `_run_captured_command()`.
    @param[in] run_dir Argument passed to `_run_captured_command()`.
    @return Value returned by `_run_captured_command()`.
    """
    try:
        return subprocess.run(
            command,
            cwd=run_dir,
            text=True,
            capture_output=True,
            check=False,
            encoding="utf-8",
            errors="replace",
        )
    except FileNotFoundError as exc:
        raise CommandExecutionError(command, 1, f"Command not found or is not executable: '{command[0]}'") from exc
 
 

Here is the caller graph for this function:

_require_successful_command()

picurv_cli.core._require_successful_command ( list  command, subprocess.CompletedProcess  result  )

protected

Raise CommandExecutionError when a captured command failed.

Parameters

[in]	command	Argument passed to _require_successful_command().
[in]	result	Argument passed to _require_successful_command().

Definition at line 17470 of file core.py.

def _require_successful_command(command: list, result: subprocess.CompletedProcess):
    """!
    @brief Raise `CommandExecutionError` when a captured command failed.
    @param[in] command Argument passed to `_require_successful_command()`.
    @param[in] result Argument passed to `_require_successful_command()`.
    """
    if result.returncode == 0:
        return
    details = (result.stderr or result.stdout).strip()
    raise CommandExecutionError(command, result.returncode, details or None)
 
 

Here is the caller graph for this function:

_capture_command_stdout()

str picurv_cli.core._capture_command_stdout ( list  command, str  run_dir  )

protected

Run a command, require success, and return stripped stdout text.

Parameters

[in]	command	Argument passed to _capture_command_stdout().
[in]	run_dir	Argument passed to _capture_command_stdout().

Returns

Value returned by _capture_command_stdout().

Definition at line 17482 of file core.py.

def _capture_command_stdout(command: list, run_dir: str) -> str:
    """!
    @brief Run a command, require success, and return stripped stdout text.
    @param[in] command Argument passed to `_capture_command_stdout()`.
    @param[in] run_dir Argument passed to `_capture_command_stdout()`.
    @return Value returned by `_capture_command_stdout()`.
    """
    result = _run_captured_command(command, run_dir)
    _require_successful_command(command, result)
    return result.stdout.strip()
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_stream_command_to_console_and_log()

picurv_cli.core._stream_command_to_console_and_log ( list  command, str  run_dir,   log_file  )

protected

Stream command output to stdout and an already-open log file.

Parameters

[in]	command	Argument passed to _stream_command_to_console_and_log().
[in]	run_dir	Argument passed to _stream_command_to_console_and_log().
[in]	log_file	Argument passed to _stream_command_to_console_and_log().

Definition at line 17494 of file core.py.

def _stream_command_to_console_and_log(command: list, run_dir: str, log_file):
    """!
    @brief Stream command output to stdout and an already-open log file.
    @param[in] command Argument passed to `_stream_command_to_console_and_log()`.
    @param[in] run_dir Argument passed to `_stream_command_to_console_and_log()`.
    @param[in] log_file Argument passed to `_stream_command_to_console_and_log()`.
    """
    display = format_command_for_display(command)
    print(f"[INFO] Running: {display}")
    log_file.write(f"$ {display}\n")
    log_file.flush()
 
    popen_kwargs = {
        "stdout": subprocess.PIPE,
        "stderr": subprocess.STDOUT,
        "cwd": run_dir,
        "bufsize": 1,
        "universal_newlines": True,
        "encoding": "utf-8",
        "errors": "replace",
    }
 
    try:
        process = subprocess.Popen(command, **popen_kwargs)
    except FileNotFoundError as exc:
        raise CommandExecutionError(command, 1, f"Command not found or is not executable: '{command[0]}'") from exc
 
    with process:
        for line in process.stdout:
            sys.stdout.write(line)
            log_file.write(line)
    return_code = process.wait()
    log_file.write("\n")
    log_file.flush()
    if return_code != 0:
        raise CommandExecutionError(command, return_code)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_get_git_head_state()

dict picurv_cli.core._get_git_head_state ( str  run_dir )

protected

Capture the current git HEAD branch name and commit hash.

Parameters

[in]

run_dir

Argument passed to _get_git_head_state().

Returns

Value returned by _get_git_head_state().

Definition at line 17532 of file core.py.

def _get_git_head_state(run_dir: str) -> dict:
    """!
    @brief Capture the current git HEAD branch name and commit hash.
    @param[in] run_dir Argument passed to `_get_git_head_state()`.
    @return Value returned by `_get_git_head_state()`.
    """
    head_commit = _capture_command_stdout(["git", "rev-parse", "--verify", "HEAD"], run_dir)
    branch_result = _run_captured_command(["git", "symbolic-ref", "--quiet", "--short", "HEAD"], run_dir)
    branch_name = branch_result.stdout.strip() if branch_result.returncode == 0 else None
    return {"branch": branch_name, "commit": head_commit}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_get_local_branches_with_upstreams()

"list[tuple[str, str | None]]" picurv_cli.core._get_local_branches_with_upstreams ( str  run_dir )

protected

Return local branch names plus their configured upstreams.

Parameters

[in]

run_dir

Argument passed to _get_local_branches_with_upstreams().

Returns

Value returned by _get_local_branches_with_upstreams().

Definition at line 17544 of file core.py.

def _get_local_branches_with_upstreams(run_dir: str) -> "list[tuple[str, str | None]]":
    """!
    @brief Return local branch names plus their configured upstreams.
    @param[in] run_dir Argument passed to `_get_local_branches_with_upstreams()`.
    @return Value returned by `_get_local_branches_with_upstreams()`.
    """
    output = _capture_command_stdout(
        ["git", "for-each-ref", "--sort=refname", "--format=%(refname:short)\t%(upstream:short)", "refs/heads"],
        run_dir,
    )
    branches = []
    for line in output.splitlines():
        if not line.strip():
            continue
        branch_name, _, upstream_name = line.partition("\t")
        branches.append((branch_name, upstream_name or None))
    return branches
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_working_tree_has_tracked_changes()

bool picurv_cli.core._working_tree_has_tracked_changes ( str  run_dir )

protected

Return True when the repository has staged or unstaged tracked changes.

Parameters

[in]

run_dir

Argument passed to _working_tree_has_tracked_changes().

Returns

Value returned by _working_tree_has_tracked_changes().

Definition at line 17563 of file core.py.

def _working_tree_has_tracked_changes(run_dir: str) -> bool:
    """!
    @brief Return `True` when the repository has staged or unstaged tracked changes.
    @param[in] run_dir Argument passed to `_working_tree_has_tracked_changes()`.
    @return Value returned by `_working_tree_has_tracked_changes()`.
    """
    command = ["git", "status", "--porcelain", "--untracked-files=no"]
    result = _run_captured_command(command, run_dir)
    _require_successful_command(command, result)
    return bool(result.stdout.strip())
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_attempt_pull_cleanup()

picurv_cli.core._attempt_pull_cleanup ( str  run_dir, bool  rebase,   log_file  )

protected

Best-effort cleanup after a failed git pull so the original branch can be restored.

Parameters

[in]	run_dir	Argument passed to _attempt_pull_cleanup().
[in]	rebase	Argument passed to _attempt_pull_cleanup().
[in]	log_file	Argument passed to _attempt_pull_cleanup().

Definition at line 17575 of file core.py.

def _attempt_pull_cleanup(run_dir: str, rebase: bool, log_file):
    """!
    @brief Best-effort cleanup after a failed `git pull` so the original branch can be restored.
    @param[in] run_dir Argument passed to `_attempt_pull_cleanup()`.
    @param[in] rebase Argument passed to `_attempt_pull_cleanup()`.
    @param[in] log_file Argument passed to `_attempt_pull_cleanup()`.
    """
    cleanup_command = ["git", "rebase", "--abort"] if rebase else ["git", "merge", "--abort"]
    result = _run_captured_command(cleanup_command, run_dir)
    if result.returncode == 0:
        print(f"[INFO] Cleaned up the interrupted {'rebase' if rebase else 'merge'} state.")
        log_file.write(f"$ {format_command_for_display(cleanup_command)}\n")
        if result.stdout:
            sys.stdout.write(result.stdout)
            log_file.write(result.stdout)
        if result.stderr:
            sys.stderr.write(result.stderr)
            log_file.write(result.stderr)
        log_file.write("\n")
        log_file.flush()
        return
 
    details = (result.stderr or result.stdout).strip()
    if details:
        message = (
            f"[WARNING] Could not clean up a failed {'rebase' if rebase else 'merge'} automatically: {details}"
        )
        print(message, file=sys.stderr)
        log_file.write(message + "\n")
        log_file.flush()
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_restore_git_head()

picurv_cli.core._restore_git_head ( str  run_dir, dict  original_head,   log_file  )

protected

Restore the repository back to the branch or detached commit it started on.

Parameters

[in]	run_dir	Argument passed to _restore_git_head().
[in]	original_head	Argument passed to _restore_git_head().
[in]	log_file	Argument passed to _restore_git_head().

Definition at line 17607 of file core.py.

def _restore_git_head(run_dir: str, original_head: dict, log_file):
    """!
    @brief Restore the repository back to the branch or detached commit it started on.
    @param[in] run_dir Argument passed to `_restore_git_head()`.
    @param[in] original_head Argument passed to `_restore_git_head()`.
    @param[in] log_file Argument passed to `_restore_git_head()`.
    """
    current_state = _get_git_head_state(run_dir)
    if original_head["branch"]:
        if current_state["branch"] == original_head["branch"]:
            return
        _stream_command_to_console_and_log(["git", "checkout", original_head["branch"]], run_dir, log_file)
        return
 
    if current_state["branch"] is None and current_state["commit"] == original_head["commit"]:
        return
    _stream_command_to_console_and_log(["git", "checkout", "--detach", original_head["commit"]], run_dir, log_file)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_refuse_detached_source_checkout()

None picurv_cli.core._refuse_detached_source_checkout ( str  source_project_root, str  action  )

protected

Refuse a branch pull when the source checkout is pinned to a detached commit.

versions install and versions activate leave the checkout detached on the version they built. A branch pull there either fails inside Git or, in the multi-branch path, updates the branches and then restores the detached commit, so the active code never changes while the command reports success. A directory that is not a Git checkout is left for the Git command to report.

Parameters

[in]	source_project_root	PICurv source checkout to inspect.
[in]	action	User-facing command name.

Exceptions

ValueError

when HEAD is detached.

Definition at line 17626 of file core.py.

def _refuse_detached_source_checkout(source_project_root: str, action: str) -> None:
    """!
    @brief Refuse a branch pull when the source checkout is pinned to a detached commit.
 
    @details `versions install` and `versions activate` leave the checkout detached on
             the version they built. A branch pull there either fails inside Git or, in
             the multi-branch path, updates the branches and then restores the detached
             commit, so the active code never changes while the command reports success.
             A directory that is not a Git checkout is left for the Git command to report.
    @param[in] source_project_root PICurv source checkout to inspect.
    @param[in] action User-facing command name.
    @throws ValueError when HEAD is detached.
    """
    branch = _run_captured_command(["git", "symbolic-ref", "--quiet", "--short", "HEAD"], source_project_root)
    if branch.returncode == 0:
        return
    commit = _run_captured_command(["git", "rev-parse", "--short=12", "--verify", "HEAD"], source_project_root)
    if commit.returncode != 0:
        return
    raise ValueError(
        f"{action}: the source checkout at {source_project_root} is pinned to commit "
        f"{commit.stdout.strip()}, not a branch, so a branch pull would not change the code "
        "that runs.\n"
        "        Install a newer version with 'picurv versions install <tag-or-commit>', "
        "or check out a branch (for example 'git checkout main') to follow it."
    )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

pull_all_source_branches()

picurv_cli.core.pull_all_source_branches	(	str	run_dir,
		str	log_filename,
		bool	rebase = True
	)

Refresh every local tracking branch in the source repository, then restore the starting branch.

Parameters

[in]	run_dir	Argument passed to pull_all_source_branches().
[in]	log_filename	Argument passed to pull_all_source_branches().
[in]	rebase	Argument passed to pull_all_source_branches().

Definition at line 17654 of file core.py.

def pull_all_source_branches(run_dir: str, log_filename: str, rebase: bool = True):
    """!
    @brief Refresh every local tracking branch in the source repository, then restore the starting branch.
    @param[in] run_dir Argument passed to `pull_all_source_branches()`.
    @param[in] log_filename Argument passed to `pull_all_source_branches()`.
    @param[in] rebase Argument passed to `pull_all_source_branches()`.
    """
    log_path = resolve_command_log_path(run_dir, log_filename)
    os.makedirs(os.path.dirname(log_path), exist_ok=True)
 
    print("\n" + "="*23 + " PULL SOURCE STAGE " + "="*22)
    print("[INFO] Refreshing all local source branches that track an upstream.")
    print(f"       Log file: {os.path.relpath(log_path)}")
    print("-" * 60)
 
    try:
        original_head = _get_git_head_state(run_dir)
        if _working_tree_has_tracked_changes(run_dir):
            raise RuntimeError(
                "Multi-branch pull requires a clean tracked working tree in the source repository. "
                "Commit or stash those changes first, or rerun with --current-branch-only."
            )
        branches = _get_local_branches_with_upstreams(run_dir)
    except (CommandExecutionError, RuntimeError) as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(getattr(exc, "returncode", 1))
 
    if not branches:
        print("[FATAL] No local branches were found in the source repository.", file=sys.stderr)
        sys.exit(1)
 
    if original_head["branch"]:
        branches = [item for item in branches if item[0] != original_head["branch"]] + [
            item for item in branches if item[0] == original_head["branch"]
        ]
 
    skipped_branches = []
    current_operation = None
    pull_error = None
    restore_error = None
 
    with open(log_path, "w", encoding="utf-8") as log_file:
        log_file.write(f"# PICurv pull-source all-branch sync\n")
        log_file.write(f"# repository: {os.path.abspath(run_dir)}\n")
        log_file.write(f"# started: {datetime.now().isoformat()}\n")
        log_file.write(
            f"# original head: {original_head['branch'] if original_head['branch'] else original_head['commit']}\n\n"
        )
 
        try:
            for branch_name, upstream_name in branches:
                if not upstream_name:
                    warning = f"[WARNING] Skipping branch '{branch_name}' because it has no configured upstream."
                    print(warning, file=sys.stderr)
                    log_file.write(warning + "\n")
                    skipped_branches.append(branch_name)
                    continue
 
                print(f"[INFO] Refreshing branch '{branch_name}' from '{upstream_name}'.")
                log_file.write(f"[INFO] Refreshing branch '{branch_name}' from '{upstream_name}'.\n")
 
                current_operation = f"checkout:{branch_name}"
                _stream_command_to_console_and_log(["git", "checkout", branch_name], run_dir, log_file)
 
                pull_command = ["git", "pull"]
                if rebase:
                    pull_command.append("--rebase")
                current_operation = f"pull:{branch_name}"
                _stream_command_to_console_and_log(pull_command, run_dir, log_file)
                current_operation = None
        except CommandExecutionError as exc:
            pull_error = exc
            if current_operation and current_operation.startswith("pull:"):
                _attempt_pull_cleanup(run_dir, rebase, log_file)
        finally:
            try:
                _restore_git_head(run_dir, original_head, log_file)
            except CommandExecutionError as exc:
                restore_error = exc
 
    print("-" * 60)
    if pull_error:
        if restore_error:
            print(
                f"[FATAL] Multi-branch pull failed and the original branch could not be restored. "
                f"Check log: {os.path.relpath(log_path)}",
                file=sys.stderr,
            )
            sys.exit(restore_error.returncode)
        print(
            f"[FATAL] Multi-branch pull failed. Original branch restored. "
            f"Check log: {os.path.relpath(log_path)}",
            file=sys.stderr,
        )
        sys.exit(pull_error.returncode)
 
    if restore_error:
        print(
            f"[FATAL] Branch updates completed, but the original branch could not be restored. "
            f"Check log: {os.path.relpath(log_path)}",
            file=sys.stderr,
        )
        sys.exit(restore_error.returncode)
 
    if skipped_branches:
        print(f"[WARNING] Skipped branches with no upstream: {', '.join(skipped_branches)}", file=sys.stderr)
    print("[SUCCESS] All local tracking branches are up to date.")
 

Here is the call graph for this function:

Here is the caller graph for this function:

auto_identify_run_inputs()

picurv_cli.core.auto_identify_run_inputs

(

str

config_dir

)

Auto-detect case.yml, monitor.yml, and *.control in a run config directory.

Parameters

[in]

config_dir

Argument passed to auto_identify_run_inputs().

Returns

Value returned by auto_identify_run_inputs().

Definition at line 17762 of file core.py.

def auto_identify_run_inputs(config_dir: str):
    """!
    @brief Auto-detect case.yml, monitor.yml, and *.control in a run config directory.
    @param[in] config_dir Argument passed to `auto_identify_run_inputs()`.
    @return Value returned by `auto_identify_run_inputs()`.
    """
    run_dir = os.path.dirname(os.path.abspath(config_dir))
    active = load_active_run_configuration(run_dir)
    if active:
        case_path = active.get("case")
        monitor_path = active.get("monitor")
        solver_control_path = active.get("control")
        if all(path and os.path.isfile(path) for path in (case_path, monitor_path, solver_control_path)):
            return case_path, monitor_path, solver_control_path
    all_yml_files = glob.glob(os.path.join(config_dir, "*.yml"))
    case_path, monitor_path = None, None
    for f_path in all_yml_files:
        try:
            content = read_yaml_file(f_path)
            if not isinstance(content, dict):
                continue
            if 'models' in content and 'boundary_conditions' in content:
                case_path = f_path
            elif 'io' in content and 'logging' in content:
                monitor_path = f_path
        except Exception as e:
            print(f"[WARNING] Could not parse or inspect '{f_path}': {e}", file=sys.stderr)
    try:
        solver_control_path = glob.glob(os.path.join(config_dir, "*.control"))[0]
    except IndexError:
        solver_control_path = None
    return case_path, monitor_path, solver_control_path
 

Here is the call graph for this function:

Here is the caller graph for this function:

resolve_post_source_directory()

str picurv_cli.core.resolve_post_source_directory	(	str	run_dir,
		dict	monitor_cfg,
		dict	post_cfg,
		bool	strict = True
	)

Resolve post source directory token and optionally enforce existence.

Parameters

[in]	run_dir	Argument passed to resolve_post_source_directory().
[in]	monitor_cfg	Argument passed to resolve_post_source_directory().
[in]	post_cfg	Argument passed to resolve_post_source_directory().
[in]	strict	Argument passed to resolve_post_source_directory().

Returns

Value returned by resolve_post_source_directory().

Definition at line 17795 of file core.py.

def resolve_post_source_directory(run_dir: str, monitor_cfg: dict, post_cfg: dict, strict: bool = True) -> str:
    """!
    @brief Resolve post source directory token and optionally enforce existence.
    @param[in] run_dir Argument passed to `resolve_post_source_directory()`.
    @param[in] monitor_cfg Argument passed to `resolve_post_source_directory()`.
    @param[in] post_cfg Argument passed to `resolve_post_source_directory()`.
    @param[in] strict Argument passed to `resolve_post_source_directory()`.
    @return Value returned by `resolve_post_source_directory()`.
    """
    solver_output_dir_abs = os.path.join(run_dir, CANONICAL_RUN_PATHS["output"])
    source_dir_template = get_post_source_directory_template(post_cfg)
    if source_dir_template == '<solver_output_dir>':
        resolved_source_dir = solver_output_dir_abs
        print(f"[INFO] Post-processor source data: {os.path.relpath(resolved_source_dir)}")
    else:
        resolved_source_dir = os.path.abspath(os.path.join(run_dir, source_dir_template))
        print(f"[INFO] Post-processor source data (user-defined): {os.path.relpath(resolved_source_dir)}")
 
    if strict and (not os.path.isdir(resolved_source_dir) or not os.listdir(resolved_source_dir)):
        print(
            f"[FATAL] Source data directory for post-processing not found or empty: {os.path.relpath(resolved_source_dir)}",
            file=sys.stderr
        )
        sys.exit(1)
    if not strict and (not os.path.isdir(resolved_source_dir) or not os.listdir(resolved_source_dir)):
        print("[WARNING] Source data directory is not available yet; keeping deferred path for scheduled post job.")
    return resolved_source_dir
 

Here is the call graph for this function:

Here is the caller graph for this function:

render_slurm_array_stage_script()

picurv_cli.core.render_slurm_array_stage_script	(	str	script_path,
		str	job_name,
		dict	cluster_cfg,
		str	array_spec,
		str	case_index_tsv,
		str	stage,
		str	solver_exe,
		str	post_exe,
		str	stdout_path,
		str	stderr_path,
		"str | None"	expected_version_line = None
	)

Render array script that maps SLURM_ARRAY_TASK_ID to per-case run artifacts.

Parameters

[in]	script_path	Argument passed to render_slurm_array_stage_script().
[in]	job_name	Argument passed to render_slurm_array_stage_script().
[in]	cluster_cfg	Argument passed to render_slurm_array_stage_script().
[in]	array_spec	Argument passed to render_slurm_array_stage_script().
[in]	case_index_tsv	Argument passed to render_slurm_array_stage_script().
[in]	stage	Argument passed to render_slurm_array_stage_script().
[in]	solver_exe	Argument passed to render_slurm_array_stage_script().
[in]	post_exe	Argument passed to render_slurm_array_stage_script().
[in]	stdout_path	Argument passed to render_slurm_array_stage_script().
[in]	stderr_path	Argument passed to render_slurm_array_stage_script().
[in]	expected_version_line	--version output the stage's executable reported at staging; checked before launch in every task.

Returns

Value returned by render_slurm_array_stage_script().

Definition at line 17823 of file core.py.

):
    """!
    @brief Render array script that maps SLURM_ARRAY_TASK_ID to per-case run artifacts.
    @param[in] script_path Argument passed to `render_slurm_array_stage_script()`.
    @param[in] job_name Argument passed to `render_slurm_array_stage_script()`.
    @param[in] cluster_cfg Argument passed to `render_slurm_array_stage_script()`.
    @param[in] array_spec Argument passed to `render_slurm_array_stage_script()`.
    @param[in] case_index_tsv Argument passed to `render_slurm_array_stage_script()`.
    @param[in] stage Argument passed to `render_slurm_array_stage_script()`.
    @param[in] solver_exe Argument passed to `render_slurm_array_stage_script()`.
    @param[in] post_exe Argument passed to `render_slurm_array_stage_script()`.
    @param[in] stdout_path Argument passed to `render_slurm_array_stage_script()`.
    @param[in] stderr_path Argument passed to `render_slurm_array_stage_script()`.
    @param[in] expected_version_line `--version` output the stage's executable reported
                                     at staging; checked before launch in every task.
    @return Value returned by `render_slurm_array_stage_script()`.
    """
    effective_cluster_cfg = cluster_cfg
    resources = effective_cluster_cfg.get("resources", {})
    notifications = effective_cluster_cfg.get("notifications", {}) or {}
    execution = effective_cluster_cfg.get("execution", {}) or {}
    module_setup = execution.get("module_setup", []) or []
    extra_sbatch = execution.get("extra_sbatch")
 
    lines = [
        "#!/bin/bash",
        f"#SBATCH --job-name={job_name}",
        f"#SBATCH --nodes={resources['nodes']}",
        f"#SBATCH --ntasks-per-node={resources['ntasks_per_node']}",
        f"#SBATCH --mem={resources['mem']}",
        f"#SBATCH --time={resources['time']}",
        f"#SBATCH --output={stdout_path}",
        f"#SBATCH --error={stderr_path}",
        f"#SBATCH --account={resources['account']}",
        f"#SBATCH --array={array_spec}",
    ]
    partition = resources.get("partition")
    if partition:
        lines.append(f"#SBATCH --partition={partition}")
    mail_user = notifications.get("mail_user")
    mail_type = notifications.get("mail_type")
    if mail_user:
        lines.append(f"#SBATCH --mail-user={mail_user}")
    if mail_type:
        lines.append(f"#SBATCH --mail-type={mail_type}")
    if isinstance(extra_sbatch, dict):
        for key, value in extra_sbatch.items():
            flag = str(key)
            if not flag.startswith("--"):
                flag = f"--{flag}"
            if isinstance(value, bool):
                if value:
                    lines.append(f"#SBATCH {flag}")
            elif value is not None:
                lines.append(f"#SBATCH {flag}={value}")
    elif isinstance(extra_sbatch, list):
        for token in extra_sbatch:
            lines.append(f"#SBATCH {token}")
 
    lines.extend([
        "",
        "set -euo pipefail",
        "",
        f'CASE_INDEX_FILE={shlex.quote(case_index_tsv)}',
        'LINE=$(sed -n "$((SLURM_ARRAY_TASK_ID + 1))p" "$CASE_INDEX_FILE")',
        'if [ -z "$LINE" ]; then',
        '  echo "No case entry for array index ${SLURM_ARRAY_TASK_ID}" >&2',
        '  exit 1',
        "fi",
        "IFS=$'\\t' read -r CASE_INDEX CASE_ID RUN_DIR CONTROL_FILE POST_RECIPE_FILE LOG_LEVEL POST_PREFIX SOLVE_DIAGNOSTIC_ARGS POST_DIAGNOSTIC_ARGS <<< \"$LINE\"",
        'cd "$RUN_DIR"',
        'echo "[$(date)] Starting case ${CASE_ID} (array index ${SLURM_ARRAY_TASK_ID})"',
    ])
 
    if stage == "solve":
        walltime_guard_exports = build_walltime_guard_exports(effective_cluster_cfg)
        for key, value in walltime_guard_exports.items():
            lines.append(f"export {key}={value}")
 
    lines.append('export LOG_LEVEL="${LOG_LEVEL}"')
 
    for setup_line in module_setup:
        lines.append(str(setup_line))
 
    stage_exe = solver_exe if stage == "solve" else post_exe
    # A pinned `$RUN_DIR/...` copy is the installation's binary, so its PETSc is the installation's.
    lines.extend(petsc_library_path_lines(executable_petsc_library_dir(
        stage_exe if not stage_exe.startswith("$") else
        resolve_runtime_executable("simulator" if stage == "solve" else "postprocessor"))))
    lines.extend(executable_identity_check_lines(
        stage_exe, expected_version_line, pinned=stage_exe.startswith("$RUN_DIR/")
    ))
 
    if stage == "solve":
        cmd = build_cluster_launch_command(
            effective_cluster_cfg,
            solver_exe,
            ["-control_file", "$CONTROL_FILE"]
        )
    else:
        cmd = build_cluster_launch_command(
            effective_cluster_cfg,
            post_exe,
            ["-control_file", "$CONTROL_FILE", "-postprocessing_config_file", "$POST_RECIPE_FILE"],
            force_num_procs=get_cluster_total_tasks(effective_cluster_cfg),
        )
 
    # Keep shell variables unresolved inside sbatch script.
    def _token(tok: str) -> str:
        """!
        @brief Preserve shell-variable tokens while safely quoting literal command arguments for an sbatch script.
        @param[in] tok Argument passed to `_token()`.
        @return Value returned by `_token()`.
        """
        if tok.startswith("$"):
            return tok
        return shlex.quote(str(tok))
 
    diag_var = "${SOLVE_DIAGNOSTIC_ARGS}" if stage == "solve" else "${POST_DIAGNOSTIC_ARGS}"
    command_text = " ".join(_token(t) for t in cmd)
    executable_token = _token(solver_exe if stage == "solve" else post_exe)
    # Diagnostic args must be executable args, not launcher args. Insert them
    # immediately before the executable's normal control/recipe options.
    if executable_token and command_text.count(executable_token) == 1:
        command_text = command_text.replace(f"{executable_token} ", f"{executable_token} {diag_var} ", 1)
    if stage == "post":
        # A member's post runs under the same lock wrapper as a standalone run, which
        # plans the steps as the task starts, so a continued study skips every member
        # step whose output is up to date.
        lock_paths = get_post_lock_paths("$RUN_DIR")
        lines.append(
            f"{shlex.quote(sys.executable)} \"{lock_paths['wrapper_path']}\" "
            f"--lock-file \"{lock_paths['lock_file']}\" "
            f"--metadata-file \"{lock_paths['metadata_file']}\" "
            f"--run-dir \"$RUN_DIR\" --post-recipe \"$RUN_DIR/config/post.yml\" "
            f"--postprocessor {executable_token} -- {command_text}"
        )
        # Study members are ordinary root runs, but their post recipes may request the
        # same run-local physical-time PVD product and reducers as standalone runs.
        # Keep this serial and downstream of the MPI postprocessor.
        lines.append(
            f"{shlex.quote(sys.executable)} -c {shlex.quote(_post_finalize_python_source())} "
            '"$RUN_DIR" "$RUN_DIR/config/post.yml" reducers'
        )
    else:
        lines.append(f"exec {command_text}")
 
    os.makedirs(os.path.dirname(script_path), exist_ok=True)
    with open(script_path, "w") as f:
        f.write("\n".join(lines) + "\n")
    os.chmod(script_path, 0o755)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

render_metrics_aggregate_script()

picurv_cli.core.render_metrics_aggregate_script	(	str	script_path,
		str	job_name,
		dict	cluster_cfg,
		str	study_dir,
		str	picurv_path
	)

Generate a single-node sbatch script that runs metrics aggregation.

Parameters

[in]	script_path	Path to write the sbatch script.
[in]	job_name	Slurm job name.
[in]	cluster_cfg	Parsed cluster YAML dictionary.
[in]	study_dir	Absolute path to the study directory.
[in]	picurv_path	Absolute path to the picurv script.

Definition at line 17988 of file core.py.

):
    """!
    @brief Generate a single-node sbatch script that runs metrics aggregation.
    @param[in] script_path Path to write the sbatch script.
    @param[in] job_name Slurm job name.
    @param[in] cluster_cfg Parsed cluster YAML dictionary.
    @param[in] study_dir Absolute path to the study directory.
    @param[in] picurv_path Absolute path to the picurv script.
    """
    resources = cluster_cfg.get("resources", {})
    notifications = cluster_cfg.get("notifications", {}) or {}
    execution = cluster_cfg.get("execution", {}) or {}
    module_setup = execution.get("module_setup", []) or []
 
    scheduler_dir = os.path.join(study_dir, "scheduler")
    lines = [
        "#!/bin/bash",
        f"#SBATCH --job-name={job_name}",
        "#SBATCH --nodes=1",
        "#SBATCH --ntasks-per-node=1",
        "#SBATCH --mem=4G",
        "#SBATCH --time=00:10:00",
        f"#SBATCH --output={os.path.join(scheduler_dir, 'metrics_%j.out')}",
        f"#SBATCH --error={os.path.join(scheduler_dir, 'metrics_%j.err')}",
        f"#SBATCH --account={resources['account']}",
    ]
    partition = resources.get("partition")
    if partition:
        lines.append(f"#SBATCH --partition={partition}")
    mail_user = notifications.get("mail_user")
    mail_type = notifications.get("mail_type")
    if mail_user:
        lines.append(f"#SBATCH --mail-user={mail_user}")
    if mail_type:
        lines.append(f"#SBATCH --mail-type={mail_type}")
 
    lines.extend([
        "",
        "set -euo pipefail",
        'echo "[$(date)] Running metrics aggregation"',
        "",
    ])
    for setup_line in module_setup:
        lines.append(str(setup_line))
 
    lines.append(
        f"exec {shlex.quote(picurv_path)} sweep --reaggregate"
        f" --study-dir {shlex.quote(study_dir)}"
    )
 
    os.makedirs(os.path.dirname(script_path), exist_ok=True)
    with open(script_path, "w") as f:
        f.write("\n".join(lines) + "\n")
    os.chmod(script_path, 0o755)
 
 

Here is the caller graph for this function:

reduce_metric_values()

picurv_cli.core.reduce_metric_values	(		values,
		str	reduction
	)

Reduce a metric series to one scalar according to the requested reducer.

Parameters

[in]	values	Sequence of numeric values.
[in]	reduction	Reduction keyword.

Returns

Value returned by reduce_metric_values().

Definition at line 18050 of file core.py.

def reduce_metric_values(values, reduction: str):
    """!
    @brief Reduce a metric series to one scalar according to the requested reducer.
    @param[in] values Sequence of numeric values.
    @param[in] reduction Reduction keyword.
    @return Value returned by `reduce_metric_values()`.
    """
    if not values:
        return None
    np = require_numpy()
    reduction = str(reduction).lower()
    if reduction == "mean":
        return float(np.mean(values))
    if reduction == "min":
        return float(np.min(values))
    if reduction == "max":
        return float(np.max(values))
    if reduction == "p95":
        return float(np.percentile(values, 95.0))
    return float(values[-1])
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

extract_metric_from_csv()

picurv_cli.core.extract_metric_from_csv	(	str	case_dir,
		dict	spec
	)

Extract a scalar metric from a CSV source.

Parameters

[in]	case_dir	Argument passed to extract_metric_from_csv().
[in]	spec	Argument passed to extract_metric_from_csv().

Returns

Value returned by extract_metric_from_csv().

Definition at line 18072 of file core.py.

def extract_metric_from_csv(case_dir: str, spec: dict):
    """!
    @brief Extract a scalar metric from a CSV source.
    @param[in] case_dir Argument passed to `extract_metric_from_csv()`.
    @param[in] spec Argument passed to `extract_metric_from_csv()`.
    @return Value returned by `extract_metric_from_csv()`.
    """
    file_glob = spec.get("file_glob", "**/*_msd.csv")
    candidates = sorted(glob.glob(os.path.join(case_dir, file_glob), recursive=True))
    if not candidates:
        return None
    csv_path = candidates[0]
    rows = []
    with open(csv_path, "r", newline="") as f:
        reader = csv.DictReader(f)
        if reader.fieldnames:
            for row in reader:
                rows.append(row)
            if not rows:
                return None
            column = spec.get("column")
            numerator_column = spec.get("numerator_column")
            denominator_column = spec.get("denominator_column")
            denominator_floor = float(spec.get("denominator_floor", 0.0) or 0.0)
            if not column and not numerator_column:
                for name in reversed(reader.fieldnames):
                    if name and name.lower() not in {"step", "time", "timestep", "physical_time"}:
                        column = name
                        break
            if not column and not numerator_column:
                return None
            values = []
            for row in rows:
                try:
                    if numerator_column:
                        numerator = float(row[numerator_column])
                        denominator = float(row[denominator_column])
                        denominator = max(denominator_floor, denominator)
                        if denominator == 0.0:
                            continue
                        values.append(numerator / denominator)
                    else:
                        values.append(float(row[column]))
                except Exception:
                    continue
        else:
            return None
    return reduce_metric_values(values, spec.get("reduction", "last"))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

extract_metric_from_log()

picurv_cli.core.extract_metric_from_log	(	str	case_dir,
		dict	spec
	)

Extract a scalar metric from a log file using regex.

Parameters

[in]	case_dir	Argument passed to extract_metric_from_log().
[in]	spec	Argument passed to extract_metric_from_log().

Returns

Value returned by extract_metric_from_log().

Definition at line 18122 of file core.py.

def extract_metric_from_log(case_dir: str, spec: dict):
    """!
    @brief Extract a scalar metric from a log file using regex.
    @param[in] case_dir Argument passed to `extract_metric_from_log()`.
    @param[in] spec Argument passed to `extract_metric_from_log()`.
    @return Value returned by `extract_metric_from_log()`.
    """
    file_glob = spec.get("file_glob", "logs/*.log")
    regex = spec.get("regex")
    if not regex:
        return None
    candidates = sorted(glob.glob(os.path.join(case_dir, file_glob), recursive=True))
    if not candidates:
        return None
    pattern = re.compile(regex)
    values = []
    for path in candidates:
        try:
            with open(path, "r", encoding="utf-8", errors="replace") as f:
                for line in f:
                    m = pattern.search(line)
                    if m:
                        try:
                            values.append(float(m.group(1)))
                        except Exception:
                            pass
        except OSError:
            continue
    return reduce_metric_values(values, spec.get("reduction", "last"))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

normalize_metric_spec()

picurv_cli.core.normalize_metric_spec

(

metric

)

Normalize study metric definitions to a common dictionary form.

Parameters

[in]

metric

Argument passed to normalize_metric_spec().

Returns

Value returned by normalize_metric_spec().

Definition at line 18153 of file core.py.

def normalize_metric_spec(metric):
    """!
    @brief Normalize study metric definitions to a common dictionary form.
    @param[in] metric Argument passed to `normalize_metric_spec()`.
    @return Value returned by `normalize_metric_spec()`.
    """
    if isinstance(metric, str):
        if metric.lower() in {"msd", "msd_final"}:
            return {
                "name": "msd_final",
                "source": "statistics_csv",
                "file_glob": "**/*_msd.csv",
                # Named, not left to the last-column fallback, which is frac_3sigma_pct.
                "column": "MSD_total",
                "reduction": "last",
            }
        return {"name": metric, "source": "log_regex", "regex": metric}
    return dict(metric)
 

Here is the caller graph for this function:

_read_previous_metric_rows()

dict picurv_cli.core._read_previous_metric_rows ( str  results_dir )

protected

Read the metrics table an earlier aggregation wrote, keyed by case id.

Parameters

[in]

results_dir

Study analysis directory holding metrics_table.csv.

Returns

Mapping of case id to its previously recorded row, empty when absent.

Definition at line 18172 of file core.py.

def _read_previous_metric_rows(results_dir: str) -> dict:
    """!
    @brief Read the metrics table an earlier aggregation wrote, keyed by case id.
    @param[in] results_dir Study analysis directory holding metrics_table.csv.
    @return Mapping of case id to its previously recorded row, empty when absent.
    """
    path = os.path.join(results_dir, "metrics_table.csv")
    if not os.path.isfile(path):
        return {}
    try:
        with open(path, "r", encoding="utf-8", newline="") as stream:
            return {
                row["case_id"]: row for row in csv.DictReader(stream) if row.get("case_id")
            }
    except (OSError, ValueError):
        return {}
 
 

Here is the caller graph for this function:

aggregate_study_metrics()

str picurv_cli.core.aggregate_study_metrics	(	dict	study_cfg,
		list	cases,
		str	results_dir
	)

Collect metric values from generated case directories into one CSV.

Parameters

[in]	study_cfg	Argument passed to aggregate_study_metrics().
[in]	cases	Argument passed to aggregate_study_metrics().
[in]	results_dir	Argument passed to aggregate_study_metrics().

Returns

Value returned by aggregate_study_metrics().

Definition at line 18190 of file core.py.

def aggregate_study_metrics(study_cfg: dict, cases: list, results_dir: str) -> str:
    """!
    @brief Collect metric values from generated case directories into one CSV.
    @param[in] study_cfg Argument passed to `aggregate_study_metrics()`.
    @param[in] cases Argument passed to `aggregate_study_metrics()`.
    @param[in] results_dir Argument passed to `aggregate_study_metrics()`.
    @return Value returned by `aggregate_study_metrics()`.
    """
    metrics = study_cfg.get("metrics", [])
    if not metrics:
        metrics = ["msd_final"]
    normalized_specs = [normalize_metric_spec(m) for m in metrics]
 
    # A member whose payload was archived cannot be re-measured. Its previously
    # aggregated values are the correct answer for it, so they are carried forward
    # rather than overwritten with blanks or the whole table refused.
    preserved = _read_previous_metric_rows(results_dir)
    rows = []
    for case in cases:
        row = {"case_id": case["case_id"]}
        flat_parameters = flatten_study_parameters(case.get("parameters", {}))
        for p_key, p_val in flat_parameters.items():
            row[p_key] = p_val
        if is_artifact_cold(case["run_dir"]):
            retained = preserved.get(case["case_id"])
            if retained:
                for spec in normalized_specs:
                    name = spec.get("name", "metric")
                    row[name] = retained.get(name)
                row["_source"] = "retained"
                rows.append(row)
                continue
            print(
                f"[WARNING] {case['case_id']} is in cold storage and no previous metrics "
                "row was found; its values are reported as unavailable.",
                file=sys.stderr,
            )
            for spec in normalized_specs:
                row[spec.get("name", "metric")] = None
            rows.append(row)
            continue
        for spec in normalized_specs:
            name = spec.get("name", "metric")
            source = str(spec.get("source", "")).lower()
            if source in METRIC_SOURCE_KINDS[:2]:
                value = extract_metric_from_csv(case["run_dir"], spec)
            elif source in METRIC_SOURCE_KINDS[2:]:
                value = extract_metric_from_log(case["run_dir"], spec)
            else:
                value = None
 
            normalize_key = spec.get("normalize_by_parameter")
            if value is not None and normalize_key:
                denom = flat_parameters.get(normalize_key)
                try:
                    denom = float(denom)
                except Exception:
                    denom = None
                if denom not in (None, 0.0):
                    value = float(value) / denom
                else:
                    value = None
 
            row[name] = value
        rows.append(row)
 
    if not rows:
        return None
 
    all_keys = []
    seen = set()
    for row in rows:
        for k in row.keys():
            if k not in seen:
                seen.add(k)
                all_keys.append(k)
 
    os.makedirs(results_dir, exist_ok=True)
    out_csv = os.path.join(results_dir, "metrics_table.csv")
    with open(out_csv, "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=all_keys)
        writer.writeheader()
        writer.writerows(rows)
    metric_names = [spec.get("name", "metric") for spec in normalized_specs]
    if any(row.get(name) is not None for row in rows for name in metric_names):
        print(f"[SUCCESS] Aggregated metrics table: {os.path.relpath(out_csv)}")
    else:
        # At submission no member has run; the metrics job fills the table later.
        print(f"[INFO] Initialized metrics table (no member has produced metrics yet): "
              f"{os.path.relpath(out_csv)}")
    return out_csv
 

Here is the call graph for this function:

Here is the caller graph for this function:

_study_parameter_label()

str picurv_cli.core._study_parameter_label ( str  key )

protected

Return a concise report label for a study parameter path.

Parameters

[in]

key

Dotted study parameter path.

Returns

Report-facing axis or legend label.

Definition at line 18288 of file core.py.

def _study_parameter_label(key: str) -> str:
    """!
    @brief Return a concise report label for a study parameter path.
    @param[in] key Dotted study parameter path.
    @return Report-facing axis or legend label.
    """
    exact = {
        "case.run_control.dt_physical": "Physical timestep, Δt",
        "case.models.physics.particles.count": "Particle count",
        "solver.operation_mode.uniform_flow.u": "Uniform-flow velocity, u",
        "case.grid.programmatic_settings.im": "Grid nodes in i, Nᵢ",
        "case.grid.programmatic_settings.jm": "Grid nodes in j, Nⱼ",
        "case.grid.programmatic_settings.km": "Grid nodes in k, Nₖ",
    }
    return exact.get(key, _humanize_plot_identifier(key))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_study_metric_label()

str picurv_cli.core._study_metric_label ( dict  study_cfg, str  metric  )

protected

Resolve an optional configured metric label or humanize its name.

Parameters

[in]	study_cfg	Parsed study configuration.
[in]	metric	Metric column name.

Returns

Report-facing metric label.

Definition at line 18305 of file core.py.

def _study_metric_label(study_cfg: dict, metric: str) -> str:
    """!
    @brief Resolve an optional configured metric label or humanize its name.
    @param[in] study_cfg Parsed study configuration.
    @param[in] metric Metric column name.
    @return Report-facing metric label.
    """
    for raw_spec in study_cfg.get("metrics", []) or []:
        spec = normalize_metric_spec(raw_spec)
        if spec.get("name") != metric:
            continue
        label = spec.get("plot_label") or spec.get("label")
        units = spec.get("units")
        base = str(label) if label else _humanize_plot_identifier(metric)
        return f"{base} ({units})" if units else base
    return _humanize_plot_identifier(metric)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_numeric_study_column()

"list | None" picurv_cli.core._numeric_study_column ( list  rows, str  key  )

protected

Parse one complete, finite numeric study-table column.

Parameters

[in]	rows	Metrics-table rows.
[in]	key	Column name.

Returns

Numeric values, or None when the column is incomplete or nonnumeric.

Definition at line 18323 of file core.py.

def _numeric_study_column(rows: list, key: str) -> "list | None":
    """!
    @brief Parse one complete, finite numeric study-table column.
    @param[in] rows Metrics-table rows.
    @param[in] key Column name.
    @return Numeric values, or None when the column is incomplete or nonnumeric.
    """
    values = []
    for row in rows:
        try:
            value = float(row[key])
        except (KeyError, TypeError, ValueError):
            return None
        if not math.isfinite(value):
            return None
        values.append(value)
    return values
 
 

Here is the caller graph for this function:

_infer_study_plot_axis()

"dict | None" picurv_cli.core._infer_study_plot_axis ( dict  study_cfg, list  rows  )

protected

Infer the scientifically meaningful independent variable of a study.

Parameters

[in]	study_cfg	Parsed study configuration.
[in]	rows	Metrics-table rows.

Returns

Axis metadata, or None when no numeric independent variable exists.

Definition at line 18342 of file core.py.

def _infer_study_plot_axis(study_cfg: dict, rows: list) -> "dict | None":
    """!
    @brief Infer the scientifically meaningful independent variable of a study.
    @param[in] study_cfg Parsed study configuration.
    @param[in] rows Metrics-table rows.
    @return Axis metadata, or None when no numeric independent variable exists.
    """
    params = [key for key in get_study_parameter_keys(study_cfg) if rows and key in rows[0]]
    if not params or not rows:
        return None
 
    grid_keys = (
        "case.grid.programmatic_settings.im",
        "case.grid.programmatic_settings.jm",
        "case.grid.programmatic_settings.km",
    )
    if study_cfg.get("study_type") == "grid_independence" and all(key in params for key in grid_keys):
        columns = [_numeric_study_column(rows, key) for key in grid_keys]
        if all(column is not None for column in columns):
            values = [
                (columns[0][index] * columns[1][index] * columns[2][index]) ** (1.0 / 3.0)
                for index in range(len(rows))
            ]
            return {
                "key": "characteristic_grid_resolution",
                "label": "Characteristic grid resolution, (NᵢNⱼNₖ)¹⁄³",
                "slug": "characteristic_grid_resolution",
                "values": values,
                "contributors": set(grid_keys),
            }
 
    preferred = []
    if study_cfg.get("study_type") == "timestep_independence":
        preferred = [key for key in params if key.endswith(".dt_physical")]
    numeric = []
    for key in preferred + [key for key in params if key not in preferred]:
        values = _numeric_study_column(rows, key)
        if values is not None:
            numeric.append((key, values, len(set(values))))
    if not numeric:
        return None
    varied = [candidate for candidate in numeric if candidate[2] > 1]
    key, values, _unique = (varied or numeric)[0]
    return {
        "key": key,
        "label": _study_parameter_label(key),
        "slug": re.sub(r"[^A-Za-z0-9_.-]+", "_", key),
        "values": values,
        "contributors": {key},
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

infer_plot_x_axis()

picurv_cli.core.infer_plot_x_axis	(	dict	study_cfg,
		list	rows
	)

Infer x-axis key/values for study plots.

Parameters

[in]	study_cfg	Argument passed to infer_plot_x_axis().
[in]	rows	Argument passed to infer_plot_x_axis().

Returns

Value returned by infer_plot_x_axis().

Definition at line 18394 of file core.py.

def infer_plot_x_axis(study_cfg: dict, rows: list):
    """!
    @brief Infer x-axis key/values for study plots.
    @param[in] study_cfg Argument passed to `infer_plot_x_axis()`.
    @param[in] rows Argument passed to `infer_plot_x_axis()`.
    @return Value returned by `infer_plot_x_axis()`.
    """
    axis = _infer_study_plot_axis(study_cfg, rows)
    if axis is None:
        return None, None
    return axis["label"], axis["values"]
 
 

Here is the call graph for this function:

_format_study_group_value()

str picurv_cli.core._format_study_group_value (   value )

protected

Format a secondary study parameter compactly for a legend.

Parameters

[in]

value

Parameter value.

Returns

Compact report string.

Definition at line 18407 of file core.py.

def _format_study_group_value(value) -> str:
    """!
    @brief Format a secondary study parameter compactly for a legend.
    @param[in] value Parameter value.
    @return Compact report string.
    """
    try:
        number = float(value)
    except (TypeError, ValueError):
        return str(value)
    if number.is_integer():
        return f"{int(number):,}"
    return f"{number:g}"
 
 

_study_plot_groups()

list picurv_cli.core._study_plot_groups ( dict  study_cfg, list  rows, dict  axis, str  metric  )

protected

Group metric points by any secondary varied study parameters.

Parameters

[in]	study_cfg	Parsed study configuration.
[in]	rows	Metrics-table rows.
[in]	axis	Inferred independent-axis metadata.
[in]	metric	Metric column name.

Returns

Labeled point groups.

Definition at line 18422 of file core.py.

def _study_plot_groups(study_cfg: dict, rows: list, axis: dict, metric: str) -> list:
    """!
    @brief Group metric points by any secondary varied study parameters.
    @param[in] study_cfg Parsed study configuration.
    @param[in] rows Metrics-table rows.
    @param[in] axis Inferred independent-axis metadata.
    @param[in] metric Metric column name.
    @return Labeled point groups.
    """
    param_keys = [key for key in get_study_parameter_keys(study_cfg) if rows and key in rows[0]]
    secondary = []
    for key in param_keys:
        if key in axis["contributors"]:
            continue
        values = {str(row.get(key)) for row in rows}
        # A control coupled one-to-one with x (for example total_steps paired
        # with dt to keep physical duration fixed, or particle count paired with
        # grid size to keep PPC fixed) describes the same study trajectory. It
        # must not split that trajectory into one-point pseudo-series.
        if 1 < len(values) < len(rows):
            secondary.append(key)
 
    groups = {}
    for row_index, row in enumerate(rows):
        try:
            y_value = float(row[metric])
        except (KeyError, TypeError, ValueError):
            continue
        if not math.isfinite(y_value):
            continue
        identity = tuple(row.get(key) for key in secondary)
        groups.setdefault(identity, []).append([axis["values"][row_index], y_value])
 
    result = []
    for identity, points in groups.items():
        points.sort(key=lambda point: point[0])
        label = ", ".join(
            f"{_study_parameter_label(key)} = {_format_study_group_value(value)}"
            for key, value in zip(secondary, identity)
        )
        result.append({"label": label or "Study cases", "points": points})
    return result
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_study_use_log_scale()

bool picurv_cli.core._study_use_log_scale ( list  values, bool   semantic_hint = False  )

protected

Use log scaling only for positive data spanning a meaningful range.

Parameters

[in]	values	Candidate axis values.
[in]	semantic_hint	Whether the quantity is conventionally read logarithmically.

Returns

True when logarithmic scaling improves interpretation.

Definition at line 18466 of file core.py.

def _study_use_log_scale(values: list, semantic_hint: bool = False) -> bool:
    """!
    @brief Use log scaling only for positive data spanning a meaningful range.
    @param[in] values Candidate axis values.
    @param[in] semantic_hint Whether the quantity is conventionally read logarithmically.
    @return True when logarithmic scaling improves interpretation.
    """
    if not values or any(value <= 0.0 for value in values):
        return False
    ratio = max(values) / min(values)
    return ratio >= (20.0 if semantic_hint else 100.0)
 
 

Here is the caller graph for this function:

_study_linear_y_limits()

"tuple[float, float] | None" picurv_cli.core._study_linear_y_limits ( list  values )

protected

Build padded linear limits that include zero for non-negative metrics.

Parameters

[in]

values

Finite metric values.

Returns

Lower and upper limits, or None for an empty sequence.

Definition at line 18479 of file core.py.

def _study_linear_y_limits(values: list) -> "tuple[float, float] | None":
    """!
    @brief Build padded linear limits that include zero for non-negative metrics.
    @param[in] values Finite metric values.
    @return Lower and upper limits, or None for an empty sequence.
    """
    if not values:
        return None
    lower, upper = min(values), max(values)
    if lower >= 0.0:
        lower = 0.0
    span = upper - lower
    padding = max(span * 0.06, abs(upper) * 0.02, 1.0e-12)
    return (lower, upper + padding) if lower == 0.0 else (lower - padding, upper + padding)
 

Here is the caller graph for this function:

generate_study_plots()

picurv_cli.core.generate_study_plots	(	dict	study_cfg,
		str	metrics_csv,
		str	plots_dir
	)

Generate metric-vs-parameter plots for completed studies.

Parameters

[in]	study_cfg	Argument passed to generate_study_plots().
[in]	metrics_csv	Argument passed to generate_study_plots().
[in]	plots_dir	Argument passed to generate_study_plots().

Returns

Value returned by generate_study_plots().

Definition at line 18494 of file core.py.

def generate_study_plots(study_cfg: dict, metrics_csv: str, plots_dir: str):
    """!
    @brief Generate metric-vs-parameter plots for completed studies.
    @param[in] study_cfg Argument passed to `generate_study_plots()`.
    @param[in] metrics_csv Argument passed to `generate_study_plots()`.
    @param[in] plots_dir Argument passed to `generate_study_plots()`.
    @return Value returned by `generate_study_plots()`.
    """
    plotting_cfg = study_cfg.get("plotting", {}) or {}
    if plotting_cfg.get("enabled", True) is False:
        print("[INFO] Plotting disabled by study.yml.")
        return []
    plt = optional_matplotlib_pyplot()
    if plt is None:
        print("[WARNING] matplotlib not available; skipping plot generation.")
        return []
    if not metrics_csv or not os.path.isfile(metrics_csv):
        return []
 
    with open(metrics_csv, "r", newline="") as f:
        reader = csv.DictReader(f)
        rows = list(reader)
    if not rows:
        return []
 
    axis = _infer_study_plot_axis(study_cfg, rows)
    if axis is None:
        print("[WARNING] Could not infer numeric x-axis for plots; skipping.")
        return []
 
    configured_metrics = study_cfg.get("metrics", []) or ["msd_final"]
    metric_keys = [
        normalize_metric_spec(metric).get("name", "metric") for metric in configured_metrics
        if normalize_metric_spec(metric).get("name", "metric") in rows[0]
    ]
 
    out_format = plotting_cfg.get("output_format", "png")
    os.makedirs(plots_dir, exist_ok=True)
    generated = []
    for metric in metric_keys:
        groups = _study_plot_groups(study_cfg, rows, axis, metric)
        if not groups:
            continue
        all_x = [point[0] for group in groups for point in group["points"]]
        all_y = [point[1] for group in groups for point in group["points"]]
        metric_label = _study_metric_label(study_cfg, metric)
        metric_hint = metric.lower()
        y_log = _study_use_log_scale(
            all_y,
            any(token in metric_hint for token in ("error", "residual", "drift", "msd")),
        )
        x_log = _study_use_log_scale(all_x)
        grid_cross_product = (
            study_cfg.get("study_type") == "grid_independence"
            and bool(study_cfg.get("parameters")) and len(axis["contributors"]) == 3
            and sum(
                len(set(float(row[key]) for row in rows)) > 1
                for key in axis["contributors"]
            ) > 1
        )
 
        plt.figure(figsize=(9.2, 5.5), facecolor="white")
        for index, group in enumerate(groups):
            x_values = [point[0] for point in group["points"]]
            y_values = [point[1] for point in group["points"]]
            repeated_x = len(set(x_values)) != len(x_values)
            plt.plot(
                x_values, y_values,
                color=_STUDY_REPORT_COLORS[index % len(_STUDY_REPORT_COLORS)],
                marker="o", markersize=5.2, markeredgewidth=0.7,
                linewidth=0.0 if repeated_x or grid_cross_product else 1.8,
                linestyle="none" if repeated_x or grid_cross_product else "-",
                label=group["label"],
            )
        plt.xlabel(axis["label"], fontsize=11)
        plt.ylabel(metric_label, fontsize=11)
        study_label = {
            "grid_independence": "Grid-independence study",
            "timestep_independence": "Timestep-independence study",
            "sensitivity": "Sensitivity study",
        }.get(study_cfg.get("study_type"), "Parameter study")
        plt.title(f"{metric_label} vs. {axis['label']}\n{study_label}", fontsize=13, loc="left", pad=12)
        if x_log and hasattr(plt, "xscale"):
            plt.xscale("log")
        if y_log:
            plt.yscale("log")
        elif hasattr(plt, "ylim"):
            limits = _study_linear_y_limits(all_y)
            if limits:
                plt.ylim(*limits)
        if hasattr(plt, "tick_params"):
            plt.tick_params(axis="both", which="major", labelsize=9.5)
        plt.grid(True, alpha=0.24, which="major", linewidth=0.7)
        if x_log or y_log:
            plt.grid(True, alpha=0.08, which="minor", linewidth=0.5)
        if len(groups) > 1:
            plt.legend(
                loc="upper left", bbox_to_anchor=(1.01, 1.0), borderaxespad=0.0,
                frameon=False, title="Fixed parameters", fontsize=9, title_fontsize=9.5,
            )
            plt.tight_layout(rect=(0.0, 0.0, 0.76, 1.0))
        else:
            plt.tight_layout()
        safe_metric = re.sub(r"[^A-Za-z0-9_.-]+", "_", metric)
        out_path = os.path.join(plots_dir, f"{safe_metric}_vs_{axis['slug']}.{out_format}")
        plt.savefig(out_path, dpi=240, bbox_inches="tight", facecolor="white")
        plt.close()
        generated.append(out_path)
    if generated:
        print(f"[SUCCESS] Generated {len(generated)} plot(s) in {os.path.relpath(plots_dir)}")
    return generated
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_command_to_string()

str picurv_cli.core._command_to_string ( list  command_tokens )

protected

Render a command list as a shell-safe display string.

Parameters

[in]

command_tokens

Argument passed to _command_to_string().

Returns

Value returned by _command_to_string().

Definition at line 18607 of file core.py.

def _command_to_string(command_tokens: list) -> str:
    """!
    @brief Render a command list as a shell-safe display string.
    @param[in] command_tokens Argument passed to `_command_to_string()`.
    @return Value returned by `_command_to_string()`.
    """
    return " ".join(shlex.quote(str(tok)) for tok in command_tokens)
 
 

Here is the caller graph for this function:

_resolve_post_source_directory_preview()

str picurv_cli.core._resolve_post_source_directory_preview ( str  run_dir, dict  monitor_cfg, dict  post_cfg  )

protected

Resolve post source directory without side effects or stdout/stderr output.

Parameters

[in]	run_dir	Argument passed to _resolve_post_source_directory_preview().
[in]	monitor_cfg	Argument passed to _resolve_post_source_directory_preview().
[in]	post_cfg	Argument passed to _resolve_post_source_directory_preview().

Returns

Value returned by _resolve_post_source_directory_preview().

Definition at line 18616 of file core.py.

def _resolve_post_source_directory_preview(run_dir: str, monitor_cfg: dict, post_cfg: dict) -> str:
    """!
    @brief Resolve post source directory without side effects or stdout/stderr output.
    @param[in] run_dir Argument passed to `_resolve_post_source_directory_preview()`.
    @param[in] monitor_cfg Argument passed to `_resolve_post_source_directory_preview()`.
    @param[in] post_cfg Argument passed to `_resolve_post_source_directory_preview()`.
    @return Value returned by `_resolve_post_source_directory_preview()`.
    """
    solver_output_dir_abs = os.path.join(run_dir, CANONICAL_RUN_PATHS["output"])
    source_dir_template = get_post_source_directory_template(post_cfg)
    if source_dir_template == '<solver_output_dir>':
        return solver_output_dir_abs
    return os.path.abspath(os.path.join(run_dir, source_dir_template))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

build_run_dry_plan()

dict picurv_cli.core.build_run_dry_plan

(

args

)

Build a no-write execution plan for run --dry-run.

Parameters

[in]

args

Command-line style argument list supplied to the function.

Returns

Value returned by build_run_dry_plan().

Definition at line 18631 of file core.py.

def build_run_dry_plan(args) -> dict:
    """!
    @brief Build a no-write execution plan for `run --dry-run`.
    @param[in] args Command-line style argument list supplied to the function.
    @return Value returned by `build_run_dry_plan()`.
    """
    plan = {
        "mode": "dry-run",
        "created_at": datetime.now().isoformat(),
        "warnings": [],
        "inputs": {},
        "stages": {},
        "artifacts": [],
    }
 
    if args.dry_run and args.no_submit:
        plan["warnings"].append("--dry-run takes precedence over --no-submit; no files will be written.")
 
    cluster_mode = bool(getattr(args, "cluster", None))
    cluster_cfg = None
    cluster_path = None
    solver_num_procs_effective = args.num_procs
    post_num_procs_effective = args.num_procs
    run_id = None
    run_dir = None
    solver_control_path = None
    loaded_case_cfg = None
    loaded_monitor_cfg = None
    resolved_restart_source_dir = None
 
    if cluster_mode:
        cluster_path = os.path.abspath(args.cluster)
        cluster_cfg = read_yaml_file(cluster_path)
        validate_cluster_config(cluster_cfg, cluster_path)
        scheduler_type = str(cluster_cfg.get("scheduler", {}).get("type", "slurm")).lower()
        if args.scheduler and args.scheduler.lower() != scheduler_type:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="scheduler.type",
                file_path=cluster_path,
                message=f"--scheduler={args.scheduler} does not match cluster.yml scheduler.type={scheduler_type}.",
            )
            sys.exit(1)
        if scheduler_type != "slurm":
            emit_structured_error(
                ERROR_CODE_CFG_INVALID_VALUE,
                key="scheduler.type",
                file_path=cluster_path,
                message=f"Unsupported scheduler '{scheduler_type}'. Only Slurm is supported.",
            )
            sys.exit(1)
        cluster_tasks = get_cluster_total_tasks(cluster_cfg)
        if (args.solve or args.post_process) and args.num_procs not in (1, cluster_tasks):
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="resources.ntasks_per_node",
                file_path=cluster_path,
                message=(
                    "--num-procs must be 1 (auto) or "
                    f"exactly nodes*ntasks_per_node ({cluster_tasks}) in cluster mode."
                ),
            )
            sys.exit(1)
        if args.solve:
            solver_num_procs_effective = cluster_tasks
        if args.post_process:
            post_num_procs_effective = cluster_tasks
        plan["launch_mode"] = "slurm"
        plan["inputs"]["cluster"] = cluster_path
    else:
        if getattr(args, "scheduler", None):
            fail_cli_usage("--scheduler requires --cluster in this version.")
        plan["launch_mode"] = "local"
 
    # --- Guard: restart flags without --solve ---
    if not args.solve:
        if getattr(args, 'restart_from', None):
            print("[WARNING] --restart-from has no effect without --solve and will be ignored.", file=sys.stderr)
        if getattr(args, 'continue_run', False):
            print("[WARNING] --continue only extends a solve in place and is ignored here. "
                  "Post-processing always skips steps whose output is up to date; drop "
                  "--continue from post-only commands.", file=sys.stderr)
 
    if args.solve:
        case_path = os.path.abspath(args.case)
        workspace_root = find_workspace_root(case_path, args.solver, args.monitor, os.getcwd())
        if workspace_root:
            enforce_workspace_version(workspace_root)
            enforce_reproducibility_policy(workspace_root)
        solver_path = os.path.abspath(args.solver)
        monitor_path = os.path.abspath(args.monitor)
        loaded_case_cfg = read_yaml_file(case_path)
        solver_cfg = read_yaml_file(solver_path)
        loaded_monitor_cfg = read_yaml_file(monitor_path)
        validate_simulation_configs(
            loaded_case_cfg, solver_cfg, loaded_monitor_cfg, case_path, solver_path, monitor_path,
            restart_source_given=bool(getattr(args, 'restart_from', None) or getattr(args, 'continue_run', False)),
        )
 
        continue_mode = getattr(args, 'continue_run', False)
 
        if continue_mode:
            # --continue reuses existing run directory
            if not args.run_dir:
                fail_cli_usage(RESTART_RUN_DIR_REQUIRED_MESSAGE)
            run_dir = os.path.abspath(args.run_dir)
            if not os.path.isdir(run_dir):
                emit_structured_error(
                    ERROR_CODE_CFG_FILE_NOT_FOUND,
                    key="run-dir",
                    file_path=run_dir,
                    message="Specified run directory not found.",
                )
                sys.exit(1)
            adopt_relocated_artifact(run_dir, dry_run=True)
            run_id = os.path.basename(run_dir)
        else:
            runs_root = workspace_artifact_root(workspace_root, "runs")
            run_id = allocate_generated_run_id(runs_root, loaded_case_cfg, case_path)
            run_dir = os.path.join(runs_root, run_id)
 
        try:
            resolved_restart_source_dir, is_continue, planned_lineage = resolve_restart_source(
                args, loaded_case_cfg, solver_cfg, loaded_monitor_cfg, run_dir,
                materialize=False,
            )
            plan["lineage"] = planned_lineage or {"relationship": "root"}
            planned_index_bytes = select_run_petsc_index_bytes(
                args, loaded_case_cfg, case_path, loaded_monitor_cfg, resolved_restart_source_dir)
        except ValueError as e:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="restart",
                file_path=case_path,
                message=str(e),
                hint=_STORAGE_RESTORE_HINT if isinstance(e.__cause__, StorageError) else _RESTART_HINT,
            )
            sys.exit(1)
 
        config_dir = os.path.join(run_dir, "config")
        scheduler_dir = os.path.join(run_dir, "scheduler")
        # Report the directories the run will ACTUALLY use, not the defaults. A plan
        # that hides a configured path cannot warn about where output really lands -
        # and the fresh-run log directory is deleted recursively by the C runtime.
        _plan_dirs = {}
        logs_dir = os.path.join(run_dir, CANONICAL_RUN_PATHS["logs"])
        planned_output_dir = os.path.join(run_dir, CANONICAL_RUN_PATHS["output"])
        solver_control_path = os.path.join(config_dir, f"{run_id}.control")
        profile_path = os.path.join(config_dir, "profile.run")
        profiling_preview = resolve_profiling_config(loaded_monitor_cfg)
 
        plan["run_id_preview"] = run_id
        plan["run_dir_preview"] = run_dir
        # A layout the coarsest multigrid level cannot hold aborts grid setup on the
        # cluster, after the queue wait; it is decidable here from the grid's size.
        block_dims = resolve_grid_node_dims(
            loaded_case_cfg, case_path,
            os.path.join(run_dir, "inputs", "grid", "grid.run") if continue_mode else None)
        decomposition = resolve_decomposition(
            solver_num_procs_effective, loaded_case_cfg.get("grid") or {}, block_dims, solver_cfg,
            case_declares_periodic_axis(loaded_case_cfg), getattr(args, "decomposition", None),
            cluster_cfg if cluster_mode else None)
        plan.setdefault("blocking", []).extend(decomposition["problems"])
        plan["decomposition"] = {"layout": list(decomposition["layout"]) if decomposition.get("layout") else None,
                                 "source": decomposition["source"],
                                 "summary": describe_decomposition(decomposition, solver_num_procs_effective)}
        if block_dims is None and solver_num_procs_effective > 1:
            plan["warnings"].append(
                "Could not determine the grid's dimensions without building it, so the "
                "decomposition was not checked against the multigrid levels.")
        # A plan that omits what a real run would refuse is not a plan. The run
        # directory does not exist yet, but `realpath` still normalizes it, so the
        # run-root and ancestor verdicts are decidable here.
        _authorized, _ = resolve_unsafe_paths_override(_plan_dirs, "monitor.yml")
        plan.setdefault("blocking", [])
        # A run resumed into a directory that grew an unrouted peer would be refused,
        # so the plan has to say so rather than promising a launch that will not happen.
        structure_errors, structure_warnings = validate_run_directory_structure(run_dir)
        plan["blocking"].extend(structure_errors)
        plan["warnings"].extend(structure_warnings)
        for _key, _verdict, _message in classify_physical_containment(
                run_dir, effective_run_directories(_plan_dirs)):
            if _authorized and _verdict in WAIVABLE_PHYSICAL_VERDICTS:
                plan["warnings"].append(f"{_message} Allowed only because "
                                        f"'allow_unsafe_paths: true' is set.")
            else:
                plan["blocking"].append(_message)
        plan["inputs"].update({"case": case_path, "solver": solver_path, "monitor": monitor_path})
        asset_plan = plan_run_assets(
            loaded_case_cfg, case_path, unused_asset_kinds(loaded_case_cfg, solver_cfg)
        )
        plan["asset_actions"] = [
            {"kind": item["kind"], "provider": item["provider"], "action": item["action"]}
            for item in asset_plan["actions"]
        ]
        runtime_kinds = {
            item["kind"] for item in asset_plan["actions"]
            if item["execution"] == "runtime-c"
        }
        for item in asset_plan["actions"]:
            blocked_dependencies = runtime_kinds.intersection(item.get("dependencies", []))
            if item["execution"] == "precomputable" and blocked_dependencies:
                plan["blocking"].append(
                    f"{item['kind']}={item['provider']} requires a file-backed "
                    f"{', '.join(sorted(blocked_dependencies))}, but that dependency is generated "
                    "only inside the simulator. Select a precomputable provider for the dependency."
                )
        plan["artifacts"].extend(
            [
                run_dir,
                *(os.path.join(run_dir, *relative.split("/"))
                  for relative in RUN_DIRECTORY_LAYOUT),
                os.path.join(config_dir, "case.yml"),
                os.path.join(config_dir, "solver.yml"),
                os.path.join(config_dir, "monitor.yml"),
                os.path.join(config_dir, "active.json"),
                os.path.join(run_dir, CANONICAL_RUN_PATHS["inputs"], "assets.lock.yml"),
                solver_control_path,
                os.path.join(run_dir, "manifest.json"),
            ]
        )
        add_planned_grid_artifacts(plan, loaded_case_cfg, run_dir)
        add_planned_profile_artifacts(plan, loaded_case_cfg, run_dir)
        add_planned_initial_condition_artifacts(plan, loaded_case_cfg, solver_cfg, run_dir)
        if has_explicit_monitor_whitelist(loaded_monitor_cfg):
            plan["artifacts"].append(os.path.join(config_dir, "whitelist.run"))
        if profiling_preview["mode"] == "selected":
            plan["artifacts"].append(profile_path)
        solve_diagnostics = resolve_diagnostics_config(loaded_monitor_cfg, run_dir, "Solver")
        plan["artifacts"].extend(solve_diagnostics["artifacts"])
        if cluster_mode:
            plan["artifacts"].append(os.path.join(config_dir, "cluster.yml"))
            plan["artifacts"].append(os.path.join(scheduler_dir, "submission.json"))
 
        executable_plan = plan_run_executable_paths(run_dir, args, workspace_root)
        solver_exe = executable_plan["paths"]["simulator"]
        if executable_plan["pinning"] == "new":
            plan["artifacts"].extend(executable_plan["paths"].values())
        solver_args = build_petsc_diagnostics_args(loaded_monitor_cfg, run_dir, "Solver") + ["-control_file", solver_control_path]
        if cluster_mode:
            solver_script = os.path.join(scheduler_dir, "solver.sbatch")
            solver_cmd = build_cluster_launch_command(
                cluster_cfg,
                solver_exe,
                solver_args,
                config_search_anchor=case_path,
                extra_search_anchors=[cluster_path],
            )
            plan["artifacts"].append(solver_script)
            plan["stages"]["solve"] = {
                "mode": "slurm",
                "script": solver_script,
                "num_procs_effective": solver_num_procs_effective,
                "launch_command": solver_cmd,
                "launch_command_string": _command_to_string(solver_cmd),
            }
        else:
            solver_cmd = build_local_launch_command(
                solver_exe,
                solver_args,
                solver_num_procs_effective,
                config_search_anchor=case_path,
            )
            solver_stream_log = os.path.join(scheduler_dir, f"{run_id}_solver.log")
            plan["artifacts"].append(solver_stream_log)
            plan["stages"]["solve"] = {
                "mode": "local",
                "num_procs_effective": solver_num_procs_effective,
                "stream_log": solver_stream_log,
                "launch_command": solver_cmd,
                "launch_command_string": _command_to_string(solver_cmd),
            }
        plan["stages"]["solve"]["executable_pinning"] = executable_plan["pinning"]
        plan["stages"]["solve"]["petsc_index_bits"] = 8 * planned_index_bytes
        planned_run_control = loaded_case_cfg.get("run_control") or {}
        plan["stages"]["solve"]["start_step"] = int(planned_run_control.get("start_step", 0) or 0)
        plan["stages"]["solve"]["end_step"] = (plan["stages"]["solve"]["start_step"]
                                               + int(planned_run_control.get("total_steps", 0) or 0))
        if resolved_restart_source_dir:
            plan["stages"]["solve"]["restart_source_directory"] = resolved_restart_source_dir
        if is_continue:
            plan["stages"]["solve"]["continue_mode"] = True
 
    if args.post_process:
        post_path = os.path.abspath(args.post)
        plan["inputs"]["post"] = post_path
        post_cfg = read_yaml_file(post_path)
        validate_post_config(post_cfg, post_path, loaded_monitor_cfg, loaded_case_cfg)
 
        if args.run_dir:
            run_dir = os.path.abspath(args.run_dir)
            if not os.path.isdir(run_dir):
                emit_structured_error(
                    ERROR_CODE_CFG_FILE_NOT_FOUND,
                    key="run-dir",
                    file_path=run_dir,
                    message="Specified run directory not found.",
                )
                sys.exit(1)
            adopt_relocated_artifact(run_dir, dry_run=True)
            run_id = os.path.basename(run_dir)
        elif not args.solve:
            fail_cli_usage("--post-process requires --run-dir when not used with --solve.")
 
        if args.run_dir:
            config_dir = os.path.join(run_dir, "config")
            case_path, monitor_path, solver_control_path = auto_identify_run_inputs(config_dir)
            if not all([case_path, monitor_path, solver_control_path]):
                emit_structured_error(
                    ERROR_CODE_CFG_MISSING_KEY,
                    key="run_dir.config",
                    file_path=config_dir,
                    message=(
                        "Could not auto-identify required run inputs "
                        "(case.yml/monitor.yml/*.control) in run config directory."
                    ),
                )
                sys.exit(1)
            loaded_case_cfg = read_yaml_file(case_path)
            loaded_monitor_cfg = read_yaml_file(monitor_path)
        else:
            config_dir = os.path.join(run_dir, "config")
            case_path = os.path.join(config_dir, "case.yml")
            monitor_path = os.path.join(config_dir, "monitor.yml")
            if solver_control_path is None:
                solver_control_path = os.path.join(config_dir, f"{run_id}.control")
 
        post_cfg, recipe_id = apply_canonical_post_paths(post_cfg, run_dir)
        allow_source_frontier_scan = not args.solve
        recompute = bool(getattr(args, 'recompute_post', False))
        if args.solve:
            post_exe = executable_plan["paths"]["postprocessor"]
        else:
            try:
                select_existing_run_petsc_index_bytes(run_dir, args)
            except ValueError as e:
                emit_structured_error(ERROR_CODE_CFG_INCONSISTENT_COMBO, key="petsc_index_bits",
                                      file_path=run_dir, message=str(e))
                sys.exit(1)
            post_exe = run_executable_path(run_dir, "postprocessor")
        post_plan = build_post_execution_plan(
            run_dir,
            run_id,
            loaded_case_cfg,
            loaded_monitor_cfg,
            post_cfg,
            recompute=recompute,
            allow_source_frontier_scan=allow_source_frontier_scan,
            postprocessor_sha=_file_sha256(post_exe),
        )
 
        if args.solve:
            post_decomposition = resolve_decomposition(
                post_num_procs_effective, loaded_case_cfg.get("grid") or {}, block_dims, solver_cfg,
                case_declares_periodic_axis(loaded_case_cfg), getattr(args, "decomposition", None),
                cluster_cfg if cluster_mode else None)
        else:
            post_decomposition = resolve_post_decomposition(
                run_dir, post_num_procs_effective, getattr(args, "decomposition", None),
                cluster_cfg if cluster_mode else None)
        plan.setdefault("blocking", []).extend(
            problem for problem in post_decomposition["problems"] if problem not in plan["blocking"])
        plan["post_decomposition"] = {
            "layout": list(post_decomposition["layout"]) if post_decomposition.get("layout") else None,
            "source": post_decomposition["source"],
            "summary": describe_decomposition(post_decomposition, post_num_procs_effective)}
 
        post_recipe_path = os.path.join(get_post_recipe_root(run_dir, post_cfg), "post.run")
        archived_post_path = os.path.join(get_post_recipe_root(run_dir, post_cfg), "post.yml")
        post_finalize_command = build_post_finalize_command(run_dir, archived_post_path, post_cfg)
        output_dir_rel = post_cfg.get("io", {}).get("output_directory")
        output_prefix = post_cfg.get("io", {}).get("output_filename_prefix")
        if not output_prefix:
            emit_structured_error(
                ERROR_CODE_CFG_MISSING_KEY,
                key="io.output_filename_prefix",
                file_path=post_path,
                message="Missing required post output filename prefix.",
            )
            sys.exit(1)
        output_dir_abs = os.path.abspath(os.path.join(run_dir, output_dir_rel))
        statistics_output_paths = get_post_statistics_output_artifacts(post_cfg, run_dir, loaded_monitor_cfg)
        post_diagnostics = resolve_diagnostics_config(loaded_monitor_cfg, run_dir, "PostProcessor")
        plan["artifacts"].extend(post_diagnostics["artifacts"])
        post_args = build_petsc_diagnostics_args(loaded_monitor_cfg, run_dir, "PostProcessor") + [
            "-control_file",
            solver_control_path,
            "-postprocessing_config_file",
            post_recipe_path,
        ]
        plan["artifacts"].extend([
            post_recipe_path,
            archived_post_path,
            output_dir_abs,
            post_plan["resume_state_path"],
            post_plan["lock_paths"]["wrapper_path"],
            post_plan["lock_paths"]["lock_file"],
            post_plan["lock_paths"]["metadata_file"],
        ])
        plan["artifacts"].extend(statistics_output_paths)
        if post_finalize_command:
            io_cfg = post_cfg.get("io", {}) or {}
            if _post_requests_eulerian_output(post_cfg):
                plan["artifacts"].append(os.path.join(
                    output_dir_abs, f"{io_cfg.get('output_filename_prefix', 'Field')}.pvd"
                ))
            if _post_requests_particle_output(post_cfg):
                plan["artifacts"].append(os.path.join(
                    output_dir_abs, f"{io_cfg.get('particle_filename_prefix', 'Particle')}.pvd"
                ))
 
        stage_meta = {
            "source_data_directory": post_plan["source_data_directory"],
            "requested_start_step": post_plan["requested_start_step"],
            "requested_end_step": post_plan["requested_end_step"],
            "step_interval": post_plan["step_interval"],
            "recompute": recompute,
            "steps_to_process": post_plan["steps_to_process"],
            "steps_current": post_plan["steps_current"],
            "steps_other_build": post_plan["steps_other_build"],
            "steps_unavailable": post_plan["steps_unavailable"],
            "process_reasons": post_plan["process_reasons"],
            "source_frontier_step": post_plan["source_frontier_step"],
            "source_frontier_diagnostic": post_plan["source_frontier_diagnostic"],
            "source_frontier_deferred": post_plan["source_frontier_deferred"],
            "effective_start_step": post_plan["effective_start_step"],
            "effective_end_step": post_plan["effective_end_step"],
            "skip_reason": post_plan["skip_reason"],
            "post_skipped_as_complete": post_plan["skip_reason"] == "already-complete-window",
            "recipe_fingerprint": post_plan["recipe_fingerprint"],
            "num_procs_effective": post_num_procs_effective,
            "finalize_command": post_finalize_command,
        }
 
        if post_plan["skip_reason"] is None:
            if cluster_mode:
                scheduler_dir = os.path.join(run_dir, "scheduler")
                post_script = os.path.join(scheduler_dir, "post.sbatch")
                post_cluster_cfg = cluster_cfg
                raw_post_cmd = build_cluster_launch_command(
                    post_cluster_cfg,
                    post_exe,
                    post_args,
                    config_search_anchor=case_path,
                    extra_search_anchors=[cluster_path],
                    force_num_procs=post_num_procs_effective,
                )
                post_cmd, _ = build_post_locked_command(
                    run_dir,
                    post_plan["recipe_fingerprint"],
                    raw_post_cmd,
                    create_wrapper=False,
                    success_command=post_finalize_command,
                    post_recipe=archived_post_path,
                    postprocessor=post_exe,
                    recompute=recompute,
                )
                plan["artifacts"].append(post_script)
                stage_meta.update({
                    "mode": "slurm",
                    "script": post_script,
                    "launch_command": post_cmd,
                    "launch_command_string": _command_to_string(post_cmd),
                })
            else:
                raw_post_cmd = build_local_launch_command(
                    post_exe,
                    post_args,
                    post_num_procs_effective,
                    config_search_anchor=case_path,
                    allow_single_rank_launcher_override=True,
                    force_num_procs=post_num_procs_effective,
                )
                post_cmd, _ = build_post_locked_command(
                    run_dir,
                    post_plan["recipe_fingerprint"],
                    raw_post_cmd,
                    create_wrapper=False,
                    success_command=post_finalize_command,
                    post_recipe=archived_post_path,
                    postprocessor=post_exe,
                    recompute=recompute,
                )
                post_stream_log = os.path.join(run_dir, "scheduler", f"{run_id}_{output_prefix}.log")
                plan["artifacts"].append(post_stream_log)
                stage_meta.update({
                    "mode": "local",
                    "stream_log": post_stream_log,
                    "launch_command": post_cmd,
                    "launch_command_string": _command_to_string(post_cmd),
                })
        else:
            stage_meta.update({
                "mode": "slurm" if cluster_mode else "local",
                "launch_command": [],
                "launch_command_string": "",
            })
 
        plan["stages"]["post-process"] = stage_meta
 
    # Preserve insertion order while removing duplicates.
    deduped = []
    seen = set()
    for item in plan["artifacts"]:
        if item not in seen:
            seen.add(item)
            deduped.append(item)
    plan["artifacts"] = deduped
    if run_id and "run_id_preview" not in plan:
        plan["run_id_preview"] = run_id
    if run_dir and "run_dir_preview" not in plan:
        plan["run_dir_preview"] = run_dir
    plan["solver_num_procs_effective"] = solver_num_procs_effective
    plan["post_num_procs_effective"] = post_num_procs_effective
    plan["num_procs_effective"] = solver_num_procs_effective
    return plan
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

add_planned_grid_artifacts()

None picurv_cli.core.add_planned_grid_artifacts	(	dict	plan,
		dict	case_cfg,
		str	run_dir
	)

Add grid-mode-specific staged artifacts to a dry-run plan.

Parameters

[in,out]	plan	Dry-run plan to update.
[in]	case_cfg	Parsed case configuration.
[in]	run_dir	Preview run directory for relative artifact resolution.

Definition at line 19149 of file core.py.

def add_planned_grid_artifacts(plan: dict, case_cfg: dict, run_dir: str) -> None:
    """!
    @brief Add grid-mode-specific staged artifacts to a dry-run plan.
    @param[in,out] plan Dry-run plan to update.
    @param[in] case_cfg Parsed case configuration.
    @param[in] run_dir Preview run directory for relative artifact resolution.
    """
    grid_cfg = case_cfg.get("grid", {})
    if not isinstance(grid_cfg, dict):
        return
 
    mode = grid_cfg.get("mode")
    grid_dir = os.path.join(run_dir, "inputs", "grid")
 
    if mode == "file":
        plan["artifacts"].append(os.path.join(grid_dir, "grid.run"))
    elif mode == "grid_gen":
        generator = grid_cfg.get("generator", {})
        if not isinstance(generator, dict):
            return
        plan["artifacts"].extend([
            os.path.join(grid_dir, "grid.run"),
            os.path.join(grid_dir, "grid.generated.picgrid"),
            os.path.join(run_dir, "output", "analysis", "metrics", "grid.info"),
            os.path.join(run_dir, "output", "visualization", "precompute", "grid.vts"),
        ])
 

Here is the caller graph for this function:

add_planned_profile_artifacts()

None picurv_cli.core.add_planned_profile_artifacts	(	dict	plan,
		dict	case_cfg,
		str	run_dir
	)

Add generated prescribed-flow profile artifacts to a dry-run plan.

Parameters

[in,out]	plan	Dry-run plan to update.
[in]	case_cfg	Parsed case configuration.
[in]	run_dir	Preview run directory.

Definition at line 19176 of file core.py.

def add_planned_profile_artifacts(plan: dict, case_cfg: dict, run_dir: str) -> None:
    """!
    @brief Add generated prescribed-flow profile artifacts to a dry-run plan.
    @param[in,out] plan Dry-run plan to update.
    @param[in] case_cfg Parsed case configuration.
    @param[in] run_dir Preview run directory.
    """
    try:
        prepared_blocks = validate_and_prepare_boundary_conditions(case_cfg)
    except ValueError:
        return
    profile_dir = os.path.join(run_dir, "inputs", "inlet_profiles")
    has_generated = False
    for block_idx, block in enumerate(prepared_blocks):
        for bc in block:
            if bc.get("handler") != "prescribed_flow":
                continue
            source = (bc.get("params") or {}).get("source", {})
            if source.get("type") not in PRESCRIBED_FLOW_SOURCE_TYPES[1:]:
                continue
            has_generated = True
            face_token = _face_artifact_token(bc["face"])
            suffix = "generated" if source.get("type") == "generated" else "sliced"
            generated_path = os.path.join(
                profile_dir, f"inlet_profile_block{block_idx}_{face_token}.{suffix}.dimensional.picslice"
            )
            staged_path = os.path.join(profile_dir, f"inlet_profile_block{block_idx}_{face_token}.picslice")
            plan["artifacts"].append(generated_path)
            plan["artifacts"].append(staged_path)
    if has_generated:
        plan["artifacts"].append(os.path.join(profile_dir, "profile.info"))
 

Here is the call graph for this function:

Here is the caller graph for this function:

add_planned_initial_condition_artifacts()

None picurv_cli.core.add_planned_initial_condition_artifacts	(	dict	plan,
		dict	case_cfg,
		dict	solver_cfg,
		str	run_dir
	)

Add authoritative file-backed initial-condition artifacts to a dry-run plan.

Parameters

[in,out]	plan	Dry-run plan receiving artifact paths.
[in]	case_cfg	Parsed case configuration.
[in]	solver_cfg	Parsed solver configuration.
[in]	run_dir	Planned run directory.

Definition at line 19208 of file core.py.

def add_planned_initial_condition_artifacts(plan: dict, case_cfg: dict, solver_cfg: dict, run_dir: str) -> None:
    """!
    @brief Add authoritative file-backed initial-condition artifacts to a dry-run plan.
    @param[in,out] plan Dry-run plan receiving artifact paths.
    @param[in] case_cfg Parsed case configuration.
    @param[in] solver_cfg Parsed solver configuration.
    @param[in] run_dir Planned run directory.
    """
    source = normalize_eulerian_field_source(
        (solver_cfg.get("operation_mode", {}) or {}).get("eulerian_field_source", "solve")
    )
    start_step = int((case_cfg.get("run_control", {}) or {}).get("start_step", 0) or 0)
    if source != "solve" or start_step != 0:
        return
    try:
        fluid_scaling = resolve_fluid_scaling(case_cfg)
        resolved = resolve_initial_condition_config(
            (case_cfg.get("properties", {}) or {}).get("initial_conditions", {}),
            validate_and_prepare_boundary_conditions(case_cfg),
            scales=fluid_scaling,
            provider_context={"kinematic_viscosity": fluid_scaling["nondimensional_kinematic_viscosity"]},
        )
    except (KeyError, ValueError):
        return
    if resolved["kind"] != "file" and not is_generated_ic_provider(resolved):
        return
    initial_dir = os.path.join(run_dir, "inputs", "initial_condition")
    plan["artifacts"].append(
        os.path.join(initial_dir, f"{resolved['field_name']}00000_0.dat")
    )
    if is_generated_ic_provider(resolved):
        if (case_cfg.get("grid", {}) or {}).get("mode") == "programmatic_c":
            plan["artifacts"].append(os.path.join(run_dir, "inputs", "grid", "grid.run"))
        plan["artifacts"].append(os.path.join(initial_dir, "initial_condition.generated.dat"))
        plan["artifacts"].extend(initial_condition_diagnostic_paths(run_dir, resolved))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

render_run_dry_plan()

picurv_cli.core.render_run_dry_plan	(	dict	plan,
		str	output_format = "text"
	)

Render dry-run plan in human or JSON format.

Parameters

[in]	plan	Dry-run plan produced by build_run_dry_plan().
[in]	output_format	Either "text" or "json".

Returns

1 when the plan carries blocking findings, 0 otherwise.

Definition at line 19245 of file core.py.

def render_run_dry_plan(plan: dict, output_format: str = "text"):
    """!
    @brief Render dry-run plan in human or JSON format.
    @param[in] plan Dry-run plan produced by build_run_dry_plan().
    @param[in] output_format Either "text" or "json".
    @return 1 when the plan carries blocking findings, 0 otherwise.
    """
    if output_format == "json":
        print(json.dumps(plan, indent=2, sort_keys=True))
        return 1 if plan.get("blocking") else 0
 
    for message in plan.get("warnings", []):
        print(f"[WARNING]   {message}", file=sys.stderr)
    if plan.get("blocking"):
        print("[FATAL] This configuration would be refused. The plan below is what the "
              "run WOULD do; it will not get that far:", file=sys.stderr)
        for message in plan["blocking"]:
            print(f"  {message}", file=sys.stderr)
 
    print("\n" + "=" * 60)
    print("                      DRY-RUN PLAN")
    print("=" * 60)
    print(f"  Launch mode     : {plan.get('launch_mode')}")
    print(f"  Created at      : {plan.get('created_at')}")
    if plan.get("run_id_preview"):
        print(f"  Run ID preview  : {plan.get('run_id_preview')}")
    if plan.get("run_dir_preview"):
        print(f"  Run dir preview : {plan.get('run_dir_preview')}")
    lineage = plan.get("lineage") or {}
    if lineage.get("relationship") == "branch":
        print(f"  Branched from   : {lineage.get('parent_run_id')} "
              f"@ step {lineage.get('checkpoint_step')} "
              f"(statistics: {lineage.get('statistics_state')})")
    planned_stages = plan.get("stages") or {}
    if "solve" in planned_stages:
        print(f"  Solver MPI procs: {plan.get('solver_num_procs_effective')}")
        if "start_step" in planned_stages["solve"]:
            print(f"  Solver steps    : {planned_stages['solve']['start_step']} -> "
                  f"{planned_stages['solve']['end_step']}")
    if "post-process" in planned_stages:
        print(f"  Post MPI procs  : {plan.get('post_num_procs_effective')}")
    for key, label in (("decomposition", "Solver"), ("post_decomposition", "Post")):
        if plan.get(key):
            print(f"  {label} {plan[key]['summary']}")
    if plan.get("warnings"):
        print("  Warnings        :")
        for warning in plan["warnings"]:
            print(f"    - {warning}")
 
    if plan.get("inputs"):
        print("\n  Inputs:")
        for key, value in plan["inputs"].items():
            print(f"    - {key}: {value}")
 
    if plan.get("stages"):
        print("\n  Planned stage commands:")
        for stage, details in plan["stages"].items():
            print(f"    - {stage} ({details.get('mode')}):")
            if details.get('skip_reason'):
                print(f"      skipped: {details.get('skip_reason')}")
            else:
                print(f"      {details.get('launch_command_string')}")
 
    if plan.get("asset_actions"):
        print("\n  Asset resolution:")
        for item in plan["asset_actions"]:
            print(f"    - {item['kind']}: {item['action']} ({item['provider']})")
 
    diagnostics_artifacts = [item for item in plan.get("artifacts", []) if "PETSc_" in os.path.basename(str(item)) or os.path.basename(str(item)) == RUNTIME_MEMORY_FILE]
    if diagnostics_artifacts:
        print("\n  Diagnostics artifacts:")
        for artifact in diagnostics_artifacts:
            print(f"    - {artifact}")
 
    print("\n  Planned artifacts (no files created in dry-run):")
    for artifact in plan.get("artifacts", []):
        print(f"    - {artifact}")
    print("=" * 60)
 
 

Here is the caller graph for this function:

validate_workflow()

picurv_cli.core.validate_workflow

(

args

)

Implements picurv validate without launching solver/post workflows.

Parameters

[in]

args

Command-line style argument list supplied to the function.

Definition at line 19325 of file core.py.

def validate_workflow(args):
    """!
    @brief Implements `picurv validate` without launching solver/post workflows.
    @param[in] args Command-line style argument list supplied to the function.
    """
    checked = []
    solver_group_selected = any([args.case, args.solver, args.monitor])
    any_group_selected = solver_group_selected or any([args.post, args.cluster, args.study])
    case_path = None
    cluster_path = None
 
    if getattr(args, 'continue_run', False) and not getattr(args, 'run_dir', None):
        fail_cli_usage(RESTART_RUN_DIR_REQUIRED_MESSAGE)
    if not any_group_selected:
        fail_cli_usage(
            "validate requires at least one config group. Provide solver trio and/or --post/--cluster/--study.",
            hint="Example: picurv validate --case case.yml --solver solver.yml --monitor monitor.yml --post post.yml",
        )
 
    if solver_group_selected and not all([args.case, args.solver, args.monitor]):
        fail_cli_usage("When solver validation is requested, --case, --solver, and --monitor are all required.")
 
    # --- Guard: restart flags without solver group ---
    restart_from = getattr(args, 'restart_from', None)
    continue_run = getattr(args, 'continue_run', False)
    run_dir_val = getattr(args, 'run_dir', None)
    if not solver_group_selected:
        if restart_from:
            print("[WARNING] --restart-from has no effect without --case/--solver/--monitor and will be ignored.", file=sys.stderr)
        if continue_run:
            print("[WARNING] --continue validates a solve continued in place and needs "
                  "--case/--solver/--monitor; it is ignored here.", file=sys.stderr)
 
    monitor_cfg = None
    case_cfg = None
    if solver_group_selected:
        case_path = os.path.abspath(args.case)
        solver_path = os.path.abspath(args.solver)
        monitor_path = os.path.abspath(args.monitor)
        case_cfg = read_yaml_file(case_path)
        solver_cfg = read_yaml_file(solver_path)
        monitor_cfg = read_yaml_file(monitor_path)
        validate_simulation_configs(
            case_cfg, solver_cfg, monitor_cfg, case_path, solver_path, monitor_path,
            restart_source_given=bool(restart_from or continue_run),
        )
        checked.extend([case_path, solver_path, monitor_path])
 
        # Validate restart flags if provided
        if restart_from or continue_run:
            target_run_dir = os.path.abspath(run_dir_val) if run_dir_val else os.path.abspath("runs/_validate_dummy")
            try:
                resolve_restart_source(args, case_cfg, solver_cfg, monitor_cfg, target_run_dir)
                print("[SUCCESS] Restart source validation passed.")
            except ValueError as e:
                print(f"[FATAL] Restart validation failed: {e}", file=sys.stderr)
                sys.exit(1)
 
    post_cfg = None
    if args.post:
        post_path = os.path.abspath(args.post)
        post_cfg = read_yaml_file(post_path)
        validate_post_config(post_cfg, post_path, monitor_cfg, case_cfg)
        checked.append(post_path)
 
    cluster_cfg = None
    if args.cluster:
        cluster_path = os.path.abspath(args.cluster)
        cluster_cfg = read_yaml_file(cluster_path)
        validate_cluster_config(cluster_cfg, cluster_path)
        checked.append(cluster_path)
 
    # The rank layout that run --dry-run checks; without a cluster profile the process
    # count is unknown, so only each axis is checked against the coarsest multigrid level.
    if solver_group_selected:
        grid_cfg = case_cfg.get("grid") or {}
        block_dims = resolve_grid_node_dims(case_cfg, case_path)
        if cluster_cfg:
            tasks = get_cluster_total_tasks(cluster_cfg)
            decomposition = resolve_decomposition(tasks, grid_cfg, block_dims, solver_cfg,
                                                  case_declares_periodic_axis(case_cfg), None, cluster_cfg)
            layout_problems = decomposition["problems"]
            if not layout_problems:
                print(f"[INFO] {describe_decomposition(decomposition, tasks)}")
        else:
            layout_problems = da_processor_layout_problems(
                grid_cfg, None, block_dims, solver_cfg, case_declares_periodic_axis(case_cfg))
        if layout_problems:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="grid.da_processors",
                file_path=case_path,
                message=" ".join(layout_problems),
            )
            sys.exit(1)
        if block_dims is None and resolve_grid_da_processor_layout(grid_cfg):
            print(f"[WARNING] {case_path}: could not determine the grid's dimensions without building "
                  "it, so the da_processors layout was not checked against the multigrid levels.",
                  file=sys.stderr)
 
    try:
        runtime_execution_path, _ = load_runtime_execution_config(
            case_path,
            extra_search_anchors=[cluster_path] if cluster_path else None,
        )
    except ValueError as exc:
        emit_structured_error(
            ERROR_CODE_CFG_INVALID_VALUE,
            key="runtime_execution",
            file_path=case_path or cluster_path or os.getcwd(),
            message=str(exc),
        )
        sys.exit(1)
    if runtime_execution_path:
        checked.append(runtime_execution_path)
 
    study_cfg = None
    if args.study:
        study_path = os.path.abspath(args.study)
        study_cfg = read_yaml_file(study_path)
        validate_study_config(study_cfg, study_path)
        checked.append(study_path)
 
    if post_cfg is not None and run_dir_val:
        post_path = os.path.abspath(args.post)
        validate_run_dir = os.path.abspath(run_dir_val)
        if os.path.isdir(validate_run_dir):
            monitor_for_post = monitor_cfg if solver_group_selected else None
            if monitor_for_post is None:
                config_dir_candidate = os.path.join(validate_run_dir, "config")
                monitor_candidate = os.path.join(config_dir_candidate, "monitor.yml")
                if os.path.isfile(monitor_candidate):
                    monitor_for_post = read_yaml_file(monitor_candidate)
            if monitor_for_post is not None:
                resolved_source = _resolve_post_source_directory_preview(validate_run_dir, monitor_for_post, post_cfg)
                if os.path.isdir(resolved_source) and os.listdir(resolved_source):
                    print(f"[SUCCESS] Post-processor source data directory exists: {resolved_source}")
                else:
                    print(f"[WARNING] Post-processor source data directory is missing or empty: {resolved_source}", file=sys.stderr)
 
    if post_cfg is not None:
        # apply_canonical_post_paths always reads the run's own output, so a configured
        # directory is never used; say so instead of checking that it exists.
        source_dir = (post_cfg.get("source_data") or {}).get("directory")
        if source_dir and source_dir != "<solver_output_dir>":
            print(f"[WARNING] {os.path.abspath(args.post)}: source_data.directory '{source_dir}' is "
                  "ignored; post-processing always reads the run's own output. Remove the key.",
                  file=sys.stderr)
 
    if args.strict and study_cfg is not None:
        study_path = os.path.abspath(args.study)
        base_cfgs = study_cfg.get("base_configs", {})
        if isinstance(base_cfgs, dict):
            base_case_path = resolve_path(study_path, base_cfgs.get("case"))
            base_solver_path = resolve_path(study_path, base_cfgs.get("solver"))
            base_monitor_path = resolve_path(study_path, base_cfgs.get("monitor"))
            base_post_path = resolve_path(study_path, base_cfgs.get("post"))
            if all([base_case_path, base_solver_path, base_monitor_path]):
                validate_simulation_configs(
                    read_yaml_file(base_case_path),
                    read_yaml_file(base_solver_path),
                    read_yaml_file(base_monitor_path),
                    base_case_path,
                    base_solver_path,
                    base_monitor_path,
                )
            if base_post_path:
                validate_post_config(read_yaml_file(base_post_path), base_post_path,
                                     read_yaml_file(base_monitor_path) if base_monitor_path else None,
                                     read_yaml_file(base_case_path) if base_case_path else None)
 
    print(f"[SUCCESS] Validation completed for {len(checked)} file(s).")
    for path in checked:
        print(f"  - {path}")
 

Here is the call graph for this function:

Here is the caller graph for this function:

_asset_file_sha256()

str picurv_cli.core._asset_file_sha256 ( str  path )

protected

Hash an asset source or payload without loading it into memory.

Parameters

[in]

path

File to hash.

Returns

Lowercase SHA-256 digest.

Definition at line 19507 of file core.py.

def _asset_file_sha256(path: str) -> str:
    """!
    @brief Hash an asset source or payload without loading it into memory.
    @param[in] path File to hash.
    @return Lowercase SHA-256 digest.
    """
    digest = hashlib.sha256()
    with open(path, "rb") as stream:
        for block in iter(lambda: stream.read(8 * 1024 * 1024), b""):
            digest.update(block)
    return digest.hexdigest()
 
 

Here is the caller graph for this function:

_stable_mapping_sha256()

str picurv_cli.core._stable_mapping_sha256 (   payload )

protected

Hash a JSON-compatible value with deterministic serialization.

Parameters

[in]

payload

Value to hash.

Returns

Lowercase SHA-256 digest.

Definition at line 19520 of file core.py.

def _stable_mapping_sha256(payload) -> str:
    """!
    @brief Hash a JSON-compatible value with deterministic serialization.
    @param[in] payload Value to hash.
    @return Lowercase SHA-256 digest.
    """
    encoded = json.dumps(payload, sort_keys=True, separators=(",", ":"), default=str).encode("utf-8")
    return hashlib.sha256(encoded).hexdigest()
 
 

Here is the caller graph for this function:

_provider_source_fingerprints()

dict picurv_cli.core._provider_source_fingerprints (   value, str  case_path, str   key = ""  )

protected

Hash every existing file explicitly referenced by an asset provider.

Parameters

[in]	value	Provider subtree to inspect.
[in]	case_path	Owning case configuration path.
[in]	key	Current dotted key for diagnostics.

Returns

Mapping of dotted path identity to path/content fingerprint.

Definition at line 19530 of file core.py.

def _provider_source_fingerprints(value, case_path: str, key: str = "") -> dict:
    """!
    @brief Hash every existing file explicitly referenced by an asset provider.
    @param[in] value Provider subtree to inspect.
    @param[in] case_path Owning case configuration path.
    @param[in] key Current dotted key for diagnostics.
    @return Mapping of dotted path identity to path/content fingerprint.
    """
    result = {}
    if isinstance(value, dict):
        for child_key, child in value.items():
            dotted = f"{key}.{child_key}" if key else str(child_key)
            result.update(_provider_source_fingerprints(child, case_path, dotted))
        return result
    if isinstance(value, list):
        for index, child in enumerate(value):
            result.update(_provider_source_fingerprints(child, case_path, f"{key}[{index}]"))
        return result
    basename = key.rsplit(".", 1)[-1]
    if basename not in _ASSET_SOURCE_REFERENCE_KEYS or not isinstance(value, str) or not value.strip():
        return result
    try:
        resolved = resolve_workspace_path(case_path, value)
    except ValueError:
        return result
    if os.path.isfile(resolved):
        workspace_root = find_workspace_root(case_path)
        display = (
            os.path.relpath(resolved, workspace_root).replace(os.sep, "/")
            if workspace_root and os.path.commonpath([workspace_root, resolved]) == workspace_root
            else resolved
        )
        result[key] = {"path": display, "sha256": _asset_file_sha256(resolved)}
    return result
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

build_case_asset_graph()

dict picurv_cli.core.build_case_asset_graph	(	dict	case_cfg,
		str	case_path
	)

Classify case inputs into precomputable or simulator-runtime providers.

Parameters

[in]	case_cfg	Parsed case configuration.
[in]	case_path	Owning case YAML path.

Returns

Provider graph with stable identities and explicit dependencies.

Definition at line 19566 of file core.py.

def build_case_asset_graph(case_cfg: dict, case_path: str) -> dict:
    """!
    @brief Classify case inputs into precomputable or simulator-runtime providers.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Owning case YAML path.
    @return Provider graph with stable identities and explicit dependencies.
    """
    providers = []
    grid_cfg = copy.deepcopy(case_cfg.get("grid", {}) or {})
    grid_mode = str(grid_cfg.get("mode", "")).strip().lower()
    if isinstance(grid_cfg.get("generator"), dict):
        grid_cfg["generator"].pop("output_file", None)
        grid_cfg["generator"].pop("vts_file", None)
        grid_cfg["generator"].pop("stats_file", None)
    grid_provider = {
        "kind": "grid",
        "provider": grid_mode or "missing",
        "execution": "runtime-c" if grid_mode == "programmatic_c" else "precomputable",
        "dependencies": [],
        "spec": grid_cfg,
    }
    providers.append(grid_provider)
 
    initial = copy.deepcopy(
        ((case_cfg.get("properties") or {}).get("initial_conditions") or {})
    )
    initial_mode = str(initial.get("mode", "generated")).strip().lower()
    initial_generator = str(initial.get("generator", "constant")).strip().lower()
    generated_python = (
        initial_mode == "generated"
        and initial_generator in _PYTHON_INITIAL_CONDITION_PROVIDERS
    )
    initial_provider = {
        "kind": "initial-condition",
        "provider": "file" if initial_mode == "file" else initial_generator,
        "execution": "precomputable" if initial_mode == "file" or generated_python else "runtime-c",
        "dependencies": ["grid"] if generated_python else [],
        "spec": initial,
    }
    providers.append(initial_provider)
 
    inlet_specs = []
    raw_blocks = case_cfg.get("boundary_conditions") or []
    if raw_blocks and isinstance(raw_blocks[0], dict):
        raw_blocks = [raw_blocks]
    for block_index, block in enumerate(raw_blocks):
        for entry in block or []:
            if not isinstance(entry, dict) or str(entry.get("handler", "")).strip().lower() != "prescribed_flow":
                continue
            source = copy.deepcopy(((entry.get("params") or {}).get("source") or {}))
            inlet_specs.append({"block": block_index, "face": entry.get("face"), "source": source})
    if inlet_specs:
        field_slice = any((item.get("source") or {}).get("type") == "field_slice" for item in inlet_specs)
        providers.append({
            "kind": "inlet-profiles",
            "provider": "prescribed-flow",
            "execution": "precomputable",
            "dependencies": ["grid"] if field_slice or grid_mode in _FILE_BACKED_GRID_VALUES else [],
            "spec": inlet_specs,
        })
 
    # A provider's identity has to cover every case value its build reads, not only its
    # own configuration subtree. The grid build nondimensionalizes by
    # properties.scaling.length_ref and validates against the declared block count;
    # both are outside `grid:`, and a change to either produces different payload bytes
    # from an identical provider spec. Left out, the staleness check reports `reuse`
    # and the solver silently receives geometry scaled by the wrong reference length.
    scaling = (case_cfg.get("properties") or {}).get("scaling") or {}
    fluid = (case_cfg.get("properties") or {}).get("fluid") or {}
    domain_blocks = (case_cfg.get("models") or {}).get("domain", {}).get("blocks", 1)
    build_contexts = {
        "grid": {
            "length_ref": scaling.get("length_ref"),
            "blocks": domain_blocks,
        },
        # The IC build resolves fluid scaling and the prepared boundary conditions.
        "initial-condition": {
            "length_ref": scaling.get("length_ref"),
            "velocity_ref": scaling.get("velocity_ref"),
            "density": fluid.get("density"),
            "viscosity": fluid.get("viscosity"),
            "boundary_conditions": case_cfg.get("boundary_conditions"),
        },
        # Profile generation dimensionalizes against the same scaling contract. On a
        # programmatic_c grid, which is not an asset the profile can depend on, it samples
        # the bridge built from programmatic_settings, so those settings are read too.
        "inlet-profiles": {
            "length_ref": scaling.get("length_ref"),
            "velocity_ref": scaling.get("velocity_ref"),
            "blocks": domain_blocks,
            "programmatic_settings": (
                grid_cfg.get("programmatic_settings") if grid_mode == "programmatic_c" else None
            ),
        },
    }
 
    # Hash in dependency order so a provider built on top of another re-identifies when
    # the thing it was built from changes.
    by_kind = {provider["kind"]: provider for provider in providers}
    resolved_order = sorted(
        providers, key=lambda provider: len(provider.get("dependencies") or [])
    )
    for provider in resolved_order:
        provider["build_context"] = build_contexts.get(provider["kind"], {})
        provider["source_files"] = _provider_source_fingerprints(provider["spec"], case_path)
        provider["software"] = {
            "release_version": PICURV_RELEASE_VERSION,
            "git_commit": picurv_build().get("git_commit"),
        }
        provider["spec_sha256"] = _stable_mapping_sha256({
            "kind": provider["kind"],
            "provider": provider["provider"],
            "spec": provider["spec"],
            "build_context": provider["build_context"],
            "source_files": provider["source_files"],
            "software": provider["software"],
            "dependencies": {
                name: by_kind[name].get("spec_sha256")
                for name in (provider.get("dependencies") or [])
                if name in by_kind
            },
        })
    return {
        "case_sha256": _stable_mapping_sha256(case_cfg),
        "providers": providers,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_asset_selection()

list picurv_cli.core._asset_selection ( dict  graph,   requested = None, *bool   precomputable_only = False  )

protected

Resolve requested asset kinds plus dependency closure.

Parameters

[in]	graph	Provider graph returned by build_case_asset_graph.
[in]	requested	Optional iterable of requested kind names.
[in]	precomputable_only	Exclude runtime-C providers for normal-run staging.

Returns

Ordered provider list.

Definition at line 19694 of file core.py.

def _asset_selection(graph: dict, requested=None, *, precomputable_only: bool = False) -> list:
    """!
    @brief Resolve requested asset kinds plus dependency closure.
    @param[in] graph Provider graph returned by build_case_asset_graph.
    @param[in] requested Optional iterable of requested kind names.
    @param[in] precomputable_only Exclude runtime-C providers for normal-run staging.
    @return Ordered provider list.
    """
    by_kind = {item["kind"]: item for item in graph["providers"]}
    requested_set = set(requested or by_kind)
    unknown = requested_set - set(by_kind)
    if unknown:
        raise ValueError(
            f"No configured provider exists for asset kind(s): {sorted(unknown)}. "
            f"Configured kinds: {sorted(by_kind)}."
        )
    closure = set()
 
    def add(kind):
        """!
        @brief Add one requested asset kind and its dependency closure.
        @param[in] kind Asset kind to include.
        @return None.
        """
        if kind in closure:
            return
        closure.add(kind)
        for dependency in by_kind[kind].get("dependencies", []):
            if dependency in by_kind:
                add(dependency)
 
    for kind in requested_set:
        add(kind)
    selected = [item for item in graph["providers"] if item["kind"] in closure]
    if precomputable_only:
        selected = [item for item in selected if item["execution"] == "precomputable"]
    return selected
 
 

Here is the caller graph for this function:

_asset_payload_files()

list picurv_cli.core._asset_payload_files ( str  build_root, str  kind  )

protected

Enumerate canonical files belonging to one asset kind in a build tree.

Parameters

[in]	build_root	Temporary run-like build root.
[in]	kind	Asset kind.

Returns

Absolute payload file paths.

Definition at line 19733 of file core.py.

def _asset_payload_files(build_root: str, kind: str) -> list:
    """!
    @brief Enumerate canonical files belonging to one asset kind in a build tree.
    @param[in] build_root Temporary run-like build root.
    @param[in] kind Asset kind.
    @return Absolute payload file paths.
    """
    roots = {
        "grid": ["inputs/grid", "output/analysis/metrics", "output/visualization/precompute"],
        "initial-condition": ["inputs/initial_condition", "output/analysis/spectra", "output/analysis/metrics"],
        "inlet-profiles": ["inputs/inlet_profiles"],
    }[kind]
    result = []
    for relative in roots:
        root = Path(build_root, *relative.split("/"))
        if root.is_dir():
            result.extend(str(path) for path in sorted(root.rglob("*")) if path.is_file())
    intermediate_names = {
        "grid": {"grid.generated.picgrid", "grid.converted.picgrid"},
        "initial-condition": {"initial_condition.generated.dat"},
        "inlet-profiles": set(),
    }[kind]
    return [
        path for path in dict.fromkeys(result)
        if os.path.basename(path) not in intermediate_names
    ]
 
 

Here is the caller graph for this function:

_build_selected_asset_payloads()

dict picurv_cli.core._build_selected_asset_payloads ( str  build_root, dict  case_cfg, str  case_path, list  selected  )

protected

Execute existing generators into one isolated run-like build tree.

Parameters

[in]	build_root	Temporary output root.
[in]	case_cfg	Parsed case config.
[in]	case_path	Owning case path.
[in]	selected	Ordered selected providers.

Returns

Asset-kind to generated file list.

Definition at line 19761 of file core.py.

                                   selected: list) -> dict:
    """!
    @brief Execute existing generators into one isolated run-like build tree.
    @param[in] build_root Temporary output root.
    @param[in] case_cfg Parsed case config.
    @param[in] case_path Owning case path.
    @param[in] selected Ordered selected providers.
    @return Asset-kind to generated file list.
    """
    ensure_run_layout(build_root)
    selected_kinds = {item["kind"] for item in selected}
    payloads = {}
 
    def fingerprint(kind):
        """!
        @brief Snapshot current payload checksums for one asset kind.
        @param[in] kind Asset kind to inspect.
        @return Absolute-path to checksum mapping.
        """
        return {
            path: _asset_file_sha256(path)
            for path in _asset_payload_files(build_root, kind)
        }
 
    def record_changes(kind, before):
        """!
        @brief Record files created or changed by one provider stage.
        @param[in] kind Asset kind whose build just completed.
        @param[in] before Pre-build checksum mapping.
        @return None.
        """
        after = fingerprint(kind)
        payloads[kind] = [
            path for path, digest in after.items()
            if before.get(path) != digest
        ]
 
    grid_cfg = case_cfg.get("grid", {}) or {}
    expected_nblk = int((case_cfg.get("models", {}) or {}).get("domain", {}).get("blocks", 1))
    staged_grid = os.path.join(build_root, "inputs", "grid", "grid.run")
    if "grid" in selected_kinds:
        before = fingerprint("grid")
        if grid_cfg.get("mode") in _FILE_BACKED_GRID_VALUES:
            grid_length_scale = input_reference_scale(("case", "grid", "source_file"),
                                                      resolve_reference_scales(case_cfg))
        if grid_cfg.get("mode") == "grid_gen":
            generated = run_grid_generator(case_path, build_root, grid_cfg, case_cfg=case_cfg)
            validate_and_nondimensionalize_picgrid(
                generated, staged_grid, grid_length_scale, expected_nblk=expected_nblk
            )
        elif grid_cfg.get("mode") == "file":
            source = _resolve_case_relative_path(
                grid_cfg.get("source_file"), os.path.dirname(os.path.abspath(case_path))
            )
            validate_and_nondimensionalize_picgrid(
                source, staged_grid, grid_length_scale, expected_nblk=expected_nblk
            )
        record_changes("grid", before)
 
    if "inlet-profiles" in selected_kinds:
        before = fingerprint("inlet-profiles")
        generate_multi_block_bcs(
            build_root, "asset-build", case_cfg,
            {"Case": case_path},
        )
        record_changes("inlet-profiles", before)
 
    if "initial-condition" in selected_kinds:
        before = fingerprint("initial-condition")
        fluid_scaling = resolve_fluid_scaling(case_cfg)
        resolved_ic = resolve_initial_condition_config(
            (case_cfg.get("properties", {}) or {}).get("initial_conditions", {}),
            validate_and_prepare_boundary_conditions(case_cfg),
            scales=fluid_scaling,
            provider_context={
                "kinematic_viscosity": fluid_scaling["nondimensional_kinematic_viscosity"]
            },
        )
        if (grid_cfg.get("mode") == "programmatic_c" and is_generated_ic_provider(resolved_ic)
                and not os.path.isfile(staged_grid)):
            # "grid" is excluded from this closure when the caller passed
            # precomputable_only=True (materialize_run_assets, staging before a solve): a
            # runtime-C grid is never itself precomputed. But the Python IC generator run
            # below is a separate process from the solver and needs real coordinates on
            # disk regardless. This bridge uses the identical formula as
            # ComputeStretchedCoord in src/grid.c, so it is guaranteed to match what the
            # solver builds moments later; it is not published as its own asset, since a
            # programmatic_c grid is never a persisted asset in its own right.
            generate_picgrid_from_programmatic_settings(
                grid_cfg.get("programmatic_settings", {}), staged_grid,
                input_reference_scale(("case", "grid", "programmatic_settings", "xMins"), fluid_scaling),
            )
        stage_initial_condition_file(build_root, case_path, resolved_ic)
        record_changes("initial-condition", before)
    return payloads
 
 
#: Largest grid, in nodes, for which a published asset carries an inline VTS preview.
#: Beyond this the ASCII payload costs more than the inspection is worth, and
#: validation.json records that it was skipped rather than silently omitting it.

Here is the call graph for this function:

Here is the caller graph for this function:

_picgrid_geometry_summary()

dict picurv_cli.core._picgrid_geometry_summary ( str  path )

protected

Read a canonical PICGRID and summarize what a user would want to check.

Parameters

[in]

path

Staged PICGRID file.

Returns

Mapping of block dimensions, bounds, and spacing extremes.

Definition at line 19865 of file core.py.

def _picgrid_geometry_summary(path: str) -> dict:
    """!
    @brief Read a canonical PICGRID and summarize what a user would want to check.
    @param[in] path Staged PICGRID file.
    @return Mapping of block dimensions, bounds, and spacing extremes.
    """
    dims = read_picgrid_header_dimensions(path)
    bounds = [[float("inf")] * 3, [float("-inf")] * 3]
    nodes = 0
    with open(path, "r", encoding="utf-8", errors="replace") as stream:
        iterator = _iter_nonempty_noncomment_lines(stream)
        # Header token, block count, and one dimension row per block.
        for _ in range(2 + len(dims)):
            next(iterator, None)
        for _lineno, line in iterator:
            parts = line.split()
            if len(parts) != 3:
                continue
            try:
                point = [float(value) for value in parts]
            except ValueError:
                continue
            nodes += 1
            for axis in range(3):
                bounds[0][axis] = min(bounds[0][axis], point[axis])
                bounds[1][axis] = max(bounds[1][axis], point[axis])
    extent = [bounds[1][axis] - bounds[0][axis] for axis in range(3)] if nodes else [0.0, 0.0, 0.0]
    return {
        "blocks": len(dims),
        "dimensions": [list(item) for item in dims],
        "total_nodes": nodes,
        "bounds_min": bounds[0] if nodes else None,
        "bounds_max": bounds[1] if nodes else None,
        "extent": extent,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_write_structured_grid_preview()

bool picurv_cli.core._write_structured_grid_preview ( str  picgrid_path, str  destination,   dims  )

protected

Write a single-block ASCII VTS preview of a staged PICGRID.

Only the first block is written: the preview exists so a user can confirm the shape they configured, not to reproduce the solver's view of a multi-block domain.

Parameters

[in]	picgrid_path	Staged PICGRID file.
[in]	destination	Preview path to write.
[in]	dims	Per-block dimension triples.

Returns

True when a preview was written.

Definition at line 19902 of file core.py.

def _write_structured_grid_preview(picgrid_path: str, destination: str, dims) -> bool:
    """!
    @brief Write a single-block ASCII VTS preview of a staged PICGRID.
 
    @details Only the first block is written: the preview exists so a user can confirm
             the shape they configured, not to reproduce the solver's view of a
             multi-block domain.
    @param[in] picgrid_path Staged PICGRID file.
    @param[in] destination Preview path to write.
    @param[in] dims Per-block dimension triples.
    @return True when a preview was written.
    """
    if not dims:
        return False
    im, jm, km = (int(value) for value in dims[0])
    if im * jm * km > ASSET_PREVIEW_NODE_LIMIT:
        return False
    coordinates = []
    with open(picgrid_path, "r", encoding="utf-8", errors="replace") as stream:
        iterator = _iter_nonempty_noncomment_lines(stream)
        for _ in range(2 + len(dims)):
            next(iterator, None)
        for _lineno, line in iterator:
            parts = line.split()
            if len(parts) == 3:
                coordinates.append(line)
            if len(coordinates) >= im * jm * km:
                break
    if len(coordinates) < im * jm * km:
        return False
    os.makedirs(os.path.dirname(destination), exist_ok=True)
    with open(destination, "w", encoding="utf-8") as out:
        extent = f"0 {im - 1} 0 {jm - 1} 0 {km - 1}"
        out.write('<?xml version="1.0"?>\n')
        out.write('<VTKFile type="StructuredGrid" version="1.0" byte_order="LittleEndian">\n')
        out.write(f'  <StructuredGrid WholeExtent="{extent}">\n')
        out.write(f'    <Piece Extent="{extent}">\n')
        out.write('      <Points>\n')
        out.write('        <DataArray type="Float64" NumberOfComponents="3" format="ascii">\n')
        for row in coordinates:
            out.write(f"          {row}\n")
        out.write('        </DataArray>\n      </Points>\n')
        out.write('    </Piece>\n  </StructuredGrid>\n</VTKFile>\n')
    return True
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_build_asset_inspection()

dict picurv_cli.core._build_asset_inspection ( str  kind, str  build_root, dict  provider, list  payload_files  )

protected

Produce the inspection material published beside an asset's payload.

Precompute exists so a user can look at a grid, field, or profile and change it before committing a solve. An asset that carries only opaque solver input cannot serve that purpose, so every published object gets a validation record and, where it is affordable, a preview.

Parameters

[in]	kind	Asset kind.
[in]	build_root	Temporary build tree.
[in]	provider	Provider metadata for the asset.
[in]	payload_files	Absolute payload paths produced for this asset.

Returns

Mapping of published inspection filename to its absolute source path.

Definition at line 19948 of file core.py.

                            payload_files: list) -> dict:
    """!
    @brief Produce the inspection material published beside an asset's payload.
 
    @details Precompute exists so a user can look at a grid, field, or profile and
             change it before committing a solve. An asset that carries only opaque
             solver input cannot serve that purpose, so every published object gets a
             validation record and, where it is affordable, a preview.
    @param[in] kind Asset kind.
    @param[in] build_root Temporary build tree.
    @param[in] provider Provider metadata for the asset.
    @param[in] payload_files Absolute payload paths produced for this asset.
    @return Mapping of published inspection filename to its absolute source path.
    """
    inspection_dir = os.path.join(build_root, ".inspection")
    os.makedirs(inspection_dir, exist_ok=True)
    published = {}
    validation = {
        "asset_kind": kind,
        "provider": provider["provider"],
        "generated_at": datetime.now().astimezone().isoformat(),
        "files": [os.path.relpath(path, build_root).replace(os.sep, "/") for path in payload_files],
    }
 
    if kind == "grid":
        staged = os.path.join(build_root, "inputs", "grid", "grid.run")
        if os.path.isfile(staged):
            try:
                geometry = _picgrid_geometry_summary(staged)
                validation["geometry"] = geometry
                preview = os.path.join(inspection_dir, "preview.vts")
                if _write_structured_grid_preview(staged, preview, geometry["dimensions"]):
                    published["preview.vts"] = preview
                else:
                    validation["preview"] = (
                        "skipped: the first block exceeds "
                        f"{ASSET_PREVIEW_NODE_LIMIT} nodes"
                    )
            except (OSError, ValueError, StopIteration) as exc:
                validation["geometry_error"] = str(exc)
        generator_preview = os.path.join(
            build_root, "output", "visualization", "precompute", "grid.vts"
        )
        if os.path.isfile(generator_preview):
            published["preview.vts"] = generator_preview
            validation.pop("preview", None)
        info = os.path.join(build_root, "output", "analysis", "metrics", "grid.info")
        if os.path.isfile(info):
            published["grid.info"] = info
 
    elif kind == "initial-condition":
        # The generators name these for the run tree they were written into; the asset
        # publishes them under the names the object contract uses.
        for published_name, suffix in (
            ("summary.json", "_summary.json"), ("spectrum.csv", "_spectrum.csv"),
        ):
            for candidate in payload_files:
                base = os.path.basename(candidate)
                if base == published_name or base.endswith(suffix):
                    published[published_name] = candidate
                    break
        for candidate in payload_files:
            base = os.path.basename(candidate)
            if base.startswith(("initial_condition_plane_spectrum_", "initial_condition_line_spectrum_")) and base.endswith((".csv", ".json")):
                published[base] = candidate
        validation["fields"] = sorted(
            os.path.basename(path) for path in payload_files if path.endswith(".dat")
        )
        summary_source = published.get("summary.json")
        if summary_source:
            try:
                with open(summary_source, "r", encoding="utf-8") as stream:
                    validation["summary"] = json.load(stream)
            except (OSError, ValueError):
                pass
 
    elif kind == "inlet-profiles":
        for candidate in payload_files:
            if os.path.basename(candidate) == "profile.info":
                published["profile.info"] = candidate
        validation["profiles"] = sorted(
            os.path.basename(path) for path in payload_files
            if path.endswith(".picslice")
        )
 
    validation_path = os.path.join(inspection_dir, "validation.json")
    write_json_file(validation_path, validation)
    published["validation.json"] = validation_path
    return published
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_publish_asset_object()

dict picurv_cli.core._publish_asset_object ( str  workspace_root, str  build_root, dict  provider, list  payload_files  )

protected

Publish one immutable content-addressed asset object atomically.

Parameters

[in]	workspace_root	Owning workspace.
[in]	build_root	Temporary build root.
[in]	provider	Provider metadata.
[in]	payload_files	Files produced for the provider.

Returns

Asset reference written to the asset set.

Definition at line 20040 of file core.py.

                          payload_files: list) -> dict:
    """!
    @brief Publish one immutable content-addressed asset object atomically.
    @param[in] workspace_root Owning workspace.
    @param[in] build_root Temporary build root.
    @param[in] provider Provider metadata.
    @param[in] payload_files Files produced for the provider.
    @return Asset reference written to the asset set.
    """
    file_inventory = []
    for path in payload_files:
        relative = os.path.relpath(path, build_root).replace(os.sep, "/")
        file_inventory.append({
            "path": relative,
            "bytes": os.path.getsize(path),
            "sha256": _asset_file_sha256(path),
        })
    asset_id = _stable_mapping_sha256({
        "provider_spec_sha256": provider["spec_sha256"],
        "files": file_inventory,
    })
    # Identity is the payload's; inspection material describes it and must not change
    # which object a run resolves to.
    inspection = _build_asset_inspection(
        provider["kind"], build_root, provider, payload_files
    )
    kind_dir = ASSET_KIND_DIRECTORIES[provider["kind"]]
    object_root = os.path.join(workspace_root, "assets", "objects", kind_dir, asset_id)
    if not os.path.isdir(object_root):
        parent = os.path.dirname(object_root)
        os.makedirs(parent, exist_ok=True)
        temporary = tempfile.mkdtemp(prefix=f".{asset_id[:12]}-", dir=parent)
        try:
            for item, source in zip(file_inventory, payload_files):
                destination = os.path.join(temporary, "payload", *item["path"].split("/"))
                os.makedirs(os.path.dirname(destination), exist_ok=True)
                shutil.copy2(source, destination)
            for name, source in sorted(inspection.items()):
                shutil.copy2(source, os.path.join(temporary, name))
            manifest = {
                "schema_version": ASSET_MANIFEST_SCHEMA_VERSION,
                "asset_id": asset_id,
                "kind": provider["kind"],
                "provider": provider["provider"],
                "provider_execution": provider["execution"],
                "provider_spec_sha256": provider["spec_sha256"],
                "provider_spec": provider["spec"],
                "source_files": provider["source_files"],
                "software": provider["software"],
                "created_at": datetime.now().astimezone().isoformat(),
                "files": file_inventory,
                "inspection": sorted(inspection),
            }
            write_json_file(os.path.join(temporary, "asset.json"), manifest)
            try:
                os.replace(temporary, object_root)
            except OSError as exc:
                if exc.errno != errno.ENOTEMPTY and not os.path.isdir(object_root):
                    raise
        finally:
            if os.path.isdir(temporary):
                shutil.rmtree(temporary, ignore_errors=True)
    return {
        "asset_id": asset_id,
        "kind": provider["kind"],
        "provider": provider["provider"],
        "provider_spec_sha256": provider["spec_sha256"],
        "object": os.path.relpath(object_root, workspace_root).replace(os.sep, "/"),
        "files": file_inventory,
        "inspection": sorted(inspection),
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_workspace_asset_set_name()

str picurv_cli.core._workspace_asset_set_name ( str  workspace_root, str  case_path  )

protected

Return a collision-free, readable mutable asset-set name.

Parameters

[in]	workspace_root	Owning initialized workspace.
[in]	case_path	Source case configuration path.

Returns

Stable asset-set filename stem.

Definition at line 20114 of file core.py.

def _workspace_asset_set_name(workspace_root: str, case_path: str) -> str:
    """!
    @brief Return a collision-free, readable mutable asset-set name.
    @param[in] workspace_root Owning initialized workspace.
    @param[in] case_path Source case configuration path.
    @return Stable asset-set filename stem.
    """
    stem = re.sub(r"[^A-Za-z0-9_.-]+", "-", Path(case_path).stem).strip("-") or "case"
    relative = _relative_to_workspace(case_path, workspace_root) or os.path.abspath(case_path)
    digest = hashlib.sha256(str(relative).encode("utf-8")).hexdigest()[:10]
    return f"{stem}-{digest}"
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_write_workspace_asset_set()

str picurv_cli.core._write_workspace_asset_set ( str  workspace_root, str  case_path, dict  graph, dict  references  )

protected

Atomically update the named asset set and workspace asset catalog.

Parameters

[in]	workspace_root	Owning workspace.
[in]	case_path	Source case YAML.
[in]	graph	Complete provider graph.
[in]	references	Newly published or reused asset references.

Returns

Asset-set YAML path.

Definition at line 20127 of file core.py.

                               references: dict) -> str:
    """!
    @brief Atomically update the named asset set and workspace asset catalog.
    @param[in] workspace_root Owning workspace.
    @param[in] case_path Source case YAML.
    @param[in] graph Complete provider graph.
    @param[in] references Newly published or reused asset references.
    @return Asset-set YAML path.
    """
    name = _workspace_asset_set_name(workspace_root, case_path)
    set_path = os.path.join(workspace_root, "assets", "sets", f"{name}.yml")
    existing = read_yaml_file(set_path) if os.path.isfile(set_path) else {}
    assets = dict(existing.get("assets") or {})
    assets.update(references)
    payload = {
        "schema_version": ASSET_LOCK_SCHEMA_VERSION,
        "name": name,
        "case": os.path.relpath(case_path, workspace_root).replace(os.sep, "/"),
        "case_sha256": graph["case_sha256"],
        "updated_at": datetime.now().astimezone().isoformat(),
        "assets": assets,
        "runtime_providers": {
            item["kind"]: {
                "provider": item["provider"],
                "provider_spec_sha256": item["spec_sha256"],
            }
            for item in graph["providers"] if item["execution"] == "runtime-c"
        },
    }
    write_yaml_file(set_path, payload)
    catalog_path = os.path.join(workspace_root, "assets", "catalog.yml")
    catalog = read_yaml_file(catalog_path) if os.path.isfile(catalog_path) else {
        "schema_version": 1, "objects": {}
    }
    objects = catalog.setdefault("objects", {})
    for reference in references.values():
        objects[reference["asset_id"]] = {
            "kind": reference["kind"],
            "provider": reference["provider"],
            "object": reference["object"],
        }
    write_yaml_file(catalog_path, catalog)
    return set_path
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

precompute_case_assets()

dict picurv_cli.core.precompute_case_assets	(	str	workspace_root,
		dict	case_cfg,
		str	case_path,
			requested = None,
		bool	precomputable_only = False
	)

Build and publish a selected deterministic asset dependency closure.

Parameters

[in]	workspace_root	Owning workspace.
[in]	case_cfg	Parsed case configuration.
[in]	case_path	Source case path.
[in]	requested	Requested asset kinds, or all configured providers.
[in]	precomputable_only	Drop runtime-C dependencies from the closure instead of refusing. For internal run-staging only: a run legitimately depends on a runtime-C grid that its own solver builds moments later, so its presence in the dependency closure is expected there, not an error. The standalone picurv precompute command leaves this False, since nothing will ever build a runtime-C provider in that context.

Returns

Provider graph, selected providers, references, and asset-set path.

Definition at line 20173 of file core.py.

                           requested=None, precomputable_only: bool = False) -> dict:
    """!
    @brief Build and publish a selected deterministic asset dependency closure.
    @param[in] workspace_root Owning workspace.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Source case path.
    @param[in] requested Requested asset kinds, or all configured providers.
    @param[in] precomputable_only Drop runtime-C dependencies from the closure instead of
                                  refusing. For internal run-staging only: a run legitimately
                                  depends on a runtime-C grid that its own solver builds
                                  moments later, so its presence in the dependency closure is
                                  expected there, not an error. The standalone `picurv
                                  precompute` command leaves this False, since nothing will
                                  ever build a runtime-C provider in that context.
    @return Provider graph, selected providers, references, and asset-set path.
    """
    enforce_workspace_version(workspace_root)
    graph = build_case_asset_graph(case_cfg, case_path)
    selected = _asset_selection(graph, requested, precomputable_only=precomputable_only)
    if not precomputable_only:
        runtime = [item for item in selected if item["execution"] == "runtime-c"]
        if runtime:
            details = ", ".join(f"{item['kind']}={item['provider']}" for item in runtime)
            raise ValueError(
                "Precompute is atomic and cannot execute simulator-runtime providers. "
                f"Selected dependency graph requires C generation: {details}. "
                "Use --only to select an independent precomputable subset, or run the case; "
                "the simulator will report each runtime provider before generation."
            )
    if not selected:
        raise ValueError("The selected case has no precomputable providers.")
    staging_parent = os.path.join(workspace_root, "assets")
    os.makedirs(staging_parent, exist_ok=True)
    build_root = tempfile.mkdtemp(prefix=".precompute-", dir=staging_parent)
    references = {}
    try:
        payloads = _build_selected_asset_payloads(build_root, case_cfg, case_path, selected)
        for provider in selected:
            files = payloads.get(provider["kind"], [])
            if not files:
                raise ValueError(
                    f"Provider {provider['kind']}={provider['provider']} produced no files."
                )
            references[provider["kind"]] = _publish_asset_object(
                workspace_root, build_root, provider, files
            )
    finally:
        shutil.rmtree(build_root, ignore_errors=True)
    set_path = _write_workspace_asset_set(workspace_root, case_path, graph, references)
    return {"graph": graph, "selected": selected, "assets": references, "set_path": set_path}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_workspace_asset_set_path()

str picurv_cli.core._workspace_asset_set_path ( str  workspace_root, str  case_path  )

protected

Return the mutable asset-set pointer associated with a case config name.

Parameters

[in]	workspace_root	Owning workspace.
[in]	case_path	Source case path.

Returns

Absolute asset-set YAML path.

Definition at line 20226 of file core.py.

def _workspace_asset_set_path(workspace_root: str, case_path: str) -> str:
    """!
    @brief Return the mutable asset-set pointer associated with a case config name.
    @param[in] workspace_root Owning workspace.
    @param[in] case_path Source case path.
    @return Absolute asset-set YAML path.
    """
    name = _workspace_asset_set_name(workspace_root, case_path)
    return os.path.join(workspace_root, "assets", "sets", f"{name}.yml")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_find_stored_asset()

picurv_cli.core._find_stored_asset ( str  workspace_root, dict  provider  )

protected

Find a published object built from exactly this provider's inputs.

Asset sets are named after case files, so they miss an object another case file already built from identical inputs. The provider identity is what the object was built from, so any published object carrying it is reusable; the lowest asset id is taken so repeated lookups agree. Payload checksums are verified when the object is materialized, not here.

Parameters

[in]	workspace_root	Owning workspace.
[in]	provider	Provider entry from build_case_asset_graph().

Returns

Asset reference in the shape _publish_asset_object() returns, or None.

Definition at line 20237 of file core.py.

def _find_stored_asset(workspace_root: str, provider: dict):
    """!
    @brief Find a published object built from exactly this provider's inputs.
    @details Asset sets are named after case files, so they miss an object another case
             file already built from identical inputs. The provider identity is what the
             object was built from, so any published object carrying it is reusable; the
             lowest asset id is taken so repeated lookups agree. Payload checksums are
             verified when the object is materialized, not here.
    @param[in] workspace_root Owning workspace.
    @param[in] provider Provider entry from build_case_asset_graph().
    @return Asset reference in the shape _publish_asset_object() returns, or None.
    """
    kind_dir = ASSET_KIND_DIRECTORIES.get(provider["kind"])
    if not kind_dir:
        return None
    objects_root = os.path.join(workspace_root, "assets", "objects", kind_dir)
    if not os.path.isdir(objects_root):
        return None
    for asset_id in sorted(os.listdir(objects_root)):
        object_root = os.path.join(objects_root, asset_id)
        manifest = _read_json_if_exists(os.path.join(object_root, "asset.json"))
        if not (isinstance(manifest, dict)
                and manifest.get("schema_version") == ASSET_MANIFEST_SCHEMA_VERSION
                and manifest.get("asset_id") == asset_id
                and manifest.get("kind") == provider["kind"]
                and manifest.get("provider_spec_sha256") == provider["spec_sha256"]):
            continue
        return {
            "asset_id": asset_id,
            "kind": provider["kind"],
            "provider": manifest.get("provider", provider["provider"]),
            "provider_spec_sha256": provider["spec_sha256"],
            "object": os.path.relpath(object_root, workspace_root).replace(os.sep, "/"),
            "files": manifest.get("files", []),
            "inspection": manifest.get("inspection", []),
        }
    return None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

plan_run_assets()

dict picurv_cli.core.plan_run_assets	(	dict	case_cfg,
		str	case_path,
			skip_kinds = ()
	)

Plan reuse/build/runtime actions for all configured run providers.

Parameters

[in]	case_cfg	Parsed case configuration.
[in]	case_path	Source case path.
[in]	skip_kinds	Kinds the run will not read; planned as unused, never built.

Returns

Workspace, graph, set path, and per-provider actions.

Definition at line 20276 of file core.py.

def plan_run_assets(case_cfg: dict, case_path: str, skip_kinds=()) -> dict:
    """!
    @brief Plan reuse/build/runtime actions for all configured run providers.
    @param[in] case_cfg Parsed case configuration.
    @param[in] case_path Source case path.
    @param[in] skip_kinds Kinds the run will not read; planned as `unused`, never built.
    @return Workspace, graph, set path, and per-provider actions.
    """
    workspace_root = find_workspace_root(case_path)
    graph = build_case_asset_graph(case_cfg, case_path)
    asset_set = {}
    set_path = None
    if workspace_root:
        set_path = _workspace_asset_set_path(workspace_root, case_path)
        if os.path.isfile(set_path):
            asset_set = read_yaml_file(set_path)
    refs = asset_set.get("assets", {}) if isinstance(asset_set, dict) else {}
    actions = []
    for provider in graph["providers"]:
        reference = refs.get(provider["kind"]) if isinstance(refs, dict) else None
        matches = bool(
            isinstance(reference, dict)
            and reference.get("provider_spec_sha256") == provider["spec_sha256"]
            and workspace_root
            and os.path.isfile(os.path.join(
                workspace_root, reference.get("object", ""), "asset.json"
            ))
        )
        adopted = False
        if provider["kind"] in skip_kinds:
            actions.append({**provider, "action": "unused", "reference": None, "adopted": False})
            continue
        if not matches and workspace_root and provider["execution"] != "runtime-c":
            # The asset set is named after the case file, so a copied or renamed case
            # has none; identity is the provider's, so an object built for another case
            # file with the same inputs is the same asset.
            reference = _find_stored_asset(workspace_root, provider)
            matches = adopted = reference is not None
        if provider["execution"] == "runtime-c":
            action = "runtime-c"
        elif matches:
            action = "reuse"
        else:
            action = "build"
        actions.append({**provider, "action": action, "reference": reference if matches else None,
                        "adopted": adopted})
    return {
        "workspace_root": workspace_root,
        "graph": graph,
        "asset_set_path": set_path,
        "actions": actions,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_materialize_asset_file()

str picurv_cli.core._materialize_asset_file ( str  source, str  destination  )

protected

Expose one immutable shared-asset file through reflink, hardlink, or copy.

Parameters

[in]	source	Immutable asset payload file.
[in]	destination	Run-local destination.

Returns

Materialization mode used.

Definition at line 20330 of file core.py.

def _materialize_asset_file(source: str, destination: str) -> str:
    """!
    @brief Expose one immutable shared-asset file through reflink, hardlink, or copy.
    @param[in] source Immutable asset payload file.
    @param[in] destination Run-local destination.
    @return Materialization mode used.
    """
    os.makedirs(os.path.dirname(destination), exist_ok=True)
    temporary = f"{destination}.tmp.{os.getpid()}"
    try:
        cp = shutil.which("cp")
        if cp:
            result = subprocess.run(
                [cp, "--reflink=always", "--preserve=mode,timestamps", source, temporary],
                text=True, capture_output=True, check=False,
            )
            if result.returncode == 0:
                os.replace(temporary, destination)
                return "reflink"
            if os.path.lexists(temporary):
                os.remove(temporary)
        try:
            os.link(source, temporary)
            os.replace(temporary, destination)
            return "hardlink"
        except OSError:
            if os.path.lexists(temporary):
                os.remove(temporary)
        shutil.copy2(source, temporary)
        os.replace(temporary, destination)
        return "copy"
    finally:
        if os.path.lexists(temporary):
            os.remove(temporary)
 
 

Here is the caller graph for this function:

materialize_run_assets()

dict picurv_cli.core.materialize_run_assets	(	str	run_dir,
		dict	case_cfg,
		str	case_path,
		bool	require_precomputed = False,
		bool	fetch_missing = False,
			skip_kinds = ()
	)

Resolve/build workspace assets and write the exact run input lock.

Parameters

[in]	run_dir	Run receiving immutable input exposures.
[in]	case_cfg	Parsed case config.
[in]	case_path	Source case path.
[in]	require_precomputed	Refuse any missing deterministic asset.
[in]	fetch_missing	Request remote fetch before local build.
[in]	skip_kinds	Kinds the run will not read (see unused_asset_kinds()).

Returns

Written lock mapping, or a standalone-provider summary outside a workspace.

Definition at line 20366 of file core.py.

                           fetch_missing: bool = False, skip_kinds=()) -> dict:
    """!
    @brief Resolve/build workspace assets and write the exact run input lock.
    @param[in] run_dir Run receiving immutable input exposures.
    @param[in] case_cfg Parsed case config.
    @param[in] case_path Source case path.
    @param[in] require_precomputed Refuse any missing deterministic asset.
    @param[in] fetch_missing Request remote fetch before local build.
    @param[in] skip_kinds Kinds the run will not read (see unused_asset_kinds()).
    @return Written lock mapping, or a standalone-provider summary outside a workspace.
    """
    plan = plan_run_assets(case_cfg, case_path, skip_kinds)
    workspace_root = plan["workspace_root"]
    if not workspace_root:
        return {
            "schema_version": ASSET_LOCK_SCHEMA_VERSION,
            "workspace": None,
            "assets": {},
            "runtime_providers": {
                item["kind"]: item["provider"] for item in plan["actions"]
                if item["execution"] == "runtime-c"
            },
        }
    enforce_workspace_version(workspace_root)
    missing = [item for item in plan["actions"] if item["action"] == "build"]
    if missing and fetch_missing:
        # Storage imports this module indirectly, so remote asset recovery is routed
        # through a late import that cannot create a module cycle at startup.
        try:
            from .storage import restore_missing_workspace_assets
        except ImportError:
            restore_missing_workspace_assets = getattr(
                _storage_module, "restore_missing_workspace_assets", None
            )
        restored = restore_missing_workspace_assets(
            workspace_root, [item["spec_sha256"] for item in missing]
        ) if restore_missing_workspace_assets else {}
        if restored:
            recovered_refs = {
                item["kind"]: restored[item["spec_sha256"]]
                for item in missing if item["spec_sha256"] in restored
            }
            if recovered_refs:
                _write_workspace_asset_set(
                    workspace_root, case_path, plan["graph"], recovered_refs
                )
            plan = plan_run_assets(case_cfg, case_path, skip_kinds)
            missing = [item for item in plan["actions"] if item["action"] == "build"]
    if missing and require_precomputed:
        names = ", ".join(f"{item['kind']}={item['provider']}" for item in missing)
        raise ValueError(
            f"Required precomputed asset(s) are missing or stale: {names}. "
            f"Run 'picurv precompute --case {case_path} --only "
            + ",".join(item["kind"] for item in missing) + "'."
        )
    if missing:
        precompute_case_assets(
            workspace_root, case_cfg, case_path,
            requested=[item["kind"] for item in missing],
            precomputable_only=True,
        )
        plan = plan_run_assets(case_cfg, case_path, skip_kinds)
        still_missing = [item for item in plan["actions"] if item["action"] == "build"]
        if still_missing:
            raise ValueError(
                "Asset generation completed without satisfying: "
                + ", ".join(item["kind"] for item in still_missing)
            )
 
    adopted = {
        item["kind"]: item["reference"] for item in plan["actions"] if item.get("adopted")
    }
    if adopted:
        # Found by provider identity rather than through this case's own set; record it
        # there so the next run of this case file resolves it directly.
        _write_workspace_asset_set(workspace_root, case_path, plan["graph"], adopted)
    assets = {}
    for item in plan["actions"]:
        reference = item.get("reference")
        if item["action"] != "reuse" or not isinstance(reference, dict):
            continue
        object_root = os.path.join(workspace_root, reference["object"])
        manifest = _read_json_if_exists(os.path.join(object_root, "asset.json"))
        if not isinstance(manifest, dict) or manifest.get("asset_id") != reference.get("asset_id"):
            raise ValueError(f"Asset object is missing or invalid: {object_root}")
        exposed = []
        for file_info in manifest.get("files", []):
            relative = file_info["path"]
            source = os.path.join(object_root, "payload", *relative.split("/"))
            if _asset_file_sha256(source) != file_info.get("sha256"):
                raise ValueError(f"Asset payload checksum mismatch: {source}")
            destination = os.path.join(run_dir, *relative.split("/"))
            mode = _materialize_asset_file(source, destination)
            exposed.append({"path": relative, "mode": mode, "sha256": file_info["sha256"]})
        assets[item["kind"]] = {**reference, "exposed": exposed}
        print(f"[INFO] Asset {item['kind']}: reuse {reference['asset_id']}")
    runtime_providers = {
        item["kind"]: {
            "provider": item["provider"],
            "provider_spec_sha256": item["spec_sha256"],
        }
        for item in plan["actions"]
        if item["execution"] == "runtime-c" and item["action"] != "unused"
    }
    for kind, provider in runtime_providers.items():
        print(f"[INFO] Runtime provider {kind}: {provider['provider']} (generated by simulator)")
    lock = {
        "schema_version": ASSET_LOCK_SCHEMA_VERSION,
        "workspace": workspace_root,
        "case_sha256": plan["graph"]["case_sha256"],
        "created_at": datetime.now().astimezone().isoformat(),
        "assets": assets,
        "runtime_providers": runtime_providers,
    }
    write_yaml_file(os.path.join(run_dir, "inputs", "assets.lock.yml"), lock)
    write_software_lock(run_dir)
    return lock
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

precompute_workflow()

picurv_cli.core.precompute_workflow

(

args

)

Resolve, preflight, and atomically publish reusable workspace assets.

Parameters

[in]

args

Parsed precompute command arguments.

Definition at line 20487 of file core.py.

def precompute_workflow(args):
    """!
    @brief Resolve, preflight, and atomically publish reusable workspace assets.
    @param[in] args Parsed precompute command arguments.
    """
    case_path = os.path.abspath(args.case)
    workspace_root = find_workspace_root(case_path, os.getcwd())
    if not workspace_root:
        raise ValueError(
            "Precompute requires an initialized PICurv workspace. Run 'picurv init ...', "
            "then use its config/case.yml."
        )
    case_cfg = read_yaml_file(case_path)
    raw_only = getattr(args, "only", None)
    requested = None
    if raw_only and str(raw_only).strip().lower() != "all":
        requested = [token.strip() for token in str(raw_only).split(",") if token.strip()]
    graph = build_case_asset_graph(case_cfg, case_path)
    selected = _asset_selection(graph, requested)
    print(f"[INFO] Workspace : {workspace_root}")
    print(f"[INFO] Case      : {os.path.relpath(case_path, workspace_root)}")
    print("[INFO] Asset dependency plan:")
    for provider in selected:
        dependencies = ",".join(provider.get("dependencies", [])) or "none"
        print(
            f"  - {provider['kind']}: {provider['provider']} "
            f"[{provider['execution']}], dependencies={dependencies}"
        )
    result = precompute_case_assets(workspace_root, case_cfg, case_path, requested=requested)
    for kind, reference in sorted(result["assets"].items()):
        print(f"[SUCCESS] {kind}: {reference['asset_id']} ({reference['object']})")
    print(f"[SUCCESS] Asset set: {os.path.relpath(result['set_path'], workspace_root)}")
 

Here is the call graph for this function:

Here is the caller graph for this function:

run_workflow()

picurv_cli.core.run_workflow

(

args

)

Main orchestrator for the 'run' command (local and Slurm modes).

Parameters

[in]

args

Command-line style argument list supplied to the function.

Definition at line 20520 of file core.py.

def run_workflow(args):
    """!
    @brief Main orchestrator for the 'run' command (local and Slurm modes).
    @param[in] args Command-line style argument list supplied to the function.
    """
    if getattr(args, "dry_run", False):
        plan = build_run_dry_plan(args)
        render_run_dry_plan(plan, output_format=getattr(args, "output_format", "text"))
        if plan.get("blocking"):
            sys.exit(1)
        return
 
    run_dir = None
    run_id = None
    output_dir_abs = None
    # A post-only invocation never resolves a restart source, so this stays None and
    # `build_run_manifest()` preserves whatever lineage the run was created with.
    run_lineage = None
    statistics_output_paths = []
    workflow_start = time.time()
    stages_completed = []
    configs = None
    submission_meta = {"launch_mode": "local", "no_submit": bool(args.no_submit), "stages": {}}
 
    cluster_mode = bool(getattr(args, "cluster", None))
    cluster_cfg = None
    cluster_path = None
    solver_num_procs_effective = args.num_procs
    post_num_procs_effective = args.num_procs
 
    if cluster_mode:
        cluster_path = os.path.abspath(args.cluster)
        cluster_cfg = read_yaml_file(cluster_path)
        validate_cluster_config(cluster_cfg, cluster_path)
        scheduler_type = str(cluster_cfg.get("scheduler", {}).get("type", "slurm")).lower()
        if args.scheduler and args.scheduler.lower() != scheduler_type:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO, key="scheduler.type", file_path=cluster_path,
                message=f"--scheduler={args.scheduler} does not match cluster.yml scheduler.type={scheduler_type}.",
                hint="Omit --scheduler, or give the scheduler cluster.yml names.",
            )
            sys.exit(1)
        if scheduler_type != "slurm":
            emit_structured_error(
                ERROR_CODE_CFG_INVALID_VALUE, key="scheduler.type", file_path=cluster_path,
                message=f"Unsupported scheduler '{scheduler_type}'. Only Slurm is supported.",
                hint="Set scheduler.type: slurm in cluster.yml.",
            )
            sys.exit(1)
        cluster_tasks = get_cluster_total_tasks(cluster_cfg)
        if (args.solve or args.post_process) and args.num_procs not in (1, cluster_tasks):
            fail_cli_usage(
                "In cluster mode, --num-procs must be "
                f"1 (auto) or exactly nodes*ntasks_per_node ({cluster_tasks}).",
                hint="Omit -n to use the task count cluster.yml sets.",
            )
        if args.solve:
            solver_num_procs_effective = cluster_tasks
        if args.post_process:
            post_num_procs_effective = cluster_tasks
        submission_meta["launch_mode"] = "slurm"
        submission_meta["cluster_config"] = cluster_path
        submission_meta["no_submit"] = bool(args.no_submit)
        if args.solve and args.post_process:
            print(
                f"[INFO] Cluster mode enabled (Slurm). Solver and post stages use "
                f"{solver_num_procs_effective} MPI tasks from cluster.yml."
            )
        elif args.solve:
            print(f"[INFO] Cluster mode enabled (Slurm). Solver uses {solver_num_procs_effective} MPI tasks from cluster.yml.")
        else:
            print(f"[INFO] Cluster mode enabled (Slurm). Post stage uses {post_num_procs_effective} MPI tasks from cluster.yml.")
 
    # --- Guard: restart flags without --solve ---
    if not args.solve:
        if getattr(args, 'restart_from', None):
            print("[WARNING] --restart-from has no effect without --solve and will be ignored.", file=sys.stderr)
        if getattr(args, 'continue_run', False):
            print("[WARNING] --continue only extends a solve in place and is ignored here. "
                  "Post-processing always skips steps whose output is up to date; drop "
                  "--continue from post-only commands.", file=sys.stderr)
 
    # --- Stage 1: Solver (if requested) ---
    if args.solve:
        case_input_path = os.path.abspath(args.case)
        workspace_root = find_workspace_root(case_input_path, args.solver, args.monitor, os.getcwd())
        if workspace_root:
            enforce_workspace_version(workspace_root)
            enforce_reproducibility_policy(workspace_root)
        walltime_guard_policy = resolve_walltime_guard_policy(cluster_cfg) if cluster_mode else None
        configs = {
            'case': read_yaml_file(args.case), 'case_path': case_input_path,
            'solver': read_yaml_file(args.solver), 'solver_path': os.path.abspath(args.solver),
            'monitor': read_yaml_file(args.monitor), 'monitor_path': os.path.abspath(args.monitor),
            'walltime_guard_policy': walltime_guard_policy,
            'statistics_state': getattr(args, "statistics_state", None) or "reset",
            'decomposition': getattr(args, "decomposition", None),
            'cluster_cfg': cluster_cfg if cluster_mode else None,
        }
 
        print("\n[INFO] Validating configuration files...")
        validate_simulation_configs(
            configs['case'], configs['solver'], configs['monitor'],
            args.case, args.solver, args.monitor,
            restart_source_given=bool(getattr(args, 'restart_from', None) or getattr(args, 'continue_run', False)),
        )
        print("[SUCCESS] All configuration files passed validation.\n")
 
        continue_mode = getattr(args, 'continue_run', False)
 
        if continue_mode:
            if not args.run_dir:
                fail_cli_usage(RESTART_RUN_DIR_REQUIRED_MESSAGE)
            run_dir = os.path.abspath(args.run_dir)
            if not os.path.isdir(run_dir):
                emit_structured_error(
                    ERROR_CODE_CFG_FILE_NOT_FOUND,
                    key="run-dir",
                    file_path=run_dir,
                    message="Specified run directory not found.",
                )
                sys.exit(1)
            adopt_relocated_artifact(run_dir)
            run_id = os.path.basename(run_dir)
        else:
            runs_root = workspace_artifact_root(workspace_root, "runs")
            run_id = allocate_generated_run_id(
                runs_root, configs["case"], configs["case_path"]
            )
            run_dir = os.path.join(runs_root, run_id)
 
        if workspace_root and os.path.commonpath([os.path.abspath(run_dir), workspace_root]) != workspace_root:
            fail_cli_usage("A workspace run directory must remain below the owning workspace.")
        if not continue_mode and os.path.exists(run_dir):
            raise ValueError(f"Generated run directory already exists: {run_dir}")
        ensure_run_layout(run_dir)
        # Checked after the skeleton exists so a resumed run is judged on what is
        # actually there, and before any stage writes into it.
        enforce_run_directory_structure(run_dir)
 
        # Captured before restart resolution, which materializes the checkpoint it reads.
        staged_records = (capture_continuation_records(run_dir, resolve_run_restart_dir(run_dir, configs["monitor"]))
                          if continue_mode else None)
        try:
            resolved_restart_source_dir, is_continue, run_lineage = resolve_restart_source(
                args, configs["case"], configs["solver"], configs["monitor"], run_dir
            )
            select_run_petsc_index_bytes(args, configs["case"], configs["case_path"], configs["monitor"],
                                         resolved_restart_source_dir)
        except ValueError as e:
            # Restart resolution is the first thing that can refuse a run, and the
            # skeleton is already on disk. Leaving it behind puts an empty directory in
            # runs/ that is indistinguishable from a real run to `ls`, to storage
            # status, and to anyone browsing the workspace, once per refused attempt.
            discard_unused_run_directory(run_dir, created=not continue_mode)
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="restart",
                file_path=args.case,
                message=str(e),
                hint=_STORAGE_RESTORE_HINT if isinstance(e.__cause__, StorageError) else _RESTART_HINT,
            )
            sys.exit(1)
 
        config_dir = os.path.join(run_dir, "config")
        if continue_mode:
            print(f"[INFO] Continuing in existing run directory: {os.path.relpath(run_dir)}")
        else:
            print(f"[INFO] Created new self-contained run directory: {os.path.relpath(run_dir)}")
 
        # Read before staging, which rewrites a continuation's own grid inputs.
        source_run_dir = run_dir if is_continue else (
            os.path.join(workspace_root or "", run_lineage["parent_path"]) if run_lineage else None)
        source_grid_inputs = None
        if source_run_dir and os.path.isdir(source_run_dir):
            source_case_path = load_active_run_configuration(source_run_dir).get("case")
            if source_case_path and os.path.isfile(source_case_path):
                source_grid_inputs = restart_grid_inputs(source_run_dir, read_yaml_file(source_case_path))
        active_config = snapshot_run_configuration(
            run_dir,
            {
                "case": args.case,
                "solver": args.solver,
                "monitor": args.monitor,
                "cluster": cluster_path if cluster_mode else None,
            },
            continuation=continue_mode,
        )
        # Pinned before the asset lock and manifest are written, so both record the
        # executables this run will launch rather than the installation's.
        had_pinned_executables = bool(load_run_executables(run_dir))
        record_run_petsc_index_bytes(run_dir)
        try:
            apply_run_executable_pinning(run_dir, active_config["revision"], args, workspace_root)
        except ValueError as exc:
            discard_unused_run_directory(run_dir, created=not continue_mode)
            print(f"[FATAL] {exc}", file=sys.stderr)
            sys.exit(1)
        try:
            asset_lock = materialize_run_assets(
                run_dir,
                configs["case"],
                configs["case_path"],
                require_precomputed=bool(getattr(args, "require_precomputed", False)),
                fetch_missing=bool(getattr(args, "fetch_missing", False)),
                skip_kinds=unused_asset_kinds(configs["case"], configs["solver"]),
            )
        except ValueError as exc:
            discard_unused_run_directory(run_dir, created=not continue_mode)
            print(f"[FATAL] {exc}", file=sys.stderr)
            sys.exit(1)
        # Publish identity and lineage before either executable starts.  Besides making
        # a staged run self-describing, this lets a dependent post job resolve branch
        # ownership even though the interactive conductor has already exited.
        write_json_file(
            os.path.join(run_dir, "manifest.json"),
            build_run_manifest(
                run_dir,
                run_id,
                workspace_root=workspace_root,
                launch_mode="slurm" if cluster_mode else "local",
                num_procs=solver_num_procs_effective,
                post_num_procs=post_num_procs_effective,
                stages_requested={"solve": True, "post_process": bool(args.post_process)},
                inputs={
                    "case": _relative_to_workspace(args.case, workspace_root),
                    "solver": _relative_to_workspace(args.solver, workspace_root),
                    "monitor": _relative_to_workspace(args.monitor, workspace_root),
                },
                asset_lock=asset_lock,
                lineage=run_lineage,
            ),
        )
 
        print("\n" + "="*25 + " SOLVER STAGE " + "="*25)
        source_files = {'Case': args.case, 'Solver': args.solver, 'Monitor': args.monitor}
        generated_config_dir = (
            config_dir if active_config["revision"] == "initial"
            else os.path.join(config_dir, "history", active_config["revision"])
        )
        monitor_files = prepare_monitor_files(
            run_dir, run_id, configs['monitor'], source_files,
            config_dir=generated_config_dir,
        )
        if resolved_restart_source_dir:
            print(f"[INFO] Restart source: {resolved_restart_source_dir}")
        if is_continue:
            print("[INFO] Continue mode: logs will be appended, not overwritten.")
        control_file = generate_solver_control_file(
            run_dir,
            run_id,
            configs,
            solver_num_procs_effective,
            monitor_files,
            restart_source_dir=resolved_restart_source_dir,
            continue_mode=is_continue,
            config_dir=generated_config_dir,
        )
        active_config = archive_active_generated_configuration(
            run_dir,
            [
                control_file,
                monitor_files.get("whitelist"),
                monitor_files.get("profile"),
                *glob.glob(os.path.join(generated_config_dir, "bcs*.run")),
            ],
        )
        control_file = load_active_run_configuration(run_dir).get("control", control_file)
 
        solver_exe = run_executable_path(run_dir, "simulator")
        # Staging is the last point before the binary's identity becomes the one written
        # into this run's checkpoints, so a stale build is worth saying out loud here.
        # A run kept on its earlier pin is meant to differ from the source, so it is not.
        if not had_pinned_executables or getattr(args, "pin_executables", None) is True:
            warn_on_stale_runtime_binaries(runtime_build_identities(run_dir=run_dir))
        solver_args = build_petsc_diagnostics_args(configs["monitor"], run_dir, "Solver") + ["-control_file", control_file]
        if source_grid_inputs is not None:
            warn_on_restart_grid_change(source_grid_inputs, restart_grid_inputs(run_dir, configs["case"]))
        carries_statistics = is_continue or str(configs.get("statistics_state", "reset")).lower() == "carry"
        if carries_statistics and normalize_field_statistics_config(configs["monitor"])["enabled"]:
            refusal = check_restart_continuation(solver_exe, solver_args, run_dir,
                                                 config_search_anchor=configs["case_path"])
            if refusal:
                if continue_mode:
                    restore_continuation_records(run_dir, staged_records, active_config["revision"])
                    undone = f"{os.path.relpath(run_dir)} is left as it was"
                else:
                    discard_unused_run_directory(run_dir, created=True, staged=True)
                    undone = "the branch run directory was removed"
                print(f"[FATAL] This restart cannot continue its statistics windows: {refusal}\n"
                      f"        Nothing was launched or submitted, and {undone}.", file=sys.stderr)
                sys.exit(1)
        if cluster_mode:
            scheduler_dir = os.path.join(run_dir, "scheduler")
            solver_script = os.path.join(scheduler_dir, "solver.sbatch")
            solver_log = os.path.join(scheduler_dir, "solver_%j.out")
            solver_err = os.path.join(scheduler_dir, "solver_%j.err")
            solver_cmd = build_cluster_launch_command(
                cluster_cfg,
                solver_exe,
                solver_args,
                config_search_anchor=args.case,
                extra_search_anchors=[cluster_path],
            )
            render_slurm_script(
                solver_script,
                f"{run_id}_solve",
                cluster_cfg,
                solver_cmd,
                run_dir,
                solver_log,
                solver_err,
                env_vars={"LOG_LEVEL": configs['monitor'].get('logging', {}).get('verbosity', 'INFO').upper()},
                shell_env_vars=build_walltime_guard_exports(cluster_cfg),
                identity_check=(solver_exe, read_binary_build_identity(solver_exe).get("version_line"),
                                "simulator" in load_run_executables(run_dir)),
            )
            submission_meta["stages"]["solve"] = {
                "script": solver_script,
                "submitted": False,
                "num_procs_effective": solver_num_procs_effective,
                "decomposition": _decomposition_record(configs.get("decomposition_resolved")),
            }
            print(f"[SUCCESS] Generated solver Slurm script: {os.path.relpath(solver_script)}")
            if not args.no_submit:
                submit_info = submit_sbatch(solver_script)
                submission_meta["stages"]["solve"].update(submit_info)
                submission_meta["stages"]["solve"]["submitted"] = True
                print(f"[SUCCESS] Submitted solver job: {submit_info['job_id']}")
            stages_completed.append('solve')
        else:
            command = build_local_launch_command(
                solver_exe,
                solver_args,
                solver_num_procs_effective,
                config_search_anchor=configs["case_path"],
            )
            solver_log = os.path.join("scheduler", f"{run_id}_solver.log")
            submission_meta["stages"]["solve"] = {
                "command": command,
                "command_string": format_command_for_display(command),
                "log_file": solver_log,
                "submitted": False,
                "num_procs_effective": solver_num_procs_effective,
                "decomposition": _decomposition_record(configs.get("decomposition_resolved")),
            }
            if args.no_submit:
                print(f"[SUCCESS] Staged local solve stage; run it with "
                      f"'picurv submit --run-dir {os.path.relpath(run_dir)}'.")
            else:
                try:
                    with runtime_stage_lock(run_dir, "solver"):
                        execute_command(command, run_dir, solver_log, configs['monitor'])
                except StorageError as exc:
                    print(f"[FATAL] {exc}", file=sys.stderr)
                    sys.exit(1)
                submission_meta["stages"]["solve"]["submitted"] = True
                submission_meta["stages"]["solve"]["executed"] = True
                submission_meta["stages"]["solve"]["completed_at"] = datetime.now().isoformat()
            stages_completed.append('solve')
 
    # --- Stage 2: Post-Processing (if requested) ---
    if args.post_process:
        if not args.solve and getattr(args, "pin_executables", None) is not None:
            fail_cli_usage(
                "--pin-executables and --no-pin-executables apply when the solve stage is staged.",
                hint="Post-processing launches the postprocessor the run is pinned to, or the "
                     "installation's when the run is not pinned.",
            )
        if args.run_dir:
            run_dir = os.path.abspath(args.run_dir)
            if not os.path.isdir(run_dir):
                emit_structured_error(ERROR_CODE_CFG_FILE_NOT_FOUND, key="run_dir", file_path=run_dir,
                                      message="Run directory not found.")
                sys.exit(1)
            print(f"[INFO] Operating on existing run directory: {os.path.relpath(run_dir)}")
            adopt_relocated_artifact(run_dir)
            enforce_run_directory_structure(run_dir)
            run_id = read_artifact_identity(run_dir)["run_id"]
 
        print("\n" + "="*20 + " POST-PROCESSING STAGE " + "="*20)
        config_dir = os.path.join(run_dir, "config")
        case_path, monitor_path, solver_control_path = auto_identify_run_inputs(config_dir)
 
        if not all([case_path, monitor_path, solver_control_path]):
            print(f"[FATAL] Could not automatically identify required config files in {config_dir}", file=sys.stderr)
            if not case_path:
                print("         - No 'case' file found (expected 'models' + 'boundary_conditions').", file=sys.stderr)
            if not monitor_path:
                print("         - No 'monitor' file found (expected 'io' + 'logging').", file=sys.stderr)
            if not solver_control_path:
                print("         - No '.control' file found.", file=sys.stderr)
            sys.exit(1)
 
        print(f"[INFO] Auto-identified Case file:    {os.path.basename(case_path)}")
        print(f"[INFO] Auto-identified Monitor file: {os.path.basename(monitor_path)}")
 
        case_cfg = read_yaml_file(case_path)
        monitor_cfg = read_yaml_file(monitor_path)
        post_cfg = read_yaml_file(args.post)
 
        print("[INFO] Validating post-processing configuration...")
        validate_post_config(post_cfg, args.post, monitor_cfg, case_cfg)
        print("[SUCCESS] Post-processing configuration passed validation.\n")
 
        post_cfg, recipe_id = apply_canonical_post_paths(post_cfg, run_dir)
        for relative in (
            post_cfg["_picurv_paths"]["visualization"],
            post_cfg["_picurv_paths"]["statistics"],
            post_cfg["_picurv_paths"]["spectra"],
        ):
            os.makedirs(os.path.join(run_dir, relative), exist_ok=True)
        archived_post_path = os.path.join(get_post_recipe_root(run_dir, post_cfg), "post.yml")
        os.makedirs(os.path.dirname(archived_post_path), exist_ok=True)
        if os.path.abspath(args.post) != os.path.abspath(archived_post_path):
            shutil.copy2(args.post, archived_post_path)
 
        solver_sources_deferred = bool(args.solve and (cluster_mode or args.no_submit))
        recompute = bool(getattr(args, 'recompute_post', False))
        post_stages = resolve_post_stage_selection(getattr(args, 'only', None))
        try:
            if not args.solve:
                select_existing_run_petsc_index_bytes(run_dir, args)
            post_exe = run_executable_path(run_dir, "postprocessor")
        except ValueError as exc:
            post_exe = None
            post_exe_error = exc
        post_plan = build_post_execution_plan(
            run_dir,
            run_id,
            case_cfg,
            monitor_cfg,
            post_cfg,
            recompute=recompute,
            allow_source_frontier_scan=not solver_sources_deferred,
            postprocessor_sha=_file_sha256(post_exe) if post_exe else None,
        )
        # Only the checkpoints of steps that need work must be local: a step whose output
        # is up to date is not read, so an offload that archived it does not block the run.
        needed_steps = post_plan['steps_to_process'] + post_plan['steps_unavailable']
        if 'fields' in post_stages and not solver_sources_deferred and needed_steps:
            try:
                require_storage_payload_local(
                    run_dir, "post-processing", checkpoints=needed_steps,
                )
            except StorageError as exc:
                emit_structured_error(
                    ERROR_CODE_CFG_FILE_NOT_FOUND,
                    key="storage",
                    file_path=run_dir,
                    message=str(exc),
                    hint=_STORAGE_RESTORE_HINT,
                )
                sys.exit(1)
 
        post_finalize_command = (
            build_post_finalize_command(run_dir, archived_post_path, post_cfg, post_stages)
            if 'fields' in post_stages else []
        )
        if post_stages != set(POST_STAGE_NAMES):
            print(f"[INFO] Post stages selected: {','.join(sorted(post_stages))}")
            # A stage the recipe gives no tasks has nothing to do; say so rather than
            # report success for work that was never possible.
            for stage, tasks in (("spectra", normalize_post_spectra_config(post_cfg)["tasks"]),
                                 ("reducers", normalize_post_reducers_config(post_cfg)["tasks"])):
                if stage in post_stages and not tasks:
                    print(f"[WARNING] --only selects {stage}, but {args.post} defines no {stage} "
                          "tasks; nothing is measured for it.", file=sys.stderr)
 
        print(f"[INFO] Post recipe: {recipe_id}")
        print(f"[INFO] Post-processor source data: {os.path.relpath(post_plan['source_data_directory'])}")
        if post_plan['source_frontier_deferred']:
            print("[INFO] Source checkpoints: not scanned; the solver stage writes them before post starts.")
        elif post_plan['source_latest_step'] is not None:
            print(f"[INFO] Source checkpoints: {post_plan['source_committed_count']} committed, "
                  f"latest at step {post_plan['source_latest_step']}.")
        else:
            print("[INFO] Source checkpoints: none committed yet.")
 
        # A local launch plans again under the post lock and reports that plan, so only an
        # invocation that stages the work, or finds none, reports this one.
        executes_fields_now = (
            'fields' in post_stages and post_plan['skip_reason'] is None
            and not cluster_mode and not args.no_submit
        )
        if 'fields' in post_stages:
            if not executes_fields_now:
                report_post_plan(post_plan)
            warn_overlapping_post_recipes(run_dir, post_cfg, post_plan, post_stages)
        persist_post_resume_state(run_dir, post_plan, steps=post_plan['adopted_records'])
 
        # Spectra run in the conductor rather than in the submitted job, so they can
        # only be measured when this invocation is the one doing the work. Under a
        # scheduler, with --no-submit, or before the solver has written anything,
        # the sources do not exist yet and the measurement is deferred instead.
        spectra_execute_now = (
            not cluster_mode
            and not args.no_submit
            and not post_plan['source_frontier_deferred']
        )
        fields_job_measures_spectra = (
            cluster_mode and 'fields' in post_stages and post_plan['skip_reason'] is None
        )
        if 'spectra' in post_stages and spectra_execute_now:
            spectra_summary = run_post_spectra_stage(
                run_dir,
                post_plan['resolved_post_cfg'],
                monitor_cfg,
                post_plan['source_data_directory'],
                _iter_post_steps(post_plan['owned_start_step'], post_plan['requested_end_step'],
                                 post_plan['step_interval']),
                plan=post_plan,
                recompute=recompute,
            )
            for artifact in spectra_summary['artifacts']:
                print(f"[INFO] Spectra output: {os.path.relpath(artifact)}")
        elif 'spectra' in post_stages and not fields_job_measures_spectra:
            reason = ("the solver stage has not produced output yet"
                      if post_plan['source_frontier_deferred'] else
                      "this invocation only stages work")
            print(f"[INFO] Spectra deferred: {reason}. Measure them once the run has "
                  f"checkpoints with:")
            print(f"[INFO]   picurv run --post-process --only spectra "
                  f"--run-dir {os.path.relpath(run_dir)} --post {args.post}")
 
        # Without the field stage nothing finalizes, so selected reducers run here, on
        # the profiles earlier field stages wrote.
        if 'reducers' in post_stages and 'fields' not in post_stages:
            try:
                run_post_reducers_stage(run_dir, post_plan['resolved_post_cfg'])
            except ValueError as exc:
                print(f"[FATAL] {exc}", file=sys.stderr)
                sys.exit(1)
 
        if 'fields' not in post_stages:
            # --only selected a subset that excludes the field post-processor.
            print("[INFO] Skipping the field post-processor (--only "
                  f"{','.join(sorted(post_stages))}).")
            stages_completed.append('post-process')
        elif post_plan['skip_reason'] is not None:
            diagnostic = post_plan.get('source_frontier_diagnostic') or {}
            first_incomplete = diagnostic.get('first_incomplete_step')
            if post_plan['skip_reason'] == 'already-complete-window':
                print("[INFO] Every requested step is up to date; the postprocessor is not launched.")
            elif post_plan['skip_reason'] == 'already-caught-up-to-current-source-frontier':
                print("[INFO] Every requested step with a committed checkpoint is up to date; "
                      "the postprocessor is not launched.")
            else:
                print("[INFO] No requested step has a committed checkpoint yet; the "
                      "postprocessor is not launched.")
                missing_files = diagnostic.get('missing_files_for_first_incomplete_step') or []
                if first_incomplete is not None and missing_files:
                    print(f"[INFO] Missing files for step {first_incomplete}: {', '.join(missing_files[:4])}")
            if first_incomplete is not None:
                print(
                    "[INFO] Closest committed source steps: "
                    f"near start={_format_optional_step(diagnostic.get('closest_complete_step_to_start'))}, "
                    f"near end={_format_optional_step(diagnostic.get('closest_complete_step_to_end'))}"
                )
            if post_finalize_command and post_plan['steps_current']:
                run_post_finalize_locked(
                    run_dir, post_plan['recipe_fingerprint'], post_finalize_command
                )
        else:
            post_effective_cfg = post_plan['effective_post_cfg']
            post_io_cfg = post_effective_cfg.get('io', {})
            try:
                output_dir_rel = post_io_cfg['output_directory']
                output_prefix = post_io_cfg['output_filename_prefix']
            except KeyError as e:
                print(f"[FATAL] Missing required key '{e.args[0]}' in the 'io' section of {args.post}", file=sys.stderr)
                sys.exit(1)
 
            output_dir_abs = os.path.abspath(os.path.join(run_dir, output_dir_rel))
            os.makedirs(output_dir_abs, exist_ok=True)
            print(f"[INFO] Post-processor output directory: {os.path.relpath(output_dir_abs)}")
            statistics_output_paths = get_post_statistics_output_artifacts(post_effective_cfg, run_dir, monitor_cfg)
            for stats_path in statistics_output_paths:
                print(f"[INFO] Statistics CSV output: {os.path.relpath(stats_path)}")
 
            source_files_post = {'Case': case_path, 'Post-Profile': args.post}
            post_decomposition = resolve_post_decomposition(
                run_dir, post_num_procs_effective, getattr(args, "decomposition", None),
                cluster_cfg if cluster_mode else None)
            if post_decomposition["problems"]:
                print(f"[FATAL] {' '.join(post_decomposition['problems'])}", file=sys.stderr)
                sys.exit(1)
            print(f"[INFO] Post-processing {describe_decomposition(post_decomposition, post_num_procs_effective)}")
            post_recipe_file = generate_post_recipe_file(run_dir, run_id, post_effective_cfg, source_files_post,
                                                         monitor_cfg, post_decomposition)
            if post_exe is None:
                print(f"[FATAL] {post_exe_error}", file=sys.stderr)
                sys.exit(1)
            post_args = build_petsc_diagnostics_args(monitor_cfg, run_dir, "PostProcessor") + [
                "-control_file",
                solver_control_path,
                "-postprocessing_config_file",
                post_recipe_file,
            ]
            post_stage_meta = {
                "num_procs_effective": post_num_procs_effective,
                "decomposition": _decomposition_record(post_decomposition),
                "steps_planned": len(post_plan['steps_to_process']),
                "steps_current": post_plan['steps_current'],
                "recompute": recompute,
                "source_frontier_step": post_plan['source_frontier_step'],
                "source_frontier_deferred": post_plan['source_frontier_deferred'],
                "recipe_fingerprint": post_plan['recipe_fingerprint'],
                "finalize_command": post_finalize_command,
                "submitted": False,
            }
            if cluster_mode:
                scheduler_dir = os.path.join(run_dir, "scheduler")
                os.makedirs(scheduler_dir, exist_ok=True)
                post_script = os.path.join(scheduler_dir, "post.sbatch")
                post_log = os.path.join(scheduler_dir, "post_%j.out")
                post_err = os.path.join(scheduler_dir, "post_%j.err")
                post_cluster_cfg = cluster_cfg
                raw_post_cmd = build_cluster_launch_command(
                    post_cluster_cfg,
                    post_exe,
                    post_args,
                    config_search_anchor=case_path,
                    extra_search_anchors=[cluster_path],
                    force_num_procs=post_num_procs_effective,
                )
                post_cmd, _ = build_post_locked_command(
                    run_dir,
                    post_plan['recipe_fingerprint'],
                    raw_post_cmd,
                    create_wrapper=True,
                    success_command=post_finalize_command,
                    post_recipe=archived_post_path,
                    postprocessor=post_exe,
                    recompute=recompute,
                )
                spectra_follow = []
                if 'spectra' in post_stages:
                    follow = build_spectra_follow_command(run_dir, args.post, post_effective_cfg,
                                                          recompute=recompute)
                    if follow:
                        spectra_follow = [follow]
                        print("[INFO] Spectra will be measured in the post job, after "
                              "the field post-processor completes.")
                render_slurm_script(
                    post_script,
                    f"{run_id}_post",
                    post_cluster_cfg,
                    post_cmd,
                    run_dir,
                    post_log,
                    post_err,
                    env_vars={"LOG_LEVEL": monitor_cfg.get('logging', {}).get('verbosity', 'INFO').upper()},
                    follow_commands=spectra_follow,
                    identity_check=(post_exe, read_binary_build_identity(post_exe).get("version_line"),
                                    "postprocessor" in load_run_executables(run_dir)),
                )
                submission_meta["stages"]["post-process"] = {"script": post_script, **post_stage_meta}
                print(f"[SUCCESS] Generated post Slurm script: {os.path.relpath(post_script)}")
 
                if not args.no_submit:
                    dependency_job = None
                    if args.solve:
                        dependency_job = submission_meta.get("stages", {}).get("solve", {}).get("job_id")
                    submit_info = submit_sbatch(post_script, dependency=dependency_job)
                    submission_meta["stages"]["post-process"].update(submit_info)
                    submission_meta["stages"]["post-process"]["submitted"] = True
                    if dependency_job:
                        submission_meta["stages"]["post-process"]["dependency"] = f"afterok:{dependency_job}"
                    print(f"[SUCCESS] Submitted post job: {submit_info['job_id']}")
                stages_completed.append('post-process')
            else:
                raw_command = build_local_launch_command(
                    post_exe,
                    post_args,
                    post_num_procs_effective,
                    config_search_anchor=case_path,
                    allow_single_rank_launcher_override=True,
                    force_num_procs=post_num_procs_effective,
                )
                command, _ = build_post_locked_command(
                    run_dir,
                    post_plan['recipe_fingerprint'],
                    raw_command,
                    create_wrapper=True,
                    success_command=post_finalize_command,
                    post_recipe=archived_post_path,
                    postprocessor=post_exe,
                    recompute=recompute,
                )
                post_log = os.path.join("scheduler", f"{run_id}_{output_prefix}.log")
                submission_meta["stages"]["post-process"] = {
                    "command": command,
                    "command_string": format_command_for_display(command),
                    "log_file": post_log,
                    **post_stage_meta,
                }
                if args.no_submit:
                    print(f"[SUCCESS] Staged local post command: {post_log}")
                else:
                    execute_command(command, run_dir, post_log, monitor_cfg)
                    submission_meta["stages"]["post-process"]["submitted"] = True
                    submission_meta["stages"]["post-process"]["executed"] = True
                    submission_meta["stages"]["post-process"]["completed_at"] = datetime.now().isoformat()
                stages_completed.append('post-process')
 
    if run_dir:
        workspace_root = find_workspace_root(run_dir)
        manifest_inputs = {}
        if args.solve:
            manifest_inputs["case"] = _relative_to_workspace(args.case, workspace_root)
            manifest_inputs["solver"] = _relative_to_workspace(args.solver, workspace_root)
            manifest_inputs["monitor"] = _relative_to_workspace(args.monitor, workspace_root)
        if args.post_process:
            manifest_inputs["post"] = _relative_to_workspace(args.post, workspace_root)
        if cluster_mode:
            manifest_inputs["cluster"] = _relative_to_workspace(cluster_path, workspace_root)
        if submission_meta.get("stages"):
            # A stage this invocation did not stage keeps its record (a continued solve
            # leaves the run's earlier post job visible to cancel and summarize).
            submission_path = os.path.join(run_dir, "scheduler", "submission.json")
            for stage_name, stage_meta in ((_read_json_if_exists(submission_path) or {}).get("stages") or {}).items():
                submission_meta["stages"].setdefault(stage_name, stage_meta)
            write_json_file(submission_path, submission_meta)
        asset_lock = read_yaml_file(os.path.join(run_dir, "inputs", "assets.lock.yml")) \
            if os.path.isfile(os.path.join(run_dir, "inputs", "assets.lock.yml")) else {}
        manifest = build_run_manifest(
            run_dir,
            run_id,
            workspace_root=workspace_root,
            launch_mode="slurm" if cluster_mode else "local",
            num_procs=solver_num_procs_effective,
            post_num_procs=post_num_procs_effective,
            stages_requested={"solve": bool(args.solve), "post_process": bool(args.post_process)},
            stages_completed=stages_completed,
            inputs=manifest_inputs,
            asset_lock=asset_lock,
            submission=submission_meta,
            lineage=run_lineage,
        )
        write_json_file(os.path.join(run_dir, "manifest.json"), manifest)
 
    if stages_completed:
        elapsed = time.time() - workflow_start
        mins, secs = divmod(int(elapsed), 60)
        hrs, mins = divmod(mins, 60)
        if hrs > 0:
            time_str = f"{hrs}h {mins}m {secs}s"
        elif mins > 0:
            time_str = f"{mins}m {secs}s"
        else:
            time_str = f"{secs}s"
 
        print("\n" + "=" * 60)
        print("                       RUN SUMMARY")
        print("=" * 60)
        print(f"  Run ID          : {run_id}")
        print(f"  Run directory   : {os.path.relpath(run_dir)}")
        # A staged or Slurm-submitted stage has not run yet when this prints.
        staged = bool(cluster_mode or args.no_submit)
        print(f"  Wall-clock      : {time_str}")
        stages_label = "Stages staged" if args.no_submit else "Stages submitted" if staged else "Stages"
        print(f"  {stages_label:<16}: {', '.join(stages_completed)}")
        print(f"  Launch mode     : {'slurm' if cluster_mode else 'local'}")
        if args.solve:
            print(f"  Solver MPI procs: {solver_num_procs_effective}")
        if args.post_process:
            print(f"  Post MPI procs  : {post_num_procs_effective}")
        if args.solve and configs:
            total_steps = configs['case'].get('run_control', {}).get('total_steps', '?')
            result_dir = os.path.join(run_dir, CANONICAL_RUN_PATHS['output'])
            print(f"  {'Steps planned' if staged else 'Steps run':<16}: {total_steps}")
            print(f"  Solver output   : {os.path.relpath(result_dir)}")
        if 'post-process' in stages_completed and output_dir_abs:
            print(f"  Post output     : {os.path.relpath(output_dir_abs)}")
        for stats_path in statistics_output_paths:
            print(f"  Stats output    : {os.path.relpath(stats_path)}")
        # Report the configured log directory, not the default. An authorized external
        # path is exactly the case where the two differ, and it is the case where the
        # reader most needs to know where the logs actually went.
        log_display = os.path.join(run_dir, CANONICAL_RUN_PATHS['logs'])
        relative_log = os.path.relpath(log_display)
        # A relative path that climbs out of the working directory is harder to read
        # than the absolute one it stands for.
        print(f"  Logs            : "
              f"{log_display if relative_log.startswith('..') else relative_log}")
        if cluster_mode or submission_meta.get("stages"):
            submission_file = os.path.join(run_dir, "scheduler", "submission.json")
            print(f"  Submission meta : {os.path.relpath(submission_file)}")
        print("=" * 60)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

parse_case_index_tsv()

list picurv_cli.core.parse_case_index_tsv

(

str

tsv_path

)

Parse a case_index.tsv file back into a list of case entry dicts.

Parameters

[in]

tsv_path

Path to the case_index.tsv file.

Returns

List of dicts with keys: index, case_id, run_dir, control_file, post_recipe_file, log_level, post_prefix.

Definition at line 21312 of file core.py.

def parse_case_index_tsv(tsv_path: str) -> list:
    """!
    @brief Parse a case_index.tsv file back into a list of case entry dicts.
    @param[in] tsv_path Path to the case_index.tsv file.
    @return List of dicts with keys: index, case_id, run_dir, control_file,
            post_recipe_file, log_level, post_prefix.
    """
    entries = []
    with open(tsv_path) as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            parts = line.split("\t")
            entries.append({
                "index": int(parts[0]),
                "case_id": parts[1],
                "run_dir": parts[2],
                "control_file": parts[3],
                "post_recipe_file": parts[4],
                "log_level": parts[5],
                "post_prefix": parts[6],
            })
    return entries
 
 

Here is the caller graph for this function:

resolve_sweep_stage_executables()

dict picurv_cli.core.resolve_sweep_stage_executables

(

list

run_dirs

)

Choose the executables an array stage launches for every member of a study.

Array tasks share one script, which reads each member's RUN_DIR from the case index, so pinned members launch their own copy through the same $RUN_DIR-relative path. Members must agree: a study half pinned, or pinned at different paths, has no single command that launches each member's build.

Parameters

[in]

run_dirs

Member run directories the stage covers.

Returns

Mapping of executable name to (path token, staged --version line or None).

Exceptions

ValueError

when members disagree about pinning.

Definition at line 21338 of file core.py.

def resolve_sweep_stage_executables(run_dirs: list) -> dict:
    """!
    @brief Choose the executables an array stage launches for every member of a study.
 
    @details Array tasks share one script, which reads each member's `RUN_DIR` from the
             case index, so pinned members launch their own copy through the same
             `$RUN_DIR`-relative path. Members must agree: a study half pinned, or pinned
             at different paths, has no single command that launches each member's build.
    @param[in] run_dirs Member run directories the stage covers.
    @return Mapping of executable name to `(path token, staged --version line or None)`.
    @throws ValueError when members disagree about pinning.
    """
    pins = [load_run_executables(run_dir) for run_dir in run_dirs]
    chosen = {}
    for name in RUN_EXECUTABLE_NAMES:
        entries = [pin.get(name) for pin in pins]
        if not any(entries):
            path = resolve_runtime_executable(name)
            chosen[name] = (path, read_binary_build_identity(path).get("version_line"))
            continue
        relatives = {
            os.path.relpath(entry["path"], run_dir).replace(os.sep, "/") if entry else None
            for entry, run_dir in zip(entries, run_dirs)
        }
        lines = {entry.get("version_line") if entry else None for entry in entries}
        if None in relatives or len(relatives) != 1:
            raise ValueError(
                f"Study members disagree about the {name} they are pinned to; one array "
                "script cannot launch each member's build. Restage the study."
            )
        chosen[name] = (f"$RUN_DIR/{relatives.pop()}", lines.pop() if len(lines) == 1 else None)
    return chosen
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

sweep_workflow()

picurv_cli.core.sweep_workflow

(

args

)

Study/sweep orchestration using Slurm job arrays.

Parameters

[in]

args

Command-line style argument list supplied to the function.

Definition at line 21372 of file core.py.

def sweep_workflow(args):
    """!
    @brief Study/sweep orchestration using Slurm job arrays.
    @param[in] args Command-line style argument list supplied to the function.
    """
    study_path = os.path.abspath(args.study)
    cluster_path = os.path.abspath(args.cluster)
    workspace_root = find_workspace_root(study_path, cluster_path, os.getcwd())
    if workspace_root:
        enforce_workspace_version(workspace_root)
        enforce_reproducibility_policy(workspace_root)
 
    study_cfg = read_yaml_file(study_path)
    cluster_cfg = read_yaml_file(cluster_path)
    validate_study_config(study_cfg, study_path)
    validate_cluster_config(cluster_cfg, cluster_path)
 
    study_name = case_run_label(study_cfg, study_path)
    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
    study_id = f"{study_name}_{timestamp}"
    study_dir = os.path.join(workspace_artifact_root(workspace_root, "studies"), study_id)
    cases_dir = os.path.join(study_dir, "cases")
    scheduler_dir = os.path.join(study_dir, "scheduler")
    results_dir = os.path.join(study_dir, "output", "analysis")
    for path in [cases_dir, scheduler_dir, results_dir, os.path.join(study_dir, "logs")]:
        os.makedirs(path, exist_ok=True)
 
    print(f"[INFO] Creating study directory: {os.path.relpath(study_dir)}")
    base_cfgs = study_cfg["base_configs"]
    base_paths = {k: resolve_path(study_path, v) for k, v in base_cfgs.items()}
    base_snapshot_dir = os.path.join(study_dir, "base_configs")
    os.makedirs(base_snapshot_dir, exist_ok=True)
    portable_study_cfg = copy.deepcopy(study_cfg)
    portable_study_cfg["base_configs"] = {}
    for role in ("case", "solver", "monitor", "post"):
        snapshot_name = f"{role}.yml"
        snapshot_path = os.path.join(base_snapshot_dir, snapshot_name)
        shutil.copy2(base_paths[role], snapshot_path)
        portable_study_cfg["base_configs"][role] = os.path.join("base_configs", snapshot_name)
    shutil.copy2(study_path, os.path.join(study_dir, "study.source.yml"))
    write_yaml_file(os.path.join(study_dir, "study.yml"), portable_study_cfg)
    shutil.copy2(cluster_path, os.path.join(study_dir, "cluster.yml"))
 
    base_case = read_yaml_file(base_paths["case"])
    base_solver = read_yaml_file(base_paths["solver"])
    base_monitor = read_yaml_file(base_paths["monitor"])
    base_post = read_yaml_file(base_paths["post"])
    validate_simulation_configs(base_case, base_solver, base_monitor, base_paths["case"], base_paths["solver"], base_paths["monitor"])
    validate_post_config(base_post, base_paths["post"], base_monitor, base_case)
 
    combinations = expand_study_parameter_combinations(study_cfg)
    if not combinations:
        print("[FATAL] Study parameter matrix expanded to zero cases.", file=sys.stderr)
        sys.exit(1)
    print(f"[INFO] Expanded sweep matrix to {len(combinations)} case(s).")
 
    cluster_tasks = get_cluster_total_tasks(cluster_cfg)
    case_entries = []
    case_index_file = os.path.join(scheduler_dir, "case_index.tsv")
 
    # One array script launches every member, so the study runs on one PetscInt width: the
    # widest any member needs, unless one was requested.
    member_widths = []
    for combo in combinations:
        member = {"case": copy.deepcopy(base_case), "monitor": copy.deepcopy(base_monitor),
                  "solver": {}, "post": {}}
        for full_key, value in combo.items():
            root, nested = full_key.split(".", 1)
            _deep_set(member[root], nested, value)
        absolutize_case_external_paths(member["case"], base_paths["case"])
        member_widths.append(required_petsc_index_bytes(member["case"], base_paths["case"], member["monitor"]))
    try:
        requested = requested_petsc_index_bytes(args)
        widest = max(member_widths, default=(4, "particle and grid fields fit 32-bit indices"))
        if requested == 4 and widest[0] == 8:
            raise ValueError(f"--petsc-index-bits 32 cannot run every study member: {widest[1]}.")
        if requested is not None:
            select_petsc_index_bytes(requested, f"{8 * requested}-bit indices were requested")
        else:
            select_petsc_index_bytes(*widest)
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    for idx, combo in enumerate(combinations):
        case_id = f"case_{idx:04d}"
        run_dir = os.path.join(cases_dir, case_id)
        config_dir = os.path.join(run_dir, "config")
        ensure_run_layout(run_dir)
 
        case_cfg = copy.deepcopy(base_case)
        solver_cfg = copy.deepcopy(base_solver)
        monitor_cfg = copy.deepcopy(base_monitor)
        post_cfg = copy.deepcopy(base_post)
        target_map = {"case": case_cfg, "solver": solver_cfg, "monitor": monitor_cfg, "post": post_cfg}
        for full_key, value in combo.items():
            root, nested = full_key.split(".", 1)
            _deep_set(target_map[root], nested, value)
 
        # Preserve file-based/grid-gen workflows when study cases are materialized
        # into new directories by rewriting external paths as absolute.
        absolutize_case_external_paths(case_cfg, base_paths["case"])
 
        case_path = os.path.join(config_dir, "case.yml")
        solver_path = os.path.join(config_dir, "solver.yml")
        monitor_path = os.path.join(config_dir, "monitor.yml")
        post_path = os.path.join(config_dir, "post.yml")
        write_yaml_file(case_path, case_cfg)
        write_yaml_file(solver_path, solver_cfg)
        write_yaml_file(monitor_path, monitor_cfg)
        write_yaml_file(post_path, post_cfg)
        write_json_file(os.path.join(config_dir, "active.json"), {
            "schema_version": 1,
            "revision": "initial",
            "updated_at": datetime.now().astimezone().isoformat(),
            "files": {
                "case": "config/case.yml",
                "solver": "config/solver.yml",
                "monitor": "config/monitor.yml",
            },
        })
        record_run_petsc_index_bytes(run_dir)
        if resolve_executable_pinning(args, workspace_root):
            try:
                pin_run_executables(run_dir, "initial")
            except ValueError as exc:
                print(f"[FATAL] {exc}", file=sys.stderr)
                sys.exit(1)
 
        validate_simulation_configs(case_cfg, solver_cfg, monitor_cfg, case_path, solver_path, monitor_path)
        validate_post_config(post_cfg, post_path, monitor_cfg, case_cfg)
 
        try:
            asset_lock = materialize_run_assets(
                run_dir, case_cfg, case_path, skip_kinds=unused_asset_kinds(case_cfg, solver_cfg)
            )
        except ValueError as exc:
            print(f"[FATAL] Study case {case_id}: {exc}", file=sys.stderr)
            sys.exit(1)
 
        source_files = {'Case': case_path, 'Solver': solver_path, 'Monitor': monitor_path}
        monitor_files = prepare_monitor_files(run_dir, case_id, monitor_cfg, source_files)
        configs = {
            "case": case_cfg, "case_path": case_path,
            "solver": solver_cfg, "solver_path": solver_path,
            "monitor": monitor_cfg, "monitor_path": monitor_path,
            "walltime_guard_policy": resolve_walltime_guard_policy(cluster_cfg),
            "cluster_cfg": cluster_cfg,
        }
        control_file = generate_solver_control_file(run_dir, case_id, configs, cluster_tasks, monitor_files)
        archive_active_generated_configuration(
            run_dir,
            [control_file, monitor_files.get("whitelist"), monitor_files.get("profile"),
             *glob.glob(os.path.join(config_dir, "bcs*.run"))],
        )
 
        source_dir = resolve_post_source_directory(run_dir, monitor_cfg, post_cfg, strict=False)
        if not isinstance(post_cfg.get('source_data'), dict):
            post_cfg['source_data'] = {}
        post_cfg['source_data']['directory'] = source_dir
        post_cfg, recipe_id = apply_canonical_post_paths(post_cfg, run_dir)
        for relative in (
            post_cfg["_picurv_paths"]["visualization"],
            post_cfg["_picurv_paths"]["statistics"],
            post_cfg["_picurv_paths"]["spectra"],
        ):
            os.makedirs(os.path.join(run_dir, relative), exist_ok=True)
        output_prefix = post_cfg.get("io", {}).get("output_filename_prefix", "post")
        post_decomposition = resolve_post_decomposition(run_dir, cluster_tasks, None, cluster_cfg)
        if post_decomposition["problems"]:
            print(f"[FATAL] Study case {case_id}: {' '.join(post_decomposition['problems'])}", file=sys.stderr)
            sys.exit(1)
        post_recipe = generate_post_recipe_file(run_dir, case_id, post_cfg, {'Case': case_path, 'Post-Profile': post_path},
                                                monitor_cfg, post_decomposition)
        ensure_post_lock_wrapper(run_dir)
 
        case_entries.append({
            "index": idx,
            "case_id": case_id,
            "run_dir": os.path.abspath(run_dir),
            "control_file": control_file,
            "post_recipe_file": post_recipe,
            "log_level": str(monitor_cfg.get("logging", {}).get("verbosity", "INFO")).upper(),
            "post_prefix": output_prefix,
            "solve_diagnostic_args": shlex.join(build_petsc_diagnostics_args(monitor_cfg, run_dir, "Solver")),
            "post_diagnostic_args": shlex.join(build_petsc_diagnostics_args(monitor_cfg, run_dir, "PostProcessor")),
            "parameters": combo,
        })
        write_json_file(
            os.path.join(run_dir, "manifest.json"),
            build_run_manifest(
                run_dir, case_id, workspace_root=workspace_root, launch_mode="slurm",
                artifact_type="study-case", study_id=study_id, case_id=case_id,
                num_procs=cluster_tasks, post_num_procs=cluster_tasks,
                stages_requested={"solve": True, "post_process": True},
                inputs={
                    "case": _relative_to_workspace(case_path, workspace_root),
                    "solver": _relative_to_workspace(solver_path, workspace_root),
                    "monitor": _relative_to_workspace(monitor_path, workspace_root),
                    "post": _relative_to_workspace(post_path, workspace_root),
                },
                asset_lock=asset_lock,
            ),
        )
 
    with open(case_index_file, "w") as f:
        for entry in case_entries:
            f.write(
                "\t".join(
                    [
                        str(entry["index"]),
                        entry["case_id"],
                        entry["run_dir"],
                        entry["control_file"],
                        entry["post_recipe_file"],
                        entry["log_level"],
                        entry["post_prefix"],
                        entry["solve_diagnostic_args"],
                        entry["post_diagnostic_args"],
                    ]
                ) + "\n"
            )
    print(f"[SUCCESS] Wrote sweep case index: {os.path.relpath(case_index_file)}")
 
    max_idx = len(case_entries) - 1
    max_conc = study_cfg.get("execution", {}).get("max_concurrent_array_tasks")
    array_spec = f"0-{max_idx}"
    if max_conc:
        array_spec = f"{array_spec}%{max_conc}"
 
    stage_executables = resolve_sweep_stage_executables([entry["run_dir"] for entry in case_entries])
    solver_exe, solver_version_line = stage_executables["simulator"]
    post_exe, post_version_line = stage_executables["postprocessor"]
    solver_array_script = os.path.join(scheduler_dir, "solver_array.sbatch")
    post_array_script = os.path.join(scheduler_dir, "post_array.sbatch")
    render_slurm_array_stage_script(
        solver_array_script,
        f"{study_id}_solve",
        cluster_cfg,
        array_spec,
        case_index_file,
        "solve",
        solver_exe,
        post_exe,
        os.path.join(scheduler_dir, "solver_%A_%a.out"),
        os.path.join(scheduler_dir, "solver_%A_%a.err"),
        expected_version_line=solver_version_line,
    )
    render_slurm_array_stage_script(
        post_array_script,
        f"{study_id}_post",
        cluster_cfg,
        array_spec,
        case_index_file,
        "post",
        solver_exe,
        post_exe,
        os.path.join(scheduler_dir, "post_%A_%a.out"),
        os.path.join(scheduler_dir, "post_%A_%a.err"),
        expected_version_line=post_version_line,
    )
    print(f"[SUCCESS] Generated Slurm array scripts in {os.path.relpath(scheduler_dir)}")
 
    picurv_path = os.path.abspath(os.path.join(INVOKED_SCRIPT_DIR, "picurv"))
    metrics_aggregate_script = os.path.join(scheduler_dir, "metrics_aggregate.sbatch")
    render_metrics_aggregate_script(
        metrics_aggregate_script,
        f"{study_id}_metrics",
        cluster_cfg,
        study_dir,
        picurv_path,
    )
    print(f"[SUCCESS] Generated metrics aggregation script: {os.path.relpath(metrics_aggregate_script)}")
 
    submission = {
        "launch_mode": "slurm",
        "study_id": study_id,
        "solver_array": {"script": solver_array_script, "submitted": False},
        "post_array": {"script": post_array_script, "submitted": False},
        "metrics_aggregate": {"script": metrics_aggregate_script, "submitted": False},
        "no_submit": bool(args.no_submit),
    }
    if not args.no_submit:
        solver_submit = submit_sbatch(solver_array_script)
        submission["solver_array"].update(solver_submit)
        submission["solver_array"]["submitted"] = True
        post_submit = submit_sbatch(post_array_script, dependency=solver_submit["job_id"])
        submission["post_array"].update(post_submit)
        submission["post_array"]["submitted"] = True
        submission["post_array"]["dependency"] = f"afterok:{solver_submit['job_id']}"
        metrics_submit = submit_sbatch(metrics_aggregate_script, dependency=post_submit["job_id"], dependency_type="afterany")
        submission["metrics_aggregate"].update(metrics_submit)
        submission["metrics_aggregate"]["submitted"] = True
        submission["metrics_aggregate"]["dependency"] = f"afterany:{post_submit['job_id']}"
        print(f"[SUCCESS] Submitted solver array job:  {solver_submit['job_id']}")
        print(f"[SUCCESS] Submitted post array job:    {post_submit['job_id']}")
        print(f"[SUCCESS] Submitted metrics agg. job:  {metrics_submit['job_id']}")
 
    metrics_csv = aggregate_study_metrics(study_cfg, case_entries, results_dir)
    plots = generate_study_plots(study_cfg, metrics_csv, os.path.join(results_dir, "plots"))
 
    summary = {
        "schema_version": 2,
        "artifact_type": "study",
        "study_id": study_id,
        "created_at": datetime.now().isoformat(),
        "software": dict(picurv_build()),
        "study_type": study_cfg.get("study_type"),
        "num_cases": len(case_entries),
        "paths": {
            "study_dir": study_dir,
            "case_index": case_index_file,
            "solver_array_script": solver_array_script,
            "post_array_script": post_array_script,
            "metrics_table": metrics_csv,
            "plots_dir": os.path.join(results_dir, "plots"),
        },
        "submission": submission,
    }
    write_json_file(os.path.join(scheduler_dir, "submission.json"), submission)
    write_json_file(os.path.join(study_dir, "study_manifest.json"), summary)
    write_json_file(os.path.join(results_dir, "summary.json"), {"study_id": study_id, "metrics_csv": metrics_csv, "plots": plots})
 
    print("\n" + "=" * 60)
    print("                     STUDY SUMMARY")
    print("=" * 60)
    print(f"  Study ID        : {study_id}")
    print(f"  Study directory : {os.path.relpath(study_dir)}")
    print(f"  Cases generated : {len(case_entries)}")
    print(f"  Array spec      : {array_spec}")
    print(f"  Solver script   : {os.path.relpath(solver_array_script)}")
    print(f"  Post script     : {os.path.relpath(post_array_script)}")
    if args.no_submit:
        print(f"  Submit with     : picurv submit --study-dir {os.path.relpath(study_dir)}")
    if metrics_csv:
        print(f"  Metrics table   : {os.path.relpath(metrics_csv)}")
    if plots:
        print(f"  Plots           : {os.path.relpath(os.path.join(results_dir, 'plots'))}")
    print("=" * 60)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

sweep_continue_workflow()

picurv_cli.core.sweep_continue_workflow

(

args

)

Continue a partially-completed Slurm parameter sweep study.

Detects incomplete cases, prepares them for continuation (updating start_step, populating restart directories, regenerating control files), and submits new solver/post/metrics Slurm jobs. If all cases are already complete, performs metrics aggregation automatically.

Parameters

[in]

args

Parsed CLI arguments with study_dir and optional cluster override.

Definition at line 21713 of file core.py.

def sweep_continue_workflow(args):
    """!
    @brief Continue a partially-completed Slurm parameter sweep study.
    @details Detects incomplete cases, prepares them for continuation (updating
             start_step, populating restart directories, regenerating control files),
             and submits new solver/post/metrics Slurm jobs. If all cases are already
             complete, performs metrics aggregation automatically.
    @param[in] args Parsed CLI arguments with study_dir and optional cluster override.
    """
    study_dir = os.path.abspath(args.study_dir)
    manifest_path = os.path.join(study_dir, "study_manifest.json")
    if not os.path.isfile(manifest_path):
        emit_structured_error(ERROR_CODE_CFG_FILE_NOT_FOUND, key="study_dir", file_path=manifest_path,
                              message="Study manifest not found.", hint=_STUDY_DIR_HINT)
        sys.exit(1)
    adopt_relocated_artifact(study_dir, kind="study")
    manifest = _read_json_if_exists(manifest_path)
    study_id = manifest["study_id"]
 
    study_path = os.path.join(study_dir, "study.yml")
    cluster_path = os.path.abspath(args.cluster) if args.cluster else os.path.join(study_dir, "cluster.yml")
    study_cfg = read_yaml_file(study_path)
    cluster_cfg = read_yaml_file(cluster_path)
    validate_study_config(study_cfg, study_path, skip_base_file_check=True)
    validate_cluster_config(cluster_cfg, cluster_path)
 
    if args.cluster:
        shutil.copy(os.path.abspath(args.cluster), os.path.join(study_dir, "cluster.yml"))
        print(f"[INFO] Updated study cluster config from: {os.path.relpath(args.cluster)}")
 
    scheduler_dir = os.path.join(study_dir, "scheduler")
    cases_dir = os.path.join(study_dir, "cases")
    results_dir = os.path.join(study_dir, "output", "analysis")
    case_index_file = os.path.join(scheduler_dir, "case_index.tsv")
    if not os.path.isfile(case_index_file):
        print(f"[FATAL] Case index not found: {case_index_file}", file=sys.stderr)
        sys.exit(1)
 
    parsed_entries = parse_case_index_tsv(case_index_file)
 
    cold_cases = cold_study_members(study_dir)
    if cold_cases and getattr(args, "auto_fetch", False):
        print(
            "[INFO] --auto-fetch: restoring cold-storage member(s) before continuing: "
            + ", ".join(cold_cases)
        )
        try:
            restore_cold_study_members(study_dir, cold_cases)
        except StorageError as exc:
            print(f"[FATAL] Automatic restore failed: {exc}", file=sys.stderr)
            sys.exit(1)
        cold_cases = cold_study_members(study_dir)
    if cold_cases:
        print(
            "[FATAL] Study continuation requires payload from cold-storage member(s): "
            + ", ".join(cold_cases),
            file=sys.stderr,
        )
        for case_id in cold_cases:
            state = storage_state_summary(os.path.join(cases_dir, case_id))
            print(
                f"        Restore {case_id} with: picurv storage restore --archive-id "
                f"{state.get('archive_id') or '<archive-id>'}",
                file=sys.stderr,
            )
        print(
            "        Or pass --auto-fetch to restore them automatically.",
            file=sys.stderr,
        )
        sys.exit(1)
 
    # Staging writes these as snapshots inside the study (base_configs/<role>.yml), so
    # they resolve against the study directory, not the workspace that holds it.
    base_cfgs = study_cfg["base_configs"]
    base_paths = {k: os.path.join(study_dir, v) for k, v in base_cfgs.items()}
    base_case = read_yaml_file(base_paths["case"])
 
    combinations = expand_study_parameter_combinations(study_cfg)
    if len(combinations) != len(parsed_entries):
        print(
            f"[FATAL] Parameter matrix ({len(combinations)} cases) does not match "
            f"case_index.tsv ({len(parsed_entries)} entries).",
            file=sys.stderr,
        )
        sys.exit(1)
 
    print(f"\n[INFO] Study: {study_id}")
    print(f"[INFO] Scanning {len(combinations)} case(s) for completion status...")
 
    incomplete_indices = []
    all_case_entries = []
    for idx, combo in enumerate(combinations):
        case_id = f"case_{idx:04d}"
        entry = parsed_entries[idx]
        entry["parameters"] = combo
        run_dir = entry["run_dir"]
 
        effective_case = copy.deepcopy(base_case)
        for full_key, value in combo.items():
            root, nested = full_key.split(".", 1)
            if root == "case":
                _deep_set(effective_case, nested, value)
        try:
            eff_start = int(effective_case.get("run_control", {}).get("start_step", 0) or 0)
        except (TypeError, ValueError):
            eff_start = 0
        eff_total = int(effective_case["run_control"]["total_steps"])
        target = eff_start + eff_total
 
        monitor_cfg = read_yaml_file(os.path.join(run_dir, "config", "monitor.yml"))
        status = detect_case_completion_status(run_dir, monitor_cfg, target)
        entry["_status"] = status
 
        if status["status"] == "complete":
            print(f"  {case_id}: complete (step {status['last_step']}/{target})")
        elif status["status"] == "partial":
            print(f"  {case_id}: incomplete (step {status['last_step']}/{target}) — will continue")
            incomplete_indices.append(idx)
        else:
            print(f"  {case_id}: no checkpoint — will re-run from scratch")
            incomplete_indices.append(idx)
 
        all_case_entries.append(entry)
 
    if not incomplete_indices:
        print("\n[INFO] All cases are complete. Running metrics aggregation...")
        metrics_csv = aggregate_study_metrics(study_cfg, all_case_entries, results_dir)
        plots = generate_study_plots(study_cfg, metrics_csv, os.path.join(results_dir, "plots"))
        print("\n" + "=" * 60)
        print("              STUDY CONTINUATION SUMMARY")
        print("=" * 60)
        print(f"  Study ID        : {study_id}")
        print(f"  Status          : ALL COMPLETE")
        if metrics_csv:
            print(f"  Metrics table   : {os.path.relpath(metrics_csv)}")
        if plots:
            print(f"  Plots           : {os.path.relpath(os.path.join(results_dir, 'plots'))}")
        print("=" * 60)
        return
 
    print(f"\n[INFO] {len(incomplete_indices)} incomplete case(s) to continue/re-run.")
 
    skipped = []
    for idx in incomplete_indices:
        entry = all_case_entries[idx]
        status = entry["_status"]
        if status["status"] == "partial":
            prepare_case_for_continuation(
                entry["run_dir"], entry["case_id"],
                status["last_step"], status["target_step"],
                cluster_cfg,
            )
        elif status["status"] == "empty":
            print(f"[INFO] {entry['case_id']}: re-running from scratch (no control file changes)")
 
    solver_array_spec = ",".join(str(i) for i in incomplete_indices)
    max_conc = study_cfg.get("execution", {}).get("max_concurrent_array_tasks")
    if max_conc:
        solver_array_spec = f"{solver_array_spec}%{max_conc}"
 
    max_idx = len(combinations) - 1
    post_array_spec = f"0-{max_idx}"
    if max_conc:
        post_array_spec = f"{post_array_spec}%{max_conc}"
 
    try:
        stage_executables = resolve_sweep_stage_executables(
            [entry["run_dir"] for entry in all_case_entries]
        )
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
    solver_exe, solver_version_line = stage_executables["simulator"]
    post_exe, post_version_line = stage_executables["postprocessor"]
    # The post array relaunches every member through the lock wrapper; a study staged
    # by an earlier version holds a wrapper without the launch-time planning it needs.
    for entry in all_case_entries:
        ensure_post_lock_wrapper(entry["run_dir"])
 
    solver_continue_script = os.path.join(scheduler_dir, "solver_continue_array.sbatch")
    post_continue_script = os.path.join(scheduler_dir, "post_continue_array.sbatch")
    render_slurm_array_stage_script(
        solver_continue_script,
        f"{study_id}_solve_cont",
        cluster_cfg,
        solver_array_spec,
        case_index_file,
        "solve",
        solver_exe, post_exe,
        os.path.join(scheduler_dir, "solver_cont_%A_%a.out"),
        os.path.join(scheduler_dir, "solver_cont_%A_%a.err"),
        expected_version_line=solver_version_line,
    )
    render_slurm_array_stage_script(
        post_continue_script,
        f"{study_id}_post_cont",
        cluster_cfg,
        post_array_spec,
        case_index_file,
        "post",
        solver_exe, post_exe,
        os.path.join(scheduler_dir, "post_cont_%A_%a.out"),
        os.path.join(scheduler_dir, "post_cont_%A_%a.err"),
        expected_version_line=post_version_line,
    )
 
    picurv_path = os.path.abspath(os.path.join(INVOKED_SCRIPT_DIR, "picurv"))
    metrics_aggregate_script = os.path.join(scheduler_dir, "metrics_continue_aggregate.sbatch")
    render_metrics_aggregate_script(
        metrics_aggregate_script,
        f"{study_id}_metrics_cont",
        cluster_cfg,
        study_dir,
        picurv_path,
    )
    print(f"[SUCCESS] Generated continuation scripts in {os.path.relpath(scheduler_dir)}")
 
    submission = {
        "launch_mode": "slurm",
        "study_id": study_id,
        "continuation": True,
        "incomplete_cases": [all_case_entries[i]["case_id"] for i in incomplete_indices],
        "solver_continue_array": {"script": solver_continue_script, "submitted": False},
        "post_continue_array": {"script": post_continue_script, "submitted": False},
        "metrics_aggregate": {"script": metrics_aggregate_script, "submitted": False},
        "no_submit": bool(args.no_submit),
    }
    if not args.no_submit:
        solver_submit = submit_sbatch(solver_continue_script)
        submission["solver_continue_array"].update(solver_submit)
        submission["solver_continue_array"]["submitted"] = True
        post_submit = submit_sbatch(post_continue_script, dependency=solver_submit["job_id"])
        submission["post_continue_array"].update(post_submit)
        submission["post_continue_array"]["submitted"] = True
        submission["post_continue_array"]["dependency"] = f"afterok:{solver_submit['job_id']}"
        metrics_submit = submit_sbatch(metrics_aggregate_script, dependency=post_submit["job_id"], dependency_type="afterany")
        submission["metrics_aggregate"].update(metrics_submit)
        submission["metrics_aggregate"]["submitted"] = True
        submission["metrics_aggregate"]["dependency"] = f"afterany:{post_submit['job_id']}"
        print(f"[SUCCESS] Submitted continuation solver array: {solver_submit['job_id']}")
        print(f"[SUCCESS] Submitted continuation post array:   {post_submit['job_id']}")
        print(f"[SUCCESS] Submitted metrics aggregation job:   {metrics_submit['job_id']}")
 
    write_json_file(os.path.join(scheduler_dir, "submission_continue.json"), submission)
 
    manifest["continuation"] = {
        "continued_at": datetime.now().isoformat(),
        "incomplete_cases": [all_case_entries[i]["case_id"] for i in incomplete_indices],
        "submission": submission,
    }
    write_json_file(manifest_path, manifest)
 
    print("\n" + "=" * 60)
    print("              STUDY CONTINUATION SUMMARY")
    print("=" * 60)
    print(f"  Study ID          : {study_id}")
    print(f"  Incomplete cases  : {len(incomplete_indices)}/{len(combinations)}")
    print(f"  Solver array spec : {solver_array_spec}")
    print(f"  Post array spec   : {post_array_spec}")
    print(f"  Solver script     : {os.path.relpath(solver_continue_script)}")
    print(f"  Post script       : {os.path.relpath(post_continue_script)}")
    print(f"  Metrics script    : {os.path.relpath(metrics_aggregate_script)}")
    if not args.no_submit:
        print(f"  [Metrics aggregation will run automatically after post-processing]")
    else:
        print(f"  [--no-submit] Scripts generated but not submitted. Submit them with:")
        print(f"    picurv submit --study-dir {os.path.relpath(study_dir)}")
    print("=" * 60)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

sweep_reaggregate_workflow()

picurv_cli.core.sweep_reaggregate_workflow

(

args

)

Re-run metrics aggregation and plot generation for an existing study.

Parameters

[in]

args

Parsed CLI arguments with study_dir.

Definition at line 21983 of file core.py.

def sweep_reaggregate_workflow(args):
    """!
    @brief Re-run metrics aggregation and plot generation for an existing study.
    @param[in] args Parsed CLI arguments with study_dir.
    """
    study_dir = os.path.abspath(args.study_dir)
    study_path = os.path.join(study_dir, "study.yml")
    if not os.path.isfile(study_path):
        emit_structured_error(ERROR_CODE_CFG_FILE_NOT_FOUND, key="study_dir", file_path=study_path,
                              message="Study config not found.", hint=_STUDY_DIR_HINT)
        sys.exit(1)
    adopt_relocated_artifact(study_dir, kind="study")
    study_cfg = read_yaml_file(study_path)
    validate_study_config(study_cfg, study_path, skip_base_file_check=True)
 
    case_index_file = os.path.join(study_dir, "scheduler", "case_index.tsv")
    if not os.path.isfile(case_index_file):
        print(f"[FATAL] Case index not found: {case_index_file}", file=sys.stderr)
        sys.exit(1)
 
    parsed_entries = parse_case_index_tsv(case_index_file)
    cold_cases = cold_study_members(study_dir)
    if cold_cases and getattr(args, "auto_fetch", False):
        print(
            "[INFO] --auto-fetch: restoring cold-storage member(s) before aggregating: "
            + ", ".join(cold_cases)
        )
        try:
            restore_cold_study_members(study_dir, cold_cases)
        except StorageError as exc:
            print(f"[FATAL] Automatic restore failed: {exc}", file=sys.stderr)
            sys.exit(1)
        cold_cases = cold_study_members(study_dir)
    if cold_cases:
        print(
            "[INFO] Cold-storage member(s) cannot be re-measured; their previously "
            "aggregated values are carried forward: " + ", ".join(cold_cases)
        )
    combinations = expand_study_parameter_combinations(study_cfg)
    if len(combinations) != len(parsed_entries):
        print(
            f"[FATAL] Parameter matrix ({len(combinations)} cases) does not match "
            f"case_index.tsv ({len(parsed_entries)} entries).",
            file=sys.stderr,
        )
        sys.exit(1)
 
    case_entries = []
    for idx, combo in enumerate(combinations):
        entry = parsed_entries[idx]
        entry["parameters"] = combo
        case_entries.append(entry)
 
    results_dir = os.path.join(study_dir, "output", "analysis")
    metrics_csv = aggregate_study_metrics(study_cfg, case_entries, results_dir)
    plots = generate_study_plots(study_cfg, metrics_csv, os.path.join(results_dir, "plots"))
 
    print("\n" + "=" * 60)
    print("              REAGGREGATION SUMMARY")
    print("=" * 60)
    if metrics_csv:
        print(f"  Metrics table   : {os.path.relpath(metrics_csv)}")
    if plots:
        print(f"  Plots generated : {len(plots)}")
    print("=" * 60)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_read_yaml_if_exists()

picurv_cli.core._read_yaml_if_exists ( str  filepath )

protected

Read YAML when present, otherwise return None.

Parameters

[in]

filepath

Argument passed to _read_yaml_if_exists().

Returns

Value returned by _read_yaml_if_exists().

Definition at line 22053 of file core.py.

def _read_yaml_if_exists(filepath: str):
    """!
    @brief Read YAML when present, otherwise return None.
    @param[in] filepath Argument passed to `_read_yaml_if_exists()`.
    @return Value returned by `_read_yaml_if_exists()`.
    """
    if not filepath or not os.path.isfile(filepath):
        return None
    try:
        with open(filepath, "r", encoding="utf-8") as f:
            return yaml.safe_load(f)
    except yaml.YAMLError:
        return None
 
 

Here is the caller graph for this function:

_read_json_if_exists()

picurv_cli.core._read_json_if_exists ( str  filepath )

protected

Read JSON when present, otherwise return None.

Parameters

[in]

filepath

Argument passed to _read_json_if_exists().

Returns

Value returned by _read_json_if_exists().

Definition at line 22068 of file core.py.

def _read_json_if_exists(filepath: str):
    """!
    @brief Read JSON when present, otherwise return None.
    @param[in] filepath Argument passed to `_read_json_if_exists()`.
    @return Value returned by `_read_json_if_exists()`.
    """
    if not filepath or not os.path.isfile(filepath):
        return None
    with open(filepath, "r", encoding="utf-8") as f:
        return json.load(f)
 
 

Here is the caller graph for this function:

_parse_int_loose()

picurv_cli.core._parse_int_loose (   value )

protected

Best-effort integer parsing for summary extraction.

Parameters

[in]

value

Argument passed to _parse_int_loose().

Returns

Value returned by _parse_int_loose().

Definition at line 22080 of file core.py.

def _parse_int_loose(value):
    """!
    @brief Best-effort integer parsing for summary extraction.
    @param[in] value Argument passed to `_parse_int_loose()`.
    @return Value returned by `_parse_int_loose()`.
    """
    if value is None:
        return None
    text = str(value).strip()
    if not text:
        return None
    try:
        return int(text)
    except ValueError:
        try:
            return int(float(text))
        except ValueError:
            return None
 
 

Here is the caller graph for this function:

_parse_float_loose()

picurv_cli.core._parse_float_loose (   value )

protected

Best-effort float parsing for summary extraction.

Parameters

[in]

value

Argument passed to _parse_float_loose().

Returns

Value returned by _parse_float_loose().

Definition at line 22100 of file core.py.

def _parse_float_loose(value):
    """!
    @brief Best-effort float parsing for summary extraction.
    @param[in] value Argument passed to `_parse_float_loose()`.
    @return Value returned by `_parse_float_loose()`.
    """
    if value is None:
        return None
    text = str(value).strip()
    if not text:
        return None
    try:
        return float(text)
    except ValueError:
        return None
 
 

Here is the caller graph for this function:

_extract_numeric_tuple()

picurv_cli.core._extract_numeric_tuple ( str  text )

protected

Extract a numeric tuple from a string like '(1, 2, 3)'.

Parameters

[in]

text

Argument passed to _extract_numeric_tuple().

Returns

Value returned by _extract_numeric_tuple().

Definition at line 22117 of file core.py.

def _extract_numeric_tuple(text: str):
    """!
    @brief Extract a numeric tuple from a string like '(1, 2, 3)'.
    @param[in] text Argument passed to `_extract_numeric_tuple()`.
    @return Value returned by `_extract_numeric_tuple()`.
    """
    if not text:
        return []
    return [float(token) for token in _SUMMARY_NUMERIC_RE.findall(text)]
 
 

Here is the caller graph for this function:

_build_summary_context()

dict picurv_cli.core._build_summary_context ( str  run_dir )

protected

Resolve run-local config and artifact paths for summarize.

Parameters

[in]

run_dir

Argument passed to _build_summary_context().

Returns

Value returned by _build_summary_context().

Definition at line 22128 of file core.py.

def _build_summary_context(run_dir: str) -> dict:
    """!
    @brief Resolve run-local config and artifact paths for summarize.
    @param[in] run_dir Argument passed to `_build_summary_context()`.
    @return Value returned by `_build_summary_context()`.
    """
    run_dir = os.path.abspath(run_dir)
    if not os.path.isdir(run_dir):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="run_dir",
            file_path=run_dir,
            message="Run directory not found.",
        )
        sys.exit(1)
 
    config_dir = os.path.join(run_dir, "config")
    config_paths = {
        "case": os.path.join(config_dir, "case.yml"),
        "solver": os.path.join(config_dir, "solver.yml"),
        "monitor": os.path.join(config_dir, "monitor.yml"),
    }
    monitor_cfg = _read_yaml_if_exists(config_paths["monitor"]) or {}
    case_cfg = _read_yaml_if_exists(config_paths["case"]) or {}
    solver_cfg = _read_yaml_if_exists(config_paths["solver"]) or {}
    manifest = _read_json_if_exists(os.path.join(run_dir, "manifest.json")) or {}
 
    io_cfg = monitor_cfg.get("io", {}) if isinstance(monitor_cfg, dict) else {}
    scheduler_dir = os.path.join(run_dir, "scheduler")
 
    profiling_cfg = {"mode": "off", "functions": [], "final_summary_enabled": True, "helpers": []}
    if monitor_cfg:
        profiling_cfg = resolve_profiling_config(monitor_cfg)
 
    particle_console_output_freq = None
    particle_log_interval = None
    if monitor_cfg:
        particle_console_output_freq = resolve_particle_console_output_frequency(io_cfg)
        particle_log_interval = io_cfg.get("particle_log_interval")
 
    particle_count_cfg = None
    if case_cfg:
        particle_count_cfg = (
            case_cfg.get("models", {})
            .get("physics", {})
            .get("particles", {})
            .get("count")
        )
 
    return {
        "run_dir": run_dir,
        "config_dir": config_dir,
        "log_dir": os.path.join(run_dir, CANONICAL_RUN_PATHS["logs"]),
        "metrics_dir": os.path.join(run_dir, CANONICAL_RUN_PATHS["metrics"]),
        "scheduler_dir": scheduler_dir,
        "monitor_cfg": monitor_cfg,
        "case_cfg": case_cfg,
        "solver_cfg": solver_cfg,
        "config_paths": config_paths,
        "manifest": manifest,
        "profiling_cfg": profiling_cfg,
        "particle_console_output_freq": particle_console_output_freq,
        "particle_log_interval": particle_log_interval,
        "particle_count_cfg": particle_count_cfg,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_require_summary_config()

dict picurv_cli.core._require_summary_config ( dict  context, str  name  )

protected

Return one explicitly requested copied config or fail with a structured error.

Parameters

[in]	context	Summary context returned by _build_summary_context().
[in]	name	Config selector name.

Returns

Parsed config mapping.

Definition at line 22195 of file core.py.

def _require_summary_config(context: dict, name: str) -> dict:
    """!
    @brief Return one explicitly requested copied config or fail with a structured error.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] name Config selector name.
    @return Parsed config mapping.
    """
    path = context["config_paths"][name]
    cfg = context.get(f"{name}_cfg")
    if not os.path.isfile(path):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key=name,
            file_path=path,
            message=f"Copied run config '{name}.yml' was not found.",
            hint="Use a staged run directory containing the requested copied config.",
        )
        sys.exit(1)
    if not isinstance(cfg, dict) or not cfg:
        emit_structured_error(
            ERROR_CODE_CFG_INVALID_VALUE,
            key=name,
            file_path=path,
            message=f"Copied run config '{name}.yml' is empty or is not a YAML mapping.",
        )
        sys.exit(1)
    return cfg
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_build_run_overview()

dict picurv_cli.core._build_run_overview ( dict  context )

protected

Build timestep-independent run metadata for summarize.

Parameters

[in]

context

Summary context returned by _build_summary_context().

Returns

Curated run metadata mapping.

Definition at line 22224 of file core.py.

def _build_run_overview(context: dict) -> dict:
    """!
    @brief Build timestep-independent run metadata for summarize.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Curated run metadata mapping.
    """
    manifest = context["manifest"]
    software = manifest.get("software") if isinstance(manifest.get("software"), dict) else {}
    return {
        "run_id": manifest.get("run_id", os.path.basename(context["run_dir"])),
        "run_dir": context["run_dir"],
        "created_at": manifest.get("created_at"),
        "launch_mode": manifest.get("launch_mode"),
        "release_version": software.get("release_version"),
        "build_id": software.get("build_id"),
        "git_commit": software.get("git_commit", manifest.get("git_commit")),
        "solver_num_procs": manifest.get("solver_num_procs", manifest.get("num_procs")),
        "post_num_procs": manifest.get("post_num_procs"),
        "stages_requested": manifest.get("stages_requested"),
        "stages_completed_or_submitted": manifest.get("stages_completed_or_submitted"),
    }
 
 

Here is the caller graph for this function:

_summarize_turbulence()

dict picurv_cli.core._summarize_turbulence ( dict  turbulence_cfg )

protected

Build compact turbulence and wall-model selections.

Parameters

[in]

turbulence_cfg

Case turbulence configuration mapping.

Returns

Curated turbulence and wall-model mapping.

Definition at line 22247 of file core.py.

def _summarize_turbulence(turbulence_cfg: dict) -> dict:
    """!
    @brief Build compact turbulence and wall-model selections.
    @param[in] turbulence_cfg Case turbulence configuration mapping.
    @return Curated turbulence and wall-model mapping.
    """
    result = {}
    for key in ("les", "wall_function"):
        value = turbulence_cfg.get(key)
        if isinstance(value, dict):
            result[key] = {
                "enabled": value.get("enabled", True),
                "model": value.get("model"),
                **{k: v for k, v in value.items() if k not in {"enabled", "model"}},
            }
        elif value is not None:
            result[key] = value
    return result
 
 

Here is the caller graph for this function:

_build_case_overview()

dict picurv_cli.core._build_case_overview ( dict  context )

protected

Build a curated case.yml summary with useful derived quantities.

Parameters

[in]

context

Summary context returned by _build_summary_context().

Returns

Curated case configuration mapping.

Definition at line 22267 of file core.py.

def _build_case_overview(context: dict) -> dict:
    """!
    @brief Build a curated case.yml summary with useful derived quantities.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Curated case configuration mapping.
    """
    cfg = _require_summary_config(context, "case")
    props = cfg.get("properties", {})
    scaling = props.get("scaling", {})
    fluid = props.get("fluid", {})
    run = cfg.get("run_control", {})
    grid = cfg.get("grid", {})
    models = cfg.get("models", {})
    domain = models.get("domain", {})
    physics = models.get("physics", {})
    particles = physics.get("particles", {})
    start = int(run.get("start_step", 0))
    total = int(run.get("total_steps", 0))
    dt = float(run.get("dt_physical", 0.0))
    length_ref = float(scaling.get("length_ref"))
    velocity_ref = float(scaling.get("velocity_ref"))
    density = float(fluid.get("density"))
    viscosity = float(fluid.get("viscosity"))
    prepared_bcs = validate_and_prepare_boundary_conditions(cfg)
    first_block_faces = {row["face"]: row for row in prepared_bcs[0]}
    periodic_axes = {
        "i": first_block_faces["-Xi"]["type"] == "PERIODIC",
        "j": first_block_faces["-Eta"]["type"] == "PERIODIC",
        "k": first_block_faces["-Zeta"]["type"] == "PERIODIC",
    }
    bc_blocks = []
    for block_idx, block in enumerate(prepared_bcs):
        bc_blocks.append(
            {
                "block": block_idx,
                "faces": [
                    {"face": row["face"], "type": row["type"], "handler": row["handler"]}
                    for row in block
                ],
            }
        )
    return {
        "run_control": {
            "start_step": start,
            "total_steps": total,
            "end_step": start + total,
            "dt_physical": dt,
            "duration_physical": total * dt,
            "dt_nondimensional": to_solver_units(
                dt, ("case", "run_control", "dt_physical"),
                {"length_ref": length_ref, "velocity_ref": velocity_ref}),
        },
        "properties": {
            "length_ref": length_ref,
            "velocity_ref": velocity_ref,
            "density": density,
            "viscosity": viscosity,
            "reynolds_number": density * velocity_ref * length_ref / viscosity if viscosity else None,
            "initial_conditions": props.get("initial_conditions", {}),
        },
        "grid": {
            "mode": grid.get("mode"),
            "processor_layout": resolve_grid_da_processor_layout(grid),
            "programmatic_settings": grid.get("programmatic_settings") if grid.get("mode") == "programmatic_c" else None,
            "source_file": grid.get("source_file"),
        },
        "domain": {
            "blocks": domain.get("blocks", 1),
            "dimensionality": physics.get("dimensionality", "3D"),
            "periodic": periodic_axes,
        },
        "physics": {
            "fsi": physics.get("fsi", {}),
            "particles": particles,
            "turbulence": _summarize_turbulence(physics.get("turbulence", {}) or {}),
        },
        "boundary_conditions": bc_blocks,
    }
 
 

Here is the call graph for this function:

_summary_scalar_transport()

dict picurv_cli.core._summary_scalar_transport ( dict  context, dict  solver_cfg  )

protected

Scalar-transport parameters as the run resolves them, wherever they are set.

Parameters

[in]	context	Summary context returned by _build_summary_context().
[in]	solver_cfg	Parsed solver configuration.

Returns

Mapping of parameter name to value; empty when unresolvable.

Definition at line 22347 of file core.py.

def _summary_scalar_transport(context: dict, solver_cfg: dict) -> dict:
    """!
    @brief Scalar-transport parameters as the run resolves them, wherever they are set.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] solver_cfg Parsed solver configuration.
    @return Mapping of parameter name to value; empty when unresolvable.
    """
    try:
        return resolve_scalar_transport(context.get("case_cfg") or {}, solver_cfg)
    except ValueError:
        return {}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_build_solver_overview()

dict picurv_cli.core._build_solver_overview ( dict  context )

protected

Build a curated solver.yml summary with normalized selections.

Parameters

[in]

context

Summary context returned by _build_summary_context().

Returns

Curated solver configuration mapping.

Definition at line 22360 of file core.py.

def _build_solver_overview(context: dict) -> dict:
    """!
    @brief Build a curated solver.yml summary with normalized selections.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Curated solver configuration mapping.
    """
    cfg = _require_summary_config(context, "solver")
    strategy = cfg.get("strategy", {}) or {}
    selected = normalize_momentum_solver_type(strategy.get("momentum_solver", "Dual Time Picard Jameson RK"))
    momentum_cfg = cfg.get("momentum_solver", {}) or {}
    dualtime = momentum_cfg.get("dual_time_picard_jameson_rk", momentum_cfg.get("dual_time_picard_rk4", {})) or {}
    newton_krylov = momentum_cfg.get("newton_krylov", {}) or {}
    poisson = cfg.get("poisson_solver", cfg.get("pressure_solver", {})) or {}
    operation_mode = cfg.get("operation_mode", {}) or {}
    operation_mode = {
        **operation_mode,
        "eulerian_field_source": normalize_eulerian_field_source(operation_mode.get("eulerian_field_source", "solve")),
    }
    if operation_mode.get("analytical_type") is not None:
        operation_mode["analytical_type"] = normalize_analytical_type(operation_mode["analytical_type"])
    passthrough = cfg.get("petsc_passthrough_options", {}) or {}
    return {
        "operation_mode": operation_mode,
        "momentum": {
            "type": selected,
            "central_diff": bool(strategy.get("central_diff", False)),
            "tolerances": cfg.get("tolerances", {}),
            "controls": newton_krylov if selected == "newton_krylov" else dualtime,
        },
        "poisson": poisson,
        "interpolation": cfg.get("interpolation", {"method": "Trilinear"}),
        "scalar_transport": _summary_scalar_transport(context, cfg),
        "verification": cfg.get("verification", {}),
        "petsc_passthrough": {"count": len(passthrough), "options": sorted(passthrough.keys())},
    }
 
 

Here is the call graph for this function:

_build_monitor_overview()

dict picurv_cli.core._build_monitor_overview ( dict  context )

protected

Build a curated monitor.yml summary with resolved defaults.

Parameters

[in]

context

Summary context returned by _build_summary_context().

Returns

Curated monitor configuration mapping.

Definition at line 22397 of file core.py.

def _build_monitor_overview(context: dict) -> dict:
    """!
    @brief Build a curated monitor.yml summary with resolved defaults.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Curated monitor configuration mapping.
    """
    cfg = _require_summary_config(context, "monitor")
    logging_cfg = cfg.get("logging", {}) or {}
    io_cfg = cfg.get("io", {}) or {}
    diagnostics = resolve_diagnostics_config(cfg, context["run_dir"], "Solver")
    monitoring_flags = resolve_solver_monitoring_flags(cfg)
    solution_monitoring = normalize_solution_monitoring_config(cfg)
    enabled_petsc = sorted(key for key, value in diagnostics["petsc"].items() if value not in (False, None))
    return {
        "logging": {
            "verbosity": logging_cfg.get("verbosity", "WARNING"),
            "enabled_functions": logging_cfg.get("enabled_functions", []),
        },
        "profiling": resolve_profiling_config(cfg),
        "diagnostics": {
            "enabled_petsc": enabled_petsc,
            "petsc": diagnostics["petsc"],
            "runtime_memory_log": diagnostics["runtime_memory_log"],
        },
        "io": {
            "data_output_frequency": io_cfg.get("data_output_frequency"),
            "particle_console_output_frequency": resolve_particle_console_output_frequency(io_cfg),
            "particle_log_interval": io_cfg.get("particle_log_interval"),
            "directories": {
                "output": CANONICAL_RUN_PATHS["output"],
                "restart": CANONICAL_RUN_PATHS["restart"],
                "logs": CANONICAL_RUN_PATHS["logs"],
                "analysis": CANONICAL_RUN_PATHS["analysis"],
            },
        },
        "solver_monitoring": {
            "enabled_flags": sorted(flag for flag, value in monitoring_flags.items() if value not in (False, None)),
            "flags": monitoring_flags,
        },
        "solution_monitoring": solution_monitoring,
    }
 
 

Here is the call graph for this function:

_parse_continuity_metrics_log()

"tuple[dict, list[int]]" picurv_cli.core._parse_continuity_metrics_log ( str  log_dir )

protected

Read the continuity record into rows by step (one per block) plus observed order.

Parameters

[in]

log_dir

Run log directory.

Returns

Mapping step -> list of block rows, and the order steps first appeared.

Definition at line 22440 of file core.py.

def _parse_continuity_metrics_log(log_dir: str) -> "tuple[dict, list[int]]":
    """!
    @brief Read the continuity record into rows by step (one per block) plus observed order.
    @param[in] log_dir Run log directory.
    @return Mapping step -> list of block rows, and the order steps first appeared.
    """
    rows_by_step, step_order = {}, []
    for _, row in _continuity_rows(log_dir)[1]:
        step = row["step"]
        if step not in rows_by_step:
            step_order.append(step)
            rows_by_step[step] = {}
        rows_by_step[step][row["block"]] = {key: value for key, value in row.items() if key != "step"}
    return {step: list(blocks.values()) for step, blocks in rows_by_step.items()}, step_order
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_parse_particle_metrics_log()

"tuple[dict, list[int]]" picurv_cli.core._parse_particle_metrics_log ( str  log_dir, str  metrics_dir  )

protected

Read the per-step particle record into rows by step plus observed order.

Parameters

[in]	log_dir	Run log directory.
[in]	metrics_dir	Run analysis metrics directory.

Returns

Mapping step -> row, and the steps in file order.

Definition at line 22456 of file core.py.

def _parse_particle_metrics_log(log_dir: str, metrics_dir: str) -> "tuple[dict, list[int]]":
    """!
    @brief Read the per-step particle record into rows by step plus observed order.
    @param[in] log_dir Run log directory.
    @param[in] metrics_dir Run analysis metrics directory.
    @return Mapping step -> row, and the steps in file order.
    """
    rows_by_step, step_order = {}, []
    for _, row in _particle_step_rows(log_dir, metrics_dir)[1]:
        rows_by_step[row["step"]] = {key: value for key, value in row.items() if key != "step"}
        step_order.append(row["step"])
    return rows_by_step, step_order
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_parse_momentum_convergence_logs()

"tuple[dict, dict, list[int]]" picurv_cli.core._parse_momentum_convergence_logs ( str  log_dir )

protected

Read the per-block momentum records (Picard history, Newton summary) into rows by step.

Parameters

[in]

log_dir

Run log directory.

Returns

Rows by step and block, source path per block, and step order.

Definition at line 22470 of file core.py.

def _parse_momentum_convergence_logs(log_dir: str) -> "tuple[dict, dict, list[int]]":
    """!
    @brief Read the per-block momentum records (Picard history, Newton summary) into rows by step.
    @param[in] log_dir Run log directory.
    @return Rows by step and block, source path per block, and step order.
    """
    rows_by_step, sources, step_order = {}, {}, []
    # Per (step, block): accepted/rejected trial counts and the last committed state.
    state = {}
    for block, path, rows in _picard_history_rows(log_dir):
        sources[block] = path
        for _, row in rows:
            step = row["step"]
            step_order.append(step)
            entry = state.setdefault((step, block), {"accepted_count": 0, "rejected_count": 0,
                                                    "last_accepted": None, "last_rejected": None})
            display = {key: value for key, value in row.items() if key != "step"}
            if row.get("status") == "accepted":
                entry["accepted_count"] += 1
                entry["last_accepted"] = display
            else:
                entry["rejected_count"] += 1
                entry["last_rejected"] = display
    for (step, block), entry in state.items():
        display_row = entry["last_accepted"] or entry["last_rejected"]
        if display_row:
            rows_by_step.setdefault(step, {})[block] = {
                **display_row,
                "accepted_count": entry["accepted_count"],
                "rejected_count": entry["rejected_count"],
            }
    for file_block, path, rows in _newton_summary_rows(log_dir):
        sources[file_block] = path
        for _, row in rows:
            step_order.append(row["step"])
            rows_by_step.setdefault(row["step"], {})[row["block"]] = {
                key: value for key, value in row.items() if key != "step"}
    return rows_by_step, sources, step_order
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_parse_poisson_convergence_logs()

"tuple[dict, dict, list[int]]" picurv_cli.core._parse_poisson_convergence_logs ( str  log_dir )

protected

Read the per-block Poisson histories into each step's last iteration.

Parameters

[in]

log_dir

Run log directory.

Returns

Rows by step and block, source path per block, and step order.

Definition at line 22510 of file core.py.

def _parse_poisson_convergence_logs(log_dir: str) -> "tuple[dict, dict, list[int]]":
    """!
    @brief Read the per-block Poisson histories into each step's last iteration.
    @param[in] log_dir Run log directory.
    @return Rows by step and block, source path per block, and step order.
    """
    rows_by_step, sources, step_order = {}, {}, []
    for block, path, rows in _poisson_history_rows(log_dir):
        sources[block] = path
        for _, row in rows:
            step_order.append(row["step"])
            rows_by_step.setdefault(row["step"], {})[block] = {
                key: value for key, value in row.items() if key not in ("step",)}
    return rows_by_step, sources, step_order
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_parse_profiling_timestep_csv()

"tuple[dict, list[int]]" picurv_cli.core._parse_profiling_timestep_csv ( str  filepath )

protected

Parse profiling timestep CSV into latest rows by step plus observed order.

Parameters

[in]

filepath

Argument passed to _parse_profiling_timestep_csv().

Returns

Value returned by _parse_profiling_timestep_csv().

Definition at line 22526 of file core.py.

def _parse_profiling_timestep_csv(filepath: str) -> "tuple[dict, list[int]]":
    """!
    @brief Parse profiling timestep CSV into latest rows by step plus observed order.
    @param[in] filepath Argument passed to `_parse_profiling_timestep_csv()`.
    @return Value returned by `_parse_profiling_timestep_csv()`.
    """
    rows_by_step = {}
    step_order = []
    active_step = None
    if not os.path.isfile(filepath):
        return rows_by_step, step_order
 
    with open(filepath, "r", encoding="utf-8", errors="replace", newline="") as f:
        reader = csv.DictReader(f)
        for row in reader:
            step = _parse_int_loose(row.get("step"))
            if step is None:
                continue
            if step != active_step:
                active_step = step
                step_order.append(step)
                rows_by_step[step] = []
            rows_by_step.setdefault(step, []).append(
                {
                    "function": row.get("function"),
                    "calls": _parse_int_loose(row.get("calls")),
                    "step_time_s": _parse_float_loose(row.get("step_time_s")),
                }
            )
    return rows_by_step, step_order
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_parse_runtime_memory_log()

"tuple[dict, list[int], dict]" picurv_cli.core._parse_runtime_memory_log ( str  filepath )

protected

Read the runtime memory record into rows by step and its final status.

Parameters

[in]

filepath

Runtime memory log path.

Returns

Tuple of rows by step, observed step order, and final/shutdown metadata.

Definition at line 22558 of file core.py.

def _parse_runtime_memory_log(filepath: str) -> "tuple[dict, list[int], dict]":
    """!
    @brief Read the runtime memory record into rows by step and its final status.
    @param[in] filepath Runtime memory log path.
    @return Tuple of rows by step, observed step order, and final/shutdown metadata.
    """
    rows_by_step, step_order = {}, []
    final_row = latest_sample_row = max_process_change_mb = None
    step_walls = []
    if not os.path.isfile(filepath):
        return rows_by_step, step_order, {"available": False}
    for _, row in _runtime_memory_rows(filepath):
        if row.get("step_wall_s") is not None:
            step_walls.append(row["step_wall_s"])
        change = row.get("process_change_mb_max")
        if change is not None:
            max_process_change_mb = change if max_process_change_mb is None else max(max_process_change_mb, change)
        if row["event"] in {"Step", "Post"}:
            rows_by_step[row["step"]] = row
            step_order.append(row["step"])
            latest_sample_row = row
        elif row["event"] in {"Shutdown", "Final"}:
            final_row = row
    meta = {
        "available": bool(rows_by_step or final_row),
        "source": filepath,
        "final_event": final_row.get("event") if final_row else None,
        "final_reason": final_row.get("reason") if final_row else None,
        "max_process_change_mb": max_process_change_mb,
        "mean_step_wall_s": (sum(step_walls) / len(step_walls)) if step_walls else None,
        "latest_sample_row": latest_sample_row,
        "final_row": final_row,
    }
    return rows_by_step, step_order, meta
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_parse_solution_convergence_log()

"tuple[dict, list[int]]" picurv_cli.core._parse_solution_convergence_log ( str  log_dir )

protected

Read the solution-convergence record into rows by step plus observed order.

Parameters

[in]

log_dir

Run log directory.

Returns

Mapping step -> row of every column, and the steps in file order.

Definition at line 22594 of file core.py.

def _parse_solution_convergence_log(log_dir: str) -> "tuple[dict, list[int]]":
    """!
    @brief Read the solution-convergence record into rows by step plus observed order.
    @param[in] log_dir Run log directory.
    @return Mapping step -> row of every column, and the steps in file order.
    """
    rows_by_step, step_order = {}, []
    for _, row in _solution_convergence_rows(log_dir)[1]:
        rows_by_step[row["step"]] = row
        step_order.append(row["step"])
    return rows_by_step, step_order
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_find_solver_stream_log_candidates()

"list[str]" picurv_cli.core._find_solver_stream_log_candidates ( str  run_dir, str  log_dir  )

protected

Return plausible solver stream logs for local and Slurm runs.

Parameters

[in]	run_dir	Argument passed to _find_solver_stream_log_candidates().
[in]	log_dir	Argument passed to _find_solver_stream_log_candidates().

Returns

Value returned by _find_solver_stream_log_candidates().

Definition at line 22607 of file core.py.

def _find_solver_stream_log_candidates(run_dir: str, log_dir: str) -> "list[str]":
    """!
    @brief Return plausible solver stream logs for local and Slurm runs.
    @param[in] run_dir Argument passed to `_find_solver_stream_log_candidates()`.
    @param[in] log_dir Argument passed to `_find_solver_stream_log_candidates()`.
    @return Value returned by `_find_solver_stream_log_candidates()`.
    """
    patterns = [
        os.path.join(run_dir, "scheduler", "*_solver.log"),
        os.path.join(run_dir, "scheduler", "solver_*.out"),
        os.path.join(log_dir, "*_solver.log"),
    ]
    found = []
    seen = set()
    for pattern in patterns:
        for path in sorted(glob.glob(pattern), key=os.path.getmtime, reverse=True):
            if path not in seen:
                seen.add(path)
                found.append(path)
    return found
 
 

Here is the caller graph for this function:

_parse_particle_snapshot_file()

dict picurv_cli.core._parse_particle_snapshot_file ( str  filepath )

protected

Parse sampled particle snapshots from a solver stream log.

Parameters

[in]

filepath

Argument passed to _parse_particle_snapshot_file().

Returns

Value returned by _parse_particle_snapshot_file().

Definition at line 22629 of file core.py.

def _parse_particle_snapshot_file(filepath: str) -> dict:
    """!
    @brief Parse sampled particle snapshots from a solver stream log.
    @param[in] filepath Argument passed to `_parse_particle_snapshot_file()`.
    @return Value returned by `_parse_particle_snapshot_file()`.
    """
    snapshots = {}
    if not os.path.isfile(filepath):
        return snapshots
 
    with open(filepath, "r", encoding="utf-8", errors="replace") as f:
        lines = f.readlines()
 
    idx = 0
    while idx < len(lines):
        match = re.search(r"Particle states at step\s+(\d+):", lines[idx])
        if not match:
            idx += 1
            continue
        step = int(match.group(1))
        idx += 1
        rows = []
        while idx < len(lines):
            stripped = lines[idx].strip()
            if re.search(r"Particle states at step\s+\d+:", lines[idx]):
                break
            if stripped.startswith("|"):
                parts = [part.strip() for part in stripped.split("|")[1:-1]]
                if len(parts) >= 6 and parts[0] != "Rank":
                    velocity = _extract_numeric_tuple(parts[4])
                    rows.append(
                        {
                            "rank": _parse_int_loose(parts[0]),
                            "pid": _parse_int_loose(parts[1]),
                            "cell": [int(value) for value in _extract_numeric_tuple(parts[2])],
                            "position": _extract_numeric_tuple(parts[3]),
                            "velocity": velocity,
                            "weights": _extract_numeric_tuple(parts[5]),
                            "sample_speed": math.sqrt(sum(component * component for component in velocity)) if len(velocity) == 3 else None,
                        }
                    )
            elif rows and (not stripped or stripped.startswith("Progress:")):
                break
            idx += 1
        if rows:
            snapshots[step] = rows
        else:
            snapshots.setdefault(step, [])
    return snapshots
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_find_previous_snapshot_step()

"int | None" picurv_cli.core._find_previous_snapshot_step ( "list[int]"  snapshot_steps, int  step  )

protected

Return the nearest earlier snapshot step when available.

Parameters

[in]	snapshot_steps	Argument passed to _find_previous_snapshot_step().
[in]	step	Argument passed to _find_previous_snapshot_step().

Returns

Value returned by _find_previous_snapshot_step().

Definition at line 22680 of file core.py.

def _find_previous_snapshot_step(snapshot_steps: "list[int]", step: int) -> "int | None":
    """!
    @brief Return the nearest earlier snapshot step when available.
    @param[in] snapshot_steps Argument passed to `_find_previous_snapshot_step()`.
    @param[in] step Argument passed to `_find_previous_snapshot_step()`.
    @return Value returned by `_find_previous_snapshot_step()`.
    """
    earlier_steps = [candidate for candidate in snapshot_steps if candidate < step]
    if not earlier_steps:
        return None
    return max(earlier_steps)
 
 

Here is the caller graph for this function:

_compute_particle_snapshot_delta()

dict picurv_cli.core._compute_particle_snapshot_delta ( "list[dict]"  current_rows, "list[dict]"  previous_rows  )

protected

Compute sampled deltas between two particle snapshot samples.

Parameters

[in]	current_rows	Argument passed to _compute_particle_snapshot_delta().
[in]	previous_rows	Argument passed to _compute_particle_snapshot_delta().

Returns

Value returned by _compute_particle_snapshot_delta().

Definition at line 22693 of file core.py.

def _compute_particle_snapshot_delta(current_rows: "list[dict]", previous_rows: "list[dict]") -> dict:
    """!
    @brief Compute sampled deltas between two particle snapshot samples.
    @param[in] current_rows Argument passed to `_compute_particle_snapshot_delta()`.
    @param[in] previous_rows Argument passed to `_compute_particle_snapshot_delta()`.
    @return Value returned by `_compute_particle_snapshot_delta()`.
    """
    np = require_numpy()
    previous_by_pid = {
        row.get("pid"): row
        for row in previous_rows
        if row.get("pid") is not None
    }
    current_by_pid = {
        row.get("pid"): row
        for row in current_rows
        if row.get("pid") is not None
    }
    matched_pids = sorted(set(previous_by_pid) & set(current_by_pid))
    if not matched_pids:
        return {"available": False}
 
    displacements = []
    rank_migrations = 0
    cell_changes = 0
    speed_changes = []
    for pid in matched_pids:
        current_row = current_by_pid[pid]
        previous_row = previous_by_pid[pid]
        current_pos = current_row.get("position") or []
        previous_pos = previous_row.get("position") or []
        if len(current_pos) == len(previous_pos) and current_pos:
            displacements.append(
                math.sqrt(
                    sum(
                        (float(current_pos[idx]) - float(previous_pos[idx])) ** 2
                        for idx in range(len(current_pos))
                    )
                )
            )
        current_speed = current_row.get("sample_speed")
        previous_speed = previous_row.get("sample_speed")
        if current_speed is not None and previous_speed is not None:
            speed_changes.append(float(current_speed) - float(previous_speed))
        if current_row.get("rank") is not None and previous_row.get("rank") is not None:
            if current_row["rank"] != previous_row["rank"]:
                rank_migrations += 1
        if current_row.get("cell") and previous_row.get("cell"):
            if current_row["cell"] != previous_row["cell"]:
                cell_changes += 1
 
    payload = {
        "available": True,
        "matched_pids": len(matched_pids),
        "new_count": len(set(current_by_pid) - set(previous_by_pid)),
        "gone_count": len(set(previous_by_pid) - set(current_by_pid)),
        "rank_migrations": rank_migrations,
        "cell_changes": cell_changes,
    }
    if displacements:
        payload["mean_displacement"] = float(np.mean(displacements))
        payload["max_displacement"] = float(np.max(displacements))
    if speed_changes:
        payload["mean_speed_change"] = float(np.mean(speed_changes))
        payload["max_abs_speed_change"] = float(np.max(np.abs(speed_changes)))
    return payload
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_build_particle_snapshot_summary()

dict picurv_cli.core._build_particle_snapshot_summary ( str  source, int  step, "list[dict]"  rows, int  preview_rows,   particle_console_output_freq,   particle_log_interval, "int | None"   previous_step = None, "list[dict] | None"   previous_rows = None  )

protected

Build sampled diagnostics for one particle console snapshot.

Parameters

[in]	source	Argument passed to _build_particle_snapshot_summary().
[in]	step	Argument passed to _build_particle_snapshot_summary().
[in]	rows	Argument passed to _build_particle_snapshot_summary().
[in]	preview_rows	Argument passed to _build_particle_snapshot_summary().
[in]	particle_console_output_freq	Argument passed to _build_particle_snapshot_summary().
[in]	particle_log_interval	Argument passed to _build_particle_snapshot_summary().
[in]	previous_step	Argument passed to _build_particle_snapshot_summary().
[in]	previous_rows	Argument passed to _build_particle_snapshot_summary().

Returns

Value returned by _build_particle_snapshot_summary().

Definition at line 22761 of file core.py.

) -> dict:
    """!
    @brief Build sampled diagnostics for one particle console snapshot.
    @param[in] source Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] step Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] rows Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] preview_rows Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] particle_console_output_freq Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] particle_log_interval Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] previous_step Argument passed to `_build_particle_snapshot_summary()`.
    @param[in] previous_rows Argument passed to `_build_particle_snapshot_summary()`.
    @return Value returned by `_build_particle_snapshot_summary()`.
    """
    np = require_numpy()
    payload = {
        "available": True,
        "sampled": True,
        "source": source,
        "step": step,
        "sampled_rows": len(rows),
        "preview_rows": rows[:preview_rows],
        "cadence": {
            "particle_console_output_frequency": particle_console_output_freq,
            "particle_log_interval": particle_log_interval,
        },
    }
    if not rows:
        return payload
 
    rank_counts = {}
    duplicate_pid_count = 0
    duplicate_cell_count = 0
    nan_count = 0
    inf_count = 0
    zero_weight_count = 0
    negative_weight_count = 0
    unique_pid_count = 0
 
    seen_pids = set()
    cell_counter = {}
    position_components = [[], [], []]
    weight_components = {}
    speeds = []
 
    for row in rows:
        pid = row.get("pid")
        if pid is not None:
            if pid in seen_pids:
                duplicate_pid_count += 1
            else:
                seen_pids.add(pid)
        rank = row.get("rank")
        if rank is not None:
            rank_counts[str(rank)] = rank_counts.get(str(rank), 0) + 1
 
        cell = row.get("cell") or []
        if cell:
            key = tuple(cell)
            cell_counter[key] = cell_counter.get(key, 0) + 1
 
        position = row.get("position") or []
        for idx, value in enumerate(position[:3]):
            if not np.isfinite(value):
                if np.isnan(value):
                    nan_count += 1
                else:
                    inf_count += 1
                continue
            position_components[idx].append(float(value))
 
        velocity = row.get("velocity") or []
        if any(not np.isfinite(value) for value in velocity):
            for value in velocity:
                if not np.isfinite(value):
                    if np.isnan(value):
                        nan_count += 1
                    else:
                        inf_count += 1
        speed = row.get("sample_speed")
        if speed is not None and np.isfinite(speed):
            speeds.append(float(speed))
 
        weights = row.get("weights") or []
        for idx, value in enumerate(weights):
            if not np.isfinite(value):
                if np.isnan(value):
                    nan_count += 1
                else:
                    inf_count += 1
                continue
            numeric = float(value)
            weight_components.setdefault(idx, []).append(numeric)
            if abs(numeric) <= 1.0e-15:
                zero_weight_count += 1
            if numeric < 0.0:
                negative_weight_count += 1
 
    unique_pid_count = len(seen_pids)
    duplicate_cell_count = sum(1 for count in cell_counter.values() if count > 1)
 
    payload["sampled_distribution"] = {
        "unique_cells": len(cell_counter),
        "duplicate_cells": duplicate_cell_count,
        "rank_counts": rank_counts,
        "unique_pids": unique_pid_count,
    }
    payload["checks"] = {
        "duplicate_pid_count": duplicate_pid_count,
        "nan_count": nan_count,
        "inf_count": inf_count,
        "zero_weight_count": zero_weight_count,
        "negative_weight_count": negative_weight_count,
    }
 
    if speeds:
        payload["speed"] = {
            "min": float(np.min(speeds)),
            "mean": float(np.mean(speeds)),
            "max": float(np.max(speeds)),
            "std": float(np.std(speeds)),
            "stagnant_count": sum(1 for speed in speeds if abs(speed) < 1.0e-6),
        }
 
        fastest_rows = sorted(
            [row for row in rows if row.get("sample_speed") is not None],
            key=lambda row: row["sample_speed"],
            reverse=True,
        )[:3]
        payload["top_speeds"] = [
            {
                "pid": row.get("pid"),
                "rank": row.get("rank"),
                "speed": row.get("sample_speed"),
                "cell": row.get("cell"),
            }
            for row in fastest_rows
        ]
 
    if any(position_components):
        axes = ["x", "y", "z"]
        payload["position_bounds"] = {}
        centroid = []
        for idx, axis in enumerate(axes):
            values = position_components[idx]
            if values:
                payload["position_bounds"][axis] = [float(np.min(values)), float(np.max(values))]
                centroid.append(float(np.mean(values)))
            else:
                centroid.append(None)
        payload["position_centroid"] = centroid
 
    if weight_components:
        payload["weights"] = {}
        for idx, values in sorted(weight_components.items()):
            payload["weights"][f"component_{idx}"] = {
                "min": float(np.min(values)),
                "max": float(np.max(values)),
            }
 
    delta_summary = {"available": False}
    if previous_step is not None and previous_rows:
        delta_summary = _compute_particle_snapshot_delta(rows, previous_rows)
        if delta_summary.get("available"):
            delta_summary["previous_step"] = previous_step
    payload["delta_from_previous_snapshot"] = delta_summary
    return payload
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_find_particle_snapshot_for_step()

dict picurv_cli.core._find_particle_snapshot_for_step ( str  run_dir, str  log_dir, int  step, int  preview_rows,   particle_console_output_freq,   particle_log_interval  )

protected

Locate and summarize a particle console snapshot for one step.

Parameters

[in]	run_dir	Argument passed to _find_particle_snapshot_for_step().
[in]	log_dir	Argument passed to _find_particle_snapshot_for_step().
[in]	step	Argument passed to _find_particle_snapshot_for_step().
[in]	preview_rows	Argument passed to _find_particle_snapshot_for_step().
[in]	particle_console_output_freq	Argument passed to _find_particle_snapshot_for_step().
[in]	particle_log_interval	Argument passed to _find_particle_snapshot_for_step().

Returns

Value returned by _find_particle_snapshot_for_step().

Definition at line 22938 of file core.py.

) -> dict:
    """!
    @brief Locate and summarize a particle console snapshot for one step.
    @param[in] run_dir Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] log_dir Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] step Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] preview_rows Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] particle_console_output_freq Argument passed to `_find_particle_snapshot_for_step()`.
    @param[in] particle_log_interval Argument passed to `_find_particle_snapshot_for_step()`.
    @return Value returned by `_find_particle_snapshot_for_step()`.
    """
    best = None
    for path in _find_solver_stream_log_candidates(run_dir, log_dir):
        snapshots = _parse_particle_snapshot_file(path)
        rows = snapshots.get(step)
        if not rows:
            continue
        if best is None or len(rows) > len(best["rows"]):
            best = {"source": path, "rows": rows, "snapshots": snapshots}
 
    if not best:
        return {"available": False}
 
    previous_step = _find_previous_snapshot_step(list(best["snapshots"].keys()), step)
    previous_rows = best["snapshots"].get(previous_step, []) if previous_step is not None else None
    return _build_particle_snapshot_summary(
        best["source"],
        step,
        best["rows"],
        preview_rows,
        particle_console_output_freq=particle_console_output_freq,
        particle_log_interval=particle_log_interval,
        previous_step=previous_step,
        previous_rows=previous_rows,
    )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_resolve_summary_step()

picurv_cli.core._resolve_summary_step (   requested_step,   continuity_rows,   particle_rows,   momentum_rows,   poisson_rows,   profiling_rows,   memory_rows = None,   convergence_rows = None,   step_orders = None, str   selection_mode = "latest"  )

protected

Select a step to summarize from available metric artifacts.

Parameters

[in]	requested_step	Argument passed to _resolve_summary_step().
[in]	continuity_rows	Argument passed to _resolve_summary_step().
[in]	particle_rows	Argument passed to _resolve_summary_step().
[in]	momentum_rows	Argument passed to _resolve_summary_step().
[in]	poisson_rows	Argument passed to _resolve_summary_step().
[in]	profiling_rows	Argument passed to _resolve_summary_step().
[in]	memory_rows	Argument passed to _resolve_summary_step().
[in]	convergence_rows	Argument passed to _resolve_summary_step().
[in]	step_orders	Argument passed to _resolve_summary_step().
[in]	selection_mode	Argument passed to _resolve_summary_step().

Returns

Value returned by _resolve_summary_step().

Definition at line 22982 of file core.py.

):
    """!
    @brief Select a step to summarize from available metric artifacts.
    @param[in] requested_step Argument passed to `_resolve_summary_step()`.
    @param[in] continuity_rows Argument passed to `_resolve_summary_step()`.
    @param[in] particle_rows Argument passed to `_resolve_summary_step()`.
    @param[in] momentum_rows Argument passed to `_resolve_summary_step()`.
    @param[in] poisson_rows Argument passed to `_resolve_summary_step()`.
    @param[in] profiling_rows Argument passed to `_resolve_summary_step()`.
    @param[in] memory_rows Argument passed to `_resolve_summary_step()`.
    @param[in] convergence_rows Argument passed to `_resolve_summary_step()`.
    @param[in] step_orders Argument passed to `_resolve_summary_step()`.
    @param[in] selection_mode Argument passed to `_resolve_summary_step()`.
    @return Value returned by `_resolve_summary_step()`.
    """
    if memory_rows is None:
        memory_rows = {}
    if convergence_rows is None:
        convergence_rows = {}
    if step_orders is None:
        step_orders = []
    available_steps = (
        set(continuity_rows) | set(particle_rows) | set(momentum_rows)
        | set(poisson_rows) | set(profiling_rows) | set(memory_rows) | set(convergence_rows)
    )
    if not available_steps:
        return None, []
 
    if requested_step is not None:
        return requested_step, sorted(available_steps)
 
    if selection_mode == "max_step":
        return max(available_steps), sorted(available_steps)
 
    for order in step_orders:
        if order:
            return order[-1], sorted(available_steps)
    return max(available_steps), sorted(available_steps)
 
 

Here is the caller graph for this function:

_format_summary_float()

str picurv_cli.core._format_summary_float (   value, str   spec = ".6e", str   missing = "n/a"  )

protected

Format optional numeric values for summary text output.

Parameters

[in]	value	Argument passed to _format_summary_float().
[in]	spec	Argument passed to _format_summary_float().
[in]	missing	Argument passed to _format_summary_float().

Returns

Value returned by _format_summary_float().

Definition at line 23033 of file core.py.

def _format_summary_float(value, spec: str = ".6e", missing: str = "n/a") -> str:
    """!
    @brief Format optional numeric values for summary text output.
    @param[in] value Argument passed to `_format_summary_float()`.
    @param[in] spec Argument passed to `_format_summary_float()`.
    @param[in] missing Argument passed to `_format_summary_float()`.
    @return Value returned by `_format_summary_float()`.
    """
    if value is None:
        return missing
    return format(value, spec)
 
 

_summary_source_mtime()

float picurv_cli.core._summary_source_mtime (   paths )

protected

Return the newest modification time among one or more summary sources.

Parameters

[in]

paths

Path string, iterable of paths, or mapping of paths.

Returns

Newest modification time, or -1.0 when no source exists.

Definition at line 23046 of file core.py.

def _summary_source_mtime(paths) -> float:
    """!
    @brief Return the newest modification time among one or more summary sources.
    @param[in] paths Path string, iterable of paths, or mapping of paths.
    @return Newest modification time, or -1.0 when no source exists.
    """
    if isinstance(paths, dict):
        paths = paths.values()
    elif isinstance(paths, str):
        paths = [paths]
    newest = -1.0
    for path in paths or []:
        if path and os.path.isfile(path):
            newest = max(newest, os.path.getmtime(path))
    return newest
 
 

Here is the caller graph for this function:

_order_summary_step_orders()

"list[list[int]]" picurv_cli.core._order_summary_step_orders ( "list[tuple[list[int], object]]"  sources )

protected

Order observed step sequences by the recency of their source files.

Parameters

[in]

sources

Pairs of observed steps and filesystem source path(s).

Returns

Step-order lists sorted so active append sources are considered first.

Definition at line 23063 of file core.py.

def _order_summary_step_orders(sources: "list[tuple[list[int], object]]") -> "list[list[int]]":
    """!
    @brief Order observed step sequences by the recency of their source files.
    @param[in] sources Pairs of observed steps and filesystem source path(s).
    @return Step-order lists sorted so active append sources are considered first.
    """
    ranked = []
    for priority, (order, paths) in enumerate(sources):
        if order:
            ranked.append((_summary_source_mtime(paths), priority, order))
    ranked.sort(key=lambda item: (-item[0], item[1]))
    return [order for _, _, order in ranked]
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

build_run_summary_payload()

dict picurv_cli.core.build_run_summary_payload	(	str	run_dir,
		"int | None"	step = None,
		int	snapshot_rows = 5,
		str	selection_mode = "latest"
	)

Build a read-only run-step summary from existing PICurv artifacts.

Parameters

[in]	run_dir	Argument passed to build_run_summary_payload().
[in]	step	Argument passed to build_run_summary_payload().
[in]	snapshot_rows	Argument passed to build_run_summary_payload().
[in]	selection_mode	Argument passed to build_run_summary_payload().

Returns

Value returned by build_run_summary_payload().

Definition at line 23077 of file core.py.

def build_run_summary_payload(run_dir: str, step: "int | None" = None, snapshot_rows: int = 5, selection_mode: str = "latest") -> dict:
    """!
    @brief Build a read-only run-step summary from existing PICurv artifacts.
    @param[in] run_dir Argument passed to `build_run_summary_payload()`.
    @param[in] step Argument passed to `build_run_summary_payload()`.
    @param[in] snapshot_rows Argument passed to `build_run_summary_payload()`.
    @param[in] selection_mode Argument passed to `build_run_summary_payload()`.
    @return Value returned by `build_run_summary_payload()`.
    """
    context = _build_summary_context(run_dir)
    log_dir = context["log_dir"]
    metrics_dir = context["metrics_dir"]
    continuity_path = (_log_family_path(log_dir, "Continuity_Metrics")
                       or os.path.join(log_dir, "Continuity_Metrics.csv"))
    particle_metrics_path = (_particle_step_rows(log_dir, metrics_dir)[0]
                             or os.path.join(metrics_dir, "search_metrics.csv"))
 
    continuity_rows, continuity_order = _parse_continuity_metrics_log(log_dir)
    particle_rows, particle_order = _parse_particle_metrics_log(log_dir, metrics_dir)
    momentum_rows, momentum_sources, momentum_order = _parse_momentum_convergence_logs(log_dir)
    poisson_rows, poisson_sources, poisson_order = _parse_poisson_convergence_logs(log_dir)
 
    profiling_rows = {}
    profiling_order = []
    profiling_path = os.path.join(log_dir, PROFILING_TIMESTEP_FILE)
    if context["profiling_cfg"].get("mode") != "off":
        profiling_rows, profiling_order = _parse_profiling_timestep_csv(profiling_path)
 
    memory_path = _log_family_path(log_dir, "Runtime_Memory") or os.path.join(log_dir, RUNTIME_MEMORY_FILE)
    memory_rows, memory_order, memory_meta = _parse_runtime_memory_log(memory_path)
 
    convergence_log_path = (_log_family_path(log_dir, "solution_convergence")
                            or os.path.join(log_dir, "solution_convergence.csv"))
    convergence_rows, convergence_order = _parse_solution_convergence_log(log_dir)
    step_orders = _order_summary_step_orders(
        [
            (continuity_order, continuity_path),
            (particle_order, particle_metrics_path),
            (convergence_order, convergence_log_path),
            (profiling_order, profiling_path),
            (memory_order, memory_path),
            (momentum_order, momentum_sources),
            (poisson_order, poisson_sources),
        ]
    )
 
    resolved_step, available_steps = _resolve_summary_step(
        step,
        continuity_rows,
        particle_rows,
        momentum_rows,
        poisson_rows,
        profiling_rows,
        convergence_rows,
        memory_rows,
        step_orders=step_orders,
        selection_mode=selection_mode,
    )
    if resolved_step is None:
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="summary",
            file_path=log_dir,
            message="No summary-capable run artifacts were found under the run log directory.",
            hint="Run the solver first, then retry summarize on a run directory that contains continuity or solver convergence logs.",
        )
        sys.exit(1)
 
    if step is not None and step not in set(available_steps):
        emit_structured_error(
            ERROR_CODE_CFG_INVALID_VALUE,
            key="step",
            file_path=context["run_dir"],
            message=f"Requested step {step} is not present in the available summary artifacts.",
            hint=f"Available steps include: {available_steps[:10]}{'...' if len(available_steps) > 10 else ''}",
        )
        sys.exit(1)
 
    continuity_step_rows = sorted(continuity_rows.get(resolved_step, []), key=lambda row: row["block"])
    continuity_summary = {"available": bool(continuity_step_rows), "blocks": continuity_step_rows}
    if continuity_step_rows:
        divergence_values = [
            abs(row["max_divergence"])
            for row in continuity_step_rows
            if row["max_divergence"] is not None
        ]
        continuity_summary["max_abs_divergence"] = max(divergence_values) if divergence_values else None
        continuity_summary["net_flux"] = continuity_step_rows[0].get("net_flux")
        continuity_summary["flux_in"] = continuity_step_rows[0].get("flux_in")
        continuity_summary["flux_out"] = continuity_step_rows[0].get("flux_out")
 
    momentum_step_rows = [row for _, row in sorted(momentum_rows.get(resolved_step, {}).items())]
    momentum_summary = {"available": bool(momentum_step_rows), "blocks": momentum_step_rows}
 
    poisson_step_rows = [row for _, row in sorted(poisson_rows.get(resolved_step, {}).items())]
    poisson_summary = {"available": bool(poisson_step_rows), "blocks": poisson_step_rows}
 
    particle_summary = {"available": resolved_step in particle_rows}
    if resolved_step in particle_rows:
        particle_summary.update(particle_rows[resolved_step])
 
    profiling_summary = {"available": resolved_step in profiling_rows}
    if resolved_step in profiling_rows:
        functions = sorted(
            profiling_rows[resolved_step],
            key=lambda row: (row.get("step_time_s") or 0.0),
            reverse=True,
        )
        profiling_summary["functions"] = functions
        profiling_summary["total_logged_step_time_s"] = sum(
            row.get("step_time_s") or 0.0 for row in functions
        )
 
    memory_summary = {"available": resolved_step in memory_rows}
    if resolved_step in memory_rows:
        memory_summary.update(memory_rows[resolved_step])
        memory_summary["source"] = memory_path
        memory_summary["max_process_change_mb"] = memory_meta.get("max_process_change_mb")
        memory_summary["mean_step_wall_s"] = memory_meta.get("mean_step_wall_s")
        memory_summary["final_event"] = memory_meta.get("final_event")
        memory_summary["final_reason"] = memory_meta.get("final_reason")
        memory_summary["selected_step"] = resolved_step
        memory_summary["step_match"] = True
    elif memory_meta.get("available"):
        latest_sample_row = memory_meta.get("latest_sample_row")
        if latest_sample_row:
            memory_summary.update(latest_sample_row)
        memory_summary.update(memory_meta)
        memory_summary["selected_step"] = resolved_step
        memory_summary["step_match"] = False
 
    snapshot_summary = {"available": False}
    if context["particle_console_output_freq"] and context["particle_console_output_freq"] > 0:
        snapshot_summary = _find_particle_snapshot_for_step(
            context["run_dir"],
            log_dir,
            resolved_step,
            preview_rows=max(1, snapshot_rows),
            particle_console_output_freq=context["particle_console_output_freq"],
            particle_log_interval=context["particle_log_interval"],
        )
 
    monitor_info = {
        "profiling_timestep_mode": context["profiling_cfg"].get("mode"),
        "profiling_timestep_file": PROFILING_TIMESTEP_FILE,
        "particle_console_output_frequency": context["particle_console_output_freq"],
        "particle_log_interval": context["particle_log_interval"],
    }
 
    return {
        "run_id": context["manifest"].get("run_id", os.path.basename(context["run_dir"])),
        "run_dir": context["run_dir"],
        "step": resolved_step,
        "selected_via": "explicit" if step is not None else ("max_step" if selection_mode == "max_step" else "latest_available"),
        "available_steps": available_steps,
        "launch_mode": context["manifest"].get("launch_mode"),
        "created_at": context["manifest"].get("created_at"),
        "monitor": monitor_info,
        "particles_configured": context["particle_count_cfg"],
        "sources": {
            "continuity_log": continuity_path if os.path.isfile(continuity_path) else None,
            "particle_metrics_log": particle_metrics_path if os.path.isfile(particle_metrics_path) else None,
            "momentum_logs": momentum_sources,
            "poisson_logs": poisson_sources,
            "profiling_timestep_csv": profiling_path if os.path.isfile(profiling_path) else None,
            "solution_convergence_log": convergence_log_path if os.path.isfile(convergence_log_path) else None,
            "runtime_memory_log": memory_path if os.path.isfile(memory_path) else None,
        },
        "continuity": continuity_summary,
        "momentum": momentum_summary,
        "poisson": poisson_summary,
        "particles": particle_summary,
        "particle_snapshot": snapshot_summary,
        "profiling": profiling_summary,
        "memory": memory_summary,
        "convergence": convergence_rows.get(resolved_step) if convergence_rows else None,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

render_run_summary()

picurv_cli.core.render_run_summary	(	dict	payload,
		str	output_format = "text"
	)

Render a run-step summary in human or JSON form.

Parameters

[in]	payload	Argument passed to render_run_summary().
[in]	output_format	Argument passed to render_run_summary().

Definition at line 23256 of file core.py.

def render_run_summary(payload: dict, output_format: str = "text"):
    """!
    @brief Render a run-step summary in human or JSON form.
    @param[in] payload Argument passed to `render_run_summary()`.
    @param[in] output_format Argument passed to `render_run_summary()`.
    """
    if output_format == "json":
        print(json.dumps(payload, indent=2, sort_keys=True))
        return
 
    print("\n" + "=" * 60)
    print("                     RUN STEP SUMMARY")
    print("=" * 60)
    print(f"  Run ID          : {payload.get('run_id')}")
    print(f"  Run directory   : {os.path.relpath(payload.get('run_dir'))}")
    print(f"  Step            : {payload.get('step')} ({payload.get('selected_via')})")
    if payload.get("launch_mode"):
        print(f"  Launch mode     : {payload.get('launch_mode')}")
    if payload.get("created_at"):
        print(f"  Created at      : {payload.get('created_at')}")
 
    continuity = payload.get("continuity", {})
    print("\n  Continuity:")
    if continuity.get("available"):
        if continuity.get("max_abs_divergence") is not None:
            print(f"    max |div|    : {continuity['max_abs_divergence']:.6e}")
        if continuity.get("net_flux") is not None:
            print(f"    net flux     : {continuity['net_flux']:.6e}")
        for row in continuity.get("blocks", []):
            print(
                "    "
                f"block {row['block']}: div={_format_summary_float(row.get('max_divergence'))} "
                f"rhs={_format_summary_float(row.get('rhs_sum'))} location={row['max_divergence_location']}"
            )
    else:
        print("    unavailable")
 
    momentum = payload.get("momentum", {})
    print("\n  Momentum:")
    if momentum.get("available"):
        for row in momentum.get("blocks", []):
            if row.get("solver") == "Newton Krylov":
                print(f"    block {row['block']}: solver=Newton Krylov")
                print(
                    f"      newton={row.get('newton_iterations')} "
                    f"krylov={row.get('krylov_iterations')} "
                    f"evals={row.get('residual_evaluations')}"
                )
                print(
                    f"      final={_format_summary_float(row.get('final_norm'))} "
                    f"reason={row.get('reason')} state={row.get('state')}"
                )
                continue
            status = row.get("status") or "unknown"
            accepted = row.get("accepted_count")
            rejected = row.get("rejected_count")
            counts_str = f" accepted={accepted} rejected={rejected}" if accepted is not None else ""
            # Phase 3+: logged as dtau (physical time) + cfl_eff (dimensionless Courant number).
            dtau_val = row.get("dtau")
            cfl_in   = row.get("cfl_eff")
            cfl_out  = row.get("cfl_eff_after")
            dtau_out = row.get("dtau_after")
            if cfl_in is not None and cfl_out is not None:
                cfl_str = f"cfl_eff {cfl_in:.4f}->{cfl_out:.4f}  dtau {_format_summary_float(dtau_val)}->{_format_summary_float(dtau_out)}"
            elif cfl_in is not None:
                cfl_str = f"cfl_eff={_format_summary_float(cfl_in, '.4f')}  dtau={_format_summary_float(dtau_val)}"
            else:
                cfl_str = "cfl_eff=n/a"
            ratio = row.get("trial_ratio")
            smoothed = row.get("smoothed_ratio")
            if ratio is not None and smoothed is not None:
                ratio_str = f"  ratio={_format_summary_float(ratio)} (ema={_format_summary_float(smoothed)})"
            elif ratio is not None:
                ratio_str = f"  ratio={_format_summary_float(ratio)}"
            else:
                ratio_str = ""
            print(f"    block {row['block']} [{status}]:{counts_str}  {cfl_str}{ratio_str}")
            print(
                f"      resid={_format_summary_float(row.get('residual_norm'))}"
                f"  delta={_format_summary_float(row.get('delta_norm'))}"
            )
    else:
        print("    unavailable")
 
    poisson = payload.get("poisson", {})
    print("\n  Poisson:")
    if poisson.get("available"):
        for row in poisson.get("blocks", []):
            print(
                "    "
                f"block {row['block']}: iter={row['iterations']} "
                f"true={_format_summary_float(row.get('true_norm'))} "
                f"rel={_format_summary_float(row.get('relative_norm'))}"
            )
    else:
        print("    unavailable")
 
    convergence = payload.get("convergence")
    print("\n  Solution Convergence:")
    if convergence is not None:
        mode = convergence.get("mode", "unknown")
        ref = convergence.get("ref")
        print(f"    mode           : {mode}  (ref={'yes' if ref else 'no'})")
        if mode in ("steady_deterministic", "transient"):
            print(f"    u_abs_l2       : {_format_summary_float(convergence.get('u_abs_l2'))}")
            print(f"    mean_speed     : {_format_summary_float(convergence.get('mean_speed'))}  drift={_format_summary_float(convergence.get('spd_abs'))}")
            print(f"    mean_ke        : {_format_summary_float(convergence.get('mean_ke'))}  drift={_format_summary_float(convergence.get('ke_abs'))}")
        elif mode == "periodic_deterministic":
            ph = convergence.get("ph")
            per = convergence.get("per")
            print(f"    phase          : {ph}/{per}")
            print(f"    u_abs_l2       : {_format_summary_float(convergence.get('u_abs_l2'))}")
            print(f"    mean_speed     : {_format_summary_float(convergence.get('mean_speed'))}  drift={_format_summary_float(convergence.get('spd_abs'))}")
            print(f"    mean_ke        : {_format_summary_float(convergence.get('mean_ke'))}  drift={_format_summary_float(convergence.get('ke_abs'))}")
        elif mode == "statistical_steady":
            print(f"    mean_speed     : {_format_summary_float(convergence.get('mean_speed'))}  win={_format_summary_float(convergence.get('spd_win'))}  win_drift={_format_summary_float(convergence.get('spd_win_abs'))}")
            print(f"    mean_ke        : {_format_summary_float(convergence.get('mean_ke'))}  win={_format_summary_float(convergence.get('ke_win'))}  win_drift={_format_summary_float(convergence.get('ke_win_abs'))}")
    else:
        print("    unavailable")
 
    particles = payload.get("particles", {})
    print("\n  Particles:")
    if particles.get("available"):
        loss_summary = f"lost={particles.get('lost_particles')}"
        if particles.get("lost_particles_cumulative") is not None:
            loss_summary = (
                f"lost(step/total)={particles.get('lost_particles')}/"
                f"{particles.get('lost_particles_cumulative')}"
            )
        if particles.get("exited_particles_cumulative") is not None:
            loss_summary += (
                f" exited(step/total)={particles.get('exited_particles')}/"
                f"{particles.get('exited_particles_cumulative')}"
            )
        print(
            "    "
            f"total={particles.get('total_particles')} {loss_summary} "
            f"migrated={particles.get('migrated_particles')} occupied={particles.get('occupied_cells')} "
            f"imbalance={_format_summary_float(particles.get('load_imbalance'), '.2f')}"
        )
    else:
        print("    unavailable")
 
    memory = payload.get("memory", {})
    print("\n  Runtime Memory:")
    if memory.get("available"):
        if memory.get("source"):
            print(f"    source        : {os.path.relpath(memory.get('source'))}")
        if memory.get("step") is not None and not memory.get("step_match", True):
            print(f"    memory step   : {memory.get('step')} (latest memory row; selected step {memory.get('selected_step')} has no row yet)")
        if memory.get("event"):
            print(f"    event         : {memory.get('event')}  reason={memory.get('reason', '-')}")
        print(f"    process max   : {_format_summary_float(memory.get('process_current_mb_max'), '.3f')} MB current, {_format_summary_float(memory.get('process_peak_mb_max'), '.3f')} MB peak")
        print(f"    PETSc max     : {_format_summary_float(memory.get('petsc_allocated_mb_max'), '.3f')} MB allocated, {_format_summary_float(memory.get('petsc_peak_allocated_mb_max'), '.3f')} MB peak")
        print(f"    max change    : {_format_summary_float(memory.get('max_process_change_mb'), '.3f')} MB")
        if memory.get("step_wall_s") is not None or memory.get("mean_step_wall_s") is not None:
            print(f"    step time     : {_format_summary_float(memory.get('step_wall_s'), '.4g')} s this step, "
                  f"{_format_summary_float(memory.get('mean_step_wall_s'), '.4g')} s mean (slowest rank)")
        if memory.get("final_reason"):
            print(f"    final reason  : {memory.get('final_reason')}")
        else:
            print("    final reason  : none recorded (still running, or stopped without a final row)")
    else:
        print("    unavailable")
 
    snapshot = payload.get("particle_snapshot", {})
    if snapshot.get("available"):
        print("\n  Particle Snapshot (sampled):")
        print(f"    source        : {os.path.relpath(snapshot.get('source'))}")
        cadence = snapshot.get("cadence", {})
        print(
            "    "
            f"cadence       : every {cadence.get('particle_console_output_frequency', 'n/a')} steps, "
            f"row interval {cadence.get('particle_log_interval', 'n/a')}"
        )
        print(f"    sampled rows  : {snapshot.get('sampled_rows')}")
        speed = snapshot.get("speed", {})
        if speed:
            print(
                "    "
                f"sampled speeds: min={_format_summary_float(speed.get('min'))} "
                f"mean={_format_summary_float(speed.get('mean'))} "
                f"max={_format_summary_float(speed.get('max'))} "
                f"std={_format_summary_float(speed.get('std'))} "
                f"stagnant(<1e-6)={speed.get('stagnant_count', 0)}"
            )
        bounds = snapshot.get("position_bounds", {})
        centroid = snapshot.get("position_centroid")
        if bounds:
            bound_parts = []
            for axis in ("x", "y", "z"):
                if axis in bounds:
                    bound_parts.append(
                        f"{axis}=[{_format_summary_float(bounds[axis][0])}, { _format_summary_float(bounds[axis][1])}]"
                    )
            print(f"    sampled bounds: {' '.join(bound_parts)}")
        if centroid:
            print(
                "    "
                f"sampled center: ({_format_summary_float(centroid[0])}, "
                f"{_format_summary_float(centroid[1])}, {_format_summary_float(centroid[2])})"
            )
        distribution = snapshot.get("sampled_distribution", {})
        if distribution:
            print(
                "    "
                f"sampled spread: unique_cells={distribution.get('unique_cells', 'n/a')} "
                f"duplicate_cells={distribution.get('duplicate_cells', 'n/a')} "
                f"unique_pids={distribution.get('unique_pids', 'n/a')} "
                f"ranks={distribution.get('rank_counts', {})}"
            )
        weights = snapshot.get("weights", {})
        if weights:
            weight_parts = []
            for component, summary in sorted(weights.items()):
                weight_parts.append(
                    f"{component}[min/max]=[{_format_summary_float(summary.get('min'))}, { _format_summary_float(summary.get('max'))}]"
                )
            print(f"    sampled weights: {' '.join(weight_parts)}")
        checks = snapshot.get("checks", {})
        if checks:
            print(
                "    "
                f"checks        : duplicate_pid={checks.get('duplicate_pid_count', 0)} "
                f"nan={checks.get('nan_count', 0)} inf={checks.get('inf_count', 0)} "
                f"zero_weight={checks.get('zero_weight_count', 0)} "
                f"negative_weight={checks.get('negative_weight_count', 0)}"
            )
        top_speeds = snapshot.get("top_speeds", [])
        if top_speeds:
            summary = ", ".join(
                f"pid={row.get('pid')} {_format_summary_float(row.get('speed'))}"
                for row in top_speeds
            )
            print(f"    top speeds    : {summary}")
        delta_summary = snapshot.get("delta_from_previous_snapshot", {})
        if delta_summary.get("available"):
            print(
                "    "
                f"vs prev snap  : step={delta_summary.get('previous_step')} "
                f"matched_pids={delta_summary.get('matched_pids')} "
                f"mean_disp={_format_summary_float(delta_summary.get('mean_displacement'))} "
                f"max_disp={_format_summary_float(delta_summary.get('max_displacement'))} "
                f"rank_moves={delta_summary.get('rank_migrations')} "
                f"cell_changes={delta_summary.get('cell_changes')} "
                f"new={delta_summary.get('new_count')} gone={delta_summary.get('gone_count')}"
            )
        print("    preview rows  :")
        for row in snapshot.get("preview_rows", []):
            print(
                "    "
                f"pid={row.get('pid')} rank={row.get('rank')} "
                f"cell={row.get('cell')} pos={row.get('position')} vel={row.get('velocity')}"
            )
 
    profiling = payload.get("profiling", {})
    print("\n  Profiling:")
    if profiling.get("available"):
        print(f"    total logged step time: {profiling.get('total_logged_step_time_s', 0.0):.6f}s")
        for row in profiling.get("functions", [])[:5]:
            print(
                "    "
                f"{row.get('function')}: calls={row.get('calls')} "
                f"time={_format_summary_float(row.get('step_time_s'), '.6f', '0.000000')}s"
            )
    else:
        print("    unavailable")
    print("=" * 60)
 
 

Here is the caller graph for this function:

_summary_display_value()

str picurv_cli.core._summary_display_value (   value )

protected

Format one configuration-summary value for compact text output.

Parameters

[in]

value

Value to format.

Returns

Compact human-readable value.

Definition at line 23529 of file core.py.

def _summary_display_value(value) -> str:
    """!
    @brief Format one configuration-summary value for compact text output.
    @param[in] value Value to format.
    @return Compact human-readable value.
    """
    if value is None:
        return "-"
    if isinstance(value, bool):
        return "enabled" if value else "disabled"
    if isinstance(value, float):
        return f"{value:.6g}"
    if isinstance(value, (list, tuple)):
        return ", ".join(_summary_display_value(item) for item in value) if value else "none"
    if isinstance(value, dict):
        if not value:
            return "none"
        return ", ".join(f"{key}={_summary_display_value(item)}" for key, item in value.items())
    return str(value)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_print_config_header()

picurv_cli.core._print_config_header ( str  title, "str | None"   subtitle = None  )

protected

Print a strong dashboard-style configuration summary header.

Parameters

[in]	title	Section title.
[in]	subtitle	Optional one-line section subtitle.

Definition at line 23550 of file core.py.

def _print_config_header(title: str, subtitle: "str | None" = None):
    """!
    @brief Print a strong dashboard-style configuration summary header.
    @param[in] title Section title.
    @param[in] subtitle Optional one-line section subtitle.
    """
    print("\n" + "=" * _CONFIG_SUMMARY_WIDTH)
    print(f"{title:^78}")
    if subtitle:
        print(f"{subtitle:^78}")
    print("=" * _CONFIG_SUMMARY_WIDTH)
 
 

Here is the caller graph for this function:

_print_config_group()

picurv_cli.core._print_config_group ( str  title, list  rows  )

protected

Print an aligned configuration-summary field group.

Parameters

[in]	title	Group title.
[in]	rows	Sequence of (label, value) pairs.

Definition at line 23563 of file core.py.

def _print_config_group(title: str, rows: list):
    """!
    @brief Print an aligned configuration-summary field group.
    @param[in] title Group title.
    @param[in] rows Sequence of `(label, value)` pairs.
    """
    visible_rows = [(label, value) for label, value in rows if value is not None]
    if not visible_rows:
        return
    print(f"\n  {title}")
    print(f"  {'-' * (len(title) + 1)}")
    for label, value in visible_rows:
        print(f"    {label:<32} {_summary_display_value(value)}")
 
 

Here is the caller graph for this function:

_flatten_summary_mapping()

list picurv_cli.core._flatten_summary_mapping ( dict  mapping, str   prefix = ""  )

protected

Flatten nested summary mappings into readable dotted field rows.

Parameters

[in]	mapping	Mapping to flatten.
[in]	prefix	Optional parent-field prefix.

Returns

Sequence of (field, value) pairs.

Definition at line 23578 of file core.py.

def _flatten_summary_mapping(mapping: dict, prefix: str = "") -> list:
    """!
    @brief Flatten nested summary mappings into readable dotted field rows.
    @param[in] mapping Mapping to flatten.
    @param[in] prefix Optional parent-field prefix.
    @return Sequence of `(field, value)` pairs.
    """
    rows = []
    for key, value in mapping.items():
        label = f"{prefix}.{key}" if prefix else str(key)
        if isinstance(value, dict) and value:
            rows.extend(_flatten_summary_mapping(value, label))
        else:
            rows.append((label, value))
    return rows
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_render_run_overview_text()

picurv_cli.core._render_run_overview_text ( dict  summary )

protected

Render run metadata as a compact dashboard.

Parameters

[in]

summary

Curated run overview mapping.

Definition at line 23595 of file core.py.

def _render_run_overview_text(summary: dict):
    """!
    @brief Render run metadata as a compact dashboard.
    @param[in] summary Curated run overview mapping.
    """
    _print_config_header("RUN OVERVIEW", summary.get("run_id"))
    _print_config_group(
        "Identity",
        [
            ("Run directory", os.path.relpath(summary.get("run_dir")) if summary.get("run_dir") else None),
            ("Created", summary.get("created_at")),
            ("Launch mode", summary.get("launch_mode")),
            ("PICurv release", summary.get("release_version")),
            ("Build", summary.get("build_id")),
            ("Git commit", summary.get("git_commit")),
        ],
    )
    _print_config_group(
        "Execution",
        [
            ("Solver MPI processes", summary.get("solver_num_procs")),
            ("Post MPI processes", summary.get("post_num_procs")),
            ("Stages requested", summary.get("stages_requested")),
            ("Stages ready/completed", summary.get("stages_completed_or_submitted")),
        ],
    )
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_render_case_summary_text()

picurv_cli.core._render_case_summary_text ( dict  summary )

protected

Render the case summary as a glanceable simulation dashboard.

Parameters

[in]

summary

Curated case configuration mapping.

Definition at line 23623 of file core.py.

def _render_case_summary_text(summary: dict):
    """!
    @brief Render the case summary as a glanceable simulation dashboard.
    @param[in] summary Curated case configuration mapping.
    """
    run = summary.get("run_control", {})
    props = summary.get("properties", {})
    grid = summary.get("grid", {})
    domain = summary.get("domain", {})
    physics = summary.get("physics", {})
    subtitle = (
        f"{domain.get('dimensionality', '-')} | {domain.get('blocks', '-')} block(s) | "
        f"Re={_summary_display_value(props.get('reynolds_number'))}"
    )
    _print_config_header("CASE SUMMARY", subtitle)
    _print_config_group(
        "Simulation",
        [
            ("Step range", f"{run.get('start_step')} -> {run.get('end_step')} ({run.get('total_steps')} steps)"),
            ("Physical timestep", run.get("dt_physical")),
            ("Nondimensional timestep", run.get("dt_nondimensional")),
            ("Physical duration", run.get("duration_physical")),
            ("Initial conditions", props.get("initial_conditions")),
        ],
    )
    _print_config_group(
        "Fluid And Scaling",
        [
            ("Reynolds number", props.get("reynolds_number")),
            ("Reference length", props.get("length_ref")),
            ("Reference velocity", props.get("velocity_ref")),
            ("Density", props.get("density")),
            ("Viscosity", props.get("viscosity")),
        ],
    )
    _print_config_group(
        "Domain And Grid",
        [
            ("Grid mode", grid.get("mode")),
            ("Blocks", domain.get("blocks")),
            ("Dimensionality", domain.get("dimensionality")),
            ("Periodic axes", domain.get("periodic")),
            ("MPI grid layout", grid.get("processor_layout")),
            ("Grid source", grid.get("source_file")),
        ],
    )
    if grid.get("programmatic_settings"):
        _print_config_group("Programmatic Grid", _flatten_summary_mapping(grid["programmatic_settings"]))
    _print_config_group(
        "Physics",
        [
            ("Particles", physics.get("particles")),
            ("FSI", physics.get("fsi")),
            ("Turbulence", physics.get("turbulence")),
            ("Statistics", physics.get("statistics")),
        ],
    )
    boundary_blocks = summary.get("boundary_conditions", [])
    if boundary_blocks:
        print("\n  Boundary Conditions")
        print("  --------------------")
        print(f"    {'Block':<7} {'Face':<8} {'Type':<12} Handler")
        print(f"    {'-' * 7} {'-' * 8} {'-' * 12} {'-' * 20}")
        for block in boundary_blocks:
            for face in block.get("faces", []):
                print(
                    f"    {block.get('block', '-')!s:<7} {face.get('face', '-'):<8} "
                    f"{face.get('type', '-'):<12} {face.get('handler', '-')}"
                )
 
 

Here is the call graph for this function:

_render_solver_summary_text()

picurv_cli.core._render_solver_summary_text ( dict  summary )

protected

Render the solver summary as a glanceable numerical-method dashboard.

Parameters

[in]

summary

Curated solver configuration mapping.

Definition at line 23694 of file core.py.

def _render_solver_summary_text(summary: dict):
    """!
    @brief Render the solver summary as a glanceable numerical-method dashboard.
    @param[in] summary Curated solver configuration mapping.
    """
    momentum = summary.get("momentum", {})
    poisson = summary.get("poisson", {})
    operation = summary.get("operation_mode", {})
    subtitle = (
        f"Field: {operation.get('eulerian_field_source', '-')} | "
        f"Momentum: {momentum.get('type', '-')} | Poisson: {poisson.get('method', '-')}"
    )
    _print_config_header("SOLVER SUMMARY", subtitle)
    _print_config_group("Operation", _flatten_summary_mapping(operation))
    _print_config_group(
        "Primary Methods",
        [
            ("Momentum solver", momentum.get("type")),
            ("Central differencing", momentum.get("central_diff")),
            ("Poisson method", poisson.get("method")),
            ("Interpolation", summary.get("interpolation")),
            ("Convergence mode", summary.get("solution_convergence", {}).get("mode")),
        ],
    )
    _print_config_group("Momentum Tolerances", _flatten_summary_mapping(momentum.get("tolerances", {})))
    control_heading = (
        "Newton--Krylov Controls" if momentum.get("type") == "newton_krylov"
        else "Dual-Time Pseudo-Time Controls" if momentum.get("type") == "DUALTIME_PICARD_JAMESON_RK"
        else "Momentum Controls"
    )
    _print_config_group(control_heading, _flatten_summary_mapping(momentum.get("controls", {})))
    _print_config_group("Poisson Configuration", _flatten_summary_mapping(poisson))
    _print_config_group("Solution Convergence", _flatten_summary_mapping(summary.get("solution_convergence", {})))
    _print_config_group("Scalar Transport", _flatten_summary_mapping(summary.get("scalar_transport", {})))
    _print_config_group("Verification Sources", _flatten_summary_mapping(summary.get("verification", {})))
    passthrough = summary.get("petsc_passthrough", {})
    _print_config_group(
        "Advanced PETSc Options",
        [("Option count", passthrough.get("count")), ("Option names", passthrough.get("options"))],
    )
 
 

Here is the call graph for this function:

_render_monitor_summary_text()

picurv_cli.core._render_monitor_summary_text ( dict  summary )

protected

Render the monitor summary as a glanceable observability dashboard.

Parameters

[in]

summary

Curated monitor configuration mapping.

Definition at line 23736 of file core.py.

def _render_monitor_summary_text(summary: dict):
    """!
    @brief Render the monitor summary as a glanceable observability dashboard.
    @param[in] summary Curated monitor configuration mapping.
    """
    logging_cfg = summary.get("logging", {})
    profiling = summary.get("profiling", {})
    diagnostics = summary.get("diagnostics", {})
    io_cfg = summary.get("io", {})
    memory_log = diagnostics.get("runtime_memory_log", {})
    subtitle = (
        f"Verbosity: {logging_cfg.get('verbosity', '-')} | Profiling: {profiling.get('mode', '-')} | "
        f"Output every {_summary_display_value(io_cfg.get('data_output_frequency'))} steps"
    )
    _print_config_header("MONITOR SUMMARY", subtitle)
    _print_config_group(
        "Logging",
        [
            ("Verbosity", logging_cfg.get("verbosity")),
            ("Enabled functions", logging_cfg.get("enabled_functions")),
        ],
    )
    _print_config_group("Profiling", _flatten_summary_mapping(profiling))
    _print_config_group(
        "Output Cadence",
        [
            ("Field output", io_cfg.get("data_output_frequency")),
            ("Particle snapshots", io_cfg.get("particle_console_output_frequency")),
            ("Particle row interval", io_cfg.get("particle_log_interval")),
        ],
    )
    _print_config_group("Output Directories", _flatten_summary_mapping(io_cfg.get("directories", {})))
    _print_config_group(
        "Diagnostics",
        [
            ("Enabled PETSc diagnostics", diagnostics.get("enabled_petsc")),
            ("Runtime memory log", memory_log.get("enabled")),
        ],
    )
    _print_config_group("PETSc Diagnostic Settings", _flatten_summary_mapping(diagnostics.get("petsc", {})))
    solver_monitoring = summary.get("solver_monitoring", {})
    _print_config_group(
        "Solver Monitoring",
        [
            ("Enabled flags", solver_monitoring.get("enabled_flags")),
            ("All flags", solver_monitoring.get("flags")),
        ],
    )
 
 

Here is the call graph for this function:

render_selected_summary()

picurv_cli.core.render_selected_summary	(	dict	payload,
		str	output_format = "text"
	)

Render selected timestep-independent config views and optional health.

Parameters

[in]	payload	Combined selected summary payload.
[in]	output_format	Output format.

Definition at line 23786 of file core.py.

def render_selected_summary(payload: dict, output_format: str = "text"):
    """!
    @brief Render selected timestep-independent config views and optional health.
    @param[in] payload Combined selected summary payload.
    @param[in] output_format Output format.
    """
    if output_format == "json":
        json_payload = {key: value for key, value in payload.items() if key != "_health_requested"}
        print(json.dumps(json_payload, indent=2, sort_keys=True))
        return
 
    if payload.get("run_overview") is not None:
        _render_run_overview_text(payload["run_overview"])
    renderers = {
        "case": _render_case_summary_text,
        "solver": _render_solver_summary_text,
        "monitor": _render_monitor_summary_text,
    }
    for key in ("case", "solver", "monitor"):
        if key in payload.get("configuration", {}):
            renderers[key](payload["configuration"][key])
    storage = payload.get("storage")
    if isinstance(storage, dict):
        print("\nSTORAGE")
        print("=" * 78)
        print(f"  State      : {storage.get('state', 'LOCAL')}")
        if storage.get("archive_id"):
            print(f"  Archive ID : {storage['archive_id']}")
        if storage.get("label"):
            print(f"  Label      : {storage['label']}")
    if payload.get("_health_requested"):
        health_payload = {
            key: value for key, value in payload.items()
            if key not in {"run_overview", "configuration", "storage", "_health_requested"}
        }
        render_run_summary(health_payload, output_format="text")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_humanize_plot_identifier()

str picurv_cli.core._humanize_plot_identifier ( str  value )

protected

Convert one machine-oriented identifier into a readable plot label.

Parameters

[in]

value

Dotted path or snake-case identifier.

Returns

Human-readable label.

Definition at line 23936 of file core.py.

def _humanize_plot_identifier(value: str) -> str:
    """!
    @brief Convert one machine-oriented identifier into a readable plot label.
    @param[in] value Dotted path or snake-case identifier.
    @return Human-readable label.
    """
    text = str(value).split(".")[-1].replace("_", " ").strip()
    replacements = {
        "l2": "L²", "linf": "L∞", "msd": "mean-squared displacement",
        "pct": "percentage", "p95": "95th percentile", "cfl": "CFL",
        "ke": "kinetic energy", "rms": "RMS",
    }
    words = [replacements.get(word.lower(), word) for word in text.split()]
    return " ".join(words[:1]).capitalize() + (" " + " ".join(words[1:]) if len(words) > 1 else "")
 
 

Here is the caller graph for this function:

_summary_field_label()

str picurv_cli.core._summary_field_label ( str  field )

protected

Return the report-facing label for one logged scalar field.

Parameters

[in]

field

Logged scalar field name.

Returns

Report-facing label.

Definition at line 23952 of file core.py.

def _summary_field_label(field: str) -> str:
    """!
    @brief Return the report-facing label for one logged scalar field.
    @param[in] field Logged scalar field name.
    @return Report-facing label.
    """
    return _SUMMARY_PLOT_FIELD_LABELS.get(field, _humanize_plot_identifier(field))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_summary_physical_time()

"float | None" picurv_cli.core._summary_physical_time ( dict  context, dict  record  )

protected

Resolve a record's physical time from its artifact or copied case configuration.

Parameters

[in]	context	Summary context with copied case configuration.
[in]	record	Collected plot record.

Returns

Physical time, or None when it cannot be resolved.

Definition at line 23961 of file core.py.

def _summary_physical_time(context: dict, record: dict) -> "float | None":
    """!
    @brief Resolve a record's physical time from its artifact or copied case configuration.
    @param[in] context Summary context with copied case configuration.
    @param[in] record Collected plot record.
    @return Physical time, or None when it cannot be resolved.
    """
    explicit = record.get("coordinates", {}).get("time")
    if explicit is not None:
        return float(explicit)
    try:
        dt = float((context.get("case_cfg") or {}).get("run_control", {}).get("dt_physical"))
    except (TypeError, ValueError):
        return None
    return float(record["step"]) * dt if math.isfinite(dt) and dt > 0.0 else None
 
 

Here is the caller graph for this function:

_read_runtime_diagnostics_csv()

picurv_cli.core._read_runtime_diagnostics_csv (   path )

protected

Yields (segment, row) for each data line of one of the solver's CSV records.

Every per-step file the solver writes shares one shape: a header (the first line that is not a comment) written once, data rows appended across the run, # comment lines, and a # Continuation from step N marker at each seam where a continuation resumed. A row with fewer fields than the header is skipped rather than guessed at; one with more keeps the header's columns, since columns are only ever appended. segment counts the continuations seen so far, so a caller can keep restarts as separate series instead of drawing a line across the seam.

Parameters

path	CSV to read.

Returns

Generator of (segment_index, {column: text}) pairs.

Definition at line 23978 of file core.py.

def _read_runtime_diagnostics_csv(path):
    """!
    @brief Yields `(segment, row)` for each data line of one of the solver's CSV records.
 
    Every per-step file the solver writes shares one shape: a header (the first line that is
    not a comment) written once, data rows appended across the run, `#` comment lines, and a
    `# Continuation from step N` marker at each seam where a continuation resumed. A row with
    fewer fields than the header is skipped rather than guessed at; one with more keeps the
    header's columns, since columns are only ever appended. `segment` counts the
    continuations seen so far, so a caller can keep restarts as separate series instead of
    drawing a line across the seam.
 
    @param path CSV to read.
    @return Generator of `(segment_index, {column: text})` pairs.
    """
    segment = 0
    header = []
    with open(path, "r", encoding="utf-8", errors="replace", newline="") as handle:
        for raw_line in handle:
            if _is_summary_plot_continuation_marker(raw_line):
                segment += 1
                continue
            stripped = raw_line.strip()
            if not stripped or stripped.startswith("#"):
                continue
            parts = [part.strip() for part in stripped.split(",")]
            if not header:
                header = parts
                continue
            if len(parts) < len(header):
                continue
            yield segment, dict(zip(header, parts))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_log_family_path()

"str | None" picurv_cli.core._log_family_path ( str  log_dir, str  base  )

protected

Return a solver record's CSV, or the text log an older run wrote instead.

Parameters

[in]	log_dir	Run log directory.
[in]	base	File name without extension, such as Continuity_Metrics.

Returns

Existing path, preferring .csv; None when neither exists.

Definition at line 24012 of file core.py.

def _log_family_path(log_dir: str, base: str) -> "str | None":
    """!
    @brief Return a solver record's CSV, or the text log an older run wrote instead.
    @param[in] log_dir Run log directory.
    @param[in] base File name without extension, such as `Continuity_Metrics`.
    @return Existing path, preferring `.csv`; None when neither exists.
    """
    for extension in (".csv", ".log"):
        path = os.path.join(log_dir, base + extension)
        if os.path.isfile(path):
            return path
    return None
 
 

Here is the caller graph for this function:

_block_family_paths()

"list[tuple[int, str]]" picurv_cli.core._block_family_paths ( str  log_dir, *str  bases  )

protected

Return (block, path) for each per-block solver record, CSV preferred per block.

Parameters

[in]	log_dir	Run log directory.
[in]	bases	File-name stems before _Block_<n>, newest naming first.

Returns

Sorted (block, path) pairs.

Definition at line 24026 of file core.py.

def _block_family_paths(log_dir: str, *bases: str) -> "list[tuple[int, str]]":
    """!
    @brief Return `(block, path)` for each per-block solver record, CSV preferred per block.
    @param[in] log_dir Run log directory.
    @param[in] bases File-name stems before `_Block_<n>`, newest naming first.
    @return Sorted `(block, path)` pairs.
    """
    chosen = {}
    for base in bases:
        for extension in (".csv", ".log"):
            for path in glob.glob(os.path.join(log_dir, f"{base}_Block_*{extension}")):
                match = re.search(r"_Block_(\d+)\.(csv|log)$", path)
                if match and int(match.group(1)) not in chosen:
                    chosen[int(match.group(1))] = path
    return sorted(chosen.items())
 
 

Here is the caller graph for this function:

_continuity_rows()

"tuple[str | None, list]" picurv_cli.core._continuity_rows ( str  log_dir )

protected

Return the continuity record's path and its (segment, row) pairs.

Parameters

[in]

log_dir

Run log directory.

Returns

Path (or None) and rows keyed step, block, max_divergence, max_divergence_location, rhs_sum, flux_in, flux_out, net_flux.

Definition at line 24043 of file core.py.

def _continuity_rows(log_dir: str) -> "tuple[str | None, list]":
    """!
    @brief Return the continuity record's path and its `(segment, row)` pairs.
    @param[in] log_dir Run log directory.
    @return Path (or None) and rows keyed step, block, max_divergence, max_divergence_location,
            rhs_sum, flux_in, flux_out, net_flux.
    """
    path = _log_family_path(log_dir, "Continuity_Metrics")
    rows = []
    if path is None:
        return None, rows
    if path.endswith(".csv"):
        for segment, row in _read_runtime_diagnostics_csv(path):
            step, block = _parse_int_loose(row.get("step")), _parse_int_loose(row.get("block"))
            if step is None or block is None:
                continue
            rows.append((segment, {
                "step": step, "block": block,
                "max_divergence": _parse_float_loose(row.get("max_divergence")),
                "max_divergence_location": "([{}][{}][{}] = {})".format(
                    row.get("max_divergence_k"), row.get("max_divergence_j"),
                    row.get("max_divergence_i"), row.get("max_divergence_index")),
                "rhs_sum": _parse_float_loose(row.get("poisson_source_imbalance")),
                "flux_in": _parse_float_loose(row.get("flux_in")),
                "flux_out": _parse_float_loose(row.get("flux_out")),
                "net_flux": _parse_float_loose(row.get("net_flux")),
            }))
        return path, rows
    segment = 0
    with open(path, "r", encoding="utf-8", errors="replace") as f:
        for raw_line in f:
            if _is_summary_plot_continuation_marker(raw_line):
                segment += 1
                continue
            line = raw_line.strip()
            if not line or line.startswith("-") or line.startswith("Timestep"):
                continue
            parts = [part.strip() for part in raw_line.split("|")]
            if len(parts) < 8:
                continue
            step, block = _parse_int_loose(parts[0]), _parse_int_loose(parts[1])
            if step is None or block is None:
                continue
            rows.append((segment, {
                "step": step, "block": block,
                "max_divergence": _parse_float_loose(parts[2]),
                "max_divergence_location": parts[3],
                "rhs_sum": _parse_float_loose(parts[4]),
                "flux_in": _parse_float_loose(parts[5]),
                "flux_out": _parse_float_loose(parts[6]),
                "net_flux": _parse_float_loose(parts[7]),
            }))
    return path, rows
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_particle_step_rows()

"tuple[str | None, list]" picurv_cli.core._particle_step_rows ( str  log_dir, str  metrics_dir  )

protected

Return the per-step particle record's path and its (segment, row) pairs.

search_metrics.csv carries the step's particle counts; a run that predates it in that role wrote Particle_Metrics.log, read when the CSV is absent.

Parameters

[in]	log_dir	Run log directory.
[in]	metrics_dir	Run analysis metrics directory.

Returns

Path (or None) and rows keyed step, total_particles, lost_particles, lost_particles_cumulative, migrated_particles, occupied_cells, load_imbalance, migration_passes, exited_particles, exited_particles_cumulative.

Definition at line 24098 of file core.py.

def _particle_step_rows(log_dir: str, metrics_dir: str) -> "tuple[str | None, list]":
    """!
    @brief Return the per-step particle record's path and its `(segment, row)` pairs.
 
    `search_metrics.csv` carries the step's particle counts; a run that predates it in that
    role wrote `Particle_Metrics.log`, read when the CSV is absent.
 
    @param[in] log_dir Run log directory.
    @param[in] metrics_dir Run analysis metrics directory.
    @return Path (or None) and rows keyed step, total_particles, lost_particles,
            lost_particles_cumulative, migrated_particles, occupied_cells, load_imbalance,
            migration_passes, exited_particles, exited_particles_cumulative.
    """
    rows = []
    csv_path = os.path.join(metrics_dir, "search_metrics.csv") if metrics_dir else None
    if csv_path and os.path.isfile(csv_path):
        for segment, row in _read_runtime_diagnostics_csv(csv_path):
            step = _parse_int_loose(row.get("step"))
            if step is None:
                continue
            rows.append((segment, {
                "step": step,
                "total_particles": _parse_int_loose(row.get("total_particles")),
                "lost_particles": _parse_int_loose(row.get("lost")),
                "lost_particles_cumulative": _parse_int_loose(row.get("lost_cumulative")),
                "migrated_particles": _parse_int_loose(row.get("migrated")),
                "occupied_cells": _parse_int_loose(row.get("occupied_cells")),
                "load_imbalance": _parse_float_loose(row.get("load_imbalance")),
                "migration_passes": _parse_int_loose(row.get("migration_passes")),
                "exited_particles": _parse_int_loose(row.get("exited")),
                "exited_particles_cumulative": _parse_int_loose(row.get("exited_cumulative")),
            }))
        return csv_path, rows
    path = os.path.join(log_dir, "Particle_Metrics.log")
    if not os.path.isfile(path):
        return None, rows
    segment = 0
    with open(path, "r", encoding="utf-8", errors="replace") as f:
        for raw_line in f:
            if _is_summary_plot_continuation_marker(raw_line):
                segment += 1
                continue
            line = raw_line.strip()
            if not line or line.startswith("-") or line.startswith("Stage"):
                continue
            parts = [part.strip() for part in raw_line.split("|")]
            if len(parts) < 8:
                continue
            step = _parse_int_loose(parts[1])
            if step is None:
                continue
            offset = 1 if len(parts) >= 9 else 0
            rows.append((segment, {
                "step": step,
                "total_particles": _parse_int_loose(parts[2]),
                "lost_particles": _parse_int_loose(parts[3]),
                "lost_particles_cumulative": _parse_int_loose(parts[4]) if offset else None,
                "migrated_particles": _parse_int_loose(parts[4 + offset]),
                "occupied_cells": _parse_int_loose(parts[5 + offset]),
                "load_imbalance": _parse_float_loose(parts[6 + offset]),
                "migration_passes": _parse_int_loose(parts[7 + offset]),
                "exited_particles": _parse_int_loose(parts[9]) if len(parts) >= 11 else None,
                "exited_particles_cumulative": _parse_int_loose(parts[10]) if len(parts) >= 11 else None,
            }))
    return path, rows
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_picard_history_rows()

"list[tuple[int, str, list]]" picurv_cli.core._picard_history_rows ( str  log_dir )

protected

Return (block, path, [(segment, row)]) for each Picard momentum history.

Parameters

[in]

log_dir

Run log directory.

Returns

Rows keyed step, block, pseudo_iterations, dtau, cfl_eff, delta_norm, delta_rel, residual_norm, residual_rel, trial_ratio, smoothed_ratio, status, dtau_after, cfl_eff_after; dtau is solver time and cfl_eff = dtau * lambda_max.

Definition at line 24178 of file core.py.

def _picard_history_rows(log_dir: str) -> "list[tuple[int, str, list]]":
    """!
    @brief Return `(block, path, [(segment, row)])` for each Picard momentum history.
    @param[in] log_dir Run log directory.
    @return Rows keyed step, block, pseudo_iterations, dtau, cfl_eff, delta_norm, delta_rel,
            residual_norm, residual_rel, trial_ratio, smoothed_ratio, status, dtau_after,
            cfl_eff_after; dtau is solver time and cfl_eff = dtau * lambda_max.
    """
    out = []
    for block, path in _block_family_paths(log_dir, "Momentum_Solver_DualTime_Picard_Jameson_RK_History",
                                           "Momentum_Solver_Convergence_History"):
        rows = []
        if path.endswith(".csv"):
            for segment, row in _read_runtime_diagnostics_csv(path):
                step = _parse_int_loose(row.get("step"))
                if step is None:
                    continue
                rows.append((segment, {
                    "step": step, "block": block,
                    "pseudo_iterations": _parse_int_loose(row.get("pseudo_iter")),
                    "dtau": _parse_float_loose(row.get("dtau")),
                    "cfl_eff": _parse_float_loose(row.get("cfl_eff")),
                    "delta_norm": _parse_float_loose(row.get("delta_norm")),
                    "delta_rel": _parse_float_loose(row.get("delta_rel")),
                    "residual_norm": _parse_float_loose(row.get("residual_norm")),
                    "residual_rel": _parse_float_loose(row.get("residual_rel")),
                    "trial_ratio": _parse_float_loose(row.get("trial_ratio")),
                    "smoothed_ratio": _parse_float_loose(row.get("smoothed_ratio")),
                    "status": row.get("status") or None,
                    "dtau_after": _parse_float_loose(row.get("dtau_after")),
                    "cfl_eff_after": _parse_float_loose(row.get("cfl_eff_after")),
                }))
        else:
            segment = 0
            with open(path, "r", encoding="utf-8", errors="replace") as f:
                for raw_line in f:
                    if _is_summary_plot_continuation_marker(raw_line):
                        segment += 1
                        continue
                    match = _LEGACY_PICARD_REGEX.search(raw_line)
                    if not match:
                        continue
                    rows.append((segment, {
                        "step": int(match.group("step")), "block": block,
                        "pseudo_iterations": int(match.group("pseudo_iter")),
                        "dtau": _parse_float_loose(match.group("dtau")),
                        "cfl_eff": _parse_float_loose(match.group("cfl_eff")),
                        "delta_norm": float(match.group("delta")),
                        "delta_rel": float(match.group("delta_rel")),
                        "residual_norm": float(match.group("resid")),
                        "residual_rel": float(match.group("resid_rel")),
                        "trial_ratio": _parse_float_loose(match.group("trial_ratio")),
                        "smoothed_ratio": _parse_float_loose(match.group("smoothed_ratio")),
                        "status": match.group("status"),
                        "dtau_after": _parse_float_loose(match.group("dtau_after")),
                        "cfl_eff_after": _parse_float_loose(match.group("cfl_eff_after")),
                    }))
        out.append((block, path, rows))
    return out
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_newton_history_rows()

"list[tuple[int, str, list]]" picurv_cli.core._newton_history_rows ( str  log_dir )

protected

Return (block, path, [(segment, row)]) for each Newton iteration history.

Parameters

[in]

log_dir

Run log directory.

Returns

Rows keyed step, block, newton_iterations, residual_norm.

Definition at line 24255 of file core.py.

def _newton_history_rows(log_dir: str) -> "list[tuple[int, str, list]]":
    """!
    @brief Return `(block, path, [(segment, row)])` for each Newton iteration history.
    @param[in] log_dir Run log directory.
    @return Rows keyed step, block, newton_iterations, residual_norm.
    """
    out = []
    for block, path in _block_family_paths(log_dir, "Momentum_Solver_Newton_Krylov_History"):
        rows = []
        if path.endswith(".csv"):
            for segment, row in _read_runtime_diagnostics_csv(path):
                step = _parse_int_loose(row.get("step"))
                if step is not None:
                    rows.append((segment, {"step": step, "block": _parse_int_loose(row.get("block")),
                                           "newton_iterations": _parse_int_loose(row.get("newton")),
                                           "residual_norm": _parse_float_loose(row.get("nonlinear_norm"))}))
        else:
            segment = 0
            with open(path, "r", encoding="utf-8", errors="replace") as f:
                for raw_line in f:
                    if _is_summary_plot_continuation_marker(raw_line):
                        segment += 1
                        continue
                    match = _LEGACY_NEWTON_HISTORY_REGEX.search(raw_line)
                    if match:
                        rows.append((segment, {"step": int(match.group("step")), "block": int(match.group("block")),
                                               "newton_iterations": int(match.group("newton")),
                                               "residual_norm": float(match.group("norm"))}))
        out.append((block, path, rows))
    return out
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_newton_summary_rows()

"list[tuple[int, str, list]]" picurv_cli.core._newton_summary_rows ( str  log_dir )

protected

Return (block, path, [(segment, row)]) for each Newton per-step summary.

Parameters

[in]

log_dir

Run log directory.

Returns

Rows keyed step, block, solver, reason, reason_code, newton_iterations, residual_evaluations, krylov_iterations, initial_norm, final_norm, state.

Definition at line 24287 of file core.py.

def _newton_summary_rows(log_dir: str) -> "list[tuple[int, str, list]]":
    """!
    @brief Return `(block, path, [(segment, row)])` for each Newton per-step summary.
    @param[in] log_dir Run log directory.
    @return Rows keyed step, block, solver, reason, reason_code, newton_iterations,
            residual_evaluations, krylov_iterations, initial_norm, final_norm, state.
    """
    out = []
    for block, path in _block_family_paths(log_dir, "Momentum_Solver_Newton_Krylov_Summary"):
        rows = []
        if path.endswith(".csv"):
            for segment, row in _read_runtime_diagnostics_csv(path):
                step = _parse_int_loose(row.get("step"))
                if step is None:
                    continue
                rows.append((segment, {
                    "step": step, "block": _parse_int_loose(row.get("block")),
                    "solver": row.get("solver"), "reason": row.get("reason"),
                    "reason_code": _parse_int_loose(row.get("reason_code")),
                    "newton_iterations": _parse_int_loose(row.get("newton")),
                    "residual_evaluations": _parse_int_loose(row.get("evals")),
                    "krylov_iterations": _parse_int_loose(row.get("krylov")),
                    "initial_norm": _parse_float_loose(row.get("initial_norm")),
                    "final_norm": _parse_float_loose(row.get("final_norm")),
                    "state": row.get("state"),
                }))
        else:
            segment = 0
            with open(path, "r", encoding="utf-8", errors="replace") as f:
                for raw_line in f:
                    if _is_summary_plot_continuation_marker(raw_line):
                        segment += 1
                        continue
                    match = _LEGACY_NEWTON_SUMMARY_REGEX.search(raw_line)
                    if not match:
                        continue
                    initial_text = match.group("initial")
                    rows.append((segment, {
                        "step": int(match.group("step")), "block": int(match.group("block")),
                        "solver": match.group("solver").strip(), "reason": match.group("reason"),
                        "reason_code": int(match.group("reason_code")),
                        "newton_iterations": int(match.group("newton")),
                        "residual_evaluations": int(match.group("evals")),
                        "krylov_iterations": int(match.group("krylov")),
                        "initial_norm": None if initial_text == "unavailable" else float(initial_text),
                        "final_norm": float(match.group("final")),
                        "state": match.group("state"),
                    }))
        out.append((block, path, rows))
    return out
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_poisson_history_rows()

"list[tuple[int, str, list]]" picurv_cli.core._poisson_history_rows ( str  log_dir )

protected

Return (block, path, [(segment, row)]) for each Poisson iteration history.

Parameters

[in]

log_dir

Run log directory.

Returns

Rows keyed step, block, iterations, unpreconditioned_norm, true_norm, relative_norm; true_norm and relative_norm are None unless the run computed the true residual.

Definition at line 24346 of file core.py.

def _poisson_history_rows(log_dir: str) -> "list[tuple[int, str, list]]":
    """!
    @brief Return `(block, path, [(segment, row)])` for each Poisson iteration history.
    @param[in] log_dir Run log directory.
    @return Rows keyed step, block, iterations, unpreconditioned_norm, true_norm, relative_norm;
            true_norm and relative_norm are None unless the run computed the true residual.
    """
    out = []
    for block, path in _block_family_paths(log_dir, "Poisson_Solver_Convergence_History"):
        rows = []
        if path.endswith(".csv"):
            for segment, row in _read_runtime_diagnostics_csv(path):
                step = _parse_int_loose(row.get("step"))
                if step is not None:
                    rows.append((segment, {"step": step, "block": _parse_int_loose(row.get("block")),
                                           "iterations": _parse_int_loose(row.get("iter")),
                                           "unpreconditioned_norm": _parse_float_loose(row.get("unpreconditioned_norm")),
                                           "true_norm": _parse_float_loose(row.get("true_norm")),
                                           "relative_norm": _parse_float_loose(row.get("relative_norm"))}))
        else:
            segment = 0
            with open(path, "r", encoding="utf-8", errors="replace") as f:
                for raw_line in f:
                    if _is_summary_plot_continuation_marker(raw_line):
                        segment += 1
                        continue
                    match = _LEGACY_POISSON_REGEX.search(raw_line)
                    if match:
                        rows.append((segment, {"step": int(match.group("step")), "block": int(match.group("block")),
                                               "iterations": int(match.group("iter")),
                                               "unpreconditioned_norm": float(match.group("unpre")),
                                               "true_norm": float(match.group("true")),
                                               "relative_norm": _parse_float_loose(match.group("rel"))}))
        out.append((block, path, rows))
    return out
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_runtime_memory_rows()

list picurv_cli.core._runtime_memory_rows ( str  path )

protected

Return the runtime memory record's (segment, row) pairs (CSV, or an older run's text log).

Parameters

[in]

path

Runtime memory log path as configured.

Returns

Rows keyed step, event, process_current_mb_max, process_peak_mb_max, petsc_allocated_mb_max, petsc_peak_allocated_mb_max, process_change_mb_max, reason.

Definition at line 24383 of file core.py.

def _runtime_memory_rows(path: str) -> list:
    """!
    @brief Return the runtime memory record's `(segment, row)` pairs (CSV, or an older run's text log).
    @param[in] path Runtime memory log path as configured.
    @return Rows keyed step, event, process_current_mb_max, process_peak_mb_max,
            petsc_allocated_mb_max, petsc_peak_allocated_mb_max, process_change_mb_max, reason.
    """
    rows = []
    if not path or not os.path.isfile(path):
        return rows
    keys = ("process_current_mb_max", "process_peak_mb_max", "petsc_allocated_mb_max",
            "petsc_peak_allocated_mb_max", "process_change_mb_max")
    with open(path, "r", encoding="utf-8", errors="replace") as f:
        first = ""
        for line in f:
            if line.strip() and not line.lstrip().startswith("#"):
                first = line
                break
    if first.startswith("step,"):
        for segment, row in _read_runtime_diagnostics_csv(path):
            step = _parse_int_loose(row.get("step"))
            if step is None:
                continue
            rows.append((segment, {"step": step, "event": row.get("event"), "reason": row.get("reason"),
                                   "step_wall_s": _parse_float_loose(row.get("step_wall_s")),
                                   **{key: _parse_float_loose(row.get(key)) for key in keys}}))
        return rows
    segment = 0
    with open(path, "r", encoding="utf-8", errors="replace") as f:
        for raw_line in f:
            if _is_summary_plot_continuation_marker(raw_line):
                segment += 1
                continue
            line = raw_line.strip()
            if not line or line.startswith("#") or line.startswith("Step"):
                continue
            parts = line.split()
            step = _parse_int_loose(parts[0]) if parts else None
            if len(parts) < 8 or step is None:
                continue
            rows.append((segment, {"step": step, "event": parts[1], "reason": parts[7],
                                   **{key: _parse_float_loose(parts[2 + i]) for i, key in enumerate(keys)}}))
    return rows
 
 
# Columns that identify a plot record (its step and line) rather than carry a value; text
# columns such as a status or an event are dropped by _append_summary_plot_record() itself.

Here is the call graph for this function:

Here is the caller graph for this function:

_typed_csv_value()

picurv_cli.core._typed_csv_value ( str  text )

protected

Return a CSV cell as a float (written with a point or exponent), an int, or the text.

Parameters

[in]

text

Cell text.

Returns

Parsed value.

Definition at line 24433 of file core.py.

def _typed_csv_value(text: str):
    """!
    @brief Return a CSV cell as a float (written with a point or exponent), an int, or the text.
    @param[in] text Cell text.
    @return Parsed value.
    """
    float_val = _parse_float_loose(text)
    int_val = _parse_int_loose(text)
    if float_val is not None and ("." in text or "e" in text.lower()):
        return float_val
    if int_val is not None:
        return int_val
    return text
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_solution_convergence_rows()

"tuple[str | None, list]" picurv_cli.core._solution_convergence_rows ( str  log_dir )

protected

Return the solution-convergence record's path and its (segment, row) pairs.

Parameters

[in]

log_dir

Run log directory.

Returns

Path (or None) and rows with every column, numbers parsed and mode set.

Definition at line 24448 of file core.py.

def _solution_convergence_rows(log_dir: str) -> "tuple[str | None, list]":
    """!
    @brief Return the solution-convergence record's path and its `(segment, row)` pairs.
    @param[in] log_dir Run log directory.
    @return Path (or None) and rows with every column, numbers parsed and `mode` set.
    """
    path = _log_family_path(log_dir, "solution_convergence")
    rows = []
    if path is None:
        return None, rows
 
    if path.endswith(".csv"):
        for segment, row in _read_runtime_diagnostics_csv(path):
            step = _parse_int_loose(row.get("step"))
            if step is None:
                continue
            values = {name: _typed_csv_value(text) for name, text in row.items() if name}
            values["step"] = step
            rows.append((segment, values))
        return path, rows
    mode, col_names, segment = None, None, 0
    with open(path, "r", encoding="utf-8", errors="replace") as f:
        for raw_line in f:
            line = raw_line.strip()
            if _is_summary_plot_continuation_marker(line):
                segment += 1
                continue
            if not line:
                continue
            if line.startswith("="):
                found = re.search(r"\[mode:\s*([\w_]+)", line)
                if found:
                    mode = found.group(1)
                continue
            if line.startswith("-"):
                continue
            if col_names is None:
                col_names = [p.strip() for p in raw_line.split("|")]
                continue
            parts = [p.strip() for p in raw_line.split("|")]
            step = _parse_int_loose(parts[0]) if col_names[0] == "step" and len(parts) >= 4 else None
            if step is None:
                continue
            values = {"mode": mode}
            values.update({name: _typed_csv_value(text) for name, text in zip(col_names, parts) if name})
            values["step"] = step
            rows.append((segment, values))
    return path, rows
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_append_summary_plot_record()

picurv_cli.core._append_summary_plot_record ( list  records, str  source,   step, str  line, dict  values, str  source_path, int   segment = 0, dict   coordinates = None  )

protected

Append one numeric append-ordered record for summarize plotting.

Parameters

[out]	records	Destination record list.
[in]	source	Qualified source prefix.
[in]	step	Logged timestep.
[in]	line	Human-readable line identity.
[in]	values	Candidate field mapping.
[in]	source_path	Source artifact path.
[in]	segment	Zero-based continuation segment within the source artifact.
[in]	coordinates	Optional independent variables carried by the source row.

Definition at line 24498 of file core.py.

                                source_path: str, segment: int = 0, coordinates: dict = None):
    """!
    @brief Append one numeric append-ordered record for summarize plotting.
    @param[out] records Destination record list.
    @param[in] source Qualified source prefix.
    @param[in] step Logged timestep.
    @param[in] line Human-readable line identity.
    @param[in] values Candidate field mapping.
    @param[in] source_path Source artifact path.
    @param[in] segment Zero-based continuation segment within the source artifact.
    @param[in] coordinates Optional independent variables carried by the source row.
    """
    numeric = {
        key: value
        for key, value in values.items()
        if isinstance(value, (int, float)) and not isinstance(value, bool)
    }
    if step is not None and numeric:
        records.append({
            "source": source,
            "step": int(step),
            "line": line,
            "values": numeric,
            "source_path": source_path,
            "segment": int(segment),
            "coordinates": {
                key: value for key, value in (coordinates or {}).items()
                if isinstance(value, (int, float)) and not isinstance(value, bool)
            },
        })
 
 

Here is the caller graph for this function:

_is_summary_plot_continuation_marker()

bool picurv_cli.core._is_summary_plot_continuation_marker ( str  line )

protected

Return whether a log line starts a new continuation segment.

Parameters

[in]

line

Candidate raw or stripped log line.

Returns

True for the shared continuation marker syntax.

Definition at line 24531 of file core.py.

def _is_summary_plot_continuation_marker(line: str) -> bool:
    """!
    @brief Return whether a log line starts a new continuation segment.
    @param[in] line Candidate raw or stripped log line.
    @return True for the shared continuation marker syntax.
    """
    return bool(re.match(r"^\s*#?\s*=*\s*Continuation from step\s+\d+", line, re.IGNORECASE))
 
 

Here is the caller graph for this function:

_collect_summary_plot_records()

list picurv_cli.core._collect_summary_plot_records ( dict  context )

protected

Collect append-ordered numeric records from summarize-supported scalar logs.

Parameters

[in]

context

Summary context returned by _build_summary_context().

Returns

Append-ordered plot record list.

Definition at line 24540 of file core.py.

def _collect_summary_plot_records(context: dict) -> list:
    """!
    @brief Collect append-ordered numeric records from summarize-supported scalar logs.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Append-ordered plot record list.
    """
    records = []
    log_dir = context["log_dir"]
    # The C runtime writes its per-step diagnostics CSVs to the analysis metrics home,
    # not beside the text logs; PicurvOpenDiagnosticsCsv() owns that placement.
    metrics_dir = context["metrics_dir"]
 
    continuity_path, continuity_rows = _continuity_rows(log_dir)
    for segment, row in continuity_rows:
        _append_summary_plot_record(
            records, "continuity", row["step"], f"block {row['block']}",
            {key: row[key] for key in ("max_divergence", "rhs_sum", "flux_in", "flux_out", "net_flux")},
            continuity_path, segment,
        )
 
    particle_path, particle_rows = _particle_step_rows(log_dir, metrics_dir)
    for segment, row in particle_rows:
        _append_summary_plot_record(
            records, "particles", row["step"], "particles",
            {key: value for key, value in row.items() if key != "step"},
            particle_path, segment,
        )
 
    # dtau is solver time; cfl_eff = dtau * lambda_max, the Courant number pseudo_cfl.* controls.
    for block, path, rows in _picard_history_rows(log_dir):
        for segment, row in rows:
            _append_summary_plot_record(
                records, "momentum", row["step"], f"block {block}",
                {key: value for key, value in row.items() if key not in _PLOT_ROW_IDENTITY_KEYS},
                path, segment,
                coordinates={"solver_iteration": row["pseudo_iterations"]},
            )
 
    for block, path, rows in _newton_history_rows(log_dir):
        for segment, row in rows:
            _append_summary_plot_record(
                records, "momentum", row["step"], f"block {row['block']}",
                {"newton_iterations": row["newton_iterations"], "residual_norm": row["residual_norm"]},
                path, segment,
                coordinates={"solver_iteration": row["newton_iterations"]},
            )
 
    for block, path, rows in _poisson_history_rows(log_dir):
        for segment, row in rows:
            _append_summary_plot_record(
                records, "poisson", row["step"], f"block {row['block']}",
                {key: row[key] for key in ("iterations", "unpreconditioned_norm", "true_norm", "relative_norm")},
                path, segment,
                coordinates={"solver_iteration": row["iterations"]},
            )
 
    # The LES coefficient history. cs_effective is the curve an LES run is judged on:
    # on the HOM02 benchmark at 64^3 it settles at 0.18-0.19 (page 72, section 10).
    les_path = os.path.join(metrics_dir, "les_coefficient.csv")
    if os.path.isfile(les_path):
        for segment, row in _read_runtime_diagnostics_csv(les_path):
            _append_summary_plot_record(
                records, "les", _parse_int_loose(row.get("step")), "coefficient",
                {
                    "cs_effective": _parse_float_loose(row.get("cs_effective")),
                    "cs_mean": _parse_float_loose(row.get("cs_mean")),
                    "coefficient_rms": _parse_float_loose(row.get("coefficient_rms")),
                    "coefficient_min": _parse_float_loose(row.get("coefficient_min")),
                    "coefficient_max": _parse_float_loose(row.get("coefficient_max")),
                    "nu_t_mean": _parse_float_loose(row.get("nu_t_mean")),
                    "nu_t_max": _parse_float_loose(row.get("nu_t_max")),
                    "nu_t_over_nu_mean": _parse_float_loose(row.get("nu_t_over_nu_mean")),
                    "k_sgs_mean": _parse_float_loose(row.get("k_sgs_mean")),
                    "backscatter_fraction": _parse_float_loose(row.get("backscatter_fraction")),
                    "limited_fraction": _parse_float_loose(row.get("limited_fraction")),
                },
                les_path, segment,
            )
 
    # The wall-model history. y_plus_mean is what says whether the first cell sits where
    # the selected law is valid; u_tau is what a channel run is scored against.
    wall_path = os.path.join(metrics_dir, "wall_model.csv")
    if os.path.isfile(wall_path):
        for segment, row in _read_runtime_diagnostics_csv(wall_path):
            _append_summary_plot_record(
                records, "wall_model", _parse_int_loose(row.get("step")), "near wall",
                {
                    "u_tau_mean": _parse_float_loose(row.get("u_tau_mean")),
                    "u_tau_rms": _parse_float_loose(row.get("u_tau_rms")),
                    "u_tau_min": _parse_float_loose(row.get("u_tau_min")),
                    "u_tau_max": _parse_float_loose(row.get("u_tau_max")),
                    "y_plus_mean": _parse_float_loose(row.get("y_plus_mean")),
                    "y_plus_max": _parse_float_loose(row.get("y_plus_max")),
                    "wall_distance_mean": _parse_float_loose(row.get("wall_distance_mean")),
                    "nu_wall_over_nu_mean": _parse_float_loose(row.get("nu_wall_over_nu_mean")),
                    "wall_cells": _parse_int_loose(row.get("wall_cells")),
                },
                wall_path, segment,
            )
 
    # The driven-flow controller history. driving_acceleration is the force per unit mass
    # the flow received; in a stationary driven channel its time average is u_tau^2 / h.
    driven_path = os.path.join(metrics_dir, "driven_flow.csv")
    if os.path.isfile(driven_path):
        for segment, row in _read_runtime_diagnostics_csv(driven_path):
            _append_summary_plot_record(
                records, "driven_flow", _parse_int_loose(row.get("step")), "controller",
                {
                    "target_flux": _parse_float_loose(row.get("target_flux")),
                    "measured_flux": _parse_float_loose(row.get("measured_flux")),
                    "bulk_velocity": _parse_float_loose(row.get("bulk_velocity")),
                    "bulk_velocity_correction": _parse_float_loose(row.get("bulk_velocity_correction")),
                    "driving_acceleration": _parse_float_loose(row.get("driving_acceleration")),
                },
                driven_path, segment,
            )
 
    profiling_path = os.path.join(log_dir, PROFILING_TIMESTEP_FILE)
    if os.path.isfile(profiling_path):
        segment = 0
        columns = None
        with open(profiling_path, "r", encoding="utf-8", errors="replace", newline="") as f:
            for raw_line in f:
                if _is_summary_plot_continuation_marker(raw_line):
                    segment += 1
                    continue
                values = next(csv.reader([raw_line]))
                if not values:
                    continue
                if columns is None:
                    columns = values
                    continue
                row = dict(zip(columns, values))
                _append_summary_plot_record(
                    records, "profiling", _parse_int_loose(row.get("step")), row.get("function") or "unknown",
                    {"calls": _parse_int_loose(row.get("calls")), "step_time_s": _parse_float_loose(row.get("step_time_s"))},
                    profiling_path, segment,
                )
 
    memory_path = _log_family_path(log_dir, "Runtime_Memory") or os.path.join(log_dir, RUNTIME_MEMORY_FILE)
    for segment, row in _runtime_memory_rows(memory_path):
        if row["event"] in {"Step", "Post"}:
            _append_summary_plot_record(
                records, "memory", row["step"], "memory",
                {key: value for key, value in row.items() if key not in _PLOT_ROW_IDENTITY_KEYS},
                memory_path, segment,
            )
 
    convergence_path, convergence_rows = _solution_convergence_rows(log_dir)
    for segment, row in convergence_rows:
        _append_summary_plot_record(
            records, "convergence", row["step"], "convergence",
            {name: value for name, value in row.items()
             if name not in {"step", "time", "mode", "ref", "ph", "per", "win"}},
            convergence_path, segment,
            coordinates={"time": row.get("time") if isinstance(row.get("time"), (int, float)) else None},
        )
 
    records.extend(_collect_spectra_plot_records(context))
    records.extend(_collect_profile_plot_records(context))
    return records
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_collect_spectra_plot_records()

list picurv_cli.core._collect_spectra_plot_records ( dict  context )

protected

Collect the per-step scalar histories written by the spectra post stage.

Each spectra task keeps its own history file, so one task becomes one plotted line and several tasks compare directly on the same axes.

Parameters

[in]

context

Summary context returned by _build_summary_context().

Returns

Append-ordered plot record list; empty when no spectra were measured.

Definition at line 24703 of file core.py.

def _collect_spectra_plot_records(context: dict) -> list:
    """!
    @brief Collect the per-step scalar histories written by the spectra post stage.
 
    @details Each spectra task keeps its own history file, so one task becomes one
             plotted line and several tasks compare directly on the same axes.
 
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Append-ordered plot record list; empty when no spectra were measured.
    """
    records = []
    run_dir = context.get("run_dir")
    if not run_dir:
        return records
    spectra_root = os.path.join(
        run_dir, resolve_post_spectra_output_dir(context.get("monitor_cfg") or {})
    )
    for root, _dirs, files in os.walk(spectra_root):
        for filename in sorted(files):
            if not filename.endswith("_history.csv"):
                continue
            history_path = os.path.join(root, filename)
            line = filename[: -len("_history.csv")]
            try:
                with open(history_path, "r", encoding="utf-8", errors="replace") as stream:
                    for row in csv.DictReader(stream):
                        step = _parse_int_loose(row.get("step"))
                        if step is None:
                            continue
                        values = {}
                        for column in POST_SPECTRA_SCALAR_COLUMNS:
                            parsed = _parse_float_loose(row.get(column))
                            if parsed is not None:
                                values[column] = parsed
                        if values:
                            _append_summary_plot_record(
                                records, "spectra", step, line, values, history_path, 0,
                                coordinates={"time": _parse_float_loose(row.get("time"))},
                            )
            except OSError:
                # A history a concurrent post stage is still writing is simply not
                # listed yet; summarize is read-only and must never fail on it.
                continue
    return records
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_collect_profile_plot_records()

list picurv_cli.core._collect_profile_plot_records ( dict  context )

protected

Collect the profile histories the profile_series reducer wrote.

Each <prefix>_profile_<name>_history.csv holds one row per step and one column per <output column>.<functional>, which becomes the series profile.<column>.<functional>, one line per history file. The functionals are the reducer's (generators/reduce.gen profile-series); this only reads.

Parameters

[in]

context

Summary context returned by _build_summary_context().

Returns

Append-ordered plot record list; empty when no history was written.

Definition at line 24749 of file core.py.

def _collect_profile_plot_records(context: dict) -> list:
    """!
    @brief Collect the profile histories the `profile_series` reducer wrote.
 
    @details Each `<prefix>_profile_<name>_history.csv` holds one row per step and one
             column per `<output column>.<functional>`, which becomes the series
             `profile.<column>.<functional>`, one line per history file. The functionals
             are the reducer's (`generators/reduce.gen profile-series`); this only reads.
 
    @param[in] context Summary context returned by `_build_summary_context()`.
    @return Append-ordered plot record list; empty when no history was written.
    """
    records = []
    run_dir = context.get("run_dir")
    if not run_dir:
        return records
    root_dir = os.path.join(run_dir, CANONICAL_RUN_PATHS["statistics"])
    for root, _dirs, files in os.walk(root_dir):
        for filename in sorted(files):
            if not re.match(r"^.+_profile_.+_history\.csv$", filename):
                continue
            path = os.path.join(root, filename)
            line = os.path.relpath(path, root_dir)[: -len("_history.csv")]
            try:
                with open(path, "r", encoding="utf-8", errors="replace") as stream:
                    for row in csv.DictReader(stream):
                        step = _parse_int_loose(row.pop("step", None))
                        time = _parse_float_loose(row.pop("time", None))
                        values = {key: _parse_float_loose(value) for key, value in row.items()}
                        values = {key: value for key, value in values.items() if value is not None}
                        if step is not None and values:
                            _append_summary_plot_record(records, "profile", step, line, values, path, 0,
                                                        coordinates={"time": time})
            except OSError:
                continue
    return records
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_build_summary_plot_catalog()

list picurv_cli.core._build_summary_plot_catalog ( list  records )

protected

Build available qualified-series metadata from plot records.

Parameters

[in]

records

Append-ordered plot record list.

Returns

Available series catalog.

Definition at line 24787 of file core.py.

def _build_summary_plot_catalog(records: list) -> list:
    """!
    @brief Build available qualified-series metadata from plot records.
    @param[in] records Append-ordered plot record list.
    @return Available series catalog.
    """
    catalog = {}
    for record in records:
        for field in record["values"]:
            name = f"{record['source']}.{field}"
            item = catalog.setdefault(name, {"series": name, "lines": {}, "source_paths": set(), "sample_count": 0})
            item["lines"][record["line"]] = item["lines"].get(record["line"], 0) + 1
            item["source_paths"].add(record["source_path"])
            item["sample_count"] += 1
    return [
        {
            **item,
            "lines": [{"label": label, "sample_count": count} for label, count in sorted(item["lines"].items())],
            "source_paths": sorted(item["source_paths"]),
        }
        for _, item in sorted(catalog.items())
    ]
 
 

Here is the caller graph for this function:

_representative_indices()

list picurv_cli.core._representative_indices ( int  count, int   maximum = 6  )

protected

Select evenly distributed indices while always retaining both endpoints.

Parameters

[in]	count	Number of available ordered states.
[in]	maximum	Maximum states to retain.

Returns

Sorted unique zero-based indices.

Definition at line 24811 of file core.py.

def _representative_indices(count: int, maximum: int = 6) -> list:
    """!
    @brief Select evenly distributed indices while always retaining both endpoints.
    @param[in] count Number of available ordered states.
    @param[in] maximum Maximum states to retain.
    @return Sorted unique zero-based indices.
    """
    if count <= maximum:
        return list(range(count))
    return sorted({round(index * (count - 1) / (maximum - 1)) for index in range(maximum)})
 
 

Here is the caller graph for this function:

_build_spectrum_plot_request()

dict picurv_cli.core._build_spectrum_plot_request ( dict  context, str  task, bool  reference, bool  linear_y, "str | None"  output_path  )

protected

Build a plot.gen request drawing representative measured spectra.

A decaying flow has a different spectrum at every step, so states are never averaged. Up to six evenly spaced states are retained, including the first and last, to show evolution without an unreadable legend.

Parameters

[in]	context	Summary context returned by _build_summary_context().
[in]	task	Task basename, or a unique substring of one.
[in]	reference	Overlay the staged initial-condition spectrum when available.
[in]	linear_y	Force linear axes instead of the log-log default.
[in]	output_path	Optional explicit output path.

Returns

Versioned normalized plot request.

Exceptions

ValueError

when no matching spectrum file exists.

Definition at line 24823 of file core.py.

                                 linear_y: bool, output_path: "str | None") -> dict:
    """!
    @brief Build a plot.gen request drawing representative measured spectra.
 
    @details A decaying flow has a different spectrum at every step, so states are
             never averaged. Up to six evenly spaced states are retained, including
             the first and last, to show evolution without an unreadable legend.
 
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] task Task basename, or a unique substring of one.
    @param[in] reference Overlay the staged initial-condition spectrum when available.
    @param[in] linear_y Force linear axes instead of the log-log default.
    @param[in] output_path Optional explicit output path.
    @return Versioned normalized plot request.
    @throws ValueError when no matching spectrum file exists.
    """
    spectra_dir = os.path.join(
        context["run_dir"],
        resolve_post_spectra_output_dir(context.get("monitor_cfg") or {}),
    )
    candidates = []
    if os.path.isdir(spectra_dir):
        # The staged initial-condition spectrum shares this directory but is the
        # reference overlay, never a task a user can select. Post recipes write into
        # their own subdirectory (resolve_recipe_spectra_output_dir), so one level is
        # searched too; a candidate is named by its path under the spectra directory.
        reference_name = os.path.basename(INITIAL_CONDITION_SPECTRUM_RELPATH)
        for root, _dirs, files in os.walk(spectra_dir):
            if os.path.relpath(root, spectra_dir).count(os.sep) > 0:
                continue
            for name in files:
                if (name.endswith(".csv") and not name.endswith("_history.csv")
                        and name != reference_name):
                    candidates.append(os.path.relpath(os.path.join(root, name), spectra_dir))
        candidates.sort()
    if not candidates:
        raise ValueError(
            "No spectra were found for this run. Measure them with a post.yml that defines "
            "spectra tasks: 'picurv run --post-process --only spectra --run-dir <run> --post <post.yml>'."
        )
    matches = [name for name in candidates if task in name] if task else candidates
    if len(matches) != 1:
        available = ", ".join(name[: -len(".csv")] for name in candidates)
        raise ValueError(
            f"Spectrum selector {task!r} matched {len(matches)} files. Available: {available}."
        )
    spectrum_path = os.path.join(spectra_dir, matches[0])
    if "plane_spectrum" in matches[0]:
        raise ValueError("Plane spectra have two wavenumber axes; use the spectrum CSV for a 2D plot.")
 
    by_step = {}
    times = {}
    with open(spectrum_path, "r", encoding="utf-8", errors="replace") as stream:
        for row in csv.DictReader(stream):
            step = _parse_int_loose(row.get("step"))
            wavenumber = _parse_float_loose(row.get("k"))
            energy = _parse_float_loose(row.get("energy"))
            if step is None or wavenumber is None or energy is None:
                continue
            # A log-log plot cannot carry the zero wavenumber or an empty shell.
            if wavenumber <= 0.0 or (not linear_y and energy <= 0.0):
                continue
            by_step.setdefault(step, []).append([wavenumber, energy])
            times.setdefault(step, _parse_float_loose(row.get("time")))
    if not by_step:
        raise ValueError(f"{os.path.relpath(spectrum_path)} carries no plottable spectrum rows.")
 
    lines = []
    if reference:
        reference_path = os.path.join(context["run_dir"], INITIAL_CONDITION_SPECTRUM_RELPATH)
        if os.path.isfile(reference_path):
            points = []
            with open(reference_path, "r", encoding="utf-8", errors="replace") as stream:
                for row in csv.DictReader(stream):
                    wavenumber = _parse_float_loose(row.get("k"))
                    energy = _parse_float_loose(row.get("energy"))
                    if wavenumber is None or energy is None:
                        continue
                    if wavenumber <= 0.0 or (not linear_y and energy <= 0.0):
                        continue
                    points.append([wavenumber, energy])
            if points:
                lines.append({
                    "label": "Initial condition", "points": sorted(points),
                    "role": "reference", "color": "#333333", "line_style": "--",
                })
 
    ordered_steps = sorted(by_step)
    selected_steps = [ordered_steps[index] for index in _representative_indices(len(ordered_steps))]
    spectrum_colors = ("#440154", "#414487", "#2A788E", "#22A884", "#7AD151", "#DCE319")
    for index, step in enumerate(selected_steps):
        time = times.get(step)
        label = f"Step {step}" if time is None else f"t = {time:g} (step {step})"
        lines.append({
            "label": label,
            "points": sorted(by_step[step]),
            "role": "latest" if step == ordered_steps[-1] else "snapshot",
            "color": spectrum_colors[round(index * (len(spectrum_colors) - 1) / max(1, len(selected_steps) - 1))],
            "line_width": 2.4 if step == ordered_steps[-1] else 1.65,
        })
 
    name = os.path.basename(matches[0])[: -len(".csv")]
    fallback = os.path.join(
        context["run_dir"], CANONICAL_RUN_PATHS["plots"], f"{name}.png"
    )
    task_match = re.search(r"_(?P<field>[^_]+)_block(?P<block>\d+)_(?P<symbol>[^_]+)$", name)
    subtitle = None
    if task_match:
        subtitle = (
            f"Field {task_match.group('field')} · block {int(task_match.group('block'))} "
            f"· {task_match.group('symbol')} wavenumber"
        )
    return {
        "schema_version": 1,
        "plot_type": "spectrum",
        "series": name,
        "title": "Turbulent kinetic-energy spectrum",
        "subtitle": subtitle,
        "x_label": "Wavenumber, k",
        "y_label": "Energy spectrum, E(k)",
        "x_scale": "linear" if linear_y else "log",
        "y_scale": "linear" if linear_y else "log",
        "legend_title": "Snapshot",
        "show_markers": False,
        "window": {
            "mode": "representative", "last": None,
            "available_steps": len(ordered_steps), "selected_steps": selected_steps,
        },
        "lines": lines,
        "output_path": os.path.abspath(output_path) if output_path else fallback,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_build_summary_plot_request()

dict picurv_cli.core._build_summary_plot_request ( dict  context, list  records, str  series, "int | None"  last_n, bool  linear_y, "str | None"  output_path  )

protected

Build one normalized plot.gen request from collected summarize records.

Parameters

[in]	context	Summary context returned by _build_summary_context().
[in]	records	Append-ordered plot record list.
[in]	series	Qualified series name.
[in]	last_n	Optional last-N records per plotted line.
[in]	linear_y	Whether to force linear scaling.
[in]	output_path	Optional explicit output path.

Returns

Versioned normalized plot request.

Definition at line 24957 of file core.py.

def _build_summary_plot_request(context: dict, records: list, series: str, last_n: "int | None", linear_y: bool, output_path: "str | None") -> dict:
    """!
    @brief Build one normalized plot.gen request from collected summarize records.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] records Append-ordered plot record list.
    @param[in] series Qualified series name.
    @param[in] last_n Optional last-N records per plotted line.
    @param[in] linear_y Whether to force linear scaling.
    @param[in] output_path Optional explicit output path.
    @return Versioned normalized plot request.
    """
    source, separator, field = series.partition(".")
    if not separator:
        raise ValueError("plot series must be qualified as '<source>.<field>'")
    matching = [record for record in records if record["source"] == source and field in record["values"]]
    if not matching:
        raise ValueError(f"Plot series '{series}' is unavailable. Use --list-plot-series to inspect available series.")
    latest_segments = {}
    for record in matching:
        source_path = record["source_path"]
        latest_segments[source_path] = max(latest_segments.get(source_path, 0), record.get("segment", 0))
    matching = [
        record for record in matching
        if record.get("segment", 0) == latest_segments[record["source_path"]]
    ]
    is_iteration_history = (
        source in {"momentum", "poisson"} and field in _SUMMARY_ITERATION_HISTORY_FIELDS
        and any("solver_iteration" in record.get("coordinates", {}) for record in matching)
    )
    grouped = {}
    selected_steps = set()
    if is_iteration_history:
        histories = {}
        for record in matching:
            iteration = record.get("coordinates", {}).get("solver_iteration")
            if iteration is None:
                continue
            histories.setdefault((record["source_path"], record["line"]), []).append(record)
        for (_source_path, label), history in histories.items():
            latest_step = max(record["step"] for record in history)
            selected_steps.add(latest_step)
            points = [
                [record["coordinates"]["solver_iteration"], record["values"][field]]
                for record in history if record["step"] == latest_step
            ]
            if last_n is not None:
                points = points[-last_n:]
            grouped.setdefault(f"{label} · step {latest_step}", []).extend(points)
        x_label = "Nonlinear iteration" if source == "momentum" else "Linear iteration"
        x_kind = "integer"
    else:
        uses_physical_time = all(_summary_physical_time(context, record) is not None for record in matching)
        for record in matching:
            x_value = _summary_physical_time(context, record) if uses_physical_time else record["step"]
            grouped.setdefault(record["line"], []).append([x_value, record["values"][field]])
        # Iteration-count fields occur on every nonlinear-history row. Reduce them
        # to the final effort per physical step instead of drawing a y=x staircase.
        if field in {"pseudo_iterations", "newton_iterations", "iterations"}:
            grouped = {
                label: [list(item) for item in {
                    point[0]: max(candidate[1] for candidate in points if candidate[0] == point[0])
                    for point in points
                }.items()]
                for label, points in grouped.items()
            }
        for label, points in grouped.items():
            points.sort(key=lambda point: point[0])
            if last_n is not None:
                grouped[label] = points[-last_n:]
        x_label = "Physical time" if uses_physical_time else "Physical timestep"
        x_kind = "continuous" if uses_physical_time else "integer"
 
    grouped = {label: points for label, points in grouped.items() if points}
    if not grouped:
        raise ValueError(f"Plot series '{series}' has no plottable points in the selected window.")
    if is_iteration_history and len(selected_steps) == 1:
        grouped = {
            label.rsplit(" · step ", 1)[0]: points
            for label, points in grouped.items()
        }
    all_values = [point[1] for points in grouped.values() for point in points]
    use_log = not linear_y and field in _SUMMARY_PLOT_LOG_SCALE_FIELDS and all(value > 0 for value in all_values)
    window_token = f"last-{last_n}" if last_n is not None else "full"
    safe_series = re.sub(r"[^A-Za-z0-9_.-]+", "_", series)
    fallback = os.path.join(
        context["run_dir"], CANONICAL_RUN_PATHS["plots"],
        f"{safe_series}_{window_token}.png",
    )
    field_label = _summary_field_label(field)
    source_title = _SUMMARY_PLOT_SOURCE_TITLES.get(source, _humanize_plot_identifier(source))
    title = f"{source_title}: {field_label}"
    if is_iteration_history:
        title += " convergence"
    subtitle_bits = []
    if selected_steps:
        ordered = sorted(selected_steps)
        subtitle_bits.append(
            f"Latest physical step {ordered[0]}" if len(ordered) == 1
            else f"Latest available physical steps {ordered[0]}–{ordered[-1]}"
        )
    if last_n is not None:
        subtitle_bits.append(f"Last {last_n} samples per curve")
    legend_title = {
        "continuity": "Block",
        "momentum": "Block",
        "poisson": "Block",
        "profiling": "Function",
        "spectra": "Spectrum task",
    }.get(source, "Series")
    only_label = next(iter(grouped)) if len(grouped) == 1 else None
    show_legend = len(grouped) > 1 or bool(
        only_label and (only_label.lower().startswith("block ") or source == "profiling")
    )
    return {
        "schema_version": 1,
        "plot_type": "iteration_history" if is_iteration_history else "time_history",
        "series": series,
        "title": title,
        "subtitle": " · ".join(subtitle_bits) or None,
        "x_label": x_label,
        "x_kind": x_kind,
        "y_label": field_label,
        "y_scale": "log" if use_log else "linear",
        "include_zero_y": not use_log and all(value >= 0.0 for value in all_values),
        "show_markers": not is_iteration_history,
        "show_legend": show_legend,
        "legend_title": legend_title,
        "window": {"mode": "last" if last_n is not None else "full", "last": last_n},
        "lines": [{"label": label, "points": points} for label, points in sorted(grouped.items())],
        "output_path": os.path.abspath(output_path) if output_path else None,
        "fallback_output_path": fallback,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_render_summary_plot_catalog()

picurv_cli.core._render_summary_plot_catalog ( list  catalog, str  output_format  )

protected

Render available summarize plot-series metadata.

Parameters

[in]	catalog	Available series catalog.
[in]	output_format	Text or JSON output format.

Definition at line 25091 of file core.py.

def _render_summary_plot_catalog(catalog: list, output_format: str):
    """!
    @brief Render available summarize plot-series metadata.
    @param[in] catalog Available series catalog.
    @param[in] output_format Text or JSON output format.
    """
    if output_format == "json":
        print(json.dumps({"available_series": catalog}, indent=2, sort_keys=True))
        return
    print("\nAVAILABLE PLOT SERIES")
    print("=" * 78)
    for item in catalog:
        labels = ", ".join(line["label"] for line in item["lines"])
        print(f"  {item['series']:<42} samples={item['sample_count']:<5} lines={labels}")
        print(f"    source: {', '.join(os.path.relpath(path) for path in item['source_paths'])}")
 
 
# The run's CSV records `summarize --table` prints, by name: (directory key, file name).
# Per-block solver histories take a `:<block>` suffix (block 0 by default).

Here is the caller graph for this function:

_summary_table_path()

str picurv_cli.core._summary_table_path ( dict  context, str  name  )

protected

Resolve a summarize --table name to the CSV it prints.

Parameters

[in]	context	Summary context returned by _build_summary_context().
[in]	name	Table name from SUMMARY_TABLES, optionally :<block>.

Returns

Path to the CSV (it may not exist).

Exceptions

ValueError

When the name is unknown or the block is not an integer.

Definition at line 25132 of file core.py.

def _summary_table_path(context: dict, name: str) -> str:
    """!
    @brief Resolve a `summarize --table` name to the CSV it prints.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] name Table name from SUMMARY_TABLES, optionally `:<block>`.
    @return Path to the CSV (it may not exist).
    @throws ValueError When the name is unknown or the block is not an integer.
    """
    base, _, block = name.partition(":")
    if base not in SUMMARY_TABLES:
        raise ValueError(f"Unknown table '{base}'. Known tables: {', '.join(sorted(SUMMARY_TABLES))}.")
    if block and not block.isdigit():
        raise ValueError(f"Table block '{block}' must be a non-negative integer.")
    directory_key, file_name = SUMMARY_TABLES[base]
    if "{block}" in file_name:
        file_name = file_name.format(block=int(block or 0))
    elif block:
        raise ValueError(f"Table '{base}' is not per-block; drop ':{block}'.")
    return os.path.join(context[directory_key], file_name)
 
 

Here is the caller graph for this function:

_list_summary_tables()

picurv_cli.core._list_summary_tables ( dict  context, str  output_format  )

protected

Print the summarize --table names whose CSV this run has, with row counts.

Parameters

[in]	context	Summary context returned by _build_summary_context().
[in]	output_format	Text or JSON output format.

Definition at line 25153 of file core.py.

def _list_summary_tables(context: dict, output_format: str):
    """!
    @brief Print the `summarize --table` names whose CSV this run has, with row counts.
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] output_format Text or JSON output format.
    """
    found = []
    for name in sorted(SUMMARY_TABLES):
        names = [name]
        if "{block}" in (SUMMARY_TABLES[name][1] or ""):
            pattern = os.path.join(context["log_dir"], SUMMARY_TABLES[name][1].format(block="*"))
            blocks = sorted(int(re.search(r"_Block_(\d+)\.csv$", path).group(1)) for path in glob.glob(pattern))
            names = [name if b == 0 else f"{name}:{b}" for b in blocks]
        for table in names:
            path = _summary_table_path(context, table)
            if os.path.isfile(path):
                rows = list(_read_runtime_diagnostics_csv(path))
                columns = len(rows[0][1]) if rows else 0
                found.append({"table": table, "rows": len(rows), "columns": columns, "path": path})
    if output_format == "json":
        print(json.dumps({"available_tables": found}, indent=2, sort_keys=True))
        return
    if not found:
        raise ValueError("No CSV records were found in the run (a run older than the CSV records keeps text logs).")
    print("\nAVAILABLE TABLES")
    print("=" * 78)
    for item in found:
        print(f"  {item['table']:<26} rows={item['rows']:<7} columns={item['columns']:<3} {os.path.relpath(item['path'])}")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_render_summary_table()

picurv_cli.core._render_summary_table ( dict  context, str  name,   last_n,   columns, str  output_format  )

protected

Print the last rows of one of the run's CSV records as aligned columns (or JSON).

Parameters

[in]	context	Summary context returned by _build_summary_context().
[in]	name	Table name (summarize --list-tables).
[in]	last_n	Rows to show from the end; None shows the last 20.
[in]	columns	Comma-separated column names to keep, or None for all.
[in]	output_format	Text or JSON output format.

Exceptions

ValueError

When the table is unknown, absent, or a requested column is missing.

Definition at line 25183 of file core.py.

def _render_summary_table(context: dict, name: str, last_n, columns, output_format: str):
    """!
    @brief Print the last rows of one of the run's CSV records as aligned columns (or JSON).
    @param[in] context Summary context returned by `_build_summary_context()`.
    @param[in] name Table name (`summarize --list-tables`).
    @param[in] last_n Rows to show from the end; None shows the last 20.
    @param[in] columns Comma-separated column names to keep, or None for all.
    @param[in] output_format Text or JSON output format.
    @throws ValueError When the table is unknown, absent, or a requested column is missing.
    """
    path = _summary_table_path(context, name)
    if not os.path.isfile(path):
        raise ValueError(f"Table '{name}' has no file at {os.path.relpath(path)}; --list-tables names the ones this run has.")
    rows = list(_read_runtime_diagnostics_csv(path))
    if not rows:
        raise ValueError(f"Table '{name}' has no data rows yet.")
    header = list(rows[0][1].keys())
    if columns:
        wanted = [column.strip() for column in columns.split(",") if column.strip()]
        missing = [column for column in wanted if column not in header]
        if missing:
            raise ValueError(f"Table '{name}' has no column(s) {', '.join(missing)}; its columns are: {', '.join(header)}.")
        keep = ([header[0]] if header[0] not in wanted else []) + wanted
    else:
        keep = header
    shown = rows[-(last_n or 20):]
    if output_format == "json":
        print(json.dumps({"table": name, "path": path, "columns": keep,
                          "rows": [{"segment": segment, **{key: row.get(key) for key in keep}} for segment, row in shown]},
                         indent=2))
        return
    widths = {key: max(len(key), *(len(row.get(key) or "") for _, row in shown)) for key in keep}
    print(f"\n{name}: {os.path.relpath(path)} (last {len(shown)} of {len(rows)} rows)")
    print("  ".join(key.rjust(widths[key]) for key in keep))
    print("  ".join("-" * widths[key] for key in keep))
    previous_segment = shown[0][0]
    for segment, row in shown:
        if segment != previous_segment:
            print(f"# continuation segment {segment}")
            previous_segment = segment
        print("  ".join((row.get(key) or "").rjust(widths[key]) for key in keep))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_invoke_plot_gen()

picurv_cli.core._invoke_plot_gen ( dict  request )

protected

Invoke standalone plot.gen with one normalized request over stdin.

Parameters

[in]

request

Versioned normalized plot request.

Definition at line 25226 of file core.py.

def _invoke_plot_gen(request: dict):
    """!
    @brief Invoke standalone plot.gen with one normalized request over stdin.
    @param[in] request Versioned normalized plot request.
    """
    plotgen_path = os.path.join(GENERATORS_PATH, "plot.gen")
    if not os.path.isfile(plotgen_path):
        raise ValueError(f"plot.gen script not found: {plotgen_path}")
    result = subprocess.run(
        [sys.executable, plotgen_path, "--input", "-"],
        input=json.dumps(request),
        text=True,
        capture_output=True,
        check=False,
    )
    if result.stdout:
        print(result.stdout.rstrip())
    if result.returncode != 0:
        details = (result.stderr or result.stdout or "unknown plotting error").strip()
        if result.returncode == 3:
            raise PlotDependencyError(details)
        raise ValueError(f"plot.gen failed with exit code {result.returncode}: {details}")
 
 

Here is the caller graph for this function:

summarize_workflow()

picurv_cli.core.summarize_workflow

(

args

)

Build and render a read-only health summary for a run step.

Parameters

[in]

args

Command-line style argument list supplied to the function.

Definition at line 25250 of file core.py.

def summarize_workflow(args):
    """!
    @brief Build and render a read-only health summary for a run step.
    @param[in] args Command-line style argument list supplied to the function.
    """
    if args.step is not None and args.step < 0:
        fail_cli_usage("--step must be a non-negative integer.")
    if args.snapshot_rows < 1:
        fail_cli_usage("--snapshot-rows must be at least 1.")
    plot_series = getattr(args, "plot_series", None)
    list_plot_series = bool(getattr(args, "list_plot_series", False))
    plot_spectrum = getattr(args, "plot_spectrum", None)
    last_n = getattr(args, "last_n", None)
    plot_output = getattr(args, "plot_output", None)
    linear_y = bool(getattr(args, "linear_y", False))
    table = getattr(args, "table", None)
    list_tables = bool(getattr(args, "list_tables", False))
    table_columns = getattr(args, "table_columns", None)
    plot_mode = bool(plot_series or list_plot_series or plot_spectrum is not None or table or list_tables)
    existing_selectors = any(
        [
            getattr(args, "overview", False),
            getattr(args, "case", False),
            getattr(args, "solver", False),
            getattr(args, "monitor", False),
            args.step is not None,
            getattr(args, "latest", False),
            getattr(args, "max_step", False),
        ]
    )
    if plot_mode and existing_selectors:
        fail_cli_usage("Plot discovery and --plot cannot be combined with config or selected-step selectors.")
    if not plot_series and not table and last_n is not None:
        fail_cli_usage("--last requires --plot or --table.")
    if table_columns and not table:
        fail_cli_usage("--columns requires --table.")
    if not plot_series and plot_spectrum is None and (plot_output or linear_y):
        fail_cli_usage("--plot-output and --linear-y require --plot or --plot-spectrum.")
    if last_n is not None and last_n < 1:
        fail_cli_usage("--last must be a positive integer.")
    if plot_series and args.output_format == "json":
        fail_cli_usage("--plot does not support --format json; use --list-plot-series --format json for structured discovery.")
    if table or list_tables:
        context = _build_summary_context(args.run_dir)
        try:
            if list_tables:
                _list_summary_tables(context, args.output_format)
            else:
                _render_summary_table(context, table, last_n, table_columns, args.output_format)
        except ValueError as exc:
            emit_structured_error(
                ERROR_CODE_CFG_INVALID_VALUE,
                key="table",
                file_path=context["log_dir"],
                message=str(exc),
                hint="--list-tables names the CSV records this run has.",
            )
            sys.exit(1)
        return
    if plot_mode:
        context = _build_summary_context(args.run_dir)
        try:
            records = _collect_summary_plot_records(context)
            catalog = _build_summary_plot_catalog(records)
            if list_plot_series:
                if not catalog:
                    raise ValueError("No plottable scalar histories were found in the run logs.")
                _render_summary_plot_catalog(catalog, args.output_format)
                return
            if plot_spectrum is not None:
                request = _build_spectrum_plot_request(
                    context, plot_spectrum, True, linear_y, plot_output
                )
            else:
                request = _build_summary_plot_request(
                    context, records, plot_series, last_n, linear_y, plot_output
                )
            _invoke_plot_gen(request)
            return
        except PlotDependencyError as exc:
            emit_structured_error(
                ERROR_CODE_DEPENDENCY_MISSING,
                key="plotting",
                file_path=sys.executable,
                message=str(exc),
            )
            sys.exit(1)
        except ValueError as exc:
            emit_structured_error(
                ERROR_CODE_CFG_INVALID_VALUE,
                key="plot",
                file_path=context["log_dir"],
                message=str(exc),
                hint=("--list-plot-series names the scalar histories this run recorded."
                      if plot_spectrum is None else
                      "Spectra come from the spectra tasks of a post.yml (see the post-processing reference)."),
            )
            sys.exit(1)
 
    selected_configs = {
        name
        for name in ("case", "solver", "monitor")
        if bool(getattr(args, name, False))
    }
    if getattr(args, "overview", False):
        selected_configs.update({"case", "solver", "monitor"})
    explicit_health = args.step is not None or bool(getattr(args, "latest", False)) or bool(getattr(args, "max_step", False))
    health_requested = explicit_health or (not selected_configs and not getattr(args, "overview", False))
 
    context = None
    combined = {"storage": storage_state_summary(args.run_dir)}
    if selected_configs or getattr(args, "overview", False):
        context = _build_summary_context(args.run_dir)
        if getattr(args, "overview", False):
            combined["run_overview"] = _build_run_overview(context)
        combined["configuration"] = {}
        builders = {
            "case": _build_case_overview,
            "solver": _build_solver_overview,
            "monitor": _build_monitor_overview,
        }
        for name in ("case", "solver", "monitor"):
            if name in selected_configs:
                try:
                    combined["configuration"][name] = builders[name](context)
                except (KeyError, TypeError, ValueError, ZeroDivisionError) as exc:
                    emit_structured_error(
                        ERROR_CODE_CFG_INVALID_VALUE,
                        key=name,
                        file_path=context["config_paths"][name],
                        message=f"Could not summarize copied {name}.yml: {exc}",
                    )
                    sys.exit(1)
 
    if not health_requested:
        combined["_health_requested"] = False
        render_selected_summary(combined, output_format=args.output_format)
        return
 
    requested_step = args.step
    if requested_step is None and getattr(args, "latest", False):
        requested_step = None
    selection_mode = "max_step" if getattr(args, "max_step", False) else "latest"
    health_payload = build_run_summary_payload(
        args.run_dir,
        step=requested_step,
        snapshot_rows=args.snapshot_rows,
        selection_mode=selection_mode,
    )
    if set(combined) == {"storage"}:
        combined = {**health_payload, **combined, "_health_requested": True}
        render_selected_summary(combined, output_format=args.output_format)
        return
    combined = {**health_payload, **combined, "_health_requested": True}
    render_selected_summary(combined, output_format=args.output_format)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_resolve_submission_target()

dict picurv_cli.core._resolve_submission_target ( str   run_dir = None, str   study_dir = None  )

protected

Resolve a run/study submission target from explicit directory flags.

Parameters

[in]	run_dir	Argument passed to _resolve_submission_target().
[in]	study_dir	Argument passed to _resolve_submission_target().

Returns

Value returned by _resolve_submission_target().

Definition at line 25407 of file core.py.

def _resolve_submission_target(run_dir: str = None, study_dir: str = None) -> dict:
    """!
    @brief Resolve a run/study submission target from explicit directory flags.
    @param[in] run_dir Argument passed to `_resolve_submission_target()`.
    @param[in] study_dir Argument passed to `_resolve_submission_target()`.
    @return Value returned by `_resolve_submission_target()`.
    """
    has_run_dir = bool(run_dir)
    has_study_dir = bool(study_dir)
    if has_run_dir == has_study_dir:
        fail_cli_usage("submit requires exactly one of --run-dir or --study-dir.")
 
    target_kind = "run" if has_run_dir else "study"
    target_key = "run_dir" if target_kind == "run" else "study_dir"
    root_dir = os.path.abspath(run_dir if has_run_dir else study_dir)
    if not os.path.isdir(root_dir):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key=target_key,
            file_path=root_dir,
            message=f"{'Run' if target_kind == 'run' else 'Study'} directory not found.",
        )
        sys.exit(1)
 
    scheduler_dir = os.path.join(root_dir, "scheduler")
    submission_path = os.path.join(scheduler_dir, "submission.json")
    continuation = False
    if target_kind == "study":
        # `sweep --continue` stages its scripts in a set of their own; the set staged
        # last is the one to submit.
        continue_path = os.path.join(scheduler_dir, "submission_continue.json")
        if os.path.isfile(continue_path) and (
                not os.path.isfile(submission_path)
                or os.path.getmtime(continue_path) >= os.path.getmtime(submission_path)):
            submission_path, continuation = continue_path, True
    submission_meta = _read_json_if_exists(submission_path)
    if not isinstance(submission_meta, dict):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="scheduler.submission",
            file_path=submission_path,
            message="Target directory does not contain scheduler submission metadata.",
            hint="Use a Slurm-staged run/study directory with scheduler/submission.json, or submit the script manually.",
        )
        sys.exit(1)
 
    launch_mode = str(submission_meta.get("launch_mode", "")).lower()
    if launch_mode == "local" and target_kind != "run":
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="scheduler.launch_mode",
            file_path=submission_path,
            message="Local staged submission is supported for run directories only.",
            hint="Use --run-dir for local staged execution; study submit remains Slurm-only.",
        )
        sys.exit(1)
    if launch_mode not in {"slurm", "local"}:
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="scheduler.launch_mode",
            file_path=submission_path,
            message=f"Target launch_mode={launch_mode or 'unknown'} is not supported.",
            hint="Use a staged run/study directory with launch_mode 'slurm' or a run directory with launch_mode 'local'.",
        )
        sys.exit(1)
 
    if target_kind == "run":
        script_map = {
            "solve": os.path.join(scheduler_dir, "solver.sbatch"),
            "post-process": os.path.join(scheduler_dir, "post.sbatch"),
        }
        display_label = "Run directory"
        manifest_path = None
    else:
        stage_keys = ({"solve": "solver_continue_array", "post-process": "post_continue_array",
                       "metrics": "metrics_aggregate"} if continuation else
                      {"solve": "solver_array", "post-process": "post_array",
                       "metrics": "metrics_aggregate"})
        default_scripts = ({"solve": "solver_continue_array.sbatch", "post-process": "post_continue_array.sbatch",
                            "metrics": "metrics_continue_aggregate.sbatch"} if continuation else
                           {"solve": "solver_array.sbatch", "post-process": "post_array.sbatch",
                            "metrics": "metrics_aggregate.sbatch"})
        script_map = {
            stage: ((submission_meta.get(key) or {}).get("script")
                    or os.path.join(scheduler_dir, default_scripts[stage]))
            for stage, key in stage_keys.items()
        }
        display_label = "Study continuation" if continuation else "Study directory"
        manifest_path = os.path.join(root_dir, "study_manifest.json")
 
    return {
        "target_kind": target_kind,
        "target_key": target_key,
        "root_dir": root_dir,
        "scheduler_dir": scheduler_dir,
        "submission_path": submission_path,
        "submission_meta": submission_meta,
        "launch_mode": launch_mode,
        "script_map": script_map,
        "display_label": display_label,
        "manifest_path": manifest_path,
        "continuation": continuation,
        "stage_keys": stage_keys if target_kind == "study" else None,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_get_submission_stage_metadata()

dict picurv_cli.core._get_submission_stage_metadata ( dict  target_context, str  stage_name  )

protected

Return stored metadata for one staged submission target.

Parameters

[in]	target_context	Argument passed to _get_submission_stage_metadata().
[in]	stage_name	Argument passed to _get_submission_stage_metadata().

Returns

Value returned by _get_submission_stage_metadata().

Definition at line 25513 of file core.py.

def _get_submission_stage_metadata(target_context: dict, stage_name: str) -> dict:
    """!
    @brief Return stored metadata for one staged submission target.
    @param[in] target_context Argument passed to `_get_submission_stage_metadata()`.
    @param[in] stage_name Argument passed to `_get_submission_stage_metadata()`.
    @return Value returned by `_get_submission_stage_metadata()`.
    """
    submission_meta = target_context["submission_meta"]
    if target_context["target_kind"] == "run":
        stages = submission_meta.get("stages", {})
        if not isinstance(stages, dict):
            return {}
        stage_meta = stages.get(stage_name)
        return copy.deepcopy(stage_meta) if isinstance(stage_meta, dict) else {}
 
    stage_meta = submission_meta.get(target_context["stage_keys"][stage_name])
    return copy.deepcopy(stage_meta) if isinstance(stage_meta, dict) else {}
 
 

Here is the caller graph for this function:

_get_recorded_submission_stages()

list picurv_cli.core._get_recorded_submission_stages ( dict  target_context )

protected

Return stage names explicitly recorded in scheduler submission metadata.

Parameters

[in]

target_context

Argument passed to _get_recorded_submission_stages().

Returns

Value returned by _get_recorded_submission_stages().

Definition at line 25532 of file core.py.

def _get_recorded_submission_stages(target_context: dict) -> list:
    """!
    @brief Return stage names explicitly recorded in scheduler submission metadata.
    @param[in] target_context Argument passed to `_get_recorded_submission_stages()`.
    @return Value returned by `_get_recorded_submission_stages()`.
    """
    submission_meta = target_context["submission_meta"]
    recorded = []
    if target_context["target_kind"] == "run":
        stages = submission_meta.get("stages", {})
        if isinstance(stages, dict):
            for stage_name in ["solve", "post-process"]:
                if isinstance(stages.get(stage_name), dict):
                    recorded.append(stage_name)
        return recorded
 
    for stage_name in ("solve", "post-process"):
        if isinstance(submission_meta.get(target_context["stage_keys"][stage_name]), dict):
            recorded.append(stage_name)
    return recorded
 
 

Here is the caller graph for this function:

_build_submit_missing_stage_hint()

str picurv_cli.core._build_submit_missing_stage_hint ( dict  target_context, str  requested_stage, list  selected_stages  )

protected

Build an actionable hint for requested submit stages missing from metadata.

Parameters

[in]	target_context	Argument passed to _build_submit_missing_stage_hint().
[in]	requested_stage	Argument passed to _build_submit_missing_stage_hint().
[in]	selected_stages	Argument passed to _build_submit_missing_stage_hint().

Returns

Value returned by _build_submit_missing_stage_hint().

Definition at line 25554 of file core.py.

def _build_submit_missing_stage_hint(target_context: dict, requested_stage: str, selected_stages: list) -> str:
    """!
    @brief Build an actionable hint for requested submit stages missing from metadata.
    @param[in] target_context Argument passed to `_build_submit_missing_stage_hint()`.
    @param[in] requested_stage Argument passed to `_build_submit_missing_stage_hint()`.
    @param[in] selected_stages Argument passed to `_build_submit_missing_stage_hint()`.
    @return Value returned by `_build_submit_missing_stage_hint()`.
    """
    recorded_stages = _get_recorded_submission_stages(target_context)
    recorded_set = set(recorded_stages)
    selected_set = set(selected_stages)
    solve_stage_command = (
        "picurv run --solve ... --no-submit"
        if target_context["target_kind"] == "run"
        else "picurv sweep --cluster <cluster.yml> ... --no-submit"
    )
    post_stage_command = (
        "picurv run --post-process --post <post.yml> ... --no-submit"
        if target_context["target_kind"] == "run"
        else "picurv sweep --cluster <cluster.yml> ... --no-submit"
    )
    solve_post_command = (
        "picurv run --solve --post-process --post <post.yml> ... --no-submit"
        if target_context["target_kind"] == "run"
        else "picurv sweep --cluster <cluster.yml> ... --no-submit"
    )
 
    if requested_stage == "all" and not recorded_set:
        return (
            "--stage all submits every staged stage, but submission metadata records none. "
            f"Re-stage with `{solve_stage_command}` or `{post_stage_command}`."
        )
 
    if selected_set == {"solve"} and "solve" not in recorded_set:
        return (
            "The solve stage was requested, but submission metadata does not record a staged solve command/script. "
            f"Re-stage with `{solve_stage_command}`."
        )
    if selected_set == {"post-process"} and "post-process" not in recorded_set:
        return (
            "The post-process stage was requested, but submission metadata does not record a staged post-process command/script. "
            f"Re-stage with post-processing enabled (`{post_stage_command}`, or `{solve_post_command}`)."
        )
 
    return "Re-stage the requested stage(s) with picurv run/sweep --no-submit before calling picurv submit."
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_set_submission_stage_metadata()

picurv_cli.core._set_submission_stage_metadata ( dict  target_context, str  stage_name, dict  stage_meta  )

protected

Persist one stage's metadata back into the submission payload.

Parameters

[in]	target_context	Argument passed to _set_submission_stage_metadata().
[in]	stage_name	Argument passed to _set_submission_stage_metadata().
[in]	stage_meta	Argument passed to _set_submission_stage_metadata().

Definition at line 25601 of file core.py.

def _set_submission_stage_metadata(target_context: dict, stage_name: str, stage_meta: dict):
    """!
    @brief Persist one stage's metadata back into the submission payload.
    @param[in] target_context Argument passed to `_set_submission_stage_metadata()`.
    @param[in] stage_name Argument passed to `_set_submission_stage_metadata()`.
    @param[in] stage_meta Argument passed to `_set_submission_stage_metadata()`.
    """
    submission_meta = target_context["submission_meta"]
    if target_context["target_kind"] == "run":
        stages = submission_meta.get("stages")
        if not isinstance(stages, dict):
            stages = {}
            submission_meta["stages"] = stages
        stages[stage_name] = stage_meta
        return
 
    submission_meta[target_context["stage_keys"][stage_name]] = stage_meta
 
 

Here is the caller graph for this function:

_write_submission_target_metadata()

picurv_cli.core._write_submission_target_metadata ( dict  target_context )

protected

Write updated submission metadata back to disk.

Parameters

[in]

target_context

Argument passed to _write_submission_target_metadata().

Definition at line 25620 of file core.py.

def _write_submission_target_metadata(target_context: dict):
    """!
    @brief Write updated submission metadata back to disk.
    @param[in] target_context Argument passed to `_write_submission_target_metadata()`.
    """
    write_json_file(target_context["submission_path"], target_context["submission_meta"])
 
    manifest_path = target_context.get("manifest_path")
    if manifest_path and os.path.isfile(manifest_path):
        manifest_payload = _read_json_if_exists(manifest_path)
        if isinstance(manifest_payload, dict):
            if target_context.get("continuation"):
                manifest_payload.setdefault("continuation", {})["submission"] = target_context["submission_meta"]
            else:
                manifest_payload["submission"] = target_context["submission_meta"]
            write_json_file(manifest_path, manifest_payload)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

staged_control_directories()

tuple picurv_cli.core.staged_control_directories

(

str

control_path

)

Read run-owned directory values from a staged control file.

Tokenizes with shlex because PETSc's options-file parser treats a double-quoted span as a single token. Splitting on whitespace would read -log_dir "/tmp/VICTIM DIR" as the value "/tmp/VICTIM, which looks relative and contained while PETSc would use the absolute path.

Malformed quoting is reported rather than skipped: a line the parser cannot interpret is exactly the case where preflight must not assume the run is safe.

Parameters

[in]

control_path

Path to a generated .control file.

Returns

Tuple of (values, parse_errors).

Definition at line 25638 of file core.py.

def staged_control_directories(control_path: str) -> tuple:
    """!
    @brief Read run-owned directory values from a staged control file.
 
    @details Tokenizes with `shlex` because PETSc's options-file parser treats a
             double-quoted span as a single token. Splitting on whitespace would read
             `-log_dir "/tmp/VICTIM DIR"` as the value `"/tmp/VICTIM`, which looks
             relative and contained while PETSc would use the absolute path.
 
             Malformed quoting is reported rather than skipped: a line the parser
             cannot interpret is exactly the case where preflight must not assume the
             run is safe.
    @param[in] control_path Path to a generated `.control` file.
    @return Tuple of (values, parse_errors).
    """
    flag_to_key = {
        "-log_dir": "log",
        "-output_dir": "output",
        "-restart_dir": "restart",
        "-analysis_dir": "analysis",
    }
    values: dict = {}
    parse_errors: list = []
    try:
        lines = read_text_file_lines(control_path)
    except OSError as exc:
        return values, [f"could not be read ({exc})"]
    for number, line in enumerate(lines, start=1):
        if not line.strip():
            continue
        try:
            tokens = shlex.split(line, comments=True)
        except ValueError as exc:
            parse_errors.append(
                f"line {number} has malformed quoting and cannot be interpreted ({exc}); "
                f"refusing to assume it is safe"
            )
            continue
        if tokens and tokens[0] in RESERVED_INDIRECTION_FLAGS:
            parse_errors.append(
                f"line {number} uses '{tokens[0]}', which PETSc expands itself; its contents "
                f"cannot be checked here and could set a run directory. Re-stage without it"
            )
            continue
        if len(tokens) >= 2 and tokens[0] in flag_to_key:
            values[flag_to_key[tokens[0]]] = tokens[1]
    return values, parse_errors
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

preflight_config_directories()

list picurv_cli.core.preflight_config_directories

(

str

root_dir

)

Every config directory under a run or study root that may hold a control file.

A study keeps its controls under cases/<member>/config, not at the study root, so a preflight that only looked at <root>/config was empty for every study. This walks the tree so members and nested runs are covered.

Parameters

[in]

root_dir

Run or study directory.

Returns

Sorted config directory paths.

Definition at line 25687 of file core.py.

def preflight_config_directories(root_dir: str) -> list:
    """!
    @brief Every config directory under a run or study root that may hold a control file.
 
    @details A study keeps its controls under `cases/<member>/config`, not at the study
             root, so a preflight that only looked at `<root>/config` was empty for every
             study. This walks the tree so members and nested runs are covered.
    @param[in] root_dir Run or study directory.
    @return Sorted config directory paths.
    """
    found: set = set()
    root = os.path.abspath(root_dir)
    direct = os.path.join(root, "config")
    if os.path.isdir(direct):
        found.add(direct)
    for current, dirnames, _ in os.walk(root):
        dirnames[:] = [d for d in dirnames if not os.path.islink(os.path.join(current, d))]
        if os.path.basename(current) == "config" and glob.glob(os.path.join(current, "*.control")):
            found.add(current)
    return sorted(found)
 
 

Here is the caller graph for this function:

preflight_staged_run_directories()

tuple picurv_cli.core.preflight_staged_run_directories

(

str

root_dir

)

Re-check run-directory safety against an already-staged run or study.

Staging validates the configuration it is given, but a staged run can be edited, or produced by an older version, before submission. This re-reads the effective staged control files - across study members and nested runs - and applies the same rules as configuration validation, plus a physical containment check that a symlink cannot slip past.

Parameters

[in]

root_dir

Run or study directory being submitted.

Returns

Tuple of (errors, warnings).

Definition at line 25709 of file core.py.

def preflight_staged_run_directories(root_dir: str) -> tuple:
    """!
    @brief Re-check run-directory safety against an already-staged run or study.
 
    @details Staging validates the configuration it is given, but a staged run can be
             edited, or produced by an older version, before submission. This re-reads the
             effective staged control files - across study members and nested runs - and
             applies the same rules as configuration validation, plus a physical
             containment check that a symlink cannot slip past.
    @param[in] root_dir Run or study directory being submitted.
    @return Tuple of (errors, warnings).
    """
    errors: list = []
    warnings: list = []
    config_dirs = preflight_config_directories(root_dir)
    if not config_dirs:
        return errors, warnings
    canonical = {
        "log": CANONICAL_RUN_PATHS["logs"],
        "output": CANONICAL_RUN_PATHS["output"],
        "restart": CANONICAL_RUN_PATHS["restart"],
        "analysis": CANONICAL_RUN_PATHS["metrics"],
    }
    for config_dir in config_dirs:
        run_root = os.path.dirname(config_dir)
        for control in sorted(glob.glob(os.path.join(config_dir, "*.control"))):
            staged, parse_errors = staged_control_directories(control)
            label = os.path.relpath(control)
            errors.extend(f"  {label}: {message}" for message in parse_errors)
            if not staged:
                continue
            for key, expected in canonical.items():
                actual = staged.get(key)
                if actual is not None and normalized_run_directory(actual) != expected:
                    errors.append(
                        f"  {label}: -{key}_dir is {actual!r}; the canonical value is "
                        f"{expected!r}. Re-stage the run instead of editing its path flags."
                    )
            effective = effective_run_directories(staged)
            control_errors, control_warnings = evaluate_run_directories(
                effective, False, explicit=set(staged)
            )
            errors.extend(f"  {label}: {message}" for message in control_errors)
            warnings.extend(f"  {label}: {message}" for message in control_warnings)
            for _, verdict, message in classify_physical_containment(run_root, effective):
                errors.append(f"  {label}: {message}")
    return errors, warnings
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

read_text_file_lines()

list picurv_cli.core.read_text_file_lines

(

str

path

)

Read a text file into a list of lines.

Parameters

[in]

path

File to read.

Returns

List of lines.

Definition at line 25758 of file core.py.

def read_text_file_lines(path: str) -> list:
    """!
    @brief Read a text file into a list of lines.
    @param[in] path File to read.
    @return List of lines.
    """
    with open(path, "r", encoding="utf-8", errors="replace") as handle:
        return handle.readlines()
 
 

Here is the caller graph for this function:

submit_staged_jobs()

picurv_cli.core.submit_staged_jobs

(

args

)

Submit previously staged Slurm artifacts from an existing run/study directory.

Parameters

[in]

args

Command-line style argument list supplied to the function.

Definition at line 25768 of file core.py.

def submit_staged_jobs(args):
    """!
    @brief Submit previously staged Slurm artifacts from an existing run/study directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    if getattr(args, "run_dir", None) and os.path.isdir(args.run_dir):
        adopt_relocated_artifact(args.run_dir)
    elif getattr(args, "study_dir", None) and os.path.isdir(args.study_dir):
        adopt_relocated_artifact(args.study_dir, kind="study")
    target_context = _resolve_submission_target(
        run_dir=getattr(args, "run_dir", None),
        study_dir=getattr(args, "study_dir", None),
    )
    try:
        require_storage_payload_local(target_context["root_dir"], "submission")
    except StorageError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
    preflight_errors, preflight_warnings = preflight_staged_run_directories(
        target_context["root_dir"]
    )
    for warning in preflight_warnings:
        print(f"[WARNING] {warning.strip()}", file=sys.stderr)
    if preflight_errors:
        print(
            "[FATAL] Submission preflight failed: the staged run has an unsafe run-directory "
            "configuration.",
            file=sys.stderr,
        )
        for violation in preflight_errors:
            print(violation, file=sys.stderr)
        print(
            "  Re-stage the run so PICurv regenerates its canonical path flags.",
            file=sys.stderr,
        )
        sys.exit(1)
    if target_context["target_kind"] == "study":
        cold_cases = cold_study_members(target_context["root_dir"])
        if cold_cases:
            print(
                "[FATAL] Submission requires cold-storage study member(s): " + ", ".join(cold_cases),
                file=sys.stderr,
            )
            sys.exit(1)
    stage_order = ["solve", "post-process"]
    requested_stage = args.stage
    # `all` is every staged stage not yet submitted; when each was, every staged stage, so the
    # refusal names them; with none staged, both, so the error says how to stage one.
    recorded_stages = _get_recorded_submission_stages(target_context)
    pending_stages = [stage for stage in recorded_stages
                      if not _get_submission_stage_metadata(target_context, stage).get("submitted")]
    selected_stages = ([requested_stage] if requested_stage != "all"
                       else pending_stages or recorded_stages or stage_order)
 
    print(f"[INFO] {target_context['display_label']:<20}: {os.path.relpath(target_context['root_dir'])}")
    print(f"[INFO] Submission metadata : {os.path.relpath(target_context['submission_path'])}")
    print(f"[INFO] Requested stages    : {', '.join(selected_stages)}")
 
    if target_context.get("launch_mode") == "local":
        submit_staged_local_run(args, target_context, selected_stages)
        return
 
    stage_plans = []
    solve_existing_meta = _get_submission_stage_metadata(target_context, "solve")
    solve_existing_job_id = str(solve_existing_meta.get("job_id", "")).strip()
 
    for stage_name in selected_stages:
        existing_meta = _get_submission_stage_metadata(target_context, stage_name)
        script_path = target_context["script_map"][stage_name]
        missing_stage_hint = _build_submit_missing_stage_hint(target_context, requested_stage, selected_stages)
        if not existing_meta:
            emit_structured_error(
                ERROR_CODE_CFG_MISSING_KEY,
                key=f"scheduler.{stage_name}.metadata",
                file_path=target_context["submission_path"],
                message=f"Submission metadata does not record stage '{stage_name}'.",
                hint=missing_stage_hint,
            )
            sys.exit(1)
 
        if not os.path.isfile(script_path):
            emit_structured_error(
                ERROR_CODE_CFG_FILE_NOT_FOUND,
                key=f"scheduler.{stage_name}.script",
                file_path=script_path,
                message=f"Required {stage_name} sbatch artifact is missing.",
                hint=missing_stage_hint,
            )
            sys.exit(1)
 
        if existing_meta.get("submitted") and not args.force:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key=f"scheduler.{stage_name}.submitted",
                file_path=target_context["submission_path"],
                message=f"Stage '{stage_name}' is already recorded as submitted.",
                hint="Use --force to resubmit this stage intentionally.",
            )
            sys.exit(1)
 
        dependency = None
        if stage_name == "post-process":
            if "solve" in selected_stages:
                dependency = "__NEW_SOLVE_JOB_ID__"
            elif solve_existing_meta.get("submitted") and solve_existing_job_id:
                dependency = solve_existing_job_id
                end, state = slurm_job_end_state(solve_existing_job_id)
                if end == "completed":
                    # Slurm rejects a dependency on a job it has forgotten, and the post
                    # job plans from committed checkpoints when it starts, so a solve that
                    # already succeeded leaves nothing to wait for.
                    print(f"[INFO] Solve job {solve_existing_job_id} has completed; the post job is "
                          "submitted without a dependency.")
                    dependency = None
                elif end == "failed" and not args.force:
                    emit_structured_error(
                        ERROR_CODE_CFG_INCONSISTENT_COMBO,
                        key="scheduler.post-process.dependency",
                        file_path=target_context["submission_path"],
                        message=f"Solve job {solve_existing_job_id} ended {state}, so a post job waiting on its success would never start.",
                        hint="Resubmit the solve, or use --force to post-process the checkpoints it committed.",
                    )
                    sys.exit(1)
                elif end != "active" and end != "unchecked":
                    # Failed with --force, or ended in a state sacct cannot report.
                    print(f"[WARNING] Solve job {solve_existing_job_id} is no longer queued "
                          f"({state or 'end state unavailable from sacct'}); the post job is submitted "
                          "without a dependency and processes what was committed.", file=sys.stderr)
                    dependency = None
            elif solve_existing_meta and not args.force:
                # A post staged on its own has no solve to wait for: it reads a run solved
                # earlier and plans its steps from what is committed when it starts.
                emit_structured_error(
                    ERROR_CODE_CFG_INCONSISTENT_COMBO,
                    key="scheduler.post-process.dependency",
                    file_path=target_context["submission_path"],
                    message="This run's staged solve has not been submitted, so its post-process job would have nothing to read.",
                    hint="Submit --stage solve or --stage all first, or use --force to submit the post job without a dependency.",
                )
                sys.exit(1)
 
        stage_plans.append(
            {
                "stage": stage_name,
                "script": script_path,
                "dependency": dependency,
                "existing_meta": existing_meta,
            }
        )
 
    # A study aggregates its metrics after its post array, as `sweep` chains it, whether
    # or not every member succeeded.
    if target_context["target_kind"] == "study" and "post-process" in selected_stages:
        metrics_meta = _get_submission_stage_metadata(target_context, "metrics")
        metrics_script = target_context["script_map"]["metrics"]
        if metrics_meta and os.path.isfile(metrics_script) and (not metrics_meta.get("submitted") or args.force):
            stage_plans.append({
                "stage": "metrics",
                "script": metrics_script,
                "dependency": "__NEW_POST_JOB_ID__",
                "dependency_type": "afterany",
                "existing_meta": metrics_meta,
            })
 
    if args.dry_run:
        for plan in stage_plans:
            cmd = ["sbatch"]
            dependency = plan["dependency"]
            dependency_type = plan.get("dependency_type", "afterok")
            if dependency == "__NEW_SOLVE_JOB_ID__":
                cmd.append("--dependency=afterok:<new solve job id>")
            elif dependency == "__NEW_POST_JOB_ID__":
                cmd.append(f"--dependency={dependency_type}:<new post job id>")
            elif dependency:
                cmd.append(f"--dependency={dependency_type}:{dependency}")
            cmd.append(plan["script"])
            print(f"[DRY-RUN] Would run: {' '.join(cmd)}")
        print("[INFO] Dry-run only. No jobs were submitted.")
        return
 
    new_job_ids = {}
    for plan in stage_plans:
        dependency = plan["dependency"]
        dependency_type = plan.get("dependency_type", "afterok")
        if dependency == "__NEW_SOLVE_JOB_ID__":
            dependency = new_job_ids.get("solve")
        elif dependency == "__NEW_POST_JOB_ID__":
            dependency = new_job_ids.get("post-process")
 
        submit_info = submit_sbatch(plan["script"], dependency=dependency, dependency_type=dependency_type)
        stage_meta = copy.deepcopy(plan["existing_meta"])
        stage_meta.update(submit_info)
        stage_meta["script"] = plan["script"]
        stage_meta["submitted"] = True
        if dependency:
            stage_meta["dependency"] = f"{dependency_type}:{dependency}"
        else:
            stage_meta.pop("dependency", None)
 
        _set_submission_stage_metadata(target_context, plan["stage"], stage_meta)
        print(f"[SUCCESS] Submitted {plan['stage']} job: {submit_info['job_id']}")
        new_job_ids[plan["stage"]] = submit_info["job_id"]
 
    _write_submission_target_metadata(target_context)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

submit_staged_local_run()

picurv_cli.core.submit_staged_local_run	(		args,
		dict	target_context,
		list	selected_stages
	)

Execute previously staged local run commands from scheduler/submission.json.

Parameters

[in]	args	Command-line style argument list supplied to the function.
[in]	target_context	Resolved submission target context.
[in]	selected_stages	Ordered stage names selected by the user.

Definition at line 25974 of file core.py.

def submit_staged_local_run(args, target_context: dict, selected_stages: list):
    """!
    @brief Execute previously staged local run commands from scheduler/submission.json.
    @param[in] args Command-line style argument list supplied to the function.
    @param[in] target_context Resolved submission target context.
    @param[in] selected_stages Ordered stage names selected by the user.
    """
    if target_context["target_kind"] != "run":
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="scheduler.launch_mode",
            file_path=target_context["submission_path"],
            message="Local staged execution is supported for run directories only.",
            hint="Use --run-dir for local staged execution.",
        )
        sys.exit(1)
 
    stage_plans = []
    solve_existing_meta = _get_submission_stage_metadata(target_context, "solve")
    # Only a solve staged in this same set can still be pending; a post staged on its own
    # reads a run solved earlier and plans its steps from what is committed when it starts.
    solve_pending = bool(solve_existing_meta) and not bool(
        solve_existing_meta.get("submitted") or solve_existing_meta.get("executed"))
 
    for stage_name in selected_stages:
        existing_meta = _get_submission_stage_metadata(target_context, stage_name)
        command = existing_meta.get("command")
        if not isinstance(command, list) or not command:
            if existing_meta:
                hint = "Re-stage the run with picurv run --no-submit before calling picurv submit."
            else:
                hint = _build_submit_missing_stage_hint(target_context, args.stage, selected_stages)
            emit_structured_error(
                ERROR_CODE_CFG_MISSING_KEY,
                key=f"scheduler.{stage_name}.command",
                file_path=target_context["submission_path"],
                message=f"Required local command metadata for stage '{stage_name}' is missing.",
                hint=hint,
            )
            sys.exit(1)
 
        if existing_meta.get("submitted") and not args.force:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key=f"scheduler.{stage_name}.submitted",
                file_path=target_context["submission_path"],
                message=f"Stage '{stage_name}' is already recorded as submitted.",
                hint="Use --force to execute this stage again intentionally.",
            )
            sys.exit(1)
 
        if stage_name == "post-process" and "solve" not in selected_stages and not args.force and solve_pending:
            emit_structured_error(
                ERROR_CODE_CFG_INCONSISTENT_COMBO,
                key="scheduler.post-process.dependency",
                file_path=target_context["submission_path"],
                message="This run's staged solve has not run yet, so its post-process stage has nothing to read.",
                hint="Submit --stage solve or --stage all first, or use --force to run the post stage anyway.",
            )
            sys.exit(1)
 
        log_file = existing_meta.get("log_file")
        if not isinstance(log_file, str) or not log_file.strip():
            log_file = os.path.join("scheduler", f"{os.path.basename(target_context['root_dir'])}_{stage_name}.log")
 
        stage_plans.append(
            {
                "stage": stage_name,
                "command": [str(token) for token in command],
                "log_file": log_file,
                "existing_meta": existing_meta,
            }
        )
 
    if args.dry_run:
        for plan in stage_plans:
            print(f"[DRY-RUN] Would run: {format_command_for_display(plan['command'])}")
            print(f"[DRY-RUN] Log file : {plan['log_file']}")
        print("[INFO] Dry-run only. No local commands were executed.")
        return
 
    monitor_cfg = None
    monitor_path = os.path.join(target_context["root_dir"], "config", "monitor.yml")
    if os.path.isfile(monitor_path):
        monitor_cfg = read_yaml_file(monitor_path)
 
    for plan in stage_plans:
        if plan["stage"] == "solve":
            try:
                with runtime_stage_lock(target_context["root_dir"], "solver"):
                    execute_command(plan["command"], target_context["root_dir"], plan["log_file"], monitor_cfg)
            except StorageError as exc:
                print(f"[FATAL] {exc}", file=sys.stderr)
                sys.exit(1)
        else:
            execute_command(plan["command"], target_context["root_dir"], plan["log_file"], monitor_cfg)
        stage_meta = copy.deepcopy(plan["existing_meta"])
        stage_meta["command"] = plan["command"]
        stage_meta["command_string"] = format_command_for_display(plan["command"])
        stage_meta["log_file"] = plan["log_file"]
        stage_meta["submitted"] = True
        stage_meta["executed"] = True
        stage_meta["completed_at"] = datetime.now().isoformat()
        _set_submission_stage_metadata(target_context, plan["stage"], stage_meta)
        print(f"[SUCCESS] Executed local {plan['stage']} stage.")
 
    _write_submission_target_metadata(target_context)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

cancel_run_jobs()

picurv_cli.core.cancel_run_jobs

(

args

)

Cancel Slurm-submitted jobs for an existing run directory.

Parameters

[in]

args

Command-line style argument list supplied to the function.

Definition at line 26083 of file core.py.

def cancel_run_jobs(args):
    """!
    @brief Cancel Slurm-submitted jobs for an existing run directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    run_dir = os.path.abspath(args.run_dir)
    if not os.path.isdir(run_dir):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="run_dir",
            file_path=run_dir,
            message="Run directory not found.",
        )
        sys.exit(1)
 
    submission_path = os.path.join(run_dir, "scheduler", "submission.json")
    submission_meta = _read_json_if_exists(submission_path)
    if not isinstance(submission_meta, dict):
        emit_structured_error(
            ERROR_CODE_CFG_FILE_NOT_FOUND,
            key="scheduler.submission",
            file_path=submission_path,
            message="Run directory does not contain scheduler submission metadata.",
            hint="Use a Slurm-submitted run directory with scheduler/submission.json, or cancel the job manually.",
        )
        sys.exit(1)
 
    launch_mode = str(submission_meta.get("launch_mode", "")).lower()
    if launch_mode != "slurm":
        emit_structured_error(
            ERROR_CODE_CFG_INCONSISTENT_COMBO,
            key="scheduler.launch_mode",
            file_path=submission_path,
            message=f"Run directory launch_mode={launch_mode or 'unknown'} is not Slurm.",
            hint="picurv cancel currently supports Slurm-submitted runs only.",
        )
        sys.exit(1)
 
    stage_order = ["solve", "post-process"]
    requested_stage = args.stage
    selected_stages = stage_order if requested_stage == "all" else [requested_stage]
    recorded_stages = submission_meta.get("stages", {})
    if not isinstance(recorded_stages, dict):
        recorded_stages = {}
 
    job_to_stages = {}
    skipped = []
    for stage_name in selected_stages:
        stage_meta = recorded_stages.get(stage_name)
        if not isinstance(stage_meta, dict):
            skipped.append((stage_name, "no stage metadata recorded"))
            continue
 
        job_id = str(stage_meta.get("job_id", "")).strip()
        if not stage_meta.get("submitted"):
            skipped.append((stage_name, "job was generated but not submitted"))
            continue
        if not job_id:
            skipped.append((stage_name, "submitted stage is missing a recorded job id"))
            continue
 
        job_to_stages.setdefault(job_id, []).append(stage_name)
 
    if not job_to_stages:
        print(f"[INFO] Run directory       : {os.path.relpath(run_dir)}")
        print(f"[INFO] Submission metadata : {os.path.relpath(submission_path)}")
        for stage_name, reason in skipped:
            print(f"[INFO] Skipping stage '{stage_name}': {reason}")
        print("[FATAL] No submitted Slurm job IDs were found for the requested stage selection.", file=sys.stderr)
        sys.exit(1)
 
    print(f"[INFO] Run directory       : {os.path.relpath(run_dir)}")
    print(f"[INFO] Submission metadata : {os.path.relpath(submission_path)}")
    print(f"[INFO] Requested stages    : {', '.join(selected_stages)}")
 
    if skipped:
        for stage_name, reason in skipped:
            print(f"[INFO] Skipping stage '{stage_name}': {reason}")
 
    graceful = bool(getattr(args, "graceful", False))
    failures = []
    for job_id, stage_names in job_to_stages.items():
        joined_stage_names = ", ".join(stage_names)
        use_graceful_signal = graceful and "solve" in stage_names
        scancel_cmd = ["scancel"]
        if use_graceful_signal:
            # A directly launched ``mpirun`` replaces the batch shell (via ``exec``)
            # and is therefore not necessarily a Slurm job step.  ``--full`` also
            # signals the batch process and its children, so the MPI launcher can
            # forward SIGUSR1 to the solver ranks.
            scancel_cmd.extend(["--signal=USR1", "--full"])
        scancel_cmd.append(job_id)
 
        if args.dry_run:
            print(f"[DRY-RUN] Would run: {' '.join(scancel_cmd)}  # stage(s): {joined_stage_names}")
            continue
 
        # scancel exits 0 for a job that already ended, so ask Slurm before claiming a cancel.
        status, end_state = slurm_job_end_state(job_id)
        # Every status but "active" with a recorded end state is a job Slurm has finished.
        if end_state and status != "active":
            print(f"[INFO] Slurm job {job_id} for stage(s) {joined_stage_names} already ended "
                  f"({end_state}); nothing to cancel.")
            continue
 
        result = subprocess.run(scancel_cmd, text=True, capture_output=True, check=False)
        stderr_text = (result.stderr or "").strip()
        stdout_text = (result.stdout or "").strip()
        if result.returncode == 0:
            if use_graceful_signal:
                print(
                    f"[SUCCESS] Requested graceful shutdown for Slurm job {job_id} for stage(s): {joined_stage_names}. "
                    "Solver jobs trap SIGUSR1 and write the latest safe off-cadence step at the next checkpoint."
                )
            else:
                print(f"[SUCCESS] Canceled Slurm job {job_id} for stage(s): {joined_stage_names}")
            continue
 
        detail = stderr_text or stdout_text or "unknown scancel failure"
        failures.append((job_id, joined_stage_names, detail, result.returncode))
        print(
            f"[ERROR] Failed to cancel Slurm job {job_id} for stage(s) {joined_stage_names}: {detail}",
            file=sys.stderr,
        )
 
    if args.dry_run:
        print("[INFO] Dry-run only. No jobs were canceled.")
        return
 
    if failures:
        sys.exit(1)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_workspace_yaml_role()

picurv_cli.core._workspace_yaml_role ( str  path )

protected

Infer the owned workspace role of one copied YAML file.

Parameters

[in]

path

YAML file copied from an example template.

Returns

One of case, solver, monitor, post, cluster, study, or None.

Definition at line 26216 of file core.py.

def _workspace_yaml_role(path: str):
    """!
    @brief Infer the owned workspace role of one copied YAML file.
    @param[in] path YAML file copied from an example template.
    @return One of case, solver, monitor, post, cluster, study, or None.
    """
    try:
        payload = read_yaml_file(path)
    except (OSError, ValueError):
        return None
    keys = set(payload)
    if {"grid", "properties", "run_control"} <= keys:
        return "case"
    if "base_configs" in keys and ("study_type" in keys or "parameters" in keys or "parameter_sets" in keys):
        return "study"
    if "scheduler" in keys and "resources" in keys:
        return "cluster"
    # Any key only a post recipe owns; a spectra- or statistics-only recipe has no
    # pipeline, and source_data is optional. run_control is shared with case.yml.
    post_only = _POST_SCHEMA[()] - _MONITOR_SCHEMA[()] - {"run_control"}
    if keys & post_only or ("run_control" in keys and not keys & _CASE_SCHEMA[()] - {"run_control", "title"}):
        return "post"
    if "io" in keys and ("logging" in keys or "profiling" in keys or "diagnostics" in keys):
        return "monitor"
    if "momentum_solver" in keys or "poisson_solver" in keys or "operation_mode" in keys:
        return "solver"
    return None
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_rewrite_workspace_path_values()

picurv_cli.core._rewrite_workspace_path_values (   value, dict  replacements  )

protected

Rewrite copied template path scalars to workspace-root-relative homes.

Parameters

[in]	value	YAML subtree to rewrite.
[in]	replacements	Old relative/basename paths mapped to new workspace paths.

Returns

Rewritten YAML subtree.

Definition at line 26245 of file core.py.

def _rewrite_workspace_path_values(value, replacements: dict):
    """!
    @brief Rewrite copied template path scalars to workspace-root-relative homes.
    @param[in] value YAML subtree to rewrite.
    @param[in] replacements Old relative/basename paths mapped to new workspace paths.
    @return Rewritten YAML subtree.
    """
    if isinstance(value, dict):
        return {key: _rewrite_workspace_path_values(item, replacements) for key, item in value.items()}
    if isinstance(value, list):
        return [_rewrite_workspace_path_values(item, replacements) for item in value]
    if not isinstance(value, str):
        return value
    normalized = value.replace("\\", "/").lstrip("./")
    return replacements.get(normalized, replacements.get(os.path.basename(normalized), value))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_choose_primary_workspace_role()

picurv_cli.core._choose_primary_workspace_role ( list  candidates, str  role, str  template_name  )

protected

Select the canonical role file from a template that may carry variants.

Parameters

[in]	candidates	Candidate absolute YAML paths.
[in]	role	Config role being selected.
[in]	template_name	Source example directory name.

Returns

Selected absolute path or None.

Definition at line 26262 of file core.py.

def _choose_primary_workspace_role(candidates: list, role: str, template_name: str):
    """!
    @brief Select the canonical role file from a template that may carry variants.
    @param[in] candidates Candidate absolute YAML paths.
    @param[in] role Config role being selected.
    @param[in] template_name Source example directory name.
    @return Selected absolute path or None.
    """
    if not candidates:
        return None
    preferred = {
        "case": ("case.yml", f"{template_name}.yml", "master_case.yml"),
        "solver": ("solver.yml", "Imp-MG-Standard.yml", "master_solver.yml"),
        "monitor": ("monitor.yml", "Standard_Output.yml", "master_monitor.yml"),
        "post": ("post.yml", "standard_analysis.yml", "master_postprocessor.yml"),
        "cluster": ("cluster.yml", "slurm_cluster.yml", "master_cluster.yml"),
    }.get(role, ())
    by_name = {os.path.basename(path): path for path in candidates}
    for name in preferred:
        if name in by_name:
            return by_name[name]
    return sorted(candidates)[0]
 
 

Here is the caller graph for this function:

organize_initialized_workspace()

dict picurv_cli.core.organize_initialized_workspace	(	str	workspace_root,
		str	template_name,
		str	source_template_root = None
	)

Convert a copied example into the canonical editable workspace layout.

Parameters

[in]	workspace_root	Newly copied workspace root.
[in]	template_name	Example template identity.
[in]	source_template_root	Optional original template root used to vendor references.

Returns

Mapping of canonical config roles and relocated imported inputs.

Definition at line 26286 of file core.py.

                                   source_template_root: str = None) -> dict:
    """!
    @brief Convert a copied example into the canonical editable workspace layout.
    @param[in] workspace_root Newly copied workspace root.
    @param[in] template_name Example template identity.
    @param[in] source_template_root Optional original template root used to vendor references.
    @return Mapping of canonical config roles and relocated imported inputs.
    """
    workspace_root = os.path.abspath(workspace_root)
    ensure_workspace_layout(workspace_root)
    # Skip the workspace's own runs/ and studies/ trees, judged inside the workspace: a
    # workspace that itself sits under a directory named runs/ must still be organized.
    yaml_files = [
        str(path)
        for pattern in ("*.yml", "*.yaml")
        for path in Path(workspace_root).rglob(pattern)
        if path.name not in {RUNTIME_EXECUTION_EXAMPLE_FILENAME, RUNTIME_EXECUTION_CONFIG_FILENAME}
        and not {"runs", "studies"} & set(path.relative_to(workspace_root).parts)
    ]
    vendored_replacements = {}
    if source_template_root:
        source_template_root = os.path.abspath(source_template_root)
 
        def vendor_references(value, source_yaml: str, dotted: str = ""):
            """!
            @brief Vendor referenced generator inputs into canonical workspace homes.
            @param[in] value YAML subtree to inspect.
            @param[in] source_yaml Original template YAML path.
            @param[in] dotted Current dotted key path.
            @return None.
            """
            if isinstance(value, dict):
                for key, child in value.items():
                    vendor_references(child, source_yaml, f"{dotted}.{key}" if dotted else str(key))
                return
            if isinstance(value, list):
                for index, child in enumerate(value):
                    vendor_references(child, source_yaml, f"{dotted}[{index}]")
                return
            key = dotted.rsplit(".", 1)[-1]
            if key not in _VENDORABLE_CONFIG_REFERENCE_KEYS or not isinstance(value, str) or not value.strip():
                return
            origin = os.path.abspath(os.path.join(os.path.dirname(source_yaml), value))
            if not os.path.isfile(origin):
                return
            if key == "script":
                home = "config/generators"
            elif "grid" in dotted:
                home = "config/grids"
            elif "initial_condition" in dotted:
                home = "config/initial_conditions"
            elif "inlet" in dotted or "boundary_conditions" in dotted:
                home = "config/inlet_profiles"
            else:
                home = "config"
            destination = os.path.join(workspace_root, *home.split("/"), os.path.basename(origin))
            os.makedirs(os.path.dirname(destination), exist_ok=True)
            if not os.path.exists(destination):
                shutil.copy2(origin, destination)
            relative = os.path.relpath(destination, workspace_root).replace(os.sep, "/")
            vendored_replacements[value.replace("\\", "/").lstrip("./")] = relative
            vendored_replacements[os.path.basename(value)] = relative
 
        for copied_yaml in sorted(set(yaml_files)):
            relative = os.path.relpath(copied_yaml, workspace_root)
            source_yaml = os.path.join(source_template_root, relative)
            if not os.path.isfile(source_yaml):
                continue
            try:
                vendor_references(read_yaml_file(copied_yaml), source_yaml)
            except (OSError, ValueError):
                continue
    roles = {}
    for path in sorted(set(yaml_files)):
        role = _workspace_yaml_role(path)
        if role:
            roles.setdefault(role, []).append(path)
 
    selected = {
        role: _choose_primary_workspace_role(paths, role, template_name)
        for role, paths in roles.items() if role != "study"
    }
    destinations = {}
    occupied = set()
    for role, paths in roles.items():
        for source in paths:
            if role == "study":
                relative = os.path.join("config", "studies", os.path.basename(source))
            elif source == selected.get(role):
                relative = os.path.join("config", f"{role}.yml")
            else:
                relative = os.path.join("config", os.path.basename(source))
            destination = os.path.join(workspace_root, relative)
            if os.path.abspath(source) == os.path.abspath(destination):
                destinations[source] = relative.replace(os.sep, "/")
                occupied.add(os.path.abspath(destination))
                continue
            if os.path.abspath(destination) in occupied or os.path.exists(destination):
                original_relative = os.path.relpath(source, workspace_root)
                relative = os.path.join("config", "variants", original_relative)
                destination = os.path.join(workspace_root, relative)
                counter = 2
                while os.path.abspath(destination) in occupied or os.path.exists(destination):
                    stem, suffix = os.path.splitext(relative)
                    destination = os.path.join(workspace_root, f"{stem}-{counter}{suffix}")
                    counter += 1
            os.makedirs(os.path.dirname(destination), exist_ok=True)
            shutil.move(source, destination)
            destinations[source] = relative.replace(os.sep, "/")
            occupied.add(os.path.abspath(destination))
 
    input_extensions = {
        ".picgrid": "inputs/grids",
        ".vts": "inputs/grids",
        ".picslice": "inputs/inlet_profiles",
        ".dat": "inputs/initial_conditions",
    }
    input_moves = {}
    for path in sorted(Path(workspace_root).rglob("*")):
        if not path.is_file() or path.suffix.lower() not in input_extensions:
            continue
        if any(part in _WORKSPACE_MANAGED_PATHS for part in path.relative_to(workspace_root).parts):
            continue
        destination_dir = os.path.join(workspace_root, *input_extensions[path.suffix.lower()].split("/"))
        destination = os.path.join(destination_dir, path.name)
        if os.path.exists(destination):
            continue
        old_relative = path.relative_to(workspace_root).as_posix()
        shutil.move(str(path), destination)
        new_relative = os.path.relpath(destination, workspace_root).replace(os.sep, "/")
        input_moves[old_relative] = new_relative
        input_moves[path.name] = new_relative
 
    config_replacements = {}
    basename_counts = {}
    for source in destinations:
        basename = os.path.basename(source)
        basename_counts[basename] = basename_counts.get(basename, 0) + 1
    for source, relative in destinations.items():
        old_relative = os.path.relpath(source, workspace_root).replace(os.sep, "/")
        config_replacements[old_relative] = relative
        if basename_counts[os.path.basename(source)] == 1:
            config_replacements[os.path.basename(source)] = relative
    replacements = {**config_replacements, **input_moves, **vendored_replacements}
    for path in sorted(Path(workspace_root, "config").rglob("*.yml")):
        payload = read_yaml_file(str(path))
        local_replacements = dict(replacements)
        original_source = next(
            (
                source for source, relative in destinations.items()
                if os.path.abspath(os.path.join(workspace_root, relative)) == os.path.abspath(path)
            ),
            None,
        )
        if original_source:
            original_parent = os.path.dirname(original_source)
            for candidate_source, candidate_relative in destinations.items():
                relative_reference = os.path.relpath(candidate_source, original_parent).replace(os.sep, "/")
                local_replacements[relative_reference] = candidate_relative
                if os.path.dirname(candidate_source) == original_parent:
                    local_replacements[os.path.basename(candidate_source)] = candidate_relative
        rewritten = _rewrite_workspace_path_values(payload, local_replacements)
        role = _workspace_yaml_role(str(path))
        if role == "monitor" and isinstance(rewritten.get("io"), dict):
            rewritten["io"].pop("directories", None)
        if role == "case" and path == Path(workspace_root, "config", "case.yml"):
            rewritten.setdefault("title", template_name)
        if role == "post":
            if isinstance(rewritten.get("source_data"), dict):
                rewritten["source_data"].pop("directory", None)
            if isinstance(rewritten.get("io"), dict):
                rewritten["io"].pop("output_directory", None)
        if role == "study" and isinstance(rewritten.get("base_configs"), dict):
            for role in ("case", "solver", "monitor", "post"):
                canonical = os.path.join("config", f"{role}.yml").replace(os.sep, "/")
                if os.path.isfile(os.path.join(workspace_root, canonical)):
                    rewritten["base_configs"][role] = canonical
        write_yaml_file(str(path), rewritten)
 
    return {
        "workspace_config": initialize_workspace_root(workspace_root, template_name),
        "canonical_roles": {
            role: os.path.join(workspace_root, "config", f"{role}.yml")
            for role in ("case", "solver", "monitor", "post", "cluster")
            if os.path.isfile(os.path.join(workspace_root, "config", f"{role}.yml"))
        },
        "input_moves": input_moves,
    }
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

import_workspace_input()

dict picurv_cli.core.import_workspace_input	(	str	workspace_root,
		str	kind,
		str	source,
		str	name = None,
		str	mode = "copy"
	)

Explicitly import or register one workspace input.

Parameters

[in]	workspace_root	Initialized workspace root.
[in]	kind	Semantic input kind.
[in]	source	Existing source file path.
[in]	name	Optional destination basename.
[in]	mode	Copy, reflink, hardlink, or external-reference mode.

Returns

Catalog entry describing the durable input identity.

Definition at line 26485 of file core.py.

                           name: str = None, mode: str = "copy") -> dict:
    """!
    @brief Explicitly import or register one workspace input.
    @param[in] workspace_root Initialized workspace root.
    @param[in] kind Semantic input kind.
    @param[in] source Existing source file path.
    @param[in] name Optional destination basename.
    @param[in] mode Copy, reflink, hardlink, or external-reference mode.
    @return Catalog entry describing the durable input identity.
    """
    workspace_root = os.path.abspath(workspace_root)
    load_workspace_config(workspace_root)
    ensure_workspace_layout(workspace_root)
    if kind not in WORKSPACE_INPUT_DIRECTORIES:
        raise ValueError(f"Unsupported input kind: {kind}")
    source = os.path.abspath(os.path.expanduser(source))
    if not os.path.isfile(source):
        raise ValueError(f"Input source is not a file: {source}")
    basename = name or os.path.basename(source)
    if basename != os.path.basename(basename) or basename in _PLAIN_FILENAME_SENTINELS:
        raise ValueError("--name must be a plain filename without directory traversal.")
    target_dir = os.path.join(workspace_root, *WORKSPACE_INPUT_DIRECTORIES[kind].split("/"))
    os.makedirs(target_dir, exist_ok=True)
    if mode == "reference":
        destination = os.path.join(target_dir, basename + ".reference.yml")
        write_yaml_file(destination, {
            "schema_version": 1,
            "picurv_external_reference": source,
            "sha256_at_registration": _asset_file_sha256(source),
            "bytes_at_registration": os.path.getsize(source),
        })
    else:
        destination = os.path.join(target_dir, basename)
        if os.path.exists(destination):
            raise ValueError(f"Workspace input already exists: {destination}")
        temporary = f"{destination}.tmp.{os.getpid()}"
        try:
            if mode == "copy":
                shutil.copy2(source, temporary)
            elif mode == "hardlink":
                os.link(source, temporary)
            elif mode == "reflink":
                cp = shutil.which("cp")
                if not cp:
                    raise ValueError("reflink mode requires the 'cp' command.")
                result = subprocess.run(
                    [cp, "--reflink=always", "--preserve=mode,timestamps", source, temporary],
                    text=True, capture_output=True, check=False,
                )
                if result.returncode != 0:
                    raise ValueError((result.stderr or "reflink copy failed").strip())
            else:
                raise ValueError(f"Unsupported import mode: {mode}")
            os.replace(temporary, destination)
        finally:
            if os.path.lexists(temporary):
                os.remove(temporary)
    relative = os.path.relpath(destination, workspace_root).replace(os.sep, "/")
    entry_id = _stable_mapping_sha256({"kind": kind, "path": relative, "source": source})[:16]
    catalog_path = os.path.join(workspace_root, "inputs", "catalog.yml")
    catalog = read_yaml_file(catalog_path) if os.path.isfile(catalog_path) else {
        "schema_version": 1, "inputs": {}
    }
    catalog.setdefault("inputs", {})[entry_id] = {
        "kind": kind,
        "path": relative,
        "mode": mode,
        "sha256": _asset_file_sha256(source),
        "bytes": os.path.getsize(source),
        "source": source if mode == "reference" else None,
        "registered_at": datetime.now().astimezone().isoformat(),
    }
    write_yaml_file(catalog_path, catalog)
    return {"id": entry_id, **catalog["inputs"][entry_id]}
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

inputs_workflow()

picurv_cli.core.inputs_workflow

(

args

)

Handle explicit workspace input management.

Parameters

[in]

args

Parsed inputs command arguments.

Returns

None.

Definition at line 26562 of file core.py.

def inputs_workflow(args):
    """!
    @brief Handle explicit workspace input management.
    @param[in] args Parsed inputs command arguments.
    @return None.
    """
    workspace_root = os.path.abspath(args.workspace) if args.workspace else find_workspace_root(os.getcwd())
    if not workspace_root:
        raise ValueError("No initialized workspace found; run picurv init first or pass --workspace.")
    if args.inputs_action != "import":
        raise ValueError(f"Unsupported inputs action: {args.inputs_action}")
    entry = import_workspace_input(
        workspace_root, args.kind, args.source, name=args.name, mode=args.mode
    )
    print(f"[SUCCESS] Registered input {entry['id']}: {entry['path']}")
    if entry["mode"] == "reference":
        print("[WARNING] This is an external reference. Storage will record it but will not copy or prune its target.")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

version_workflow()

picurv_cli.core.version_workflow

(

args

)

Report, and for the status action validate, the shared build identity.

Bare picurv version reports and always succeeds; it is an informational surface that scripts and documentation already depend on. picurv version status additionally exits non-zero when the conductor, the executables, and the workspace requirement do not agree, so a job script can refuse to launch a run whose provenance would be incoherent.

Parameters

[in]

args

Parsed version command arguments.

Returns

None.

Definition at line 26581 of file core.py.

def version_workflow(args):
    """!
    @brief Report, and for the `status` action validate, the shared build identity.
 
    @details Bare `picurv version` reports and always succeeds; it is an informational
             surface that scripts and documentation already depend on. `picurv version
             status` additionally exits non-zero when the conductor, the executables,
             and the workspace requirement do not agree, so a job script can refuse to
             launch a run whose provenance would be incoherent.
    @param[in] args Parsed version command arguments.
    @return None.
    """
    workspace_root = find_workspace_root(os.getcwd())
    payload = dict(picurv_build())
    payload["source_root"] = PACKAGE_PROJECT_ROOT
    payload["workspace"] = workspace_root
    payload["workspace_requirement"] = None
    if workspace_root:
        software = load_workspace_config(workspace_root).get("software") or {}
        payload["workspace_requirement"] = software.get("picurv") if isinstance(software, dict) else None
    payload["binaries"] = runtime_build_identities()
    for identity in payload["binaries"].values():
        library = resolved_petsc_library(identity["path"]) if identity.get("path") else None
        identity["petsc_library"] = library
        identity["petsc_library_mismatch"] = petsc_library_mismatch(identity.get("petsc"), library)
    validating = getattr(args, "version_action", None) == "status"
    problems = build_identity_problems(payload["binaries"], payload["workspace_requirement"])
    payload["coherent"] = not problems
    payload["problems"] = problems
    if getattr(args, "output_format", "text") == "json":
        print(json.dumps(payload, indent=2, sort_keys=True))
        if validating and problems:
            sys.exit(1)
        return
    print(f"PICurv release : {payload['release_version']}")
    print(f"Build identity : {payload['build_id']}")
    print(f"Git commit     : {payload.get('git_commit') or 'unavailable'}")
    print(f"Dirty tree     : {payload.get('dirty') if payload.get('dirty') is not None else 'unknown'}")
    if workspace_root:
        print(f"Workspace      : {workspace_root}")
        print(f"Requirement    : {payload['workspace_requirement'] or 'latest active version'}")
    print("\nNative executables")
    for name, identity in sorted(payload["binaries"].items()):
        if not identity.get("available"):
            print(f"  {name:<15}: unavailable ({identity.get('reason', 'unknown')})")
        else:
            agreement = "matches source" if identity["matches_source"] else "STALE - rebuild"
            print(f"  {name:<15}: {identity['build_id']} ({agreement})")
        _print_petsc_build(identity)
    if not problems:
        print("\nBuild identity is coherent.")
        return
    print("\nBuild identity is NOT coherent:", file=sys.stderr)
    for problem in problems:
        print(f"  - {problem}", file=sys.stderr)
    if validating:
        sys.exit(1)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_print_petsc_build()

None picurv_cli.core._print_petsc_build ( dict  identity )

protected

Print the PETSc an executable was built against and the library it would load.

Parameters

[in]

identity

One executable's entry from runtime_build_identities(), with petsc_library and petsc_library_mismatch filled in.

Returns

None.

Definition at line 26640 of file core.py.

def _print_petsc_build(identity: dict) -> None:
    """!
    @brief Print the PETSc an executable was built against and the library it would load.
    @param[in] identity One executable's entry from `runtime_build_identities()`, with
                        `petsc_library` and `petsc_library_mismatch` filled in.
    @return None.
    """
    petsc = identity.get("petsc")
    if not petsc:
        print(f"  {'':<15}  PETSc: not recorded (built before PETSc stamping)")
        return
    location = ", ".join(part for part in (petsc.get("arch"), petsc.get("dir")) if part)
    bits = 8 * PETSC_INDEX_BYTES[petsc.get("indices", "int32")]
    print(f"  {'':<15}  PETSc: {petsc['version']} {petsc['mode']}, {bits}-bit indices ({location})")
    library = identity.get("petsc_library")
    if library:
        flag = ("  <- NOT the PETSc it was built against; load that PETSc's module, "
                "or rebuild under this one") if identity["petsc_library_mismatch"] else ""
        print(f"  {'':<15}  loads: {library}{flag}")
 
 

Here is the caller graph for this function:

_require_clean_source_checkout()

None picurv_cli.core._require_clean_source_checkout ( str  action )

protected

Refuse version-changing Git operations in a dirty source checkout.

Parameters

[in]

action

User-facing action name.

Returns

None.

Definition at line 26661 of file core.py.

def _require_clean_source_checkout(action: str) -> None:
    """!
    @brief Refuse version-changing Git operations in a dirty source checkout.
    @param[in] action User-facing action name.
    @return None.
    """
    result = subprocess.run(
        ["git", "status", "--porcelain"], cwd=PACKAGE_PROJECT_ROOT,
        text=True, capture_output=True, check=False,
    )
    if result.returncode != 0:
        raise ValueError(f"{action}: cannot inspect the PICurv Git checkout.")
    if result.stdout.strip():
        raise ValueError(
            f"{action}: the PICurv source checkout has uncommitted changes. "
            "Commit or stash them before changing versions."
        )
 
 

Here is the caller graph for this function:

_git_source_command()

subprocess.CompletedProcess picurv_cli.core._git_source_command ( list  arguments )

protected

Run a checked Git command against the active PICurv source checkout.

Parameters

[in]

arguments

Git arguments excluding the executable.

Returns

Completed successful Git process.

Definition at line 26680 of file core.py.

def _git_source_command(arguments: list) -> subprocess.CompletedProcess:
    """!
    @brief Run a checked Git command against the active PICurv source checkout.
    @param[in] arguments Git arguments excluding the executable.
    @return Completed successful Git process.
    """
    result = subprocess.run(
        ["git", *arguments], cwd=PACKAGE_PROJECT_ROOT,
        text=True, capture_output=True, check=False,
    )
    if result.returncode != 0:
        raise ValueError((result.stderr or result.stdout or "Git command failed.").strip())
    return result
 
 

Here is the caller graph for this function:

source_workflow()

picurv_cli.core.source_workflow

(

args

)

Fetch source history without silently changing the active code.

Parameters

[in]

args

Parsed source command arguments.

Returns

None.

Definition at line 26695 of file core.py.

def source_workflow(args):
    """!
    @brief Fetch source history without silently changing the active code.
    @param[in] args Parsed source command arguments.
    @return None.
    """
    if args.source_action != "update":
        raise ValueError(f"Unsupported source action: {args.source_action}")
    _git_source_command(["fetch", "--tags", "--prune", args.remote])
    print(f"[SUCCESS] Fetched branches and tags from {args.remote}; active checkout was not changed.")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_workspace_requested_version()

picurv_cli.core._workspace_requested_version ( str  workspace_root )

protected

Resolve an exact version requested by an initialized workspace.

Parameters

[in]

workspace_root

Initialized workspace root.

Returns

Exact version or tag text.

Definition at line 26707 of file core.py.

def _workspace_requested_version(workspace_root: str):
    """!
    @brief Resolve an exact version requested by an initialized workspace.
    @param[in] workspace_root Initialized workspace root.
    @return Exact version or tag text.
    """
    software = load_workspace_config(workspace_root).get("software") or {}
    requirement = software.get("picurv") if isinstance(software, dict) else None
    if not requirement:
        raise ValueError(
            f"{workspace_root}/{WORKSPACE_CONFIG_FILENAME} has no software.picurv pin; "
            "name a version explicitly."
        )
    if any(token in str(requirement) for token in "<>=!~,*"):
        raise ValueError(
            "Automatic activation needs an exact release/tag, not a version range. "
            f"Pass the desired version explicitly (workspace requires {requirement!r})."
        )
    return str(requirement)
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

versions_workflow()

picurv_cli.core.versions_workflow

(

args

)

List or activate a release using the existing source/build owners.

Parameters

[in]

args

Parsed versions command arguments.

Returns

None.

Definition at line 26728 of file core.py.

def versions_workflow(args):
    """!
    @brief List or activate a release using the existing source/build owners.
    @param[in] args Parsed versions command arguments.
    @return None.
    """
    action = args.versions_action
    if action == "list":
        result = _git_source_command(["tag", "--list", "--sort=-version:refname"])
        print(f"Active: {picurv_build()['build_id']}")
        tags = [line for line in result.stdout.splitlines() if line.strip()]
        if tags:
            print("Installed/available tags:")
            for tag in tags:
                print(f"  {tag}")
        else:
            print("No version tags are present in this checkout.")
        return
    version = getattr(args, "version", None)
    make_args = list(getattr(args, "make_args", None) or [])
    if version and (_MAKE_ASSIGNMENT_PATTERN.match(str(version)) or str(version).startswith("-")):
        # `versions activate SYSTEM=cluster` and `versions activate -- -j8` bind the
        # make argument to the optional version positional. No tag or commit contains
        # '=' or starts with '-', so either is a make argument; handing '-j8' to git as
        # a ref printed git's usage instead.
        make_args.insert(0, str(version))
        version = None
    if make_args_include_explicit_goal(make_args):
        raise ValueError(
            f"versions {action} builds the default target; pass only make variables and "
            f"options (for example SYSTEM=cluster), not a target: {' '.join(make_args)}"
        )
    if action == "activate" and not version:
        workspace_root = os.path.abspath(args.workspace) if args.workspace else find_workspace_root(os.getcwd())
        if not workspace_root:
            raise ValueError("No workspace found and no version was named.")
        version = _workspace_requested_version(workspace_root)
    if not version:
        raise ValueError(f"versions {action}: name the tag or commit to install.")
    if action not in _VERSION_BUILD_ACTIONS:
        raise ValueError(f"Unsupported versions action: {action}")
    _require_clean_source_checkout(f"versions {action}")
    # There is one installation, and this rewrites it in place. Anything resolving
    # executables from it - other workspaces, and any running job that did not pin its
    # binaries - is changed by this too, so say what is about to move before it moves.
    print(
        f"[WARNING] {PACKAGE_PROJECT_ROOT} is a single shared installation. Building "
        f"{version!r} here re-points every workspace that resolves executables from it, "
        "including any job already running against them.",
        file=sys.stderr,
    )
    print(
        "          Runs staged with --pin-executables keep their own copies and are unaffected; "
        "unpinned queued jobs stop at their job-start identity check.",
        file=sys.stderr,
    )
    _git_source_command(["fetch", "--tags", "origin"])
    ref = _resolve_version_ref(str(version))
    _git_source_command(["checkout", "--detach", ref])
    run_project_make(PACKAGE_PROJECT_ROOT, make_args)
    # picurv_build() was computed when this process started, before the checkout moved,
    # so the source identity the new binaries must match is read again here.
    source_identity = _source_build_identity(_read_release_version())
    problems = build_identity_problems(
        runtime_build_identities(source_identity), source_identity=source_identity
    )
    if problems:
        raise ValueError(
            f"Built {ref!r}, but the executables do not carry its identity "
            f"({source_identity['build_id']}):\n  - " + "\n  - ".join(problems)
        )
    print(f"[SUCCESS] Activated and built PICurv {ref} ({source_identity['build_id']}).")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

_resolve_version_ref()

str picurv_cli.core._resolve_version_ref ( str  version )

protected

Resolve a user-named version to a Git ref that exists in the source checkout.

Release tags are spelled v<release>, while VERSION and workspace software.picurv pins carry the bare release. The name is tried as given first, so a commit, branch, or already-prefixed tag is never rewritten.

Parameters

[in]

version

Tag, bare release, or commit named by the user or workspace pin.

Returns

Ref accepted by git checkout --detach.

Exceptions

ValueError

when neither spelling resolves to a commit.

Definition at line 26802 of file core.py.

def _resolve_version_ref(version: str) -> str:
    """!
    @brief Resolve a user-named version to a Git ref that exists in the source checkout.
    @details Release tags are spelled `v<release>`, while `VERSION` and workspace
             `software.picurv` pins carry the bare release. The name is tried as given
             first, so a commit, branch, or already-prefixed tag is never rewritten.
    @param[in] version Tag, bare release, or commit named by the user or workspace pin.
    @return Ref accepted by `git checkout --detach`.
    @throws ValueError when neither spelling resolves to a commit.
    """
    candidates = [version]
    if not version.startswith("v"):
        candidates.append(f"v{version}")
    for candidate in candidates:
        result = subprocess.run(
            ["git", "rev-parse", "--verify", "--quiet", f"{candidate}^{{commit}}"],
            cwd=PACKAGE_PROJECT_ROOT, text=True, capture_output=True, check=False,
        )
        if result.returncode == 0:
            return candidate
    raise ValueError(
        f"No tag or commit named {' or '.join(repr(c) for c in candidates)} exists in "
        f"{PACKAGE_PROJECT_ROOT}; 'picurv versions list' shows the available tags."
    )
 
 

Here is the caller graph for this function:

init_case()

picurv_cli.core.init_case

(

args

)

Implements the 'init' command.

Creates a new case study directory by copying a template. Runtime binaries are resolved from the project bin/ directory via PATH; pass –pin-binaries to pin specific versions locally.

Parameters

[in]

args

The command-line arguments parsed by argparse.

Definition at line 26828 of file core.py.

def init_case(args):
    """!
    @brief Implements the 'init' command.
    @details Creates a new case study directory by copying a template.
             Runtime binaries are resolved from the project bin/ directory
             via PATH; pass --pin-binaries to pin specific versions locally.
    @param[in] args The command-line arguments parsed by argparse.
    """
    context = resolve_case_origin_context(source_root_override=getattr(args, "source_root", None))
    try:
        source_project_root = require_project_root(context["source_project_root"], "init")
        template_path = resolve_template_directory(source_project_root, args.template_name)
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    # The destination path is relative to the current working directory.
    dest_path = os.path.abspath(os.path.join(os.getcwd(), args.dest_name if args.dest_name else args.template_name))
 
    if os.path.exists(dest_path):
        print(f"[FATAL] Destination directory '{dest_path}' already exists.", file=sys.stderr)
        sys.exit(1)
 
    print(f"[INFO] Initializing new case '{os.path.basename(dest_path)}' from template '{args.template_name}'...")
 
    try:
        workspace_layout = render_template_workspace(template_path, args.template_name, dest_path)
        template_managed_files = list_rendered_template_files(dest_path)
        print(f"[SUCCESS] Copied template files to: {dest_path}")
        print(f"[INFO] Wrote workspace identity: {os.path.relpath(workspace_layout['workspace_config'])}")
        if workspace_layout["canonical_roles"]:
            print("[INFO] Canonical editable configurations:")
            for role, path in sorted(workspace_layout["canonical_roles"].items()):
                print(f"  - {role}: {os.path.relpath(path)}")
    except Exception as exc:
        print(f"[FATAL] Failed to create canonical workspace layout: {exc}", file=sys.stderr)
        shutil.rmtree(dest_path, ignore_errors=True)
        sys.exit(1)
 
    try:
        runtime_result = ensure_case_runtime_execution_config(dest_path, source_project_root, overwrite=True)
        print(f"[INFO] Wrote optional runtime launcher config: {os.path.relpath(runtime_result['path'])}")
        if runtime_result["seed_source"] and os.path.basename(runtime_result["seed_source"]) == RUNTIME_EXECUTION_CONFIG_FILENAME:
            print("       Seeded from repo-local '.picurv-execution.yml'.")
        print("       Leave it unchanged for ordinary local runs; edit it only if your site needs custom MPI launcher tokens.")
    except Exception as e:
        print(f"[ERROR] Failed to write runtime execution config: {e}", file=sys.stderr)
 
    try:
        metadata_path, _ = write_case_origin_metadata(
            dest_path,
            source_project_root,
            template_name=args.template_name,
            template_managed_files=template_managed_files,
        )
        print(f"[INFO] Wrote case origin metadata: {os.path.relpath(metadata_path)}")
    except Exception as e:
        print(f"[ERROR] Failed to write case origin metadata: {e}", file=sys.stderr)
 
    cluster_profile_candidates = sorted(
        {
            os.path.basename(path)
            for pattern in ("*cluster*.yml", "*cluster*.yaml")
            for search_root in (dest_path, os.path.join(dest_path, "config"))
            for path in glob.glob(os.path.join(search_root, pattern))
        }
    )
    if cluster_profile_candidates:
        print("[INFO] Cluster profile sample(s) copied with this case:")
        for profile_name in cluster_profile_candidates:
            print(f"  - {profile_name}")
        print("       Edit account/partition/module_setup and any batch-specific launcher overrides before using --cluster.")
 
    if getattr(args, "pin_binaries", False):
        print("[INFO] Pinning runtime binaries into case directory...")
        try:
            copied_binaries = sync_case_binaries(dest_path, source_project_root)
            for dest_file_path in copied_binaries:
                print(f"  - Pinned '{os.path.basename(dest_file_path)}'")
            print("[SUCCESS] Case directory is ready with pinned binaries.")
            print("          These local copies will be used instead of bin/ originals.")
        except ValueError as exc:
            print(f"[WARNING] {exc}", file=sys.stderr)
            print("          No binaries were pinned. Run 'picurv build' first.", file=sys.stderr)
    else:
        print("[SUCCESS] Case directory is ready.")
        print("          Runtime binaries (simulator, postprocessor) are resolved from the active PICurv installation.")
        print("          Pin software.picurv in .picurv-workspace.yml only when this workspace needs a release constraint.")
    print("          Ensure 'picurv' is on your PATH (source etc/picurv.sh) to run from any directory.")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

sync_case_config_command()

picurv_cli.core.sync_case_config_command

(

args

)

Refresh template-managed config/docs files in a case directory.

Parameters

[in]

args

Command-line style argument list supplied to the function.

Definition at line 26919 of file core.py.

def sync_case_config_command(args):
    """!
    @brief Refresh template-managed config/docs files in a case directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    try:
        context = resolve_case_origin_context(
            case_dir_hint=getattr(args, "case_dir", None),
            source_root_override=getattr(args, "source_root", None),
            template_name_override=getattr(args, "template_name", None),
        )
        source_project_root = require_project_root(context["source_project_root"], "sync-config")
        case_dir = require_existing_case_dir(context["case_dir"], "sync-config", source_project_root)
        template_name = context.get("template_name")
        template_dir = resolve_template_directory(source_project_root, template_name)
        existing_managed = context.get("metadata", {}).get("template_managed_files")
        if not isinstance(existing_managed, list):
            existing_managed = None
        summary = sync_case_template_files(
            case_dir,
            template_dir,
            overwrite=getattr(args, "overwrite", False),
            prune=getattr(args, "prune", False),
            managed_rel_paths=existing_managed,
            template_name=template_name,
        )
        metadata_path, _ = write_case_origin_metadata(
            case_dir,
            source_project_root,
            template_name=template_name,
            existing=context.get("metadata"),
            template_managed_files=summary["template_managed_files"],
        )
        runtime_result = ensure_case_runtime_execution_config(case_dir, source_project_root, overwrite=False)
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    print(f"[SUCCESS] Synced template files from '{template_name}' into: {case_dir}")
    print(f"[INFO] Copied new files     : {len(summary['copied'])}")
    print(f"[INFO] Overwritten files   : {len(summary['overwritten'])}")
    print(f"[INFO] Skipped modified    : {len(summary['skipped_modified'])}")
    print(f"[INFO] Already unchanged   : {len(summary['unchanged'])}")
    print(f"[INFO] Pruned stale files  : {len(summary['pruned'])}")
    if runtime_result["created"]:
        print(f"[INFO] Created runtime launcher config: {os.path.relpath(runtime_result['path'])}")
        if runtime_result["seed_source"] and os.path.basename(runtime_result["seed_source"]) == RUNTIME_EXECUTION_CONFIG_FILENAME:
            print("[INFO] Seed source              : repo-local .picurv-execution.yml")
    if summary.get("prune_requested_without_tracking"):
        print("[WARNING] Prune tracking unavailable for this case; no removed template files were deleted.", file=sys.stderr)
    print(f"[INFO] Case origin metadata refreshed: {os.path.relpath(metadata_path)}")
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

pull_source_repo()

picurv_cli.core.pull_source_repo

(

args

)

Refresh source branches in the repository resolved from a case directory.

Parameters

[in]

args

Command-line style argument list supplied to the function.

Definition at line 26972 of file core.py.

def pull_source_repo(args):
    """!
    @brief Refresh source branches in the repository resolved from a case directory.
    @param[in] args Command-line style argument list supplied to the function.
    """
    try:
        context = resolve_case_origin_context(
            case_dir_hint=getattr(args, "case_dir", None),
            source_root_override=getattr(args, "source_root", None),
        )
        source_project_root = require_project_root(context["source_project_root"], "pull-source")
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    try:
        _refuse_detached_source_checkout(source_project_root, "pull-source")
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    rebase = not getattr(args, "no_rebase", False)
    remote = getattr(args, "remote", None)
    branch = getattr(args, "branch", None)
    current_branch_only = (
        getattr(args, "current_branch_only", False)
        or remote is not None
        or branch is not None
    )
 
    if not current_branch_only:
        pull_all_source_branches(source_project_root, "pull-source.log", rebase=rebase)
        return
 
    command = ["git", "pull"]
    if rebase:
        command.append("--rebase")
    if remote:
        command.append(remote)
        if branch:
            command.append(branch)
    elif branch:
        command.extend(["origin", branch])
 
    execute_command(command, source_project_root, "pull-source.log", {})
 

Here is the call graph for this function:

Here is the caller graph for this function:

build_project()

picurv_cli.core.build_project

(

args

)

Implements the 'build' command.

Executes the top-level Makefile directly, passing through any additional arguments to make. This allows for building, cleaning, and other Makefile targets via the orchestrator without maintaining a separate build wrapper script.

Parameters

[in]

args

The command-line arguments parsed by argparse.

Definition at line 27018 of file core.py.

def build_project(args):
    """!
    @brief Implements the 'build' command.
    @details Executes the top-level Makefile directly, passing through any
             additional arguments to `make`. This allows for building,
             cleaning, and other Makefile targets via the orchestrator
             without maintaining a separate build wrapper script.
    @param[in] args The command-line arguments parsed by argparse.
    """
 
    print("\n" + "="*27 + " BUILD STAGE " + "="*27)
    try:
        context = resolve_case_origin_context(
            case_dir_hint=getattr(args, "case_dir", None),
            source_root_override=getattr(args, "source_root", None),
        )
        source_project_root = require_project_root(context["source_project_root"], "build")
    except ValueError as exc:
        print(f"[FATAL] {exc}", file=sys.stderr)
        sys.exit(1)
 
    run_project_make(source_project_root, list(args.make_args or []))
 
 

Here is the call graph for this function:

Here is the caller graph for this function:

run_project_make()

None picurv_cli.core.run_project_make	(	str	source_project_root,
		"list[str]"	make_args
	)

Run the project Makefile with caller-supplied arguments, defaulting to all.

Shared by picurv build and picurv versions install/activate, so a site setting such as SYSTEM=cluster reaches make the same way from both.

Parameters

[in]	source_project_root	PICurv source checkout containing the Makefile.
[in]	make_args	Arguments passed through to make.

Returns

None. Exits non-zero when the Makefile is missing or make fails.

Definition at line 27042 of file core.py.

def run_project_make(source_project_root: str, make_args: "list[str]") -> None:
    """!
    @brief Run the project Makefile with caller-supplied arguments, defaulting to `all`.
    @details Shared by `picurv build` and `picurv versions install/activate`, so a site
             setting such as `SYSTEM=cluster` reaches `make` the same way from both.
    @param[in] source_project_root PICurv source checkout containing the Makefile.
    @param[in] make_args Arguments passed through to `make`.
    @return None. Exits non-zero when the Makefile is missing or `make` fails.
    """
    makefile_path = os.path.join(source_project_root, "Makefile")
 
    if not os.path.isfile(makefile_path):
        print(f"[FATAL] Makefile not found at expected location: {makefile_path}", file=sys.stderr)
        print("        Please ensure the project root contains a valid Makefile.", file=sys.stderr)
        sys.exit(1)
 
    if make_args_include_explicit_goal(make_args):
        command = ["make"] + make_args
    else:
        command = ["make", "all"] + make_args
        print("[INFO] No explicit make target supplied; defaulting to 'all'.")
        print("       Use 'picurv build clean-project ...' or another target when you want a non-build make action.")
    # For the build process, we don't have a monitor.yml, so we pass an empty
    # dict to execute_command. The command should be run in the project root.
    execute_command(command, source_project_root, "build.log", {})
 
 
 
 
# ==============================================================================

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

_package_parent

picurv_cli.core._package_parent = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))

protected

Definition at line 64 of file core.py.

_storage_module

picurv_cli.core._storage_module = importlib.import_module("picurv_cli.storage")

protected

Definition at line 67 of file core.py.

StorageError

picurv_cli.core.StorageError = _storage_module.StorageError

Definition at line 68 of file core.py.

cold_study_members

picurv_cli.core.cold_study_members = _storage_module.cold_study_members

Definition at line 69 of file core.py.

restore_cold_study_members

picurv_cli.core.restore_cold_study_members = _storage_module.restore_cold_study_members

Definition at line 70 of file core.py.

is_artifact_cold

picurv_cli.core.is_artifact_cold = _storage_module.is_artifact_cold

Definition at line 71 of file core.py.

read_artifact_identity

picurv_cli.core.read_artifact_identity = _storage_module.read_artifact_identity

Definition at line 72 of file core.py.

STORAGE_LOCK_FILENAME

picurv_cli.core.STORAGE_LOCK_FILENAME = _storage_module.STORAGE_LOCK_FILENAME

Definition at line 73 of file core.py.

STORAGE_STATE_FILENAME

picurv_cli.core.STORAGE_STATE_FILENAME = _storage_module.STORAGE_STATE_FILENAME

Definition at line 74 of file core.py.

require_storage_payload_local

picurv_cli.core.require_storage_payload_local = _storage_module.require_storage_payload_local

Definition at line 75 of file core.py.

runtime_stage_lock

picurv_cli.core.runtime_stage_lock = _storage_module.runtime_stage_lock

Definition at line 76 of file core.py.

storage_state_summary

picurv_cli.core.storage_state_summary = _storage_module.storage_state_summary

Definition at line 77 of file core.py.

_rebase_restored_text_paths

picurv_cli.core._rebase_restored_text_paths = _storage_module._rebase_restored_text_paths

protected

Definition at line 78 of file core.py.

_NUMPY_MODULE

picurv_cli.core._NUMPY_MODULE = None

protected

Definition at line 80 of file core.py.

_MATPLOTLIB_PYPLOT

picurv_cli.core._MATPLOTLIB_PYPLOT = None

protected

Definition at line 81 of file core.py.

np

picurv_cli.core.np = _LazyNumpyProxy()

Definition at line 98 of file core.py.

PACKAGE_PATH

picurv_cli.core.PACKAGE_PATH = os.path.dirname(os.path.realpath(__file__))

Definition at line 188 of file core.py.

PACKAGE_PROJECT_ROOT

picurv_cli.core.PACKAGE_PROJECT_ROOT = os.path.dirname(PACKAGE_PATH)

Definition at line 189 of file core.py.

INVOKED_SCRIPT_DIR

picurv_cli.core.INVOKED_SCRIPT_DIR

Initial value:

=  os.environ.get(
    "_PICURV_INVOKED_SCRIPT_DIR",
    PACKAGE_PATH,
)

Definition at line 190 of file core.py.

SCRIPT_PATH

picurv_cli.core.SCRIPT_PATH

Initial value:

=  os.environ.get(
    "_PICURV_SCRIPT_PATH",
    PACKAGE_PATH,
)

Definition at line 194 of file core.py.

PROJECT_ROOT

picurv_cli.core.PROJECT_ROOT = os.path.dirname(SCRIPT_PATH)

Definition at line 198 of file core.py.

GENERATORS_PATH

picurv_cli.core.GENERATORS_PATH = os.path.join(PACKAGE_PROJECT_ROOT, "generators")

Definition at line 199 of file core.py.

DEFAULT_BIN_DIR

picurv_cli.core.DEFAULT_BIN_DIR = SCRIPT_PATH

Definition at line 201 of file core.py.

VERSION_FILE

picurv_cli.core.VERSION_FILE = os.path.join(PACKAGE_PROJECT_ROOT, "VERSION")

Definition at line 205 of file core.py.

PICURV_RELEASE_VERSION

str picurv_cli.core.PICURV_RELEASE_VERSION = _read_release_version()

Definition at line 301 of file core.py.

CASE_ORIGIN_METADATA_FILENAME

str picurv_cli.core.CASE_ORIGIN_METADATA_FILENAME = ".picurv-origin.json"

Definition at line 302 of file core.py.

WORKSPACE_CONFIG_FILENAME

str picurv_cli.core.WORKSPACE_CONFIG_FILENAME = ".picurv-workspace.yml"

Definition at line 303 of file core.py.

WORKSPACE_SCHEMA_VERSION

int picurv_cli.core.WORKSPACE_SCHEMA_VERSION = 1

Definition at line 304 of file core.py.

RUN_MANIFEST_SCHEMA_VERSION

int picurv_cli.core.RUN_MANIFEST_SCHEMA_VERSION = 3

Definition at line 305 of file core.py.

ASSET_MANIFEST_SCHEMA_VERSION

int picurv_cli.core.ASSET_MANIFEST_SCHEMA_VERSION = 1

Definition at line 306 of file core.py.

ASSET_LOCK_SCHEMA_VERSION

int picurv_cli.core.ASSET_LOCK_SCHEMA_VERSION = 1

Definition at line 307 of file core.py.

RUNTIME_EXECUTION_CONFIG_FILENAME

str picurv_cli.core.RUNTIME_EXECUTION_CONFIG_FILENAME = ".picurv-execution.yml"

Definition at line 308 of file core.py.

LEGACY_LOCAL_RUNTIME_CONFIG_FILENAME

str picurv_cli.core.LEGACY_LOCAL_RUNTIME_CONFIG_FILENAME = ".picurv-local.yml"

Definition at line 309 of file core.py.

RUNTIME_EXECUTION_EXAMPLE_FILENAME

str picurv_cli.core.RUNTIME_EXECUTION_EXAMPLE_FILENAME = "execution.example.yml"

Definition at line 310 of file core.py.

RUNTIME_EXECUTION_CONFIG_FILENAMES

tuple picurv_cli.core.RUNTIME_EXECUTION_CONFIG_FILENAMES

Initial value:

=  (
    RUNTIME_EXECUTION_CONFIG_FILENAME,
    LEGACY_LOCAL_RUNTIME_CONFIG_FILENAME,
)

Definition at line 311 of file core.py.

DEFAULT_RUNTIME_EXECUTION_CONFIG_TEMPLATE

str picurv_cli.core.DEFAULT_RUNTIME_EXECUTION_CONFIG_TEMPLATE

Initial value:

=  """# Optional shared runtime launcher overrides.
# This file is safe to leave unchanged on ordinary local machines.
# Edit it only when your site needs custom MPI launcher tokens.
#
# Precedence:
#   - local/login-node runs: local_execution -> default_execution -> built-in mpiexec
#   - generated cluster jobs: cluster.yml.execution -> cluster_execution -> default_execution -> built-in srun
#
# Example override:
# default_execution:
#   launcher: "mpirun"
#   launcher_args:
#     - --bind-to
#     - none
default_execution: {}
 
local_execution: {}
 
cluster_execution: {}
"""

Definition at line 316 of file core.py.

CLUSTER_TEMPLATE_PLACEHOLDER_ACCOUNT

str picurv_cli.core.CLUSTER_TEMPLATE_PLACEHOLDER_ACCOUNT = "my_project_account"

Definition at line 337 of file core.py.

CLUSTER_TEMPLATE_PLACEHOLDER_MAIL

str picurv_cli.core.CLUSTER_TEMPLATE_PLACEHOLDER_MAIL = "user@example.edu"

Definition at line 338 of file core.py.

DEFAULT_WALLTIME_GUARD_POLICY

dict picurv_cli.core.DEFAULT_WALLTIME_GUARD_POLICY

Initial value:

=  {
    "enabled": True,
    "warmup_steps": 10,
    "multiplier": 2.0,
    "min_seconds": 60.0,
    "estimator_alpha": 0.35,
}

Definition at line 340 of file core.py.

WALLTIME_GUARD_ENV_JOB_START_EPOCH

str picurv_cli.core.WALLTIME_GUARD_ENV_JOB_START_EPOCH = "PICURV_JOB_START_EPOCH"

Definition at line 347 of file core.py.

WALLTIME_GUARD_ENV_LIMIT_SECONDS

str picurv_cli.core.WALLTIME_GUARD_ENV_LIMIT_SECONDS = "PICURV_WALLTIME_LIMIT_SECONDS"

Definition at line 348 of file core.py.

POST_RESUME_STATE_FILENAME

str picurv_cli.core.POST_RESUME_STATE_FILENAME = "post.resume.json"

Definition at line 349 of file core.py.

POST_LOCK_FILENAME

str picurv_cli.core.POST_LOCK_FILENAME = "post.lock"

Definition at line 350 of file core.py.

POST_LOCK_METADATA_FILENAME

str picurv_cli.core.POST_LOCK_METADATA_FILENAME = "post.lock.json"

Definition at line 351 of file core.py.

POST_LOCK_WRAPPER_FILENAME

str picurv_cli.core.POST_LOCK_WRAPPER_FILENAME = "post_lock_wrapper.py"

Definition at line 352 of file core.py.

POST_RESUME_SCHEMA_VERSION

int picurv_cli.core.POST_RESUME_SCHEMA_VERSION = 2

Definition at line 353 of file core.py.

POST_RECIPE_SIGNATURE_EXCLUDED_KEYS

dict picurv_cli.core.POST_RECIPE_SIGNATURE_EXCLUDED_KEYS = {"startTime", "endTime", "timeStep", "source_directory"}

Definition at line 356 of file core.py.

CHECKPOINT_FORMAT

str picurv_cli.core.CHECKPOINT_FORMAT = "picurv-checkpoint"

Definition at line 357 of file core.py.

CHECKPOINT_VERSION

int picurv_cli.core.CHECKPOINT_VERSION = 1

Definition at line 358 of file core.py.

CHECKPOINT_STEP_WIDTH

int picurv_cli.core.CHECKPOINT_STEP_WIDTH = 12

Definition at line 359 of file core.py.

CHECKPOINT_REQUIRED_EULERIAN_FIELDS

dict picurv_cli.core.CHECKPOINT_REQUIRED_EULERIAN_FIELDS = {"Ucat", "Ucont", "Ucont_rm1", "P", "Nvert"}

Definition at line 360 of file core.py.

WORKSPACE_DIRECTORY_LAYOUT

tuple picurv_cli.core.WORKSPACE_DIRECTORY_LAYOUT

Initial value:

=  (
    "config",
    "config/studies",
    "config/grids",
    "config/initial_conditions",
    "config/inlet_profiles",
    "inputs",
    "inputs/grids",
    "inputs/initial_conditions",
    "inputs/inlet_profiles",
    "inputs/reference_fields",
    "assets",
    "assets/objects",
    "assets/objects/grids",
    "assets/objects/initial_conditions",
    "assets/objects/inlet_profiles",
    "assets/sets",
    "runs",
    "studies",
)

Definition at line 362 of file core.py.

RUN_DIRECTORY_LAYOUT

tuple picurv_cli.core.RUN_DIRECTORY_LAYOUT

Initial value:

=  (
    "config",
    "config/history",
    "config/post-recipes",
    "inputs",
    "inputs/grid",
    "inputs/initial_condition",
    "inputs/inlet_profiles",
    "inputs/restart",
    "output",
    "output/checkpoints",
    "output/analysis",
    "output/analysis/metrics",
    "output/analysis/statistics",
    "output/analysis/spectra",
    "output/analysis/plots",
    "output/visualization",
    "logs",
    "scheduler",
)

Definition at line 383 of file core.py.

CANONICAL_RUN_PATHS

dict picurv_cli.core.CANONICAL_RUN_PATHS

Initial value:

=  {
    "config": "config",
    "inputs": "inputs",
    "restart": "inputs/restart",
    "output": "output",
    "checkpoints": "output/checkpoints",
    "analysis": "output/analysis",
    "metrics": "output/analysis/metrics",
    "statistics": "output/analysis/statistics",
    "spectra": "output/analysis/spectra",
    "plots": "output/analysis/plots",
    "visualization": "output/visualization",
    "logs": "logs",
    "scheduler": "scheduler",
}

Definition at line 404 of file core.py.

INITIAL_CONDITION_SPECTRUM_RELPATH

picurv_cli.core.INITIAL_CONDITION_SPECTRUM_RELPATH

Initial value:

=  os.path.join(
    CANONICAL_RUN_PATHS["spectra"], "initial_condition_spectrum.csv"
)

Definition at line 422 of file core.py.

_WORKSPACE_ARTIFACT_ROOT_VALUES

dict picurv_cli.core._WORKSPACE_ARTIFACT_ROOT_VALUES = {"runs", "studies"}

protected

Definition at line 426 of file core.py.

_ASSET_SOURCE_REFERENCE_KEYS

dict picurv_cli.core._ASSET_SOURCE_REFERENCE_KEYS

protected

Initial value:

=  {
    "source_file", "path", "config_file", "field_file", "grid_file", "source_case", "script"
}

Definition at line 427 of file core.py.

_PYTHON_INITIAL_CONDITION_PROVIDERS

dict picurv_cli.core._PYTHON_INITIAL_CONDITION_PROVIDERS

protected

Initial value:

=  {"ic_gen", "spectral_random_velocity", "resampled_velocity",
                                       "channel_spectral_velocity", "duct_spectral_velocity",
                                       "stability_mode_velocity"}

Definition at line 430 of file core.py.

SPECTRAL_IC_PROVIDERS

tuple picurv_cli.core.SPECTRAL_IC_PROVIDERS

Initial value:

=  ("spectral_random_velocity", "resampled_velocity",
                         "channel_spectral_velocity", "duct_spectral_velocity", "stability_mode_velocity")

Definition at line 434 of file core.py.

SHELL_SPECTRUM_IC_PROVIDERS

tuple picurv_cli.core.SHELL_SPECTRUM_IC_PROVIDERS = ("spectral_random_velocity", "resampled_velocity")

Definition at line 437 of file core.py.

SPECTRAL_RANDOM_VELOCITY_PARAMS

picurv_cli.core.SPECTRAL_RANDOM_VELOCITY_PARAMS

Initial value:

=  frozenset(
    {"field", "seed", "random", "spectrum", "projection", "normalization", "remove_mean"}
)

Definition at line 439 of file core.py.

RESAMPLED_VELOCITY_PARAMS

picurv_cli.core.RESAMPLED_VELOCITY_PARAMS

Initial value:

=  frozenset(
    {"field", "source_file", "format", "cells", "box_length", "sample_offset", "layout", "filter",
     "projection", "remove_mean"}
)

Definition at line 443 of file core.py.

RESAMPLED_VELOCITY_FASTEST_AXES

tuple picurv_cli.core.RESAMPLED_VELOCITY_FASTEST_AXES = ("x", "z")

Definition at line 448 of file core.py.

RESAMPLED_VELOCITY_COMPONENT_LAYOUTS

tuple picurv_cli.core.RESAMPLED_VELOCITY_COMPONENT_LAYOUTS = ("interleaved", "separate")

Definition at line 449 of file core.py.

RESAMPLED_VELOCITY_RAW_DTYPES

tuple picurv_cli.core.RESAMPLED_VELOCITY_RAW_DTYPES = ("float32", "float64")

Definition at line 450 of file core.py.

RESAMPLED_VELOCITY_BYTE_ORDERS

tuple picurv_cli.core.RESAMPLED_VELOCITY_BYTE_ORDERS = ("little", "big", "native")

Definition at line 451 of file core.py.

RESAMPLED_VELOCITY_PROJECTIONS

tuple picurv_cli.core.RESAMPLED_VELOCITY_PROJECTIONS = ("picurv_discrete", "continuum", "none")

Definition at line 452 of file core.py.

RESAMPLED_VELOCITY_LAYOUT_KEYS

dict picurv_cli.core.RESAMPLED_VELOCITY_LAYOUT_KEYS

Initial value:

=  {
    "raw": {"fastest_axis", "components", "dtype", "byte_order", "header_bytes"},
    "npy": {"fastest_axis", "components"},
    "npz": {"fastest_axis", "components", "datasets"},
    "hdf5": {"fastest_axis", "components", "datasets"},
}

Definition at line 454 of file core.py.

_FILE_BACKED_GRID_VALUES

dict picurv_cli.core._FILE_BACKED_GRID_VALUES = {"file", "grid_gen"}

protected

Definition at line 460 of file core.py.

_WORKSPACE_MANAGED_PATHS

dict picurv_cli.core._WORKSPACE_MANAGED_PATHS = {"assets", "inputs", "runs", "studies"}

protected

Definition at line 461 of file core.py.

_VENDORABLE_CONFIG_REFERENCE_KEYS

dict picurv_cli.core._VENDORABLE_CONFIG_REFERENCE_KEYS = {"config_file", "script"}

protected

Definition at line 462 of file core.py.

_PLAIN_FILENAME_SENTINELS

dict picurv_cli.core._PLAIN_FILENAME_SENTINELS = {"", ".", ".."}

protected

Definition at line 463 of file core.py.

_VERSION_BUILD_ACTIONS

dict picurv_cli.core._VERSION_BUILD_ACTIONS = {"install", "activate"}

protected

Definition at line 464 of file core.py.

RUN_DIRECTORY_ROOTS

picurv_cli.core.RUN_DIRECTORY_ROOTS

Initial value:

=  frozenset(
    relative.split("/")[0] for relative in RUN_DIRECTORY_LAYOUT
)

Definition at line 707 of file core.py.

RUN_ROOT_ALLOWED_FILES

picurv_cli.core.RUN_ROOT_ALLOWED_FILES = frozenset({"manifest.json"})

Definition at line 713 of file core.py.

CONTINUATION_STAGED_RECORDS

tuple picurv_cli.core.CONTINUATION_STAGED_RECORDS

Initial value:

=  ("config/active.json", "manifest.json",
                               "inputs/assets.lock.yml", "inputs/software.lock.json")

Definition at line 1032 of file core.py.

RUN_EXECUTABLE_NAMES

tuple picurv_cli.core.RUN_EXECUTABLE_NAMES = ("simulator", "postprocessor")

Definition at line 1104 of file core.py.

STORAGE_OFFLOADED_STATES

picurv_cli.core.STORAGE_OFFLOADED_STATES = frozenset({"COLD", "PARTIAL"})

Definition at line 1312 of file core.py.

RUN_COMPONENT_STATES

tuple picurv_cli.core.RUN_COMPONENT_STATES

Initial value:

=  (
    "not_requested", "planned", "running", "partial", "complete", "failed", "offloaded",
)

Definition at line 1315 of file core.py.

RUN_COMPONENT_LAYOUT

tuple picurv_cli.core.RUN_COMPONENT_LAYOUT

Initial value:

=  (
    ("configuration", "config", "essential"),
    ("inputs", "inputs", "essential"),
    ("checkpoints", "output/checkpoints", "policy"),
    ("analysis", "output/analysis", "derived"),
    ("field_statistics", "output/analysis/statistics", "derived"),
    ("spectra", "output/analysis/spectra", "derived"),
    ("visualization", "output/visualization", "derived"),
    ("logs", "logs", "essential"),
    ("scheduler", "scheduler", "essential"),
)

Definition at line 1320 of file core.py.

_SELECTED_PETSC_INDEX_BYTES

picurv_cli.core._SELECTED_PETSC_INDEX_BYTES = None

protected

Definition at line 1832 of file core.py.

_BINARY_VERSION_PATTERN

picurv_cli.core._BINARY_VERSION_PATTERN

protected

Initial value:

=  re.compile(
    r"^(?P<name>\S+)\s+(?P<version>(?P<release>[^+\s]+?)(?:\.dev\d+)?)\+g(?P<commit>[0-9a-f]+)(?P<dirty>\.dirty)?\s*$"
)

Definition at line 1853 of file core.py.

_BINARY_PETSC_PATTERN

picurv_cli.core._BINARY_PETSC_PATTERN

protected

Initial value:

=  re.compile(
    r"^petsc (?P<version>\S+) (?P<mode>debug|optimized)(?: (?P<indices>int32|int64))? (?P<arch>\S*) (?P<dir>.*)$"
)

Definition at line 1857 of file core.py.

PETSC_INDEX_BYTES

dict picurv_cli.core.PETSC_INDEX_BYTES = {"int32": 4, "int64": 8}

Definition at line 1861 of file core.py.

_BINARY_PETSC_STAMP_MARKER

str picurv_cli.core._BINARY_PETSC_STAMP_MARKER = b"PICURV_PETSC_BUILD:"

protected

Definition at line 1863 of file core.py.

_BINARY_BUILD_STAMP_MARKER

str picurv_cli.core._BINARY_BUILD_STAMP_MARKER = b"PICURV_BUILD:"

protected

Definition at line 1865 of file core.py.

ERROR_CODE_CLI_USAGE_INVALID

str picurv_cli.core.ERROR_CODE_CLI_USAGE_INVALID = "CLI_USAGE_INVALID"

Definition at line 2181 of file core.py.

ERROR_CODE_CFG_MISSING_SECTION

str picurv_cli.core.ERROR_CODE_CFG_MISSING_SECTION = "CFG_MISSING_SECTION"

Definition at line 2182 of file core.py.

ERROR_CODE_CFG_MISSING_KEY

str picurv_cli.core.ERROR_CODE_CFG_MISSING_KEY = "CFG_MISSING_KEY"

Definition at line 2183 of file core.py.

ERROR_CODE_CFG_INVALID_TYPE

str picurv_cli.core.ERROR_CODE_CFG_INVALID_TYPE = "CFG_INVALID_TYPE"

Definition at line 2184 of file core.py.

ERROR_CODE_CFG_INVALID_VALUE

str picurv_cli.core.ERROR_CODE_CFG_INVALID_VALUE = "CFG_INVALID_VALUE"

Definition at line 2185 of file core.py.

ERROR_CODE_CFG_FILE_NOT_FOUND

str picurv_cli.core.ERROR_CODE_CFG_FILE_NOT_FOUND = "CFG_FILE_NOT_FOUND"

Definition at line 2186 of file core.py.

ERROR_CODE_CFG_GRID_PARSE

str picurv_cli.core.ERROR_CODE_CFG_GRID_PARSE = "CFG_GRID_PARSE"

Definition at line 2187 of file core.py.

ERROR_CODE_CFG_INCONSISTENT_COMBO

str picurv_cli.core.ERROR_CODE_CFG_INCONSISTENT_COMBO = "CFG_INCONSISTENT_COMBO"

Definition at line 2188 of file core.py.

ERROR_CODE_DEPENDENCY_MISSING

str picurv_cli.core.ERROR_CODE_DEPENDENCY_MISSING = "DEPENDENCY_MISSING"

Definition at line 2189 of file core.py.

RESTART_RUN_DIR_REQUIRED_MESSAGE

tuple picurv_cli.core.RESTART_RUN_DIR_REQUIRED_MESSAGE

Initial value:

=  (
    "--continue and --restart-from both require an existing run directory. "
    "Use --continue --run-dir <run_dir> to resume in place, or "
    "--restart-from <run_dir> to create a new run."
)

Definition at line 2191 of file core.py.

_ERROR_HINTS

dict picurv_cli.core._ERROR_HINTS

protected

Initial value:

=  {
    ERROR_CODE_CLI_USAGE_INVALID: "Run 'picurv <command> --help' to see valid argument combinations.",
    ERROR_CODE_CFG_MISSING_SECTION: "Add the missing section using examples/master_template/*.yml as reference.",
    ERROR_CODE_CFG_MISSING_KEY: "Add the missing key in the referenced YAML file.",
    ERROR_CODE_CFG_INVALID_TYPE: "Fix the value type to match the documented schema in docs/pages/14_Config_Contract.md.",
    ERROR_CODE_CFG_INVALID_VALUE: "Adjust the value to a supported range/enum from the config reference pages.",
    ERROR_CODE_CFG_FILE_NOT_FOUND: "Fix the path or create the missing file before running again.",
    ERROR_CODE_CFG_GRID_PARSE: "Validate grid file format and numeric payload (block count, dims, coordinates).",
    ERROR_CODE_CFG_INCONSISTENT_COMBO: "Fix conflicting options/keys so the configuration is internally consistent.",
    ERROR_CODE_DEPENDENCY_MISSING: "Install the named optional dependency for the Python interpreter used by picurv.",
}

Definition at line 2197 of file core.py.

_RESTART_HINT

tuple picurv_cli.core._RESTART_HINT

protected

Initial value:

=  ("Check --restart-from, --continue and --run-dir against the source run's committed "
                 "checkpoints and run_control.start_step in case.yml.")

Definition at line 2209 of file core.py.

_STORAGE_RESTORE_HINT

tuple picurv_cli.core._STORAGE_RESTORE_HINT

protected

Initial value:

=  ("Run the restore command in the message; 'picurv storage status --run-dir "
                         "<run>' shows what is local.")

Definition at line 2212 of file core.py.

_STUDY_DIR_HINT

str picurv_cli.core._STUDY_DIR_HINT = "Pass a study directory that 'picurv sweep' created (studies/<study_id>)."

protected

Definition at line 2215 of file core.py.

_MAKE_ASSIGNMENT_PATTERN

picurv_cli.core._MAKE_ASSIGNMENT_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*[:+?]?=.*$")

protected

Definition at line 2814 of file core.py.

POST_RUN_CONTROL_ALIASES

dict picurv_cli.core.POST_RUN_CONTROL_ALIASES

Initial value:

=  {
    "start_step": ("start_step", "startTime"),
    "end_step": ("end_step", "endTime"),
    "step_interval": ("step_interval", "timeStep"),
}

Definition at line 3289 of file core.py.

GRID_GENERATOR_HYPHEN_KEY_HINTS

dict picurv_cli.core.GRID_GENERATOR_HYPHEN_KEY_HINTS

Initial value:

=  {
    "config-file": "config_file",
    "grid-type": "grid_type",
    "cli-args": "cli_args",
}

Definition at line 3296 of file core.py.

RETIRED_GENERATOR_DESTINATION_KEYS

tuple picurv_cli.core.RETIRED_GENERATOR_DESTINATION_KEYS

Initial value:

=  ("output_file", "stats_file", "vts_file",
                                      "output-file", "stats-file", "vts-file")

Definition at line 3305 of file core.py.

RETIRED_INITIAL_CONDITION_DESTINATION_KEYS

tuple picurv_cli.core.RETIRED_INITIAL_CONDITION_DESTINATION_KEYS = ("output_file", "summary_json", "spectrum_csv")

Definition at line 3356 of file core.py.

POST_SPECTRA_TASKS

dict picurv_cli.core.POST_SPECTRA_TASKS

Initial value:

=  {
    "plane_spectrum": {"requires_single_block": True, "fields": ("Ucat",)},
    "line_spectrum": {"requires_single_block": True, "fields": ("Ucat",)},
    "shell_spectrum": {
        "requires_uniform_cartesian": True,
        "requires_periodic_geometric": True,
        "requires_single_block": True,
        "fields": ("Ucat",),
    },
}

Definition at line 3542 of file core.py.

POST_SPECTRA_SYMBOLS

tuple picurv_cli.core.POST_SPECTRA_SYMBOLS = ("continuum", "discrete")

Definition at line 3554 of file core.py.

POST_SPECTRA_MEAN_MODES

tuple picurv_cli.core.POST_SPECTRA_MEAN_MODES = ("none", "domain", "sample")

Definition at line 3558 of file core.py.

POST_FIELD_STATISTICS_OUTPUTS

tuple picurv_cli.core.POST_FIELD_STATISTICS_OUTPUTS = ("mean", "reynolds_stress", "rms", "tke", "flux", "point_variance")

Definition at line 3562 of file core.py.

POST_FIELD_STATISTICS_DEFAULT_OUTPUTS

tuple picurv_cli.core.POST_FIELD_STATISTICS_DEFAULT_OUTPUTS = POST_FIELD_STATISTICS_OUTPUTS[:-1]

Definition at line 3565 of file core.py.

POST_FIELD_STATISTICS_FORMATS

tuple picurv_cli.core.POST_FIELD_STATISTICS_FORMATS = ("vtk", "csv")

Definition at line 3569 of file core.py.

GRID_MODES

tuple picurv_cli.core.GRID_MODES = ("file", "programmatic_c", "grid_gen")

Definition at line 3581 of file core.py.

DOMAIN_DIMENSIONALITY_MODES

tuple picurv_cli.core.DOMAIN_DIMENSIONALITY_MODES = ("3D", "2D")

Definition at line 3585 of file core.py.

GRID_GENERATOR_TYPES

tuple picurv_cli.core.GRID_GENERATOR_TYPES = ("box", "sweep")

Definition at line 3588 of file core.py.

GRID_CROSS_SECTION_KINDS

tuple picurv_cli.core.GRID_CROSS_SECTION_KINDS = ("rectangle", "circle")

Definition at line 3594 of file core.py.

GRID_WALL_SEGMENT_KINDS

tuple picurv_cli.core.GRID_WALL_SEGMENT_KINDS = ("flat", "step", "ramp", "arc", "sine", "gaussian", "hill")

Definition at line 3598 of file core.py.

GRID_PATH_SEGMENT_KINDS

tuple picurv_cli.core.GRID_PATH_SEGMENT_KINDS = ("straight", "arc")

Definition at line 3601 of file core.py.

GRID_TRANSFORM_KINDS

tuple picurv_cli.core.GRID_TRANSFORM_KINDS = ("anchor", "translate", "scale", "rotate", "mirror", "permute", "reverse")

Definition at line 3604 of file core.py.

PARTICLE_RESTART_MODES

tuple picurv_cli.core.PARTICLE_RESTART_MODES = ("init", "load")

Definition at line 3607 of file core.py.

POST_EULERIAN_PIPELINE_TASKS

tuple picurv_cli.core.POST_EULERIAN_PIPELINE_TASKS = ("q_criterion", "normalize_field", "nodal_average")

Definition at line 3610 of file core.py.

POST_LAGRANGIAN_PIPELINE_TASKS

tuple picurv_cli.core.POST_LAGRANGIAN_PIPELINE_TASKS = ("specific_ke",)

Definition at line 3613 of file core.py.

STUDY_TYPES

tuple picurv_cli.core.STUDY_TYPES = ("grid_independence", "timestep_independence", "sensitivity")

Definition at line 3616 of file core.py.

NEWTON_KRYLOV_PRECONDITIONER_MODELS

tuple picurv_cli.core.NEWTON_KRYLOV_PRECONDITIONER_MODELS = ("none", "frozen_momentum_jacobian")

Definition at line 3619 of file core.py.

NEWTON_KRYLOV_PRECONDITIONER_STRUCTURES

tuple picurv_cli.core.NEWTON_KRYLOV_PRECONDITIONER_STRUCTURES = ("none", "point_block")

Definition at line 3624 of file core.py.

POISSON_PRECONDITIONER_TYPES

tuple picurv_cli.core.POISSON_PRECONDITIONER_TYPES = ("multigrid",)

Definition at line 3628 of file core.py.

POISSON_PRECONDITIONER_SPELLINGS

dict picurv_cli.core.POISSON_PRECONDITIONER_SPELLINGS = {"mg": "multigrid", "pcmg": "multigrid"}

Definition at line 3631 of file core.py.

PRESCRIBED_FLOW_SOURCE_TYPES

tuple picurv_cli.core.PRESCRIBED_FLOW_SOURCE_TYPES = ("file", "generated", "field_slice")

Definition at line 3637 of file core.py.

VERIFICATION_SCALAR_PROFILES

tuple picurv_cli.core.VERIFICATION_SCALAR_PROFILES = ("CONSTANT", "LINEAR_X", "SIN_PRODUCT")

Definition at line 3640 of file core.py.

SCALAR_TRANSPORT_FLAGS

dict picurv_cli.core.SCALAR_TRANSPORT_FLAGS

Initial value:

=  {
    "schmidt_number": "-schmidt_number",
    "turbulent_schmidt_number": "-turb_schmidt_number",
    "iem_constant": "-iem_constant",
}

Definition at line 3646 of file core.py.

SCALAR_TRANSPORT_CASE_PATHS

dict picurv_cli.core.SCALAR_TRANSPORT_CASE_PATHS

Initial value:

=  {
    "schmidt_number": ("properties", "fluid"),
    "turbulent_schmidt_number": ("models", "physics", "turbulence"),
    "iem_constant": ("models", "physics", "particles"),
}

Definition at line 3655 of file core.py.

STUDY_PLOT_FORMATS

tuple picurv_cli.core.STUDY_PLOT_FORMATS = ("png", "pdf", "svg")

Definition at line 3709 of file core.py.

PROFILING_TIMESTEP_MODES

tuple picurv_cli.core.PROFILING_TIMESTEP_MODES = ("off", "selected", "all")

Definition at line 3712 of file core.py.

RENAMED_MONITOR_FUNCTIONS

dict picurv_cli.core.RENAMED_MONITOR_FUNCTIONS

Initial value:

=  {
    "PoissonSolver_MG": "PoissonSolver_Multigrid",
    "Projection": "ProjectVelocity",
    "PoissonLHSNew": "AssemblePoissonOperator",
    "PoissonRHS": "ComputePoissonRHS",
}

Definition at line 3716 of file core.py.

REMOVED_MONITOR_FUNCTIONS

tuple picurv_cli.core.REMOVED_MONITOR_FUNCTIONS

Initial value:

=  (
    "CorrectChannelFluxProfile", "VolumeFlux", "VolumeFlux_rev", "FullyBlocked",
    "MyNvertRestriction", "MyRestriction", "MyInterpolation", "PoissonNullSpaceFunction",
    "GridRestriction", "SetupSolverParameters",
)

Definition at line 3724 of file core.py.

GMRES_RESTART_METHODS

tuple picurv_cli.core.GMRES_RESTART_METHODS = ("gmres", "fgmres", "lgmres")

Definition at line 3731 of file core.py.

POISSON_KSP_METHODS

dict picurv_cli.core.POISSON_KSP_METHODS

Initial value:

=  {
    "fgmres": {},
    "cg": {"-ps_ksp_norm_type": "unpreconditioned"},
}

Definition at line 3740 of file core.py.

POISSON_KSP_REFUSED

dict picurv_cli.core.POISSON_KSP_REFUSED

Initial value:

=  {
    "gmres": "is not flexible",
    "lgmres": "is not flexible",
    "bcgs": "is not flexible",
}

Definition at line 3746 of file core.py.

ANALYTICAL_SOLUTION_TYPES

tuple picurv_cli.core.ANALYTICAL_SOLUTION_TYPES = ("TGV3D", "ZERO_FLOW", "UNIFORM_FLOW")

Definition at line 3753 of file core.py.

LEGACY_FIELD_INIT_SPELLINGS

tuple picurv_cli.core.LEGACY_FIELD_INIT_SPELLINGS = ("Zero", "Constant", "Poiseuille")

Definition at line 3757 of file core.py.

PROJECTION_OPERATORS

tuple picurv_cli.core.PROJECTION_OPERATORS = ("continuum", "picurv_discrete")

Definition at line 3760 of file core.py.

METRIC_SOURCE_KINDS

tuple picurv_cli.core.METRIC_SOURCE_KINDS = ("statistics_csv", "csv", "log_regex", "log")

Definition at line 3763 of file core.py.

LAUNCH_MODES

tuple picurv_cli.core.LAUNCH_MODES = ("local", "cluster")

Definition at line 3766 of file core.py.

POST_SPECTRA_SCALAR_COLUMNS

tuple picurv_cli.core.POST_SPECTRA_SCALAR_COLUMNS

Initial value:

=  (
    "resolved_kinetic_energy", "spectrum_total_energy", "parseval_residual",
    "spectrum_peak_k", "zero_mode_energy", "integral_length_scale",
    "taylor_microscale", "dissipation_over_viscosity",
)

Definition at line 4023 of file core.py.

POST_STAGE_NAMES

tuple picurv_cli.core.POST_STAGE_NAMES = ("fields", "spectra", "reducers")

Definition at line 4031 of file core.py.

POST_REDUCER_TASKS

dict picurv_cli.core.POST_REDUCER_TASKS

Initial value:

=  {
    "wall_profile": {"command": "wall-profile", "retains": 1, "axis_key": "wall_axis", "default_axis": "j"},
    "cross_section": {"command": "cross-section", "retains": 2, "axis_key": "stream_axis", "default_axis": "k"},
    "profile_series": {"command": "profile-series", "retains": 1, "axis_key": None, "default_axis": None},
}

Definition at line 4242 of file core.py.

POST_REDUCER_FRICTION_SOURCES

dict picurv_cli.core.POST_REDUCER_FRICTION_SOURCES

Initial value:

=  {
    "first_cell": {"needs": None},
    "driven_flow": {"needs": "window"},
    "wall_model": {"needs": "window"},
    "body_force": {"needs": "value"},
    "u_tau": {"needs": "value"},
}

Definition at line 4251 of file core.py.

_REDUCER_AXIS_TOKENS

dict picurv_cli.core._REDUCER_AXIS_TOKENS = {"i": "Xi", "j": "Eta", "k": "Zeta"}

protected

Definition at line 4260 of file core.py.

POST_PARAVIEW_SERIES_SCOPES

dict picurv_cli.core.POST_PARAVIEW_SERIES_SCOPES = {"run", "lineage"}

Definition at line 5069 of file core.py.

POST_PROCESS_REASON_LABELS

dict picurv_cli.core.POST_PROCESS_REASON_LABELS

Initial value:

=  {
    "missing": "no output yet",
    "recipe": "recipe changed",
    "checkpoint": "checkpoint changed",
    "recompute": "--recompute",
}

Definition at line 6291 of file core.py.

PICGRID_FLOAT_FORMAT

str picurv_cli.core.PICGRID_FLOAT_FORMAT = ".17e"

Definition at line 7143 of file core.py.

GENERATED_PROFILE_GENERATORS

dict picurv_cli.core.GENERATED_PROFILE_GENERATORS = {"square_duct_poiseuille"}

Definition at line 7486 of file core.py.

GRID_GENERATOR_CHOICE_FLAGS

dict picurv_cli.core.GRID_GENERATOR_CHOICE_FLAGS

Initial value:

=  {
    "--cross-section": GRID_CROSS_SECTION_KINDS,
}

Definition at line 7909 of file core.py.

GRID_GENERATOR_SPEC_FLAGS

dict picurv_cli.core.GRID_GENERATOR_SPEC_FLAGS

Initial value:

=  {
    "--wall-j-lo": GRID_WALL_SEGMENT_KINDS,
    "--wall-j-hi": GRID_WALL_SEGMENT_KINDS,
    "--wall-j-lo-span": GRID_WALL_SEGMENT_KINDS,
    "--wall-j-hi-span": GRID_WALL_SEGMENT_KINDS,
    "--cross-section-scale": GRID_WALL_SEGMENT_KINDS,
    "--path": GRID_PATH_SEGMENT_KINDS,
    "--transforms": GRID_TRANSFORM_KINDS,
}

Definition at line 7914 of file core.py.

BC_FACE_MAP

dict picurv_cli.core.BC_FACE_MAP

Initial value:

=  {
    "-xi": "-Xi",
    "+xi": "+Xi",
    "-eta": "-Eta",
    "+eta": "+Eta",
    "-zeta": "-Zeta",
    "+zeta": "+Zeta",
}

Definition at line 8065 of file core.py.

BC_TYPE_MAP

dict picurv_cli.core.BC_TYPE_MAP

Initial value:

=  {
    "wall": "WALL",
    "inlet": "INLET",
    "outlet": "OUTLET",
    "periodic": "PERIODIC",
}

Definition at line 8075 of file core.py.

PARTICLE_BOUNDARY_POLICIES

tuple picurv_cli.core.PARTICLE_BOUNDARY_POLICIES = ("reflect", "remove", "wrap")

Definition at line 8085 of file core.py.

BC_HANDLER_SPECS

dict picurv_cli.core.BC_HANDLER_SPECS

Definition at line 8087 of file core.py.

_NUMERIC_BC_PARAMS

dict picurv_cli.core._NUMERIC_BC_PARAMS = {"vx", "vy", "vz", "v_max", "target_flux"}

protected

Definition at line 8147 of file core.py.

_BOOL_BC_PARAMS

dict picurv_cli.core._BOOL_BC_PARAMS = {"enforce_seam_flux", "apply_trim"}

protected

Definition at line 8148 of file core.py.

_DEPRECATED_BC_PARAM_ALIASES

dict picurv_cli.core._DEPRECATED_BC_PARAM_ALIASES = {"apply_trim": "enforce_seam_flux"}

protected

Definition at line 8154 of file core.py.

RANS_PLANNED_REFUSAL

tuple picurv_cli.core.RANS_PLANNED_REFUSAL

Initial value:

=  (
    "models.physics.turbulence.rans is not accepted: RANS closures are planned, not "
    "implemented. No transport equation was ever solved for them, and the selector and "
    "its dead hooks were removed. Remove the block; use models.physics.turbulence.les, "
    "or run laminar."
)

Definition at line 8459 of file core.py.

_CASE_SCHEMA

dict picurv_cli.core._CASE_SCHEMA

protected

Definition at line 9001 of file core.py.

_SOLVER_SCHEMA

dict picurv_cli.core._SOLVER_SCHEMA

protected

Definition at line 9065 of file core.py.

_MONITOR_SCHEMA

dict picurv_cli.core._MONITOR_SCHEMA

protected

Definition at line 9157 of file core.py.

STATISTICS_ELIGIBLE_FIELDS

dict picurv_cli.core.STATISTICS_ELIGIBLE_FIELDS

Initial value:

=  {
    "Ucat": {"components": 3, "requires": None},
    "P": {"components": 1, "requires": None},
    "Nvert": {"components": 1, "requires": None},
    "Phi": {"components": 1, "requires": None},
    "Psi": {"components": 1, "requires": "particles"},
    "ParticleCount": {"components": 1, "requires": "particles"},
    "Nu_t": {"components": 1, "requires": "turbulence"},
    "CS": {"components": 1, "requires": "les"},
}

Definition at line 9208 of file core.py.

STATISTICS_PARTICLE_FIELDS

dict picurv_cli.core.STATISTICS_PARTICLE_FIELDS

Initial value:

=  {
    "Psi": {"components": 1, "requires": "particles", "target": "Psi"},
    "velocity": {"components": 3, "requires": "particles", "target": "Ucat"},
}

Definition at line 9221 of file core.py.

POST_STATISTICS_ENSEMBLE_SOURCES

tuple picurv_cli.core.POST_STATISTICS_ENSEMBLE_SOURCES = ("particles", "eulerian")

Definition at line 9228 of file core.py.

STATISTICS_MOMENT_NAMES

tuple picurv_cli.core.STATISTICS_MOMENT_NAMES = ("first", "second")

Definition at line 9243 of file core.py.

STATISTICS_WEIGHTING_MODES

tuple picurv_cli.core.STATISTICS_WEIGHTING_MODES = ("sample", "physical_time")

Definition at line 9246 of file core.py.

_POST_SCHEMA

dict picurv_cli.core._POST_SCHEMA

protected

Definition at line 9249 of file core.py.

_CLUSTER_SCHEMA

dict picurv_cli.core._CLUSTER_SCHEMA

protected

Initial value:

=  {
    (): {"scheduler", "resources", "notifications", "execution"},
    ("scheduler",): {"type"},
    ("resources",): {"account", "partition", "nodes", "ntasks_per_node", "mem", "time"},
    ("notifications",): {"mail_user", "mail_type"},
    ("execution",): {
        "module_setup", "launcher", "launcher_args", "extra_sbatch", "walltime_guard", "decomposition",
    },
    ("execution", "decomposition"): {"i", "j", "k"},
    ("execution", "extra_sbatch"): None,
    ("execution", "walltime_guard"): {
        "enabled", "warmup_steps", "multiplier", "min_seconds", "estimator_alpha",
    },
}

Definition at line 9287 of file core.py.

_STUDY_SCHEMA

dict picurv_cli.core._STUDY_SCHEMA

protected

Initial value:

=  {
    (): {
        "title", "base_configs", "study_type", "parameters", "parameter_sets", "metrics", "plotting", "execution",
    },
    ("base_configs",): {"case", "solver", "monitor", "post"},
    ("parameters",): None,
    ("parameter_sets", "[]"): None,
    ("metrics", "[]"): {
        "name", "source", "file_glob", "column", "regex", "reduction", "normalize_by_parameter",
        "numerator_column", "denominator_column", "denominator_floor",
        "plot_label", "label", "units",
    },
    ("plotting",): {"enabled", "output_format"},
    ("execution",): {"max_concurrent_array_tasks"},
}

Definition at line 9303 of file core.py.

_WORKSPACE_SCHEMA

dict picurv_cli.core._WORKSPACE_SCHEMA

protected

Initial value:

=  {
    (): {"schema_version", "workspace", "software", "paths", "reproducibility"},
    ("workspace",): {"id", "template", "created_at"},
    ("software",): {"picurv"},
    ("paths",): {"config", "inputs", "assets", "runs", "studies"},
    ("reproducibility",): {"require_clean_release", "pin_executables"},
}

Definition at line 9320 of file core.py.

DIMENSIONLESS

tuple picurv_cli.core.DIMENSIONLESS = (0, 0, 0)

Definition at line 9338 of file core.py.

LENGTH

tuple picurv_cli.core.LENGTH = (1, 0, 0)

Definition at line 9339 of file core.py.

VELOCITY

tuple picurv_cli.core.VELOCITY = (0, 1, 0)

Definition at line 9340 of file core.py.

TIME

tuple picurv_cli.core.TIME = (1, -1, 0)

Definition at line 9341 of file core.py.

WAVENUMBER

tuple picurv_cli.core.WAVENUMBER = (-1, 0, 0)

Definition at line 9342 of file core.py.

VOLUME_FLUX

tuple picurv_cli.core.VOLUME_FLUX = (2, 1, 0)

Definition at line 9343 of file core.py.

DIFFUSIVITY

tuple picurv_cli.core.DIFFUSIVITY = (1, 1, 0)

Definition at line 9344 of file core.py.

PRESSURE

tuple picurv_cli.core.PRESSURE = (0, 2, 1)

Definition at line 9345 of file core.py.

DENSITY

tuple picurv_cli.core.DENSITY = (0, 0, 1)

Definition at line 9346 of file core.py.

DYNAMIC_VISCOSITY

tuple picurv_cli.core.DYNAMIC_VISCOSITY = (1, 1, 1)

Definition at line 9347 of file core.py.

INPUT_CONVERSION_SITES

tuple picurv_cli.core.INPUT_CONVERSION_SITES = ("cli", "c", "staging", "provider", "evaluator", "reference", "passthrough", "")

Definition at line 9357 of file core.py.

NOT_A_QUANTITY

tuple picurv_cli.core.NOT_A_QUANTITY = (None, "")

Definition at line 9359 of file core.py.

UNITLESS

tuple picurv_cli.core.UNITLESS = (DIMENSIONLESS, "")

Definition at line 9360 of file core.py.

INPUT_QUANTITIES

dict picurv_cli.core.INPUT_QUANTITIES

Definition at line 9370 of file core.py.

BC_PARAM_QUANTITIES

dict picurv_cli.core.BC_PARAM_QUANTITIES

Initial value:

=  {
    "vx": (VELOCITY, "cli"),
    "vy": (VELOCITY, "cli"),
    "vz": (VELOCITY, "cli"),
    "v_max": (VELOCITY, "cli"),
    "target_flux": (VOLUME_FLUX, "cli"),
    "enforce_seam_flux": NOT_A_QUANTITY,
    "apply_trim": NOT_A_QUANTITY,
    # Every profile source stages a velocity PICSLICE: a file or generated profile is
    # physical, and a field_slice declares the scales it was written in.
    "source": (VELOCITY, "staging"),
}

Definition at line 9497 of file core.py.

IC_PARAM_QUANTITIES

dict picurv_cli.core.IC_PARAM_QUANTITIES

Initial value:

=  {
    "zero": {},
    "constant": {
        "u_physical": (VELOCITY, "cli"), "v_physical": (VELOCITY, "cli"),
        "w_physical": (VELOCITY, "cli"), "velocity_physical": (VELOCITY, "cli"),
        "flow_direction": NOT_A_QUANTITY,
    },
    "streamwise_constant": {
        "velocity_physical": (VELOCITY, "cli"), "flow_direction": NOT_A_QUANTITY,
    },
    "poiseuille": {
        "peak_velocity_physical": (VELOCITY, "cli"), "flow_direction": NOT_A_QUANTITY,
    },
    "ic_gen": {
        "field": NOT_A_QUANTITY, "script": NOT_A_QUANTITY, "cli_args": NOT_A_QUANTITY,
        # Expressions are written in physical coordinates and physical values.
        "config_file": (None, "provider"),
    },
    "spectral_random_velocity": {
        "field": NOT_A_QUANTITY, "seed": NOT_A_QUANTITY, "remove_mean": NOT_A_QUANTITY,
        "random.distribution": NOT_A_QUANTITY, "random.mean": (VELOCITY, "cli"),
        "spectrum.type": NOT_A_QUANTITY,
        "spectrum.k0": (WAVENUMBER, "cli"), "spectrum.k_cut": (WAVENUMBER, "cli"),
        "projection.type": NOT_A_QUANTITY, "projection.operator": NOT_A_QUANTITY,
        "normalization.type": NOT_A_QUANTITY, "normalization.target": (VELOCITY, "cli"),
    },
}

Definition at line 9512 of file core.py.

RUN_OWNED_DIRECTORY_KEYS

tuple picurv_cli.core.RUN_OWNED_DIRECTORY_KEYS = ("log", "output")

Definition at line 9669 of file core.py.

UNSAFE_PATHS_OVERRIDE_KEY

str picurv_cli.core.UNSAFE_PATHS_OVERRIDE_KEY = "allow_unsafe_paths"

Definition at line 9670 of file core.py.

RESERVED_RUN_DIRECTORY_NAMES

tuple picurv_cli.core.RESERVED_RUN_DIRECTORY_NAMES = ("config", "scheduler", "checkpoints", "visualization")

Definition at line 9676 of file core.py.

RUN_DIRECTORY_DEFAULTS

dict picurv_cli.core.RUN_DIRECTORY_DEFAULTS = {"log": "logs", "output": "output"}

Definition at line 9680 of file core.py.

RESERVED_DIRECTORY_FLAGS

tuple picurv_cli.core.RESERVED_DIRECTORY_FLAGS

Initial value:

=  (
    "-log_dir", "-output_dir", "-restart_dir", "-analysis_dir",
    "-allow_unsafe_log_dir",
)

Definition at line 9684 of file core.py.

RESERVED_INDIRECTION_FLAGS

tuple picurv_cli.core.RESERVED_INDIRECTION_FLAGS = ("-options_file", "-options_file_yaml", "-alias")

Definition at line 9692 of file core.py.

UNSAFE_DIRECTORY_CHARACTERS

tuple picurv_cli.core.UNSAFE_DIRECTORY_CHARACTERS = ('"', "'", "#", "\n", "\r", "\t")

Definition at line 9699 of file core.py.

PHYSICAL_VERDICT_CONTAINED

str picurv_cli.core.PHYSICAL_VERDICT_CONTAINED = "contained"

Definition at line 9935 of file core.py.

PHYSICAL_VERDICT_RUN_ROOT

str picurv_cli.core.PHYSICAL_VERDICT_RUN_ROOT = "run_root"

Definition at line 9936 of file core.py.

PHYSICAL_VERDICT_ANCESTOR

str picurv_cli.core.PHYSICAL_VERDICT_ANCESTOR = "ancestor"

Definition at line 9937 of file core.py.

PHYSICAL_VERDICT_RELATIVE_ESCAPE

str picurv_cli.core.PHYSICAL_VERDICT_RELATIVE_ESCAPE = "relative_escape"

Definition at line 9938 of file core.py.

PHYSICAL_VERDICT_EXTERNAL_ABSOLUTE

str picurv_cli.core.PHYSICAL_VERDICT_EXTERNAL_ABSOLUTE = "external_absolute"

Definition at line 9939 of file core.py.

WAIVABLE_PHYSICAL_VERDICTS

picurv_cli.core.WAIVABLE_PHYSICAL_VERDICTS = frozenset({PHYSICAL_VERDICT_EXTERNAL_ABSOLUTE})

Definition at line 9945 of file core.py.

_SLURM_FAILED_END_STATES

dict picurv_cli.core._SLURM_FAILED_END_STATES

protected

Initial value:

=  {
    "FAILED", "CANCELLED", "TIMEOUT", "OUT_OF_MEMORY", "NODE_FAIL", "PREEMPTED",
    "BOOT_FAIL", "DEADLINE",
}

Definition at line 12395 of file core.py.

RUNTIME_MEMORY_FILE

str picurv_cli.core.RUNTIME_MEMORY_FILE = "Runtime_Memory.csv"

Definition at line 12581 of file core.py.

PROFILING_TIMESTEP_FILE

str picurv_cli.core.PROFILING_TIMESTEP_FILE = "Profiling_Timestep_Summary.csv"

Definition at line 12582 of file core.py.

DIAGNOSTICS_PETSC_KEYS

dict picurv_cli.core.DIAGNOSTICS_PETSC_KEYS

Initial value:

=  {
    "info",
    "malloc_debug",
    "malloc_test",
    "malloc_dump",
    "malloc_view",
    "malloc_view_threshold",
    "memory_view",
    "log_view",
    "log_view_memory",
    "log_all",
    "log_trace",
    "objects_dump",
    "options_left",
}

Definition at line 12650 of file core.py.

PROGRAMMATIC_BRIDGE_GRID_KEYS

tuple picurv_cli.core.PROGRAMMATIC_BRIDGE_GRID_KEYS

Initial value:

=  (
    "im", "jm", "km",
    "xMins", "xMaxs", "yMins", "yMaxs", "zMins", "zMaxs",
    "rxs", "rys", "rzs",
)

Definition at line 13489 of file core.py.

GRID_DA_PROCESSOR_KEYS

tuple picurv_cli.core.GRID_DA_PROCESSOR_KEYS = ("da_processors_x", "da_processors_y", "da_processors_z")

Definition at line 13615 of file core.py.

IC_PAYLOAD_DIMENSIONS

dict picurv_cli.core.IC_PAYLOAD_DIMENSIONS = {0: VELOCITY, 1: VOLUME_FLUX}

Definition at line 14389 of file core.py.

GENERATED_IC_PROVIDERS

dict picurv_cli.core.GENERATED_IC_PROVIDERS

Initial value:

=  {
    "channel_spectral_velocity": {"requires_grid": True, "requires_fresh_3d": True},
    "duct_spectral_velocity": {"requires_grid": True, "requires_fresh_3d": True},
    "stability_mode_velocity": {"requires_grid": True},
    "ic_gen": {
        "requires_grid": True,
        "diagnostic_artifacts": (),
    },
    "spectral_random_velocity": {
        "requires_grid": True,
        "requires_periodic_geometric": True,
        "requires_fresh_3d": True,
        "diagnostic_artifacts": (
            ("summary_json", os.path.join(CANONICAL_RUN_PATHS["metrics"], "initial_condition_summary.json")),
            ("spectrum_csv", INITIAL_CONDITION_SPECTRUM_RELPATH),
        ),
    },
}

Definition at line 14449 of file core.py.

PARTICLE_SETTABLE_FIELDS

dict picurv_cli.core.PARTICLE_SETTABLE_FIELDS = {"Psi": 1}

Definition at line 14530 of file core.py.

PETSC_INDEX_BITS_CHOICES

tuple picurv_cli.core.PETSC_INDEX_BITS_CHOICES = ("32", "64")

Definition at line 14991 of file core.py.

PETSC_MAX_INT_32BIT

int picurv_cli.core.PETSC_MAX_INT_32BIT = 2**31 - 1

Definition at line 14993 of file core.py.

PARTICLE_FIELD_MAX_COMPONENTS

int picurv_cli.core.PARTICLE_FIELD_MAX_COMPONENTS = 3

Definition at line 14996 of file core.py.

GRID_FIELD_MAX_COMPONENTS

int picurv_cli.core.GRID_FIELD_MAX_COMPONENTS = 3

Definition at line 14997 of file core.py.

STATISTICS_FIELD_COMPONENTS

int picurv_cli.core.STATISTICS_FIELD_COMPONENTS = 6

Definition at line 14998 of file core.py.

LES_MODEL_NAMES

dict picurv_cli.core.LES_MODEL_NAMES = {1: "constant_smagorinsky", 2: "dynamic_smagorinsky", 3: "vreman", 4: "wale"}

Definition at line 15758 of file core.py.

LES_MODEL_OWNED_KEYS

dict picurv_cli.core.LES_MODEL_OWNED_KEYS

Initial value:

=  {
    1: ("constant_cs",),
    2: ("dynamic_frequency", "test_filter", "averaging", "clipping"),
    3: ("vreman_coefficient",),
    4: ("wale_coefficient",),
}

Definition at line 15761 of file core.py.

LES_MODEL_KEY_OWNER_DESCRIPTIONS

dict picurv_cli.core.LES_MODEL_KEY_OWNER_DESCRIPTIONS

Initial value:

=  {
    1: "the constant Smagorinsky coefficient",
    2: "the dynamic procedure",
    3: "the Vreman model",
    4: "the WALE model",
}

Definition at line 15769 of file core.py.

LES_AVERAGING_DIRECTION_AXES

tuple picurv_cli.core.LES_AVERAGING_DIRECTION_AXES = ("i", "j", "k")

Definition at line 15935 of file core.py.

SOLVER_MONITORING_POISSON_FLAG_MAP

dict picurv_cli.core.SOLVER_MONITORING_POISSON_FLAG_MAP

Initial value:

=  {
    "pic_true_residual": "-ps_ksp_pic_monitor_true_residual",
    "true_residual": "-ps_ksp_monitor_true_residual",
    "converged_reason": "-ps_ksp_converged_reason",
    "view": "-ps_ksp_view",
}

Definition at line 16237 of file core.py.

SOLVER_MONITORING_MOMENTUM_FLAG_MAP

dict picurv_cli.core.SOLVER_MONITORING_MOMENTUM_FLAG_MAP

Initial value:

=  {
    "newton_krylov_history": "-mom_nk_pic_monitor",
    "snes_monitor": "-mom_nk_snes_monitor",
    "snes_converged_reason": "-mom_nk_snes_converged_reason",
    "ksp_monitor": "-mom_nk_ksp_monitor",
    "ksp_converged_reason": "-mom_nk_ksp_converged_reason",
}

Definition at line 16244 of file core.py.

MAX_TRACED_PARTICLES

int picurv_cli.core.MAX_TRACED_PARTICLES = 64

Definition at line 16326 of file core.py.

KRYLOV_KSP_TYPES

dict picurv_cli.core.KRYLOV_KSP_TYPES

Initial value:

=  {
    "gmres", "fgmres", "lgmres", "dgmres", "pgmres", "gcr",
    "cg", "cgne", "cgs", "bcgs", "ibcgs", "fbcgs", "fbcgsr", "bcgsl",
    "tfqmr", "tcqmr", "minres", "symmlq", "cr", "lsqr", "pipecg", "pipefgmres",
}

Definition at line 16430 of file core.py.

_STUDY_REPORT_COLORS

tuple picurv_cli.core._STUDY_REPORT_COLORS

protected

Initial value:

=  (
    "#0072B2", "#D55E00", "#009E73", "#CC79A7",
    "#E69F00", "#56B4E9", "#332288", "#999999",
)

Definition at line 18282 of file core.py.

ASSET_KIND_DIRECTORIES

dict picurv_cli.core.ASSET_KIND_DIRECTORIES

Initial value:

=  {
    "grid": "grids",
    "initial-condition": "initial_conditions",
    "inlet-profiles": "inlet_profiles",
}

Definition at line 19500 of file core.py.

ASSET_PREVIEW_NODE_LIMIT

int picurv_cli.core.ASSET_PREVIEW_NODE_LIMIT = 2_000_000

Definition at line 19862 of file core.py.

_SUMMARY_NUMERIC_RE

picurv_cli.core._SUMMARY_NUMERIC_RE = re.compile(r"[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?")

protected

Definition at line 22050 of file core.py.

_CONFIG_SUMMARY_WIDTH

int picurv_cli.core._CONFIG_SUMMARY_WIDTH = 78

protected

Definition at line 23526 of file core.py.

_SUMMARY_PLOT_LOG_SCALE_FIELDS

dict picurv_cli.core._SUMMARY_PLOT_LOG_SCALE_FIELDS

protected

Initial value:

=  {
    "max_divergence", "delta_norm", "delta_rel", "residual_norm", "residual_rel",
    "unpreconditioned_norm", "true_norm", "relative_norm",
    "u_abs_l2", "u_rel_l2", "p_abs_l2", "p_rel_l2",
    "spd_abs", "spd_rel", "ke_abs", "ke_rel",
    "spd_win_abs", "spd_win_rel", "spd_rms_abs", "spd_rms_rel",
    "ke_win_abs", "ke_win_rel", "ke_rms_abs", "ke_rms_rel",
    "parseval_residual", "zero_mode_energy",
}

Definition at line 23824 of file core.py.

_SUMMARY_PLOT_FIELD_LABELS

dict picurv_cli.core._SUMMARY_PLOT_FIELD_LABELS

protected

Definition at line 23835 of file core.py.

_SUMMARY_PLOT_SOURCE_TITLES

dict picurv_cli.core._SUMMARY_PLOT_SOURCE_TITLES

protected

Initial value:

=  {
    "continuity": "Continuity",
    "particles": "Particle transport",
    "momentum": "Momentum solver",
    "poisson": "Pressure Poisson solver",
    "profiling": "Runtime profile",
    "memory": "Runtime memory",
    "convergence": "Solution convergence",
    "spectra": "Turbulence spectrum",
}

Definition at line 23910 of file core.py.

_SUMMARY_ITERATION_HISTORY_FIELDS

dict picurv_cli.core._SUMMARY_ITERATION_HISTORY_FIELDS

protected

Initial value:

=  {
    "dtau", "dtau_after", "cfl_eff", "cfl_eff_after", "delta_norm", "delta_rel",
    "residual_norm", "residual_rel", "trial_ratio", "smoothed_ratio",
    "unpreconditioned_norm", "true_norm", "relative_norm",
}

Definition at line 23922 of file core.py.

_SUMMARY_COUNT_FIELDS

dict picurv_cli.core._SUMMARY_COUNT_FIELDS

protected

Initial value:

=  {
    "total_particles", "lost_particles", "lost_particles_cumulative",
    "exited_particles", "exited_particles_cumulative", "migrated_particles", "occupied_cells", "migration_passes", "calls",
    "pseudo_iterations", "newton_iterations", "iterations",
}

Definition at line 23929 of file core.py.

_LEGACY_PICARD_REGEX

picurv_cli.core._LEGACY_PICARD_REGEX

protected

Initial value:

=  re.compile(
    r"Step:\s*(?P<step>\d+)\s*\|\s*PseudoIter\‍(k\‍):\s*(?P<pseudo_iter>\d+)\s*\|"
    r"\s*dtau:\s*(?P<dtau>[-+0-9.eE]+)\s*\|\s*cfl_eff:\s*(?P<cfl_eff>[-+0-9.eE]+)\s*\|"
    r"\s*\|dUk\|:\s*(?P<delta>[-+0-9.eE]+)\s*\|"
    r"\s*\|dUk\|/\|dU0\|:\s*(?P<delta_rel>[-+0-9.eE]+)\s*\|\s*\|Rk\|:\s*(?P<resid>[-+0-9.eE]+)\s*\|"
    r"\s*\|Rk\|/\|R0\|:\s*(?P<resid_rel>[-+0-9.eE]+)"
    r"(?:\s*\|\s*trial_ratio:\s*(?P<trial_ratio>[-+0-9.eE]+)"
    r"(?:\s*\|\s*smoothed_ratio:\s*(?P<smoothed_ratio>[-+0-9.eE]+))?"
    r"\s*\|\s*status:\s*(?P<status>\w+)\s*\|\s*dtau_after:\s*(?P<dtau_after>[-+0-9.eE]+)"
    r"(?:\s*\|\s*cfl_eff_after:\s*(?P<cfl_eff_after>[-+0-9.eE]+))?)?"
)

Definition at line 24165 of file core.py.

_LEGACY_NEWTON_HISTORY_REGEX

picurv_cli.core._LEGACY_NEWTON_HISTORY_REGEX

protected

Initial value:

=  re.compile(
    r"step:\s*(?P<step>\d+)\s*\|\s*block:\s*(?P<block>\d+)\s*\|"
    r"\s*newton:\s*(?P<newton>\d+)\s*\|\s*nonlinear_norm:\s*(?P<norm>[-+0-9.eE]+)"
)

Definition at line 24239 of file core.py.

_LEGACY_NEWTON_SUMMARY_REGEX

picurv_cli.core._LEGACY_NEWTON_SUMMARY_REGEX

protected

Initial value:

=  re.compile(
    r"step:\s*(?P<step>\d+)\s*\|\s*block:\s*(?P<block>\d+)\s*\|"
    r"\s*solver:\s*(?P<solver>[^|]+?)\s*\|"
    r"(?:\s*Jacobian:\s*[^|]+?\s*\|\s*Preconditioner:\s*[^|]+?\s*\|)?"
    r"\s*reason:\s*(?P<reason>\S+)\s*\|"
    r"\s*reason_code:\s*(?P<reason_code>-?\d+)\s*\|\s*newton:\s*(?P<newton>\d+)\s*\|"
    r"\s*evals:\s*(?P<evals>\d+)\s*\|\s*krylov:\s*(?P<krylov>\d+)\s*\|"
    r"\s*initial:\s*(?P<initial>[-+0-9.eE]+|unavailable)\s*\|"
    r"\s*final:\s*(?P<final>[-+0-9.eE]+)\s*\|\s*state:\s*(?P<state>\w+)"
)

Definition at line 24243 of file core.py.

_LEGACY_POISSON_REGEX

picurv_cli.core._LEGACY_POISSON_REGEX

protected

Initial value:

=  re.compile(
    r"ts:\s*(?P<step>\d+)\s*\|\s*block:\s*(?P<block>\d+)\s*\|\s*iter:\s*(?P<iter>\d+)\s*\|"
    r"\s*Unprecond Norm:\s*(?P<unpre>[-+0-9.eE]+)\s*\|\s*True Norm:\s*(?P<true>[-+0-9.eE]+)"
    r"(?:\s*\|\s*Rel Norm:\s*(?P<rel>[-+0-9.eE]+))?"
)

Definition at line 24339 of file core.py.

_PLOT_ROW_IDENTITY_KEYS

tuple picurv_cli.core._PLOT_ROW_IDENTITY_KEYS = ("step", "block")

protected

Definition at line 24430 of file core.py.

SUMMARY_TABLES

dict picurv_cli.core.SUMMARY_TABLES

Initial value:

=  {
    "continuity": ("log_dir", "Continuity_Metrics.csv"),
    "convergence": ("log_dir", "solution_convergence.csv"),
    "memory": ("log_dir", RUNTIME_MEMORY_FILE),
    "profiling": ("log_dir", "ProfilingSummary_Solver.csv"),
    "profiling-post": ("log_dir", "ProfilingSummary_PostProcessor.csv"),
    "profiling-steps": ("log_dir", PROFILING_TIMESTEP_FILE),
    "picard": ("log_dir", "Momentum_Solver_DualTime_Picard_Jameson_RK_History_Block_{block}.csv"),
    "newton": ("log_dir", "Momentum_Solver_Newton_Krylov_Summary_Block_{block}.csv"),
    "newton-history": ("log_dir", "Momentum_Solver_Newton_Krylov_History_Block_{block}.csv"),
    "newton-linear": ("log_dir", "Momentum_Solver_Newton_Krylov_Linear_History_Block_{block}.csv"),
    "poisson": ("log_dir", "Poisson_Solver_Convergence_History_Block_{block}.csv"),
    "search": ("metrics_dir", "search_metrics.csv"),
    "scatter": ("metrics_dir", "scatter_metrics.csv"),
    "interpolation-error": ("metrics_dir", "interpolation_error.csv"),
    "les": ("metrics_dir", "les_coefficient.csv"),
    "wall-model": ("metrics_dir", "wall_model.csv"),
    "driven-flow": ("metrics_dir", "driven_flow.csv"),
    "particle-initial-fields": ("metrics_dir", "particle_initial_fields.csv"),
}

Definition at line 25110 of file core.py.

WORKSPACE_INPUT_DIRECTORIES

dict picurv_cli.core.WORKSPACE_INPUT_DIRECTORIES

Initial value:

=  {
    "grid": "inputs/grids",
    "initial-condition": "inputs/initial_conditions",
    "inlet-profile": "inputs/inlet_profiles",
    "reference-field": "inputs/reference_fields",
}

Definition at line 26477 of file core.py.