Skip to content

Commit 68dc61d

Browse files
zasextonzasexton
authored
Merge pull request #13 from zasexton/main
Partial resolution of ghpages 404 errors and windows svZeroDSolver exe construction
2 parents 9ff9251 + 5ed466e commit 68dc61d

16 files changed

+5743
-8
lines changed

‎docs/algorithm.html‎

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1" />
6+
<title>CCO Algorithm · svVascularize Docs</title>
7+
<link href="https://fonts.googleapis.com/css?family=Montserrat:400,700" rel="stylesheet" />
8+
<link rel="stylesheet" href="style.css" />
9+
10+
<!-- MathJax: render \( ... \) and \[ ... \]; add argmin/argmax; ignore code/pre -->
11+
<script>
12+
window.MathJax = {
13+
tex: {
14+
inlineMath: [['\\(','\\)']],
15+
displayMath: [['\\[','\\]']],
16+
packages: {'[+]': ['base','ams']},
17+
macros: {
18+
argmin: '\\operatorname*{arg\\,min}',
19+
argmax: '\\operatorname*{arg\\,max}'
20+
}
21+
},
22+
options: {
23+
skipHtmlTags: ['script','noscript','style','textarea','pre','code']
24+
}
25+
};
26+
</script>
27+
<script defer src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
28+
</head>
29+
<body>
30+
<!-- Shared top navigation (copied from doc.html) -->
31+
<header class="topnav">
32+
<div class="container">
33+
<h1>svVascularize</h1>
34+
<nav>
35+
<a href="index.html#about">About</a>
36+
<a href="install.html">Installation</a>
37+
<a class="active" href="doc.html">Documentation</a>
38+
<a href="#simulation">Simulation</a>
39+
<a href="https://pypi.org/project/svv/" target="_blank" rel="noopener">PyPI</a>
40+
<a href="https://github.com/SimVascular/svVascularize" target="_blank" rel="noopener">GitHub</a>
41+
</nav>
42+
</div>
43+
</header>
44+
45+
<!-- Hero -->
46+
<section class="hero">
47+
<div class="container">
48+
<h2>Stochastic Constructive Optimization for Vascular Network Design</h2>
49+
<p></p>
50+
<a class="cta" href="doc.html">Back to Docs</a>
51+
</div>
52+
</section>
53+
54+
<main class="container content">
55+
56+
<h2 id="overview">Overview</h2>
57+
<p>
58+
Stochastic constructive design optimization refers to a class of algorithms that build complex structures
59+
iteratively by adding components (e.g. vessel segments) in accordance to some optimization rules and some
60+
additional constraints. In vascular modeling, the prototypical example is <strong>Constrained Constructive
61+
Optimization (CCO)</strong>-an algorithm introduced by <a href="https://ieeexplore.ieee.org/document/243413" target="_blank" rel="noopener">Schreiner &amp; Buxbaum (1993)</a>
62+
for generating arterial trees. CCO and its related algorithms have become gold-standard techniques for
63+
synthesizing plausible vascular networks in silico <a href="https://pubmed.ncbi.nlm.nih.gov/10207653/" target="_blank" rel="noopener">Karch et&nbsp;al. (1999)</a>.
64+
Recent open implementations (e.g.,
65+
<a href="https://www.ipol.im/pub/art/2023/477/" target="_blank" rel="noopener">OpenCCO</a>) and adaptive variants
66+
(<a href="https://www.nature.com/articles/s41598-021-85434-9" target="_blank" rel="noopener">Sci Rep 2021</a>)
67+
have continued to extend the capabilities of this group of algorithms.
68+
69+
These algorithms strive to mimic physiological design principles including balancing metabolic supply and pumping energy
70+
(Murray's Law) so that synthetic vessels closely resemble the geometry and hemodynamics of native networks.
71+
The construction is stochastic because each new vessel insertion involves a random or pseudo-random sampling of
72+
points within the build space followed by appropriate constraints and an optimization step to integrate that
73+
vessel at a bifurcation point. Over many iterations, this yields a branching network that "grows" throughout
74+
the build space. Often, these networks exhibit fractal-like properties reminiscent of native blood vessels.
75+
These algorithms are powerful in biomedical research, allowing investigators to simulate microvascular
76+
architectures for different organs, conditions, or species where imaging data is sparse.
77+
78+
</p>
79+
80+
<div class="callout tip">
81+
Think of CCO as “grow a vessel → optimize locally → check constraints → accept → repeat,” ensuring you never
82+
stray far from a valid solution.
83+
</div>
84+
85+
<h2 id="core-ideas">Core ideas</h2>
86+
<ul>
87+
<li><strong>Constructive growth:</strong> Start from a seed; add elements (nodes, segments, primitives) one at a time.</li>
88+
<li><strong>Feasibility at every step:</strong> Enforce hard constraints (e.g., geometry, non-overlap, boundary conditions) during growth.</li>
89+
<li><strong>Local optimization:</strong> After each addition, adjust a small neighborhood (topology, positions, radii, weights) to improve an objective.</li>
90+
<li><strong>Greedy–stochastic blend:</strong> Explore candidates stochastically; accept using greedy or tempered criteria.</li>
91+
<li><strong>Anytime property:</strong> You can stop early and still have a valid, usable design.</li>
92+
</ul>
93+
94+
<h2 id="cycle">One growth cycle</h2>
95+
<figure class="figure-center">
96+
<!-- Put your exported figure here; path may be assets/cco_growth_cycle.svg or .png -->
97+
<img src="graphics/growth_cycle.jpg" alt="CCO growth cycle panels A–E with fixed target X." style="max-width:100%; border:2px solid #000;"/>
98+
<figcaption>CCO growth (single iteration). Target <strong>X</strong> is fixed across panels.</figcaption>
99+
</figure>
100+
101+
<h2 id="notation">Local Bifurcation Optimization</h2>
102+
<p>For a fixed target \(X\), choose the best feasible proposal \(p\) by minimizing an objective \(J\):</p>
103+
<div class="mathblock">
104+
\[
105+
p^{*}(X)=\argmin_{p\in \mathcal{P}(X)} J\!\big(\mathcal{T}_k \oplus p\big)
106+
\quad\text{s.t.}\quad p\in\mathcal{F} \;(\text{non-intersection, domain, degree}).
107+
\]
108+
\[
109+
\mathcal{T}_{k+1}=S_k \oplus p^{*}(X).
110+
\]
111+
</div>
112+
<p>Local refinement (bifurcation position \(b\) and radii \(r\)) over a neighborhood \(\mathcal{N}\):</p>
113+
<div class="mathblock">
114+
\[
115+
(b^{*},r^{*})=\argmin_{(b,r)\in \mathcal{N}}
116+
J\!\big(S_k \oplus p(b,r)\big)
117+
\quad\text{(Poiseuille flow, Murray-style constraints).}
118+
\]
119+
</div>
120+
<p>
121+
In practice, \(J\) is a <em>penalized composite</em> that combines hemodynamic power
122+
\(\sum_i R_i Q_i^2\) with geometric costs (e.g., total volume/length and smoothness/turning penalties);
123+
the flows \(Q_i\) are obtained from a fast 0D (Poiseuille) solve for each candidate.
124+
<em>Hard</em> constraints (domain inclusion, segment–segment clearance, degree limits) are enforced as feasibility
125+
filters—candidates failing a cheap pre-check are discarded—or equivalently via an indicator
126+
\(\iota_{\mathcal{F}}(p)\in\{0,\infty\}\) added to \(J\).
127+
<em>Soft</em> constraints (angle/taper bounds, min radius, curvature) are added as penalties,
128+
e.g., \(\mu\sum_i \big[\!g_i(p)\big]_+^2+\nu\sum_j h_j(p)^2\); the Murray relation
129+
\(r_0^{\,n}=r_1^{\,n}+r_2^{\,n}\) (typically \(n\approx 3\)) is enforced either exactly (equality) or via a strong penalty while optimizing \(b\) and \(r\).
130+
The local search is low-dimensional in practice: move \(b\) along a bounded segment/plane and update radii from the flow split,
131+
using a short line search or trust-region step; the accepted proposal is the feasible candidate with the smallest penalized \(J\),
132+
otherwise the routine resamples/relaxes (anneals) if no candidate passes.
133+
</p>
134+
<h2 id="typical-pipeline">Typical CCO pipeline</h2>
135+
<ol>
136+
<li><strong>Initialize</strong> a feasible seed (root node, inlet, or minimal skeleton).</li>
137+
<li><strong>Sample a target</strong> (demand point, region of interest, or heuristic focus).</li>
138+
<li><strong>Propose connections</strong> from the existing structure to the target (multiple candidates).</li>
139+
<li><strong>Project &amp; sanitize</strong> into valid space (snap to domain, avoid collisions/violations).</li>
140+
<li><strong>Local optimize</strong> the neighborhood (positions, radii/weights, minor topology tweaks).</li>
141+
<li><strong>Evaluate constraints</strong> and <strong>score</strong> the objective (with penalties for soft rules).</li>
142+
<li><strong>Select</strong> the best feasible candidate; <strong>commit</strong> to the structure.</li>
143+
<li><strong>Repeat</strong> until coverage/quality targets are met or a budget is exhausted.</li>
144+
</ol>
145+
146+
<h2 id="objective-constraints">Objectives &amp; constraints</h2>
147+
<table>
148+
<thead>
149+
<tr><th>Type</th><th>Examples</th><th>Notes</th></tr>
150+
</thead>
151+
<tbody>
152+
<tr>
153+
<td><strong>Objective</strong></td>
154+
<td>Minimize cost/length, imbalance, pressure drop, or a weighted composite</td>
155+
<td>Often additive across elements; may include regularizers.</td>
156+
</tr>
157+
<tr>
158+
<td><strong>Hard constraints</strong></td>
159+
<td>Geometric validity, non-intersection, boundary inclusion, degree limits</td>
160+
<td>Must hold at every step; violated candidates are rejected.</td>
161+
</tr>
162+
<tr>
163+
<td><strong>Soft constraints</strong></td>
164+
<td>Preferred angles, tapering rules, smoothness</td>
165+
<td>Typically encoded as penalties in the objective.</td>
166+
</tr>
167+
</tbody>
168+
</table>
169+
170+
<h2 id="data-structures">Data structures that help</h2>
171+
<ul>
172+
<li><strong>Spatial index</strong> (k-d tree, BVH) for nearest-neighbor queries and fast collision checks.</li>
173+
<li><strong>Adjacency graph</strong> (nodes/edges) to update local neighborhoods efficiently.</li>
174+
<li><strong>Constraint cache</strong> to memoize expensive checks (e.g., local clearance or regional quotas).</li>
175+
<li><strong>Candidate pool</strong> with ranked proposals and provenance for reproducibility.</li>
176+
</ul>
177+
178+
<h2 id="deep-dive">Deep-dive: how this maps to <code>svVascularize</code></h2>
179+
<p>
180+
The <a href="https://github.com/SimVascular/svVascularize" target="_blank" rel="noopener">svVascularize</a> API follows the CCO pattern and exposes hooks to control sampling, constraints, and local refinement:
181+
</p>
182+
<ul>
183+
<li><strong>Seed/init:</strong> create a root vessel and initial terminals inside the domain (mesh/voxel/signed-distance). <em>(CCO: minimal feasible \(S_0\)).</em></li>
184+
<li><strong>Target sampling:</strong> draw a terminal location \(X\) (uniform, blue-noise, or demand-weighted) to improve coverage.</li>
185+
<li><strong>Candidate proposals:</strong> choose anchors (nearby segments/terminals) and propose a dashed path to \(X\); project into the domain and sanitize (clearance, no self-intersection).</li>
186+
<li><strong>Local optimization:</strong> refine bifurcation position and daughter radii under Poiseuille/Murray constraints to minimize \(J\).</li>
187+
<li><strong>Feasibility check:</strong> accept only if hard constraints pass; otherwise resample or relax.</li>
188+
<li><strong>Commit &amp; update:</strong> add solid segments to obtain \(S_{k+1}\), update flows/pressures and spatial indices.</li>
189+
</ul>
190+
191+
<h3 id="objective">Typical objective and constraints</h3>
192+
<table>
193+
<thead><tr><th>Type</th><th>Examples</th><th>Notes</th></tr></thead>
194+
<tbody>
195+
<tr>
196+
<td><strong>Objective</strong></td>
197+
<td>\(J = \alpha\,\text{Power} + \beta\,\text{Volume} + \gamma\,\text{Smoothness}\)</td>
198+
<td>Weights \(\alpha,\beta,\gamma\) tune energy vs material vs geometry.</td>
199+
</tr>
200+
<tr>
201+
<td><strong>Hard constraints</strong></td>
202+
<td>Domain inclusion, non-intersection, degree limits, inlet/outlet boundary rules</td>
203+
<td>Reject on failure (no penalties).</td>
204+
</tr>
205+
<tr>
206+
<td><strong>Soft constraints</strong></td>
207+
<td>Preferred angles, taper, min/max radius</td>
208+
<td>Encode as penalties within \(J\).</td>
209+
</tr>
210+
</tbody>
211+
</table>
212+
213+
<h3 id="pseudocode">Pseudocode for CCO processes</h3>
214+
<p>The loop below mirrors the implementation pattern.
215+
<pre data-copy><code class="language-python">def cco(seed, domain, params):
216+
T = initialize_structure(seed, domain, params) # T_{0}
217+
while not done(T, params):
218+
X = sample_target(domain, T, params) # fixed target for this iteration
219+
candidates = []
220+
for a in select_anchors(T, X, params):
221+
p = propose(a, X, params) # dashed proposal
222+
p = project_and_sanitize(p, domain, T) # enforce geometry/bounds
223+
(b_star, r_star) = local_optimize(p, T, params)
224+
if hard_constraints_ok(T, p, b_star, r_star, domain):
225+
score = objective(T, p, b_star, r_star, params) # J(...)
226+
candidates.append((score, (p, b_star, r_star)))
227+
if not candidates:
228+
handle_stall(T, X, params) # resample/relax; keep feasibility
229+
continue
230+
_, best = min(candidates, key=lambda t: t[0]) # argmin over feasible
231+
T = commit(T, *best) # accept → T_{k+1}
232+
return T</code></pre>
233+
234+
<h2 id="related">Related stochastic generators</h2>
235+
<ul>
236+
<li><strong>Simulated-annealing vascular optimization (SALVO):</strong>
237+
global re-wiring via Metropolis updates; see
238+
<a href="https://www.nature.com/articles/s41598-021-84432-1" target="_blank" rel="noopener">Sci Rep 2021</a>
239+
and <a href="https://arxiv.org/pdf/2007.07039" target="_blank" rel="noopener">arXiv 2020</a>.
240+
</li>
241+
<li><strong>Growth-based optimization (GBO):</strong>
242+
tissue-demand-guided constructive growth; see
243+
<a href="https://link.springer.com/article/10.1007/s10237-023-01703-8" target="_blank" rel="noopener">Kim et&nbsp;al., 2023</a>
244+
and MRI perfusion validation in
245+
<a href="https://www.sciencedirect.com/science/article/pii/S0169260723006223" target="_blank" rel="noopener">Rundfeldt et&nbsp;al., 2024</a>.
246+
</li>
247+
<li><strong>L-systems / fractal generators:</strong>
248+
procedural branching with Murray-style rules; e.g.
249+
<a href="https://tis.wu.ac.th/index.php/tis/article/view/1407" target="_blank" rel="noopener">Ritraksa et&nbsp;al., 2021</a>.
250+
</li>
251+
<li><strong>More global formulations:</strong>
252+
continuous/integer programs or constructive-global hybrids; e.g.
253+
<a href="https://openscholarship.wustl.edu/cgi/viewcontent.cgi?article=1035&context=cse_research" target="_blank" rel="noopener">WUSTL technical report</a>.
254+
</li>
255+
</ul>
256+
257+
<div class="callout warning">
258+
Over-tight constraints can cause stalls; use progressive tightening or multi-resolution domains for robustness.
259+
</div>
260+
261+
<h2 id="next">Next steps</h2>
262+
<ul>
263+
<li><a href="parameter_space.html">Parameter space &amp; sampling strategies</a></li>
264+
<!-- <li><a href="validation.html">Validation: geometric &amp; hemodynamic checks</a></li> -->
265+
</ul>
266+
</main>
267+
268+
<!-- Footer (copied from doc.html) -->
269+
<footer>
270+
<div class="container">
271+
<p>&copy; 2025 SimVascular, Stanford University, The Regents of the University of California, and others —
272+
<a href="https://opensource.org/license/BSD-3-Clause">BSD 3-Clause License</a><br></p>
273+
</div>
274+
</footer>
275+
276+
<script defer src="script.js"></script>
277+
</body>
278+
</html>

‎docs/api/boundary_conditions.html‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<title>Title</title>
6+
</head>
7+
<body>
8+
9+
</body>
10+
</html>

0 commit comments

Comments
 (0)