|
PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
|
A comprehensive conductor script for the PICurv simulation platform. More...
Go to the source code of this file.
Data Structures | |
| class | picurv_cli.core._LazyNumpyProxy |
Module-like proxy that preserves picurv.np without eager import. More... | |
| class | picurv_cli.core.CommandExecutionError |
| Raised when an external command exits unsuccessfully. More... | |
| class | picurv_cli.core.PlotDependencyError |
| Raised when plot.gen reports a missing optional dependency. More... | |
Namespaces | |
| namespace | picurv_cli |
| namespace | picurv_cli.core |
Functions | |
| picurv_cli.core._prune_incompatible_python_site_paths (paths) | |
| Remove site-package paths for a different Python major/minor version. | |
| picurv_cli.core._drop_imported_package (str package_name) | |
| Remove a failed/partial import package tree from sys.modules. | |
| picurv_cli.core.require_numpy () | |
| Import NumPy only for commands that need numeric reductions. | |
| picurv_cli.core.optional_matplotlib_pyplot () | |
| Import matplotlib.pyplot lazily for study plot generation. | |
| int | picurv_cli.core.parse_slurm_time_limit_to_seconds (str time_text) |
| Parse a Slurm time-limit string into total seconds. | |
| "dict | None" | picurv_cli.core.resolve_walltime_guard_policy ("dict | None" cluster_cfg) |
| Resolve the effective Slurm walltime-guard policy for generated solver jobs. | |
| dict | picurv_cli.core.build_walltime_guard_exports ("dict | None" cluster_cfg) |
| Build shell-evaluated environment exports for the runtime walltime guard. | |
| str | picurv_cli.core.resolve_runtime_executable (str executable_name) |
| Resolve solver/post executable path, preferring local sibling binaries. | |
| str | picurv_cli.core._sanitize_error_field (value) |
| Normalize error fields into a single-line string. | |
| 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. | |
| picurv_cli.core.fail_cli_usage (str message, str hint=None) | |
| Emit a structured CLI usage error and exit with code 2. | |
| picurv_cli.core._split_error_file_and_message (str raw_error) | |
| Split '<file>: <message>' style validation strings when possible. | |
| str | picurv_cli.core._extract_key_path (str message) |
| Best-effort key-path extraction from free-form validation messages. | |
| str | picurv_cli.core._classify_error_code (str message) |
| Map existing validation/error messages to the standardized code set. | |
| dict | picurv_cli.core.read_yaml_file (str filepath) |
| Safely reads a YAML file and returns its content. | |
| picurv_cli.core.write_yaml_file (str filepath, dict data) | |
| Write YAML with stable ordering for generated study artifacts. | |
| picurv_cli.core.write_json_file (str filepath, dict payload) | |
| Write JSON metadata/manifests with a stable, readable format. | |
| 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. | |
| bool | picurv_cli.core._launcher_arg_contains_whitespace (token) |
| Return True when a launcher arg token contains embedded whitespace and should be split. | |
| "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. | |
| 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. | |
| bool | picurv_cli.core.is_project_root (str candidate) |
| Return True when a directory looks like the PICurv source repository root. | |
| picurv_cli.core._iter_parent_dirs (str start_path) | |
| Yield a path and all of its parents up to filesystem root. | |
| picurv_cli.core.find_project_root_upwards (str start_path) | |
| Search upward from an anchor and return the first matching project root. | |
| picurv_cli.core.discover_local_project_root (*extra_anchors) | |
| Best-effort source repo discovery from runtime anchors. | |
| picurv_cli.core.find_case_origin_metadata_file (str case_dir_hint=None) | |
| Find the nearest case-origin metadata file from known runtime anchors. | |
| picurv_cli.core.load_case_origin_metadata (str case_dir_hint=None) | |
| Load case-origin metadata if present, returning (case_dir, metadata_path, payload). | |
| picurv_cli.core.find_runtime_execution_config_file (*anchors) | |
| Find the nearest optional execution config from runtime/case anchors. | |
| dict | picurv_cli.core._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. | |
| 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. | |
| dict | picurv_cli.core.merge_execution_overrides ("dict | None" base, "dict | None" override) |
| Merge execution overrides, letting explicit override values win key-by-key. | |
| dict | picurv_cli.core.resolve_runtime_execution_context (dict runtime_execution_cfg, str context) |
| Resolve default plus context-specific execution overrides. | |
| str | picurv_cli.core.get_git_commit (str repo_root=None) |
| Best-effort git commit lookup for run/study manifests and case 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. | |
| 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. | |
| 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. | |
| picurv_cli.core.require_project_root (str candidate, str purpose) | |
| Validate that a source repo root was resolved and is structurally valid. | |
| 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. | |
| picurv_cli.core.resolve_template_directory (str source_project_root, str template_name) | |
| Resolve an example template directory inside the source repository. | |
| 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. | |
| picurv_cli.core.list_source_binaries (str source_project_root) | |
| List binary artifacts currently available in the source repo bin directory. | |
| 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. | |
| picurv_cli.core.sync_case_template_files (str case_dir, str template_dir, bool overwrite=False, bool prune=False, managed_rel_paths=None) | |
| Sync template files into a case directory, preserving modified files unless overwrite is requested. | |
| 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. | |
| picurv_cli.core.print_case_source_status (dict status) | |
| Render human-readable source/case drift details. | |
| picurv_cli.core.status_source_command (args) | |
| Report source/case drift for an initialized case directory. | |
| str | picurv_cli.core.resolve_path (str anchor_file, str candidate) |
| Resolve a potentially relative path against a source YAML file path. | |
| picurv_cli.core._mapping_value_with_aliases (dict mapping, *keys, default=None) | |
| Return the first defined value from a mapping across alias keys. | |
| 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. | |
| 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. | |
| picurv_cli.core.get_post_source_data (dict post_cfg) | |
| Return source_data as a mapping when valid, else an empty mapping. | |
| 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. | |
| picurv_cli.core.get_post_input_extensions (dict post_cfg) | |
| Return post input_extensions, preferring io. | |
| picurv_cli.core.get_post_statistics_task_tokens (dict post_cfg) | |
| Return normalized statistics pipeline tokens that will be written into post.run. | |
| 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. | |
| 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. | |
| 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. | |
| 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. | |
| 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. | |
| dict | picurv_cli.core.normalize_post_recipe_signature (dict recipe_cfg) |
| Normalize post recipe settings into a stable signature mapping. | |
| "tuple[dict, str]" | picurv_cli.core.compute_post_recipe_fingerprint (dict recipe_cfg) |
| Return normalized recipe signature plus SHA-256 fingerprint. | |
| picurv_cli.core.parse_post_recipe_file (str post_recipe_path) | |
| Parse an existing generated post.run file into a key/value mapping. | |
| str | picurv_cli.core.get_post_resume_state_path (str run_dir) |
| Return the JSON resume metadata path for a run directory. | |
| dict | picurv_cli.core.get_post_lock_paths (str run_dir) |
| Return lock-wrapper related paths for a run directory. | |
| str | picurv_cli.core._post_output_directory_abs (str run_dir, dict post_cfg) |
| Resolve the absolute post output directory for the current recipe. | |
| bool | picurv_cli.core._post_requests_eulerian_output (dict post_cfg) |
| Return whether the current post recipe expects Eulerian VTK output artifacts. | |
| bool | picurv_cli.core._post_requests_particle_output (dict post_cfg) |
| Return whether the current post recipe expects particle VTP output artifacts. | |
| bool | picurv_cli.core._post_requests_statistics (dict post_cfg) |
| Return whether the current post recipe expects statistics CSV artifacts. | |
| bool | picurv_cli.core._post_needs_particle_source (dict post_cfg) |
| Return whether the current post recipe requires particle source files to be present. | |
| picurv_cli.core._iter_post_steps (int start_step, int end_step, int step_interval) | |
| Yield configured post-processing steps inclusively. | |
| "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. | |
| 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. | |
| "set[int]" | picurv_cli.core._scan_post_vtk_steps (str prefix_path, str extension) |
| Scan VTK output files matching '<prefix>_<step>. | |
| "set[int]" | picurv_cli.core._scan_post_statistics_csv_steps (str csv_path) |
| Scan step ids from the first CSV column of a statistics artifact. | |
| "list[set[int]]" | picurv_cli.core.collect_post_completion_families (str run_dir, dict post_cfg, monitor_cfg=None) |
| Collect per-family completed-step sets for the current post recipe. | |
| dict | picurv_cli.core.detect_post_completed_frontier (str run_dir, dict post_cfg, monitor_cfg, int start_step, int end_step, int step_interval) |
| Detect the highest contiguous fully completed post step for the current recipe. | |
| picurv_cli.core._nearest_step ("set[int]" steps, int target) | |
| Return the complete source step nearest to a target step. | |
| str | picurv_cli.core._format_optional_step (step) |
| Format an optional step number for user-facing diagnostics. | |
| "tuple[set[int], dict]" | picurv_cli.core._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]" | picurv_cli.core._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 | 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. | |
| picurv_cli.core.persist_post_resume_state (str run_dir, dict plan, last_successful_requested_end_step=None) | |
| Persist post resume lineage metadata for future –continue runs. | |
| str | picurv_cli.core._build_post_lock_wrapper_source () |
| Return the Python wrapper used to hold an exclusive post-stage lock. | |
| str | picurv_cli.core.ensure_post_lock_wrapper (str run_dir) |
| Ensure the lock wrapper exists for a run directory and return its path. | |
| "tuple[list, dict]" | picurv_cli.core.build_post_locked_command (str run_dir, str recipe_fingerprint, list wrapped_command, bool create_wrapper=True) |
| Wrap a postprocessor command behind the run-dir-scoped lock wrapper. | |
| dict | picurv_cli.core.build_post_execution_plan (str run_dir, str run_id, dict case_cfg, dict monitor_cfg, dict post_cfg, bool continue_requested=False, bool allow_source_frontier_scan=True) |
| Resolve post resume/source-availability behavior into one execution plan. | |
| bool | picurv_cli.core.needs_restart_source (dict case_cfg, dict solver_cfg) |
| Return True when the solver requires restart data from disk. | |
| str | picurv_cli.core.resolve_run_output_dir (str run_dir, dict monitor_cfg) |
| Resolve the output data directory within a run directory. | |
| str | picurv_cli.core.resolve_run_restart_dir (str run_dir, dict monitor_cfg) |
| Resolve the restart staging directory within a run directory. | |
| picurv_cli.core.populate_restart_directory (str source_output, str target_restart, int start_step, dict monitor_cfg) | |
| Copy checkpoint files for a specific step from source output to target restart. | |
| picurv_cli.core.detect_last_checkpoint_step (str output_dir, str euler_subdir="eulerian", str particle_subdir="particles") | |
| Scan output directory for the highest step number available. | |
| 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. | |
| 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. | |
| 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. | |
| dict | picurv_cli.core.read_monitor_from_run (str run_dir) |
| Read the monitor.yml from a run directory's config/ subdirectory. | |
| picurv_cli.core.resolve_restart_source (args, dict case_cfg, dict solver_cfg, dict monitor_cfg, str run_dir) | |
| Resolve the restart source directory based on –restart-from or –continue CLI flags. | |
| 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. | |
| 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. | |
| bool | picurv_cli.core.is_valid_email (str email) |
| Lightweight email validation for scheduler notifications. | |
| str | picurv_cli.core.normalize_statistics_task (str task_name) |
| Normalizes user-facing statistics task names to C pipeline keywords. | |
| picurv_cli.core._iter_nonempty_noncomment_lines (file_obj) | |
| Yield (lineno, stripped_line) for non-empty, non-comment lines. | |
| 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. | |
| list | picurv_cli.core.read_picgrid_header_dimensions (str source_grid, int expected_nblk=None) |
| Read only the canonical PICGRID header dimensions. | |
| 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. | |
| str | picurv_cli.core._face_artifact_token (str face) |
| Convert a BC face token into a filesystem-friendly artifact token. | |
| str | picurv_cli.core._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 | picurv_cli.core._resolve_generator_script (str configured_script, str case_path, str default_name) |
| Resolve an optional generator script override or repository default. | |
| dict | picurv_cli.core._normalize_square_duct_poiseuille_params (params, str field_name) |
| Validate square-duct Poiseuille generator parameters. | |
| dict | picurv_cli.core._normalize_field_slice_source (source, str field_name) |
| Validate a prescribed_flow field_slice source block. | |
| dict | picurv_cli.core._normalize_field_slice_selector (slice_cfg, str field_name) |
| Validate the field_slice slice selector. | |
| 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. | |
| 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. | |
| str | picurv_cli.core._resolve_case_relative_path (str path_value, str case_dir) |
| Resolve a path relative to the current case directory. | |
| float | picurv_cli.core._resolve_field_slice_velocity_scale (dict source, str case_dir) |
| Resolve field_slice dimensional velocity scale. | |
| 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. | |
| str | picurv_cli.core.resolve_target_grid_for_generated_profile (dict case_cfg, str case_path, str run_dir) |
| Resolve an optional target canonical PICGRID for generated profile sampling. | |
| str | picurv_cli.core.write_profile_info (str config_dir, list summaries) |
| Write a profile.info summary for generated inlet profiles. | |
| str | picurv_cli.core.run_grid_generator (str case_path, str run_dir, dict grid_cfg) |
| Runs generators/grid.gen to produce a PICGRID file for this run. | |
| str | picurv_cli.core.convert_legacy_grid_with_gridgen (str case_path, str run_dir, dict grid_cfg, str source_grid) |
| Optionally convert a legacy file-grid payload to canonical PICGRID using grid.gen. | |
| dict | picurv_cli.core._normalize_prescribed_flow_source (source, str field_name) |
| Validate the structured source block for prescribed_flow BCs. | |
| tuple | picurv_cli.core._bc_profile_expected_dims (str face, tuple block_dims) |
| Return expected PICSLICE dimensions for a face and block node dimensions. | |
| 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. | |
| 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. | |
| float | picurv_cli.core._to_float (value, str field_name) |
| Convert a YAML scalar to float with a clear error message. | |
| bool | picurv_cli.core._to_bool (value, str field_name) |
| Convert a YAML scalar/string to bool with a clear error message. | |
| 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. | |
| picurv_cli.core.validate_and_prepare_boundary_conditions (dict case_cfg) | |
| Validate BC entries against currently supported C-side handlers/types and. | |
| str | picurv_cli.core._schema_path_text (tuple path) |
| Render an internal schema path tuple as a user-facing YAML path. | |
| picurv_cli.core._lookup_allowed_schema_keys (dict schema, tuple path) | |
| Return allowed keys for a path, honoring '*' dynamic mapping entries. | |
| str | picurv_cli.core._schema_key_hint (dict schema, tuple path, str key, set allowed) |
| Build a concise typo or hierarchy hint for an unsupported YAML key. | |
| None | picurv_cli.core._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. | |
| picurv_cli.core.validate_solver_configs (dict case_cfg, dict solver_cfg, dict monitor_cfg, str case_path, str solver_path, str monitor_path) | |
| Validates all solver input configs before any work is done. | |
| picurv_cli.core.validate_post_config (dict post_cfg, str post_path) | |
| Validates the post-processing config before running the post-processor. | |
| picurv_cli.core.validate_cluster_config (dict cluster_cfg, str cluster_path) | |
| Validate Slurm scheduler configuration from cluster.yml. | |
| 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. | |
| picurv_cli.core._deep_set (dict container, str dotted_path, value) | |
| Set nested dictionary value, creating intermediate maps when needed. | |
| list | picurv_cli.core.expand_parameter_matrix (dict parameters) |
| Expand study parameter lists into cartesian-product combinations. | |
| list | picurv_cli.core.expand_study_parameter_combinations (dict study_cfg) |
| Expand either cartesian-study parameters or explicit parameter sets. | |
| 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. | |
| int | picurv_cli.core.get_cluster_total_tasks (dict cluster_cfg) |
| Return cluster total tasks. | |
| str | picurv_cli.core.normalize_extension (str ext) |
| Normalize extension. | |
| 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) | |
| Render a Slurm batch script for a single command. | |
| "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. | |
| "tuple[str | None, list[str]]" | picurv_cli.core.normalize_cluster_launcher (dict execution) |
| Canonicalize cluster launcher config into executable token plus argv-style 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. | |
| dict | picurv_cli.core.build_serial_post_cluster_config (dict cluster_cfg, int num_procs=1) |
| Clone cluster config and force a single-node post stage task layout. | |
| 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. | |
| 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. | |
| 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. | |
| str | picurv_cli.core.parse_slurm_job_id (str sbatch_output) |
| Extract numeric job id from standard sbatch output. | |
| dict | picurv_cli.core.submit_sbatch (str script_path, str dependency=None, str dependency_type="afterok") |
| Submit sbatch script and return submission metadata. | |
| picurv_cli.core._print_validation_errors (list errors) | |
| Prints validation errors and exits. | |
| str | picurv_cli.core.generate_header (str run_id, dict source_files) |
| Creates a standard header block for all generated files. | |
| 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) |
| Generic function to create a file containing a simple list of strings. | |
| bool | picurv_cli.core.has_explicit_monitor_whitelist (dict monitor_cfg) |
| Return True when logging.enabled_functions contains at least one entry. | |
| dict | picurv_cli.core.resolve_profiling_config (dict monitor_cfg) |
| Resolve profiling reporting config from monitor.yml. | |
| picurv_cli.core._diagnostic_bool_or_path (value, str key) | |
| Validate a diagnostics value that can be false, true, or a path/viewer string. | |
| bool | picurv_cli.core._diagnostic_bool (value, str key) |
| Validate a diagnostics boolean value. | |
| picurv_cli.core._diagnostic_bool_or_all (value, str key) | |
| Validate a diagnostics value that can be false, true, or "all". | |
| str | picurv_cli.core._diagnostic_default_file (str run_dir, str filename) |
| Return an absolute run-local diagnostics file path. | |
| picurv_cli.core._diagnostic_resolve_path_or_default (value, str run_dir, str default_filename) | |
| Resolve true/string diagnostics values to a concrete file path. | |
| 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. | |
| 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. | |
| dict | picurv_cli.core.prepare_monitor_files (str run_dir, str run_id, dict monitor_cfg, dict source_files) |
| Generate monitor sidecar files and resolve profiling reporting behavior. | |
| list | picurv_cli.core.generate_multi_block_bcs (str run_dir, str run_id, dict case_cfg, dict source_files) |
| Parses multi-block BCs from YAML, generates a .run file for each block, and returns a list of their absolute paths. | |
| picurv_cli.core.format_flag_value (value) | |
| Converts Python types to C-style command-line flag values. | |
| dict | picurv_cli.core.translate_programmatic_grid_settings (dict grid_settings) |
| Return programmatic-grid settings translated to the C node-count contract. | |
| 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. | |
| 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. | |
| None | picurv_cli.core.append_grid_da_processor_layout (list control_lines, dict grid_cfg, int num_procs) |
| Append optional global DMDA layout flags for any grid mode. | |
| str | picurv_cli.core.normalize_momentum_solver_type (str value) |
| Maps canonical user-facing momentum solver names to C-enum CLI values. | |
| str | picurv_cli.core.normalize_solution_convergence_mode (str value) |
| Normalizes the solution-convergence mode selector to the C-side canonical string. | |
| int | picurv_cli.core.normalize_field_init_mode (str value) |
| Maps canonical field init mode names to C enum/int codes (-finit). | |
| "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. | |
| dict | picurv_cli.core.resolve_initial_condition_config (dict ic, prepared_blocks, float U_ref) |
| Resolve legacy and structured initial-condition YAML into one launcher contract. | |
| dict | picurv_cli.core.validate_petsc_vec_binary (str path) |
| Validate the basic PETSc binary VecView envelope used by ReadFieldData. | |
| str | picurv_cli.core.run_initial_condition_generator (str case_path, str run_dir, dict resolved_ic) |
| Run the repository IC generator. | |
| 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. | |
| int | picurv_cli.core.normalize_flow_direction_token (str value) |
| Maps a face-token flow direction string to the C FlowDirection enum integer. | |
| bool | picurv_cli.core._ic_has_inlet (prepared_blocks) |
| Return True if any prepared BC block contains an INLET face. | |
| dict | picurv_cli.core.resolve_ic_cli_params (dict ic, int finit_code, prepared_blocks, float U_ref) |
| Resolve all IC parameters and return a dict of PETSc option values. | |
| str | picurv_cli.core.normalize_eulerian_field_source (str value) |
| Normalizes the Eulerian field source selector to the C-side canonical string. | |
| str | picurv_cli.core.normalize_analytical_type (str value) |
| Normalizes the analytical solution selector to the C-side canonical string. | |
| "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. | |
| "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. | |
| int | picurv_cli.core.normalize_particle_init_mode (str value) |
| Maps canonical particle init mode names to C enum/int codes (-pinit). | |
| int | picurv_cli.core.normalize_interpolation_method (str value) |
| Maps interpolation method names to C enum/int codes (-interpolation_method). | |
| int | picurv_cli.core.normalize_les_model (value) |
| Maps LES model selectors to C enum/int codes (-les). | |
| int | picurv_cli.core.normalize_les_test_filter (value) |
| Maps LES test-filter names to the C -testfilter_ik flag. | |
| int | picurv_cli.core.normalize_rans_model (value) |
| Maps RANS model selectors to the current C -rans switch. | |
| str | picurv_cli.core.normalize_wall_function_model (value) |
| Validates wall-function model selectors exposed in YAML. | |
| bool | picurv_cli.core.resolve_enabled_flag (dict cfg, str path, bool default=True) |
Resolves a structured enabled flag and rejects non-boolean values. | |
| picurv_cli.core.append_turbulence_flags (dict models, list control_lines) | |
| Appends turbulence model flags from legacy or structured case.yml blocks. | |
| picurv_cli.core.append_passthrough_flags (list control_lines, dict options) | |
| Appends raw CLI flags to the control list from a {flag: value} dict. | |
| dict | picurv_cli.core.resolve_solver_monitoring_flags (dict monitor_cfg) |
| Resolve human-readable solver monitoring YAML to raw control flags. | |
| "int | None" | picurv_cli.core.resolve_particle_console_output_frequency (dict io_cfg) |
| Return the effective particle-console snapshot cadence from monitor.yml. | |
| 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. | |
| dict | picurv_cli.core.parse_solver_config (dict solver_cfg) |
| Parses the structured solver.yml into a flat dictionary of {flag: value}. | |
| picurv_cli.core.generate_solver_control_file (run_dir, run_id, configs, num_procs, monitor_files, restart_source_dir=None, continue_mode=False) | |
| Generates the main .control file for the C-solver. | |
| str | picurv_cli.core.generate_post_recipe_file (str run_dir, str run_id, dict post_cfg, dict source_files, monitor_cfg=None) |
| Generates a key=value config file (post.run) for the C post-processor. | |
| 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. | |
| str | picurv_cli.core.format_command_for_display (list command) |
| Render a shell-safe command string for console and log output. | |
| str | picurv_cli.core.resolve_command_log_path (str run_dir, str log_filename) |
| Resolve a command log filename relative to the run directory. | |
| subprocess.CompletedProcess | picurv_cli.core._run_captured_command (list command, str run_dir) |
| Run a command and capture combined stdout/stderr details for later inspection. | |
| picurv_cli.core._require_successful_command (list command, subprocess.CompletedProcess result) | |
Raise CommandExecutionError when a captured command failed. | |
| str | picurv_cli.core._capture_command_stdout (list command, str run_dir) |
| Run a command, require success, and return stripped stdout text. | |
| picurv_cli.core._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 | picurv_cli.core._get_git_head_state (str run_dir) |
| Capture the current git HEAD branch name and commit hash. | |
| "list[tuple[str, str | None]]" | picurv_cli.core._get_local_branches_with_upstreams (str run_dir) |
| Return local branch names plus their configured upstreams. | |
| bool | picurv_cli.core._working_tree_has_tracked_changes (str run_dir) |
Return True when the repository has staged or unstaged tracked changes. | |
| picurv_cli.core._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. | |
| picurv_cli.core._restore_git_head (str run_dir, dict original_head, log_file) | |
| Restore the repository back to the branch or detached commit it started on. | |
| 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. | |
| picurv_cli.core.auto_identify_run_inputs (str config_dir) | |
| Auto-detect case.yml, monitor.yml, and *.control in a run config 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. | |
| 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) | |
| Render array script that maps SLURM_ARRAY_TASK_ID to per-case run artifacts. | |
| 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. | |
| picurv_cli.core.reduce_metric_values (values, str reduction) | |
| Reduce a metric series to one scalar according to the requested reducer. | |
| picurv_cli.core.extract_metric_from_csv (str case_dir, dict spec) | |
| Extract a scalar metric from a CSV source. | |
| picurv_cli.core.extract_metric_from_log (str case_dir, dict spec) | |
| Extract a scalar metric from a log file using regex. | |
| picurv_cli.core.normalize_metric_spec (metric) | |
| Normalize study metric definitions to a common dictionary form. | |
| 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. | |
| picurv_cli.core.infer_plot_x_axis (dict study_cfg, list rows) | |
| Infer x-axis key/values for 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. | |
| str | picurv_cli.core._command_to_string (list command_tokens) |
| Render a command list as a shell-safe display string. | |
| str | picurv_cli.core._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 | picurv_cli.core.build_run_dry_plan (args) |
Build a no-write execution plan for run --dry-run. | |
| 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. | |
| 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. | |
| 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. | |
| picurv_cli.core.render_run_dry_plan (dict plan, str output_format="text") | |
| Render dry-run plan in human or JSON format. | |
| picurv_cli.core.validate_workflow (args) | |
Implements picurv validate without launching solver/post workflows. | |
| picurv_cli.core.precompute_workflow (args) | |
| Generate deterministic case artifacts without launching solver/post stages. | |
| picurv_cli.core.run_workflow (args) | |
| Main orchestrator for the 'run' command (local and Slurm modes). | |
| 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. | |
| picurv_cli.core.sweep_workflow (args) | |
| Study/sweep orchestration using Slurm job arrays. | |
| picurv_cli.core.sweep_continue_workflow (args) | |
| Continue a partially-completed Slurm parameter sweep study. | |
| picurv_cli.core.sweep_reaggregate_workflow (args) | |
| Re-run metrics aggregation and plot generation for an existing study. | |
| picurv_cli.core._read_yaml_if_exists (str filepath) | |
| Read YAML when present, otherwise return None. | |
| picurv_cli.core._read_json_if_exists (str filepath) | |
| Read JSON when present, otherwise return None. | |
| picurv_cli.core._parse_int_loose (value) | |
| Best-effort integer parsing for summary extraction. | |
| picurv_cli.core._parse_float_loose (value) | |
| Best-effort float parsing for summary extraction. | |
| picurv_cli.core._extract_numeric_tuple (str text) | |
| Extract a numeric tuple from a string like '(1, 2, 3)'. | |
| dict | picurv_cli.core._build_summary_context (str run_dir) |
| Resolve run-local config and artifact paths for summarize. | |
| dict | picurv_cli.core._require_summary_config (dict context, str name) |
| Return one explicitly requested copied config or fail with a structured error. | |
| dict | picurv_cli.core._build_run_overview (dict context) |
| Build timestep-independent run metadata for summarize. | |
| dict | picurv_cli.core._summarize_turbulence (dict turbulence_cfg) |
| Build compact turbulence and wall-model selections. | |
| dict | picurv_cli.core._build_case_overview (dict context) |
| Build a curated case.yml summary with useful derived quantities. | |
| dict | picurv_cli.core._build_solver_overview (dict context) |
| Build a curated solver.yml summary with normalized selections. | |
| dict | picurv_cli.core._build_monitor_overview (dict context) |
| Build a curated monitor.yml summary with resolved defaults. | |
| "tuple[dict, list[int]]" | picurv_cli.core._parse_continuity_metrics_log (str filepath) |
| Parse Continuity_Metrics.log into latest rows by step plus observed order. | |
| "tuple[dict, list[int]]" | picurv_cli.core._parse_particle_metrics_log (str filepath) |
| Parse Particle_Metrics.log into latest rows by step plus observed order. | |
| "tuple[dict, dict, list[int]]" | picurv_cli.core._parse_momentum_convergence_logs (str log_dir) |
| Parse per-block momentum convergence logs. | |
| "tuple[dict, dict, list[int]]" | picurv_cli.core._parse_poisson_convergence_logs (str log_dir) |
| Parse per-block Poisson convergence logs. | |
| "tuple[dict, list[int]]" | picurv_cli.core._parse_profiling_timestep_csv (str filepath) |
| Parse profiling timestep CSV into latest rows by step plus observed order. | |
| "tuple[dict, list[int], dict]" | picurv_cli.core._parse_runtime_memory_log (str filepath) |
| Parse Runtime_Memory.log into latest rows by step and final status. | |
| "tuple[dict, list[int]]" | picurv_cli.core._parse_solution_convergence_log (str filepath) |
| Parse solution_convergence.log into latest rows by step plus observed order. | |
| "list[str]" | picurv_cli.core._find_solver_stream_log_candidates (str run_dir, str log_dir) |
| Return plausible solver stream logs for local and Slurm runs. | |
| dict | picurv_cli.core._parse_particle_snapshot_file (str filepath) |
| Parse sampled particle snapshots from a solver stream log. | |
| "int | None" | picurv_cli.core._find_previous_snapshot_step ("list[int]" snapshot_steps, int step) |
| Return the nearest earlier snapshot step when available. | |
| dict | picurv_cli.core._compute_particle_snapshot_delta ("list[dict]" current_rows, "list[dict]" previous_rows) |
| Compute sampled deltas between two particle snapshot samples. | |
| 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) |
| Build sampled diagnostics for one particle console snapshot. | |
| 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) |
| Locate and summarize a particle console snapshot for one 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") | |
| Select a step to summarize from available metric artifacts. | |
| str | picurv_cli.core._format_summary_float (value, str spec=".6e", str missing="n/a") |
| Format optional numeric values for summary text output. | |
| float | picurv_cli.core._summary_source_mtime (paths) |
| Return the newest modification time among one or more summary sources. | |
| "list[list[int]]" | picurv_cli.core._order_summary_step_orders ("list[tuple[list[int], object]]" sources) |
| Order observed step sequences by the recency of their source files. | |
| 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. | |
| picurv_cli.core.render_run_summary (dict payload, str output_format="text") | |
| Render a run-step summary in human or JSON form. | |
| str | picurv_cli.core._summary_display_value (value) |
| Format one configuration-summary value for compact text output. | |
| picurv_cli.core._print_config_header (str title, "str | None" subtitle=None) | |
| Print a strong dashboard-style configuration summary header. | |
| picurv_cli.core._print_config_group (str title, list rows) | |
| Print an aligned configuration-summary field group. | |
| list | picurv_cli.core._flatten_summary_mapping (dict mapping, str prefix="") |
| Flatten nested summary mappings into readable dotted field rows. | |
| picurv_cli.core._render_run_overview_text (dict summary) | |
| Render run metadata as a compact dashboard. | |
| picurv_cli.core._render_case_summary_text (dict summary) | |
| Render the case summary as a glanceable simulation dashboard. | |
| picurv_cli.core._render_solver_summary_text (dict summary) | |
| Render the solver summary as a glanceable numerical-method dashboard. | |
| picurv_cli.core._render_monitor_summary_text (dict summary) | |
| Render the monitor summary as a glanceable observability dashboard. | |
| picurv_cli.core.render_selected_summary (dict payload, str output_format="text") | |
| Render selected timestep-independent config views and optional health. | |
| picurv_cli.core._append_summary_plot_record (list records, str source, step, str line, dict values, str source_path, int segment=0) | |
| Append one numeric append-ordered record for summarize plotting. | |
| bool | picurv_cli.core._is_summary_plot_continuation_marker (str line) |
| Return whether a log line starts a new continuation segment. | |
| list | picurv_cli.core._collect_summary_plot_records (dict context) |
| Collect append-ordered numeric records from summarize-supported scalar logs. | |
| list | picurv_cli.core._build_summary_plot_catalog (list records) |
| Build available qualified-series metadata from plot records. | |
| 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) |
| Build one normalized plot.gen request from collected summarize records. | |
| picurv_cli.core._render_summary_plot_catalog (list catalog, str output_format) | |
| Render available summarize plot-series metadata. | |
| picurv_cli.core._invoke_plot_gen (dict request) | |
| Invoke standalone plot.gen with one normalized request over stdin. | |
| picurv_cli.core.summarize_workflow (args) | |
| Build and render a read-only health summary for a run step. | |
| dict | picurv_cli.core._resolve_submission_target (str run_dir=None, str study_dir=None) |
| Resolve a run/study submission target from explicit directory flags. | |
| dict | picurv_cli.core._get_submission_stage_metadata (dict target_context, str stage_name) |
| Return stored metadata for one staged submission target. | |
| list | picurv_cli.core._get_recorded_submission_stages (dict target_context) |
| Return stage names explicitly recorded in scheduler submission metadata. | |
| str | picurv_cli.core._format_stage_list (list stage_names) |
| Format a human-readable stage list for submit diagnostics. | |
| str | picurv_cli.core._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. | |
| picurv_cli.core._set_submission_stage_metadata (dict target_context, str stage_name, dict stage_meta) | |
| Persist one stage's metadata back into the submission payload. | |
| picurv_cli.core._write_submission_target_metadata (dict target_context) | |
| Write updated submission metadata back to disk. | |
| picurv_cli.core.submit_staged_jobs (args) | |
| Submit previously staged Slurm artifacts from an existing run/study directory. | |
| picurv_cli.core.submit_staged_local_run (args, dict target_context, list selected_stages) | |
| Execute previously staged local run commands from scheduler/submission.json. | |
| picurv_cli.core.cancel_run_jobs (args) | |
| Cancel Slurm-submitted jobs for an existing run directory. | |
| picurv_cli.core.init_case (args) | |
| Implements the 'init' command. | |
| picurv_cli.core.sync_case_binaries_command (args) | |
| Refresh case-local executables from the source repository bin directory. | |
| picurv_cli.core.sync_case_config_command (args) | |
| Refresh template-managed config/docs files in a case directory. | |
| picurv_cli.core.pull_source_repo (args) | |
| Refresh source branches in the repository resolved from a case directory. | |
| picurv_cli.core.build_project (args) | |
| Implements the 'build' command. | |
A comprehensive conductor script for the PICurv simulation platform.
This script acts as the central user interface for running simulations, managing configurations, and orchestrating the entire end-to-end workflow. It translates user-friendly YAML files into C-solver compatible control files, supports full multi-block configurations, and provides live log streaming. It features intelligent, content-based config file discovery and robustly manages data I/O paths for the post-processor. It also supports Slurm job generation/submission and parameter sweeps via job arrays.
Definition in file core.py.
1.9.8