|
PICurv 0.1.0
A Parallel Particle-In-Cell Solver for Curvilinear LES
|
For the full commented template, see:
# ==============================================================================
# PICurv Master Case Configuration Template
# ==============================================================================
#
# PURPOSE:
# This file defines the complete physical setup for a single simulation experiment.
# It describes the geometry, fluid properties, run duration, physical models,
# and boundary conditions. It is the "digital lab notebook" for your run.
#
# SECTIONS OVERVIEW:
# 1. simulation_control: How long the simulation runs and at what time resolution.
# 2. properties: The core physical numbers (density, viscosity, scales).
# 3. grid: The geometric domain, either from a file or generated.
# 4. models: Switches to turn on/off different physics modules (LES, FSI, etc.).
# 5. boundary_conditions: What happens at the edges of the domain.
#
# YAML SYNTAX NOTE:
# - Indentation matters! Use spaces, not tabs.
# - For lists, ensure there is a space after the hyphen (e.g., "- item").
# - For more details: https://learnxinyminutes.com/docs/yaml/
#
# ==============================================================================
# ==============================================================================
# 1. SIMULATION CONTROL
# Defines the duration and temporal resolution of the experiment.
# ==============================================================================
run_control:
# The simulation step number to start from.
# 0 for a new run, or a specific step number for a restart.
start_step: 0
# Total number of timesteps to execute in this run.
# Total simulation time = total_steps * dt_physical.
total_steps: 2000
# Restart: use the --restart-from CLI flag to point at a previous run
# directory. See `picurv run --help` for details.
# The physical time increment for each step, in seconds [s].
dt_physical: 0.001
# ==============================================================================
# 2. PHYSICAL PROPERTIES
# Defines the non-dimensional scaling and material properties.
# ==============================================================================
properties:
# --- Scaling ---
# These reference values are used to non-dimensionalize the problem for the solver.
scaling:
length_ref: 0.05 # [m] Characteristic length of the domain (e.g., pipe diameter, chord length).
velocity_ref: 1.5 # [m/s] Characteristic velocity (e.g., inlet velocity, freestream velocity).
# --- Fluid ---
# Properties of the fluid being simulated.
fluid:
density: 1000.0 # [kg/m^3]
viscosity: 0.001 # [Pa.s or kg/(m.s)]
# --- Initial Conditions ---
# The state of the fluid at the start of the simulation (t=0).
# Values are in physical units [m/s].
initial_conditions:
# Built-in generators: zero | constant | streamwise_constant | poiseuille | ic_gen
mode: generated
generator: constant
params:
u_physical: 0.0 # [m/s]
v_physical: 0.0
w_physical: 1.0
# --- Generator: streamwise_constant ---
# Sets every cell to the same scalar speed along the dominant flow axis.
# Infers flow_direction from the INLET face when one exists; otherwise,
# flow_direction is required.
# mode: generated
# generator: streamwise_constant
# params:
# velocity_physical: 1.0 # [m/s] Speed along the flow axis
# flow_direction: "+Zeta" # "+Xi" | "-Xi" | "+Eta" | "-Eta" | "+Zeta" | "-Zeta"
# # Optional when a single INLET face is present.
# --- Generator: poiseuille ---
# Sets the initial velocity to a fully-developed square-duct Poiseuille profile.
# flow_direction is required (or inferred from INLET face).
# mode: generated
# generator: poiseuille
# params:
# peak_velocity_physical: 1.5 # [m/s] Centerline (maximum) velocity
# flow_direction: "+Zeta" # Same options as streamwise_constant
# --- File IC: one PETSc .dat velocity field, staged for ReadFieldData. ---
# mode: file
# field: Ucat # Ucat | Ucont
# source_file: initial_conditions/velocity.dat
# --- External deterministic generator (ic_gen), materialized during run/precompute. ---
# Repository ic.gen supports file, grid_gen, and single-block programmatic_c grids.
# For programmatic_c, scalar programmatic_settings are materialized as config/grid.run first.
# mode: generated
# generator: ic_gen
# params:
# field: Ucat
# script: tools/custom_ic.py # Optional; defaults to generators/ic.gen
# config_file: config/initial_conditions/expression.cfg
# output_file: config/initial_condition.generated.dat
# ==============================================================================
# 3. GRID DEFINITION
# Defines the computational mesh for the simulation.
# ==============================================================================
grid:
# --- Mode Selection ---
# Determines how the grid is provided to the solver.
# Options: 'file', 'programmatic_c', or 'grid_gen'.
mode: programmatic_c
# --- Optional Global DMDA Layout (applies to all grid modes) ---
# Edit or remove these for parallel runs. The product must equal the total
# MPI process count (-n) when all three are set.
# NOTE: Per-block processor decomposition is not implemented on the C side.
da_processors_x: 2
da_processors_y: 2
da_processors_z: 4
# --- Option A: Grid from File ---
# Use this if you have a pre-generated grid file.
# The script validates and non-dimensionalizes coordinates using 'length_ref'.
# source_file: "grids/my_premade_grid.picgrid"
# --- Option B: Grid via Python Grid Generator (generators/grid.gen) ---
# Use this for complex curvilinear meshes generated before solver launch.
# generator:
# config_file: "config/grids/coarse_square_tube_curved.cfg" # Required today. Relative to case.yml or absolute.
# grid_type: "cpipe" # Optional override: cpipe | pipe | warp
# cli_args: # Optional raw CLI token list
# - "--ncells-i"
# - "96"
# - "--ncells-j"
# - "96"
# output_file: "config/grid.generated.picgrid" # Optional; relative to run dir.
# stats_file: "config/grid.generated.info" # Optional.
# vts_file: "config/grid.generated.vts" # Optional.
# --- Option D: Legacy Grid Conversion ---
# Converts an older column-text grid file to the .picgrid format before solver launch.
# Requires generators/grid.gen (or a custom script) to be present.
# legacy_conversion:
# enabled: true # [true/false] Must be true to activate this path.
# format: "column_text" # Currently supported: "column_text"
# script: null # Optional override path to conversion script.
# output_file: "config/grid.converted.picgrid" # Required. Destination path.
# axis_columns: [0, 1, 2] # Optional. 3-item list of zero-based column indices for x,y,z.
# strict_trailing: false # [true/false] Optional. Reject files with trailing data.
# cli_args: [] # Optional raw CLI token list passed to the converter.
# --- Option C: Programmatic Grid Generation in C ---
# Use this to have the C solver generate a structured Cartesian grid.
# `im/jm/km` are cell counts in YAML; picurv converts them to node counts
# before emitting `-im/-jm/-km` for the C runtime.
# For MULTI-BLOCK cases, all values must be LISTS of the same length.
programmatic_settings:
# --- Cell Counts ---
im: 64 # [Cells in i-direction] -> For 2 blocks: [64, 128]
jm: 32 # [Cells in j-direction] -> For 2 blocks: [32, 32]
km: 128 # [Cells in k-direction] -> For 2 blocks: [128, 256]
# --- Domain Bounds (in physical units [m]) ---
xMins: 0.0 # [Min x-coordinate] -> For 2 blocks: [0.0, 1.0]
xMaxs: 1.0 # [Max x-coordinate] -> For 2 blocks: [1.0, 2.0]
yMins: 0.0
yMaxs: 0.5
zMins: 0.0
zMaxs: 2.0
# --- Grid Stretching Ratios ---
# 1.0 = uniform. >1.0 = stretching towards max coordinate.
rxs: 1.0
rys: 1.05
rzs: 1.0
# --- Grid Type Flag ---
# 0 = regular Cartesian/curvilinear (default). 1 = O-type (cylindrical) grid.
# Used by the C metric routines to apply the correct Jacobian formula.
# -> -cgrids
cgrids: 0
# ==============================================================================
# 4. MODEL SELECTION
# User-friendly switches to enable different physical models and features.
# If a section or key is omitted, the C-code's default will be used.
# ==============================================================================
models:
# --- Domain and Block Configuration ---
domain:
blocks: 1 # [Integer] -> -nblk. CRITICAL for multi-block setups.
# Periodic axes are derived exclusively from paired PERIODIC boundary
# conditions. Do not add separate periodic flags here.
# --- Core Physics Modules ---
physics:
dimensionality: "3D" # Options: "3D" (default), "2D" (sets -TwoD 1)
fsi:
immersed: false # [true/false] -> -imm (Immersed Boundary Method)
moving_fsi: false # [true/false] -> -fsi (Fluid-Structure Interaction)
particles:
count: 0 # [Integer] -> -numParticles
init_mode: "Surface" # [string] -> -pinit. Options: "Surface", "Volume", "PointSource", "SurfaceEdges"
restart_mode: "init" # [string] -> -particle_restart_mode. Options: "init", "load"
point_source: # Required only when init_mode = "PointSource" (maps to -psrc_x/-psrc_y/-psrc_z)
x: 0.5
y: 0.5
z: 0.5
turbulence:
# Preferred structured LES form. Legacy shorthand is still accepted:
# les: false -> -les 0
# les: true -> -les 1 (constant Smagorinsky)
# les: 1 -> constant Smagorinsky
# les: 2 -> dynamic Smagorinsky
les:
enabled: false
# model is only needed when enabled: true. Options: constant_smagorinsky | dynamic_smagorinsky
# model: "constant_smagorinsky"
constant_cs: 0.03 # -> -const_cs; used by constant_smagorinsky
max_cs: 0.5 # -> -max_cs; clip for dynamic_smagorinsky
dynamic_frequency: 1 # -> -dynamic_freq; recompute dynamic Cs every N steps
test_filter: "volume_weighted_box" # volume_weighted_box | homogeneous_ik -> -testfilter_ik
# RANS selector. The k-omega runtime path is accepted but currently incomplete.
rans:
enabled: false
# model is only needed when enabled: true. Currently supported: k_omega
# model: "k_omega"
# Wall functions are independent of LES/RANS and apply on WALL faces.
wall_function:
enabled: false
# model is only needed when enabled: true. Currently supported: log_law
# model: "log_law"
roughness_height: 1.0e-16 # -> -wall_roughness
# --- Statistical Analysis ---
statistics:
time_averaging: false # [true/false] -> -averaging. Enables running averages.
# ==============================================================================
# 5. BOUNDARY CONDITIONS
# Defines the behavior at each of the 6 faces of the computational domain(s).
# ==============================================================================
# --- For SINGLE-BLOCK cases: Provide a simple list of 6 face definitions. ---
# --- For MULTI-BLOCK cases: Provide a LIST OF LISTS. The outer list corresponds
# to the block index [0, 1, ...], and each inner list defines the 6 faces
# for that block. See the multi-block example commented out below. ---
# --- Geometric periodicity: set both opposite faces to PERIODIC/geometric.
# Periodic axes are derived from these BC pairs. The paired grid surfaces
# must match pointwise under one nonzero constant Cartesian translation,
# and the axis must contain at least four physical nodes. Periodic particle
# wrapping is not implemented. See examples/periodic_test/. ---
boundary_conditions:
# --- Example for a Single Block Case ---
- face: "-Xi"
type: WALL
handler: noslip
- face: "+Xi"
type: WALL
handler: noslip
- face: "-Eta"
type: INLET
handler: constant_velocity
params:
vx: 1.5 # Physical velocity [m/s]
vy: 0.0
vz: 0.0
# Alternative inlet profile from a precomputed PICSLICE file:
# handler: prescribed_flow
# params:
# source:
# type: file
# path: profiles/inlet.picslice
#
# Alternative generated analytical square-duct Poiseuille profile:
# handler: prescribed_flow
# params:
# source:
# type: generated
# generator: square_duct_poiseuille
# script: tools/custom_profile.py # Optional; defaults to generators/profile.gen
# output_file: config/inlet_profile_block0_negEta.generated.picslice
# params:
# bulk_velocity: 1.5
# n_terms: 101
#
# Alternative profile sliced from an old Cartesian Ucat field:
# handler: prescribed_flow
# params:
# source:
# type: field_slice
# script: tools/custom_profile.py # Optional; defaults to generators/profile.gen
# field_file: ../old_run/output/eulerian/ufield10000_0.dat
# grid_file: ../old_run/config/grid.run
# source_case: ../old_run/config/case.yml
# output_file: config/inlet_profile_block0_negEta.sliced.picslice
# slice:
# face: "+Eta"
# orientation: opposite
- face: "+Eta"
type: OUTLET
handler: conservation
- face: "-Zeta"
type: WALL
handler: noslip
- face: "+Zeta"
type: WALL
handler: noslip
# --- All Supported BC Handlers (reference) ---
#
# WALL faces:
# handler: noslip No-slip (zero velocity) wall.
#
# INLET faces:
# handler: constant_velocity Uniform Cartesian velocity.
# params: { vx: 1.5, vy: 0.0, vz: 0.0 }
#
# handler: parabolic Fully-developed parabolic (Poiseuille) profile.
# params: { v_max: 1.5 } v_max = centerline (peak) velocity [m/s].
#
# handler: prescribed_flow Profile from a file, generator, or field slice.
# params:
# source:
# type: file
# path: profiles/inlet.picslice
#
# # OR generate analytically:
# # source:
# # type: generated
# # generator: square_duct_poiseuille
# # output_file: config/inlet_profile.generated.picslice
# # params:
# # bulk_velocity: 1.5
# # n_terms: 101
#
# # OR slice from an existing Ucat field:
# # source:
# # type: field_slice
# # field_file: ../old_run/output/eulerian/ufield10000_0.dat
# # grid_file: ../old_run/config/grid.run
# # source_case: ../old_run/config/case.yml
# # output_file: config/inlet_profile.sliced.picslice
# # slice:
# # face: "+Eta"
# # orientation: opposite
#
# OUTLET faces:
# handler: conservation Mass-conservation outflow correction.
#
# PERIODIC faces (must appear as matching opposite pairs):
# handler: geometric Pure geometric periodicity (no driving force).
# type: PERIODIC
# handler: constant_flux Drives a constant volume flux through the periodic pair.
# type: PERIODIC
# params:
# target_flux: 1.0 Target non-dimensional volumetric flux [m^3/s / (U_ref * L_ref^2)].
# apply_trim: false [true/false] Optional. Trim residual flux imbalance after correction.
# --- Example for a 2-Block Case (syntax example; all handlers shown are currently supported) ---
# boundary_conditions:
# # --- Block 0 Definitions ---
# - - face: "-Xi"
# type: INLET
# handler: constant_velocity
# params: { vx: 1.5, vy: 0.0, vz: 0.0 }
# - face: "+Xi"
# type: OUTLET
# handler: conservation
# - face: "-Eta"
# type: WALL
# handler: noslip
# - face: "+Eta"
# type: WALL
# handler: noslip
# - face: "-Zeta"
# type: WALL
# handler: noslip
# - face: "+Zeta"
# type: WALL
# handler: noslip
#
# # --- Block 1 Definitions ---
# - - face: "-Xi"
# type: INLET
# handler: parabolic
# params: { v_max: 1.5 }
# - face: "+Xi"
# type: OUTLET
# handler: conservation
# - face: "-Eta"
# type: WALL
# handler: noslip
# - face: "+Eta"
# type: WALL
# handler: noslip
# - face: "-Zeta"
# type: WALL
# handler: noslip
# - face: "+Zeta"
# type: WALL
# handler: noslip
# ==============================================================================
# 6. ADVANCED PASSTHROUGH (OPTIONAL)
# ------------------------------------------------------------------------------
# Use this for C flags not yet exposed in the structured schema.
# Keys must be full C/PETSc-style flags (including leading '-').
# ==============================================================================
# solver_parameters:
# -read_fields: true
# -some_new_flag: 123
case.yml defines physical setup, grid source, domain topology, and boundary conditions. It is intentionally modular: the same case.yml can be paired with different solver.yml, monitor.yml, and post.yml profiles when the combination remains contract-compatible.
Alternative IC forms:
Key mappings:
scaling.length_ref -> -scaling_L_refscaling.velocity_ref -> -scaling_U_reffluid.density and fluid.viscosity are used by picurv to compute Reynolds number -> -rengenerator: zero|constant|poiseuille|streamwise_constant -> the corresponding built-in -finit modemode: file and generator: ic_gen -> -finit 4, -ic_field, and staged -ic_dirparams.u_physical/v_physical/w_physical -> -ucont_x/-ucont_y/-ucont_zparams.velocity_physical and params.peak_velocity_physical -> -ic_velocity_physicalflow_direction -> -flow_direction <int> (+Xi=0,-Xi=1,+Eta=2,-Eta=3,+Zeta=4,-Zeta=5)For the scaling model and conversion logic, see Non-Dimensionalization Model. For detailed startup behavior of field initialization modes, see Initial Condition Modes.
Practical contract notes:
initial_conditions.mode is generated or file.zero, constant, streamwise_constant, and poiseuille.generator: ic_gen defaults to generators/ic.gen; optional params.script selects a compatible override.Ucat or Ucont vector and currently require a single-block case.flow_direction is required for curvilinear Constant and Poiseuille when no INLET face exists.eulerian_field_source and restart selection supersede initial_conditions.Mappings:
dt_physical -> -dt (non-dimensionalized)start_step -> -start_steptotal_steps -> -totalstepsRestart is handled via CLI flags rather than case.yml keys:
--restart-from <previous_run_dir> -> picurv resolves the prior run's actual restart source directory and emits -restart_dir <absolute_previous_source>--continue -> shorthand for resuming from the most recent run of the same caseSupported modes:
programmatic_cfilegrid_genMode compatibility note:
solve and load workflows, all three grid modes are supported.solver.yml -> operation_mode.eulerian_field_source: analytical, TGV3D requires grid.mode: programmatic_c.ZERO_FLOW and UNIFORM_FLOW support grid.mode: programmatic_c and grid.mode: file.Optional global DMDA layout hints apply to all grid modes:
These are scalar global values, not per-block vectors. Legacy placement under grid.programmatic_settings.da_processors_* is still accepted for compatibility, but the shared top-level grid.da_processors_* form is preferred.
programmatic_settings supports per-block lists for geometry arrays:
im/jm/kmxMins/xMaxs, yMins/yMaxs, zMins/zMaxsrxs/rys/rzscgrids — per-block integer grid type: 0 = Cartesian (default), 1 = O-type curvilinear → -cgridsDimension contract:
im/jm/km in YAML are cell counts.picurv converts them to node counts before emitting -im/-jm/-km for the C runtime.Important constraint:
grid.da_processors_x/y/z are scalar integers only (global DMDA layout). Per-block processor decomposition is not implemented.picurv validates existence and prepares normalized grid data for C-side ingestion.
Optional legacy conversion path (headerless 1D-axis payloads):
When enabled, picurv first calls generators/grid.gen legacy1d to create a canonical PICGRID file in the run config, then runs the normal validation/non-dimensionalization staging path.
This runs generators/grid.gen before solver launch and stages generated grid artifacts into the run config. grid.generator.config_file is required today; picurv does not synthesize a temporary grid config. grid.gen accepts cell-count inputs (ncells_* / --ncells-*) and writes node counts into the generated .picgrid header.
For direct grid.gen usage, generator types, and config-file structure, see Grid Generator Guide: generators/grid.gen.
Common mappings:
domain.blocks -> -nblkPERIODIC boundary conditions before DMDA creation; models.domain does not accept periodic flagsphysics.dimensionality: "2D" -> -TwoD 1physics.turbulence.les.enabled/model -> -les (0 none, 1 constant Smagorinsky, 2 dynamic Smagorinsky)physics.turbulence.les.constant_cs -> -const_csphysics.turbulence.les.max_cs -> -max_csphysics.turbulence.les.dynamic_frequency -> -dynamic_freqphysics.turbulence.les.test_filter -> -testfilter_ik (volume_weighted_box = 0, homogeneous_ik = 1)physics.turbulence.rans.enabled/model -> -rans (k_omega accepted; runtime update currently incomplete)physics.turbulence.wall_function.enabled -> -wallfunctionphysics.turbulence.wall_function.roughness_height -> -wall_roughnessphysics.particles.count -> -numParticlesphysics.particles.init_mode -> -pinit (Surface, Volume, PointSource, SurfaceEdges)physics.particles.restart_mode -> -particle_restart_mode-psrc_x/-psrc_y/-psrc_zLegacy turbulence shorthand remains valid:
les: false -> -les 0les: true or les: 1 -> constant Smagorinsky (-les 1)les: 2 -> dynamic Smagorinsky (-les 2)LES and RANS are mutually exclusive in one case. wall_function is a sibling option because wall functions can be used with wall-modeled LES or RANS boundary treatments.
Restart note:
run_control.start_step > 0, particles are enabled, and restart_mode is omitted, picurv warns that C will default to load.For mode-specific particle behavior and restart flow, see Particle Initialization and Restart Guide.
Single-block syntax: list of 6 face entries. Multi-block syntax: list-of-lists, one 6-face list per block.
Supported face names:
-Xi, +Xi, -Eta, +Eta, -Zeta, +ZetaSupported type/handler combinations:
INLET + constant_velocity (vx/vy/vz)INLET + parabolic (v_max)INLET + prescribed_flow:params.source.type: file, params.source.pathparams.source.type: generated, params.source.generator: square_duct_poiseuilleparams.source.type: field_slice, params.source.field_file, params.source.grid_file, params.source.slicegenerators/profile.gen; optional params.source.script selects a compatible overrideOUTLET + conservationWALL + noslipPERIODIC + geometricPERIODIC + constant_flux (target_flux, optional apply_trim)All six faces must be explicitly provided for each block. For detailed handler semantics, validation constraints, and C dispatch path, see Boundary Conditions Guide.
Generated profile example:
picurv run --solve generates the dimensional .picslice, writes profile.info, stages the solver-scale .picslice, and passes the existing source_file key to the C runtime. Use picurv precompute --case ... to create the same deterministic artifacts without launching the solver.
Field-sliced profile example:
field_slice uses Python preprocessing to write a normal dimensional PICSLICE; the C runtime still sees only the staged source_file.
Optional escape hatch for flags not yet exposed in structured schema:
Use sparingly and prefer structured keys when available.
case.yml is designed to be combined with reusable profiles for the other config roles.
Common patterns:
case.yml + multiple monitor.yml files (debug vs production output),case.yml + multiple post.yml recipes (quick scalar check vs heavy VTK/statistics),solver.yml reused across many case.yml files,cluster.yml reused across many runs and sweeps.For worked combinations, see Workflow Recipes and Config Cookbook.
Proceed to Configuration Reference: Solver YAML.
Cross-file contract/mapping:
This page describes Configuration Reference: Case YAML within the PICurv workflow. For CFD users, the most reliable reading strategy is to map the page content to a concrete run decision: what is configured, what runtime stage it influences, and which diagnostics should confirm expected behavior.
Treat this page as both a conceptual reference and a runbook. If you are debugging, pair the method/procedure described here with monitor output, generated runtime artifacts under runs/<run_id>/config, and the associated solver/post logs so numerical intent and implementation behavior stay aligned.
1.9.8