[psweens]

Summary

vsystem-library gains one opt-in, repeatable option, --family-settings FAMILY JSON, which grows a family with some of its preset values changed, for example a foam bed at a smaller spacing or a capillary fill of more generations:

vsystem-library ... --families foam capillary_bed \
    --family-settings foam '{"bed": {"spacing": 5}}' \
    --family-settings capillary_bed '{"capillary_generations": 4}'

The settings reach each member as flags on its recorded command line, which stays a runnable vsystem command line growing the same network, and are recorded in the manifest and the archives, so the library stays reproducible and resumable. A library without the option is 3.8's.

Behaviour

• Keys: library.FAMILY_SETTING_KEYS (append-only): persistence, anastomosis_fraction, anastomosis_radius, anastomosis_min_separation, aneurysm_prob, stenosis_prob, root_offsets, guidance, capillary_generations, capillary_runs, cross_connect, rung_below, rung_spacing, rung_radius, rung_lateral_deg, rung_axis, rung_min_separation, bed.

• Bed: merged over the preset's bed and normalised by bed.parse_settings, so every key of bed.KIND_KEYS[kind] is recorded (13 for foam, 21 for fibre). Refused for a family whose preset has no bed, as null, and with a kind or layout other than the preset's. The preset's own kind or layout may be repeated, as a normalised bed does.

• Other values replace the preset's: arrays whole (null refused), numbers as floats, whole numbers for the integer settings, cross_connect as a bool. A bool is refused where a number is expected.

• library.normalise_family_settings(family, spec) checks and normalises one family's settings: keys in FAMILY_SETTING_KEYS order, idempotent. It raises ValueError, which the command line turns into an exit naming the family. The command line also refuses a family not listed, a family given twice, and JSON that is malformed, not an object or empty.

• Refused options, with the reason in the message:

  • what the library fixes for every member (d0, d_min, iterations, the box, collision_margin, avoid_collisions, grow_in_volume, …);
  • what makes a family what it is (tortuosity, anastomose, anastomose_mode, a bed's kind or layout, turning a bed on or off);
  • the grammar's own ranges and the numerical and output settings.

  A negative number in exponent notation (such as -1e-05, reachable only for the two probabilities) is also refused, because argparse would read it as an option and the member's command line would not run. The README gives the reason for each class.

• Command line: member_argv(..., settings=...) appends one flag per key after the 3.8 flags, in key order. Option strings come from main.build_parser(family)'s actions; values are written as compact sorted JSON, repr for floats and digits for ints, with --cross-connect / --no-cross-connect for the bool. grow_member(..., settings=...) passes the settings through the same path. With settings=None both return what 3.8 returned.

• Checked before growth: each family with settings has its command line at R_LO and R_HI parsed by main.build_parser(family) and checked by main.validate_shaping. A refusal at either end refuses the library and names the family.

• Printed before growth, for a family with settings and a bed:

  • one line with the candidate edges planned at R_HI against --bed-max-candidates and the largest R the cap admits (largest_admitted_ratio, bisection on the count grow_member's unchanged cap reads, rounded down);
  • a second line, where feeder_stop exceeds R_LO, with the smallest R it admits.

  Members beyond either bound are recorded as failures, as before.

• Records:

  • The manifest's growth.family_settings holds the settings, and only when some family has settings, so a rerun with different settings, or none, is refused by the existing comparison.
  • Each archive of the family records them in its metadata under family_settings, and validate_existing compares the command line with them.
  • No index column is added.
  • The family keeps its name: growth.family_settings and the archive's family_settings are where a consumer tells a variant library from a default one.

Compatibility

• tests/test_pinned_release_3_8.py runs the 3.8.0 modules, copied unchanged into tests/fixtures/reference_code_3_8 (main's import closure including bed, with library, describe, join and frames), beside the current ones in the same environment. It compares:

  • member_argv for every family under each library option;
  • the growth settings;
  • grow_member for every family 3.8 offers at small R (argv, kwargs, nodes, program, index row);
  • a plan of every family;
  • the default library and one of foam, capillary_bed and aligned_bed, each grown and then resumed with its index removed (archives, index rows, manifest content).

  Every record is restricted to the keys 3.8 wrote, listed literally, with seconds, peak_rss_mb, library_version and code_sha256 left out. The global generators start from a fixed state and are compared after each case. The hashes are recorded in tests/fixtures/reference_hashes_3_8.json, and the pin was committed passing before library.py changed.

• Settings for one family leave the plan, the seeds, the ratios and the other families' members bitwise equal to a library without them.

• main.py, bed.py, main's import closure, main.FAMILIES, main.RNG_STREAMS and library.RNG_STREAMS are unchanged. Version 3.9.0 in pyproject.toml and library.LIBRARY_VERSION. Python 3.9 syntax, numpy and tifffile only.

Measurement

tests/test_library_settings.SettingsBenchmark (slow-gated) grows each member through grow_member with settings, in a fresh process, seed 1. All 28 members finished, none over 15 minutes.

	R 4	R 8	R 16
foam length density, spacing 6 / 5 / 4.5 over 7.5 (density 0.5)	1.60 / 2.29 / 2.83	1.51 / 2.14 / 2.62	1.52 / 2.15 / 2.64
tissue distance mean, preset bed → spacing 4.5, density 0.6 (d_min)	3.45 → 1.65	3.08 → 1.54	3.01 → 1.51
foam growth, preset bed → spacing 4.5, density 0.6	1.2 → 5.4 s	13.1 → 54.9 s	104.9 → 483.0 s (859 MB)
capillary_bed length density, 3 → 4 generations	0.0198 → 0.0166	0.0134 → 0.0160	–

Density 0.6 adds 14–23 % of length at any spacing. At R 8, capillary_bed with 4 generations took 882 s to grow, the slowest member measured. The largest R the default cap (2 × 10⁶ candidate edges) admits, rounded down:

foam bed	density 0.5	density 0.6
spacing 7.5	31.33	27.75
spacing 6	25.07	22.21
spacing 5	20.90	18.52
spacing 4.5	18.82	16.67

The full table (points, planned candidates, peak RSS, tissue p90 and max, capillary length share) is in the README.

Tests

• Baseline at 3.8.0: 704 tests, OK, 62 skipped. With scipy installed the two scipy-gated tests run; 64 are skipped without it.
• After: 729 tests, OK, 63 skipped (the new benchmark). pyflakes clean.
• tests/test_library_settings.py covers:
  • normalisation and every refusal, each before anything is written and naming the family, including refusals at one end of the ratio range only;
  • the flags and their parse back to the normalised values;
  • members bitwise equal to main.main on their recorded command line for foam ({"bed": {"spacing": 5}}), capillary_bed ({"capillary_generations": 4}) and a mesh member carrying every non-bed key;
  • the printed lines and the cap they report, against grow_member's own refusal;
  • the records in the manifest and the archives;
  • resuming with the same, different or no settings;
  • the other families' members, bitwise equal to a library without settings.

🤖 Generated with Claude Code