SHORE

Appearance

shore proc-input ​

Generate the Xall proc.input runtime work-distribution descriptor from a .grd file.

bash
shore proc-input MESH.grd OUT.proc.input [--np N] [--meta JSON]

What proc.input is ​

proc.input is the file Xall reads at MPI startup to learn:

  • which MPI rank each block lives on (proc field, 0-based);
  • which rigid-body group each block belongs to (group field);
  • which physical body (corpo) each block is part of, used by the solver's force / moment integration (body field).

It is a sibling of cc.par, not a downstream artefact. cc.par is consumed by the overset preprocessor (which produces the runtime artefacts the solver actually uses); proc.input is consumed directly by Xall. They happen to share the group concept but live in different files because they are read by different tools.

SHORE → .grd        ┐
SHORE → cc.par      ┘──► overset preprocessor ──► (runtime artefacts) ──┐
                                                                        ▼
SHORE → proc.input  ──────────────────────────────────────────────────► Xall

File format ​

Plain ASCII, free-format, parsed by Fortran list-directed read(*,*). 7-line header + N block records:

<line 1: free-form comment, e.g. "generated by SHORE">
<blank>
<blank>
<N>  number of blocks
<blank>
<blank>
<column-header line, free-form>
<block_idx>  <group>  <body>  <proc>  ! optional comment
...                                       (x N)

The reader skips the 7 header lines unconditionally, then reads N records of 4 numeric columns. The trailing ! comment is advisory — the Fortran reader stops at column 4.

ColumnFieldMeaning
1block_idx1-based block index. Must equal the line's position.
2groupRigid-body group (0 = stationary).
3bodyBody (corpo) index (0 = no body). Used by Xall's force / moment integration arrays.
4proc0-based MPI rank.

The reader (Xnavis-projects/Xnavis/Solver/src/input.f90) derives the total MPI rank count as max(proc) + 1 and aborts if it doesn't match the runtime --np.

How SHORE generates it ​

Block ordering and weights come from the .grd file — block 1 in proc.input is block 1 in the .grd, with weight ni * nj * nk (cell count). This matches what overset / Xall's own load-balancing tools (LoadBalance, overset-exploded) do.

shore proc-input reads only the .grd header (cheap — costs O(n_blocks) bytes regardless of mesh size) via shore.io.grd.read_grd_metadata, then assigns ranks by greedy weight-balanced distribution: sort blocks by descending weight, place each on the least-loaded rank.

group and body default to 0 for every block. To override, use --meta.

Arguments and options ​

Argument / OptionDefaultDescription
GRDrequiredPath to a SHORE / Xall .grd file.
OUTrequiredOutput proc.input path.
--np INTEGER1Total MPI rank count (≥ 1).
--meta TEXT—Per-block overrides for proc / group / body. Inline JSON or path to a JSON file. Keys are 1-based block-index strings; values are objects with any subset of {proc, group, body}.
--header-comment TEXT"generated by SHORE"Header line 1.

--meta format ​

Inline JSON:

bash
shore proc-input wall.grd wall.proc.input --np 4 \
    --meta '{"1": {"proc": 0, "body": 1}, "5": {"group": 2, "body": 1}}'

Or a JSON file:

bash
shore proc-input wall.grd wall.proc.input --np 4 --meta wall_meta.json

Resolution order: the value is parsed as JSON first; on failure it is treated as a file path (and that file's content is parsed as JSON). Inline JSON is therefore unambiguous regardless of working directory.

Any block not listed in --meta keeps its default: proc from the greedy balance, group=0, body=0.

Balance summary ​

For --np > 1, the command prints a multi-line summary on stderr:

proc.input: 11 blocks across 4 ranks
  rank 0: 3 blocks, 1.84M cells (28.1%)
  rank 1: 3 blocks, 1.62M cells (24.7%)
  rank 2: 3 blocks, 1.55M cells (23.6%)
  rank 3: 2 blocks, 1.55M cells (23.6%)
  imbalance: 4.5%

Imbalance is (max - min) / mean across the per-rank cell totals. When it exceeds 5%, a warning recommends shore balance to plan a topology-safe set of splits:

Warning: load imbalance is 22.7% (> 5%).  Run `shore balance` to
plan a topology-safe set of splits that brings the imbalance within
tolerance.

For serial runs (--np 1) no summary is printed — there's no balance to report.

Examples ​

bash
# Serial single-component: every block on rank 0
shore proc-input wall.grd wall.proc.input

# 16-rank parallel run, greedy balance
shore proc-input wall.grd wall.proc.input --np 16

# 8-rank run with explicit body assignments for rigid-body motion
shore proc-input wall.grd wall.proc.input --np 8 \
    --meta '{"1": {"body": 1}, "2": {"body": 1}, "3": {"body": 1},
             "4": {"body": 1}, "5": {"body": 1}, "6": {"body": 1}}'

Python API ​

python
from shore.io.proc_input import write_proc_input

out_path, summary = write_proc_input(
    "wall.grd",
    "wall.proc.input",
    np=16,
    proc_assignment={1: 0},                # pin block 1 to rank 0
    body_assignment={i: 1 for i in range(1, 7)},  # all wall blocks → body 1
)
print(summary.format())

write_proc_input returns (Path, BalanceSummary). See shore.io.proc_input for the full Python API.

shore proc-input-merge ​

Concatenate multiple proc.input files for a multi-component Xall run.

bash
shore proc-input-merge background.proc.input wall.proc.input \
                       -o assembly.proc.input

Block indices in subsequent inputs are shifted by the cumulative block count of the preceding inputs, mirroring shore grd-merge and shore cc-par-merge. group, body, and proc columns pass through verbatim — the merger does not re-run load balancing or renumber bodies / groups across components. Collisions across components are the user's responsibility.

Pair with grd-merge and cc-par-merge

The merged proc.input's block indices are 1-based positions into the merged .grd's block list. Always invoke proc-input-merge, grd-merge, and cc-par-merge with the same input ordering.

bash
shore grd-merge          background.grd          wall.grd          -o assembly.grd
shore cc-par-merge       background.cc.par       wall.cc.par       -o assembly.cc.par     --grd assembly.grd
shore proc-input-merge   background.proc.input   wall.proc.input   -o assembly.proc.input --grd assembly.grd

proc-input-merge accepts an optional --grd pointing at the merged .grd. When given, the printed summary uses real cell counts and shows the actual imbalance of the merged assembly:

proc.input: 11 blocks across 4 ranks
  rank 0: 3 blocks, 35.9k cells (27.8%)
  ...
  imbalance: 66.9%

Without --grd, the merger only sees block-to-rank assignments and the summary falls back to per-rank block counts only (proc.input itself doesn't store weights).

The merger does not re-balance — it concatenates the per-component assignments verbatim. To re-balance the merged assembly globally, run shore proc-input on the merged .grd (the greedy algorithm sees the full block list at once and typically finds a better global assignment than two independent component runs).

Limitations ​

  • No load-balancing splits. Some balancers (LoadBalance, overset-exploded) split blocks when no rank assignment hits the imbalance budget. SHORE does not — it does the assignment given the blocks it has. If the imbalance warning fires, use shore split to subdivide the heaviest blocks first, regenerate the .grd, and rerun shore proc-input.
  • No body / group renumbering on merge. The merger preserves every input's group and body columns verbatim. If two components both name their body 1, the merged file collides — and Xall will treat them as the same physical body. The user must ensure unique body / group indices across merged components.

See also ​

Released under the MIT License.

Copyright © Stefano Zaghi