FullVascularTreeSim.jl

FullVascularTreeSim.jl is a research simulator for predicting a coupled coronary arterial, microvascular, and venous circulation from the fixed major vessels supplied by an XCAT heart phantom.

The project is a heart-focused fork of VascularTreeSim.jl. It retains the existing constrained vascular-growth engine while extending the model from arterial trees alone to the complete path

aorta -> coronary arteries -> myocardial perfusion beds
      -> coronary veins -> coronary sinus/right atrium

Implementation status: direct final-diameter construction, explicit arterial/venous roles, paired unresolved perfusion beds, cross-network finite-radius obstacles, vein flow reversal at export, and GPU-first numerical screening are implemented. The full XCAT heart run has not yet passed its anatomical and numerical acceptance gates. A coupled pressure, rheology, compliance, and contrast-return solve remains downstream work.

The active coronary workflow constructs every predicted branch directly at its requested terminal diameter. It does not use post-growth terminal subdivision, relocation, pruning, repair, or diameter rescaling. Prescribed outlet sites are separate from the independent coverage quadrature, every unserved outlet keeps a reserved finite-radius access port, and final arteries and veins are audited with the same exact capsule predicate. The model and proofs are recorded in docs/construction/coronary-arterial-venous-construction.md. Independent hierarchy proposals can be prepared concurrently across four replicated GPU collision mirrors, while exact CPU revalidation and serial Murray/topology commits retain scientific authority. The compact range hierarchy, route-cache validity conditions, invariant proof, and incremental checkpoint schema are documented in docs/construction/concurrent-multigpu-hierarchy.md.

The earlier demand-conditioned arterial workflow is preserved as historical diagnostic evidence. Its failed 2026-07-17 checkpoint must not be resumed or promoted to FlowSim input.

Project goal

The immediate target is a static, diastolic coronary model that:

1. reads the fixed LAD, LCX, RCA, and coronary-vein surfaces from XCAT;
2. preserves the accepted XCAT geometry and diameters as supplied anatomy;
3. predicts missing arterial branches inside the myocardium;
4. predicts venous tributaries from accepted venous outlets toward the same tissue-demand beds;
5. joins arteries and veins physiologically through unresolved perfusion beds, not by forcing one-to-one geometric pairs; and
6. exports a flow-ready network with explicit vessel role, drainage system, outlet, and perfusion-bed provenance.

The first production milestone is the coronary-sinus system. Anterior cardiac and Thebesian drainage, venous arcades, anastomoses, and cardiac-cycle mechanics are later milestones.

Canonical XCAT input

The reference anatomy is:

smb://160.87.12.113/Molloilab/XCAT Phantom/vmale50_heart.nrb

On the laboratory Mac mount this is:

/Volumes/Molloilab/XCAT Phantom/vmale50_heart.nrb

The selected file contains both diastolic (dias_*) and systolic (sys_*) heart surfaces. The initial model uses one consistent diastolic surface set.

Purpose	Diastolic XCAT surfaces
Fixed LAD	dias_lad1, dias_lad2, dias_lad3
Fixed LCX	dias_lcx
Fixed RCA	dias_rca1, dias_rca2
Fixed coronary veins	dias_cor_vein1, dias_cor_vein2
Outer heart boundary	dias_pericardium
Cardiac chambers	dias_lv_0-dias_lv_4, dias_la, dias_ra, dias_rv
Great-vessel references	dias_aorta, dias_pul_art, dias_sup_vc, dias_inf_vc

The exact-hash geometry audit in docs/construction/coronary-venous-xcat-validation-2026-07-22.md accepts dias_cor_vein1 and dias_cor_vein2 as one connected fixed coronary venous system. cor_vein1 approaches the sampled right-atrial surface within 0.214 mm; cor_vein2 approaches cor_vein1 within 0.315 mm. The tree is rooted at the interior cor_vein1/right-atrial junction and physiological flow is toward that root. The numbering still does not justify exact great/middle/small cardiac-vein subtype names.

Useful companion assets in the same XCAT directory include:

• vmale50.nrb, the matching whole-body model;
• organ_ids.txt, for XCAT object-name provenance;
• Parameters_test/heart_original.par, which enables both coronary arteries and veins at 0.02 cm voxel spacing; and
• Outputs_established/whole_heart_vox0_02_1900x1300x750_8bit_little_endian_*, a high-resolution raw/log pair for registration and label audits.

The NRB is the geometric source of truth. A raster phantom is an independent registration and voxel-label check, not a replacement for the supplied vessel surfaces. XCAT voxel labels can vary between parameter sets, so the artery and vein labels must come from the matching parameter/log provenance rather than a hard-coded global assumption.

Intended model

flowchart LR
    X["XCAT heart NRB"] --> A0["Fixed LAD / LCX / RCA scaffold"]
    X --> V0["Fixed coronary-vein scaffold"]
    X --> M["Myocardial shell and transmural coordinates"]
    M --> D["Deterministic tissue-demand beds"]
    A0 --> A["Predicted arterial trees"]
    V0 --> V["Predicted venous drainage trees"]
    D --> A
    D --> V
    A --> B["Perfusion-bed resistance and compliance"]
    B --> V
    V --> O["Coronary sinus / right atrial outlets"]

Loading

Arteries and veins are different network roles

Each predicted network needs an explicit role and physiological orientation:

• arteries are geometrically rooted at an aortic inlet and carry flow away from the root;
• veins can be generated geometrically outward from a right-atrial or coronary-sinus outlet while physiological flow travels toward that root; and
• storage orientation and flow orientation must therefore be separate fields.

Vessel role must not be inferred from a label substring.

Major-vessel association is a soft prior

Known artery-vein proximity is useful only for major epicardial vessels:

Arterial reference	Venous reference	Intended prior
LAD	Anterior interventricular vein / great cardiac vein	Strong within the anterior interventricular groove
PDA	Middle cardiac vein	Moderate within the posterior interventricular groove; either side/depth allowed
LCX	Great cardiac vein	Moderate-to-weak; crossings allowed
RCA	Small cardiac vein	Weak and optional
Intramyocardial branches	Local venules	No one-to-one pairing

The routing objective should reward a broad separation corridor, not attraction to an arterial centerline. It must retain a hard radius-sum clearance and must not place venous junctions at arterial bifurcations by default. The pairing weight decays to zero when a vessel leaves an epicardial groove and penetrates the myocardium.

Perfusion beds connect the systems

Arterial terminals and venous terminals meet through shared PerfusionBed records representing unresolved arterioles, capillaries, and venules. A bed records tissue demand, location, arterial endpoint, venous endpoint, arterial owner, venous owner, and exchange-model provenance. It is not a direct artery-vein segment and does not imply matched terminal bifurcations. Calibrated bed resistance, compliance, and transmural pressure are not yet implemented.

This coarse bed representation is the first milestone. Explicit capillary meshes are deferred because coronary capillaries form a cross-connected network and a full arterial-plus-venous microvascular realization would contain tens of millions of segments.

Design contract

The full simulator should preserve these invariants:

1. Immutable supplied anatomy. Accepted fixed XCAT centerlines and diameters are inputs, not predictions, and cannot be rescaled to make growth succeed.
2. Explicit provenance. Every segment records network role, anatomical system, source (xcat, predicted, or connector), geometric parent, flow orientation, outlet, and optional bed identifier.
3. Shared demand, independent geometry. Arteries supply and veins drain the same demand beds, but their territories and branch points need not coincide.
4. Finite-radius exclusion. All artery-artery, vein-vein, and artery-vein interactions use capsule clearance. Arteries and veins may travel near one another but may not overlap.
5. Legal connections only. An artery and vein communicate only through a declared perfusion bed. Chamber entry is prohibited except at accepted outlets or explicitly modeled Thebesian endpoints.
6. Flow conservation. A coupled solution conserves mass at every node and bed and produces the steady pressure ordering artery -> bed -> vein -> right atrium.
7. Fail closed. An unresolved topology, containment, capacity, collision, registration, or flow audit fails the run rather than being silently repaired in a production export.

Current implementation status

Capability	Status in this fork
XCAT NRB parsing and NURBS sampling	Implemented
Myocardial shell and cavity subtraction	Implemented
Fixed LAD/LCX/RCA centerline import	Implemented
Direct final-diameter prospective construction	Implemented; full heart run pending
GPU distance/collision/proposal screening	Implemented; CPU remains exact transaction authority
Reading dias_cor_vein1/2 surfaces	Implemented with provisional-label fail-closed gate
Explicit artery/vein network roles and flow orientation	Implemented
Global cross-network finite-radius obstacles and audits	Implemented
Shared artery-bed-vein assignment	Implemented as unresolved paired beds
Separate prescribed sites and coverage quadrature	Implemented
Venous epicardial/groove soft routing priors	Not yet implemented
Coupled nodal pressure/flow solve	Planned
Venous contrast return through FlowContrastSim	Planned
Cardiac-phase compliance and extravascular pressure	Future work

Inherited right-leg examples and validation documents remain in the repository as regression evidence for the growth engine. They are not the scientific goal of FullVascularTreeSim.jl.

Development roadmap

Phase 0: protect the inherited arterial baseline — implemented

• Keep existing arterial tests passing.
• Reconcile the coronary example with the immutable-XCAT contract.
• Record the exact NRB hash, surface set, cardiac phase, and companion raster metadata in every serious run.

Phase 1: first-class coronary networks — implemented provisionally

• Add artery/vein role, drainage system, outlet, and flow orientation to the configuration/data model.
• Import dias_cor_vein1/2 as separate fixed venous networks.
• Classify accepted venous paths by geometry rather than identifier order.
• Export fixed and predicted arteries and veins with distinct labels.

Phase 2: coronary-sinus venous prediction — construction implemented; anatomy validation pending

• Create deterministic myocardial demand beds.
• Grow venous geometry outward from accepted coronary-sinus/right-atrial outlets toward those beds.
• Add diameter-dependent epicardial, groove, and transmural routing costs.
• Global artery-vein and vein-vein capsule clearance is now a hard gate.
• Temporarily retain binary venous topology where required by the inherited tree representation, and label that restriction explicitly.

Phase 3: coupled coronary flow

• Connect arterial and venous endpoints with bed resistances.
• Solve a sparse nodal conductance system with aortic and right-atrial pressure boundary conditions.
• Export pressure, signed flow, resistance, transit time, and bed conservation audits.
• Extend contrast transport through artery -> bed -> vein -> central return.

Phase 4: anatomical coverage

• Add RV/anterior cardiac drainage.
• Add Thebesian outlets with chamber-specific constraints.
• Generalize the flow representation from rooted trees to a vascular graph for venous arcades and anastomoses.

Phase 5: cardiac-cycle mechanics

• Add phase-aware geometry registration.
• Add venous compliance and noncircular cross-section sensitivity.
• Couple intramyocardial resistance and vessel collapse to time-varying extravascular pressure.

Installation

Requires Julia >= 1.9. The repository is not registered in Julia General:

using Pkg
Pkg.develop(path="/path/to/FullVascularTreeSim.jl")
Pkg.instantiate()

The local directory and GitHub repository are named FullVascularTreeSim.jl, but the inherited Julia package/module is still named VascularTreeSim:

using VascularTreeSim

Renaming the Julia module, UUID, extension, imports, and downstream consumers is a separate compatibility change and should not be implied by the directory rename.

GPU acceleration is supplied by the existing CUDA extension. Pure-CPU runs use the base package. Check GPU availability before starting a GPU job on shared compute resources.

Running the flow-ready 8 um arterial baseline

The first production milestone now has a dedicated, memory-bounded workflow:

julia --project=. --threads=auto examples/run_coronary_8um_flow.jl \
    configs/coronary_8um_flow.toml \
    /path/to/verified/vmale50_heart.nrb \
    /path/to/new/output_directory

It preserves the supplied XCAT LAD, LCX, and RCA geometry and diameters, routes a compact coronary scaffold, partitions a deterministic BCC discretization of the XCAT myocardium among all three complete centerline trees, and streams a demand-conditioned hierarchy to exactly one 8 um outlet per demand site. Weighted centerline distance selects LAD/LCX/RCA territory, while distance to the owning tree's predicted compact terminal tips drives initial growth and its p95/maximum stop rule. This distinction is necessary because terminal tips are a subset of the centerline: passing centerline coverage cannot prove that a distal bed can reach the tissue. Initial construction and later refinement both use the same finite-radius obstacle-aware A* and transactional geometry gates. Hard Murray quotas limit each compact terminal, and production permits zero movement of a site away from its exact nearest compact terminal. Capacity overload is a request to refine the scaffold, not permission to transport tissue demand.

Before distal construction, production audits the exact nearest-terminal Voronoi cells. A capacity or distance violation triggers deterministic farthest-demand-site proposals and real domain/lumen-constrained compact growth, followed by a complete three-tree repartition and re-audit. The hashed demand sites are conserved; intermediate obstacle-free proposal sites are not outlets and need not all become branches. A nonempty physically admissible subset may be retained only because the exact nearest-terminal capacity and distance gates are recomputed against actual geometry after every round. Zero progress or an unsatisfied gate at the configured round limit stops the run; no geometric tolerance is silently relaxed.

The 2,545,000-site production count is a declared provisional conversion of the porcine whole-coronary segment counts reported by Mittal et al.; it is not human ground truth. Likewise, the historical L/D=12 sum is retained only as a reference compact-scaffold coverage threshold and does not generate or prove the demand-conditioned path lengths. The full derivation, conservation proofs, failed symmetric-run evidence, empirical limitations, acceptance gates, and literature are recorded in docs/coronary-demand-conditioned-method.md.

The authoritative FlowContrastSim inputs are exactly lad_segments.csv, lcx_segments.csv, and rca_segments.csv. The files named *_hemodynamic_diagnostic.csv cover only the compact routed scaffold and are not substitutes for the complete CSVs. If several segments leave one shared anatomical root vertex, the export prepends a labelled 0.1 um numerical inlet so FlowContrastSim reconstructs one connected root; this connector is recorded in the manifest and is not presented as XCAT anatomy.

Long growth jobs serialize guarded checkpoints. A checkpoint can be exported without repeating growth by setting VTS_GROWTH_CHECKPOINT_PATH to that exact Artin-owned .jls file. The runner rebuilds the XCAT/domain context, hashes the checkpoint, re-audits fixed geometry, topology, Murray capacity, and coverage, requires its recorded coverage observable to be terminal_tips, then records the checkpoint path, hash, round, and branch counts in the output manifest. It does not accept a checkpoint merely because it can be deserialized. Fresh production runs also write and hash an append-only accepted compact- scaffold checkpoint immediately after coverage, topology, immutable-XCAT, Murray-capacity, and domain-capsule audits pass, before demand refinement.

Before a result is promoted, run the full-CSV structural audit on each tree:

python3 scripts/audit_coronary_flow_csv.py output/lad_segments.csv \
    --expected-terminal-um 8 \
    --summary output/lad_full_csv_audit.json

scripts/launch_coronary_8um_flow_full.sh applies the shared-compute GPU, Artin-directory, input-hash, output-collision, and storage guards and audits all three files. configs/coronary_8um_flow_smoke.toml is only a reduced software test; its geometry is not a scientific result.

That preserved milestone is an arterial-only historical workflow. New work must use the direct coupled runner below; the old post-construction output is not the active full-vascular model.

Running direct arterial–venous construction

The production-scale configuration is configs/coronary_full_vascular.toml. It requires a functional CUDA device, an exact input hash, and explicit acknowledgement while the two XCAT venous identifiers remain anatomically provisional:

VTS_ACKNOWLEDGE_PROVISIONAL_VENOUS_MAPPING=1 \
julia --project=. --threads=auto examples/run_coronary_full_vascular.jl \
    configs/coronary_full_vascular.toml /media/molloi-lab/2TB4/Artin/<new-run>

Before an SSH run, inspect GPU availability and storage, and use a new output directory under /media/molloi-lab/2TB4/Artin. Do not run this configuration as a smoke test: its prescribed direct terminal count is production scale.

Running the inherited arterial baseline

The existing coronary command remains useful as a regression baseline:

julia --project=. --threads=auto examples/run_coronary_growth.jl \
    configs/coronary.toml

At present this command grows LAD, LCX, and RCA arterial trees. It does not yet generate a physiologically connected venous system, so its output must not be described as a full vascular prediction.

For fast domain checks before growth:

julia --project=. examples/check_domain_only.jl configs/coronary.toml

The canonical config still contains a historical Linux mount path. A serious run must point to the exact reference NRB or to a verified byte-identical copy, without modifying the source file.

Output contract

The direct construction runner currently writes:

• full_vascular_segments.csv, with network, role, storage direction, flow direction, outlet, provenance, geometry, diameter, and fixed/predicted flag;
• perfusion_beds.csv;
• exact construction checkpoints and a validated route-graph cache; and
• run_manifest.toml with input hash, model status, counts, and output paths.

Coupled pressure, flow, resistance, compliance, and contrast results are not emitted by this geometry constructor and must not be inferred from these files.

Segment records should distinguish geometric direction from physiological flow direction and include explicit role, system, source, outlet_id, and bed_id fields. Downstream consumers should reconstruct topology from explicit identifiers rather than coordinate coincidence.

Validation requirements

A full coronary result is not accepted unless:

• every predicted artery reaches an accepted aortic inlet;
• every predicted vein reaches an accepted coronary-sinus, right-atrial, or explicitly modeled chamber outlet;
• every retained perfusion bed has arterial supply and venous drainage;
• fixed XCAT geometry and diameters remain unchanged;
• all segments satisfy domain and finite-radius clearance constraints;
• chamber penetration occurs only at declared legal endpoints;
• mass is conserved at every junction and bed;
• steady pressure decreases from artery to bed to vein to right atrium;
• major epicardial artery-vein association agrees with its configured soft prior without imposing intramyocardial one-to-one pairing; and
• diameter, length, asymmetry, branch degree, blood volume, drainage fraction, and transmural position are reported separately by network role and system.

Human and porcine measurements must be reported separately. Porcine coronary morphometry is a useful structural prior and sensitivity range, not direct validation of a human XCAT prediction.

Scientific interpretation

Generated vessels are computational hypotheses conditioned on supplied XCAT anatomy, numerical routing rules, demand assumptions, diameter laws, and model parameters. Internal consistency is necessary but is not biological validation.

The project must not claim that it:

• reconstructs subject-specific vessels that were not imaged;
• produces anatomical ground truth;
• infers exact venous identity from cor_vein1/2 numbering;
• proves that nearby arteries and veins have matching bifurcations;
• resolves the true capillary plexus when using lumped beds; or
• predicts clinical pressure, flow, or contrast timing without independent calibration and validation.

See docs/assumption-register.md and the direct coupled construction contract. Documents describing terminal subdivision or arterial/right-leg runs are retained as historical regression and falsification evidence, not as the active heart construction method.

Data and shared-compute stewardship

• The shared Molloilab/Artin directory is the writable project area.
• Other researchers' directories and the shared XCAT Phantom source directory are treated as read-only inputs unless explicitly authorized.
• On Linux/SSH systems, project inputs and outputs belong under /media/molloi-lab/2TB4/Artin.
• Do not overwrite source XCAT assets or another run's output directory.
• Before deleting anything, resolve and enumerate the exact target, verify that it is inside the intended project-output directory, avoid broad wildcards or recursive cleanup, and prefer reversible quarantine when practical.
• Before GPU execution, inspect GPU availability and select an appropriate free device.

Tests

Run the inherited unit and regression suite with:

julia --project=. -e 'using Pkg; Pkg.test()'

The synthetic-domain and arterial tests protect the inherited growth engine. Focused tests cover role orientation, reverse venous flow export, paired-bed geometry, shared bed assignment, exact cross-network clearance, and the prospective direct-construction path. Coupled pressure and mass-conservation tests remain future work because that solver is not yet implemented.

Repository layout

Path	Purpose
src/	Core parser, domain, routing, growth, topology, export, and voxelization code
configs/coronary.toml	Inherited arterial coronary configuration
examples/run_coronary_growth.jl	Inherited arterial coronary runner
configs/coronary_full_vascular.toml	Direct 8 um arterial–venous reference configuration
examples/run_coronary_full_vascular.jl	Fail-closed coupled construction runner
docs/	Equations, assumptions, model contracts, audits, and run reports
test/	Unit and regression tests
scripts/	Audit, voxelization, launch, and analysis helpers
dashboards/	Self-contained interactive views generated from accepted exports
output/	Generated local artifacts; do not treat as source

Scientific precedents

The implementation direction is informed by:

• Kaimovitz et al., an integrated three-dimensional porcine coronary arterial, capillary, and venous reconstruction with epicardial, transmural, and perfusion venous subnetworks: https://pmc.ncbi.nlm.nih.gov/articles/PMC2957345/.
• Kassab, Lin, and Fung, coronary venous morphometry and the distinction between sinusal and Thebesian drainage: https://pubmed.ncbi.nlm.nih.gov/7810711/.
• Kassab and Fung, arteriole-capillary-venule topology demonstrating a cross-connected capillary network rather than matched terminal pairs: https://journals.physiology.org/doi/pdf/10.1152/ajpheart.1994.267.1.H319.
• Human CT characterization of coronary sinus and major venous anatomy: https://pmc.ncbi.nlm.nih.gov/articles/PMC4121327/.
• Hague, simultaneous optimization of idealized arterial and venous trees, useful as an optimization precedent rather than a coronary calibration: https://arxiv.org/abs/2308.02700.
• XCAT pulmonary artery/vein volume-filling extension as a precedent for predicting multiple vascular systems from fixed phantom trunks: https://pmc.ncbi.nlm.nih.gov/articles/PMC6434530/.

Relationship to VascularTreeSim.jl

The original project remains the arterial growth-engine baseline. This fork is where heart-specific full vascular development should occur. Changes needed only for coronary artery-vein coupling belong here; reusable, independently validated growth-engine corrections can later be proposed upstream without making the original project depend on unfinished venous functionality.

GitHub: https://github.com/MolloiLab/FullVascularTreeSim.jl