Skip to content

Commit 9ece5a2

Browse files
zasextonzasexton
committed
Align API docs with implemented interfaces
1 parent 086da58 commit 9ece5a2

File tree

5 files changed

+136
-109
lines changed

5 files changed

+136
-109
lines changed

‎docs/api/domain.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -335,7 +335,7 @@ <h3>Mesh Generation</h3>
335335
<h4>Parameters</h4>
336336
<ul>
337337
<li><code>resolution</code> (int): Grid resolution for marching cubes/squares</li>
338-
<li><code>get_largest</code> (bool, default=True): Extract only largest connected component</li>
338+
<li><code>get_largest</code> (bool, default=True): Reserved (current implementation always returns the largest connected component)</li>
339339
</ul>
340340
<h4>Returns</h4>
341341
<ul>
@@ -664,4 +664,4 @@ <h4 class="sidebar-title">On This Page</h4>
664664
<script defer src="../script.js"></script>
665665
<script defer src="script_api.js"></script>
666666
</body>
667-
</html>
667+
</html>

‎docs/api/forest.html‎

Lines changed: 32 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -100,11 +100,11 @@ <h2>Quick Example</h2>
100100
# Grow networks
101101
forest.add(100) # Add 100 vessels to each tree
102102

103-
# Connect trees within networks
104-
forest.connect(degree=3) # Bezier connections
103+
# Connect trees within networks (start with cubic curves)
104+
forest.connect(3)
105105

106106
# Visualize
107-
forest.show()</code></pre>
107+
forest.show(plot_domain=True)</code></pre>
108108
</div>
109109

110110
<!-- Main Documentation Grid -->
@@ -333,18 +333,20 @@ <h2>Connection Methods</h2>
333333

334334
<div class="api-method">
335335
<div class="api-method-signature">
336-
<code>connect(degree=3, **kwargs)</code>
336+
<code>connect(*args, **kwargs)</code>
337337
</div>
338-
<p>Create connections between trees within networks.</p>
338+
<p>Create connections between trees within each network.</p>
339339
<div class="api-method-params">
340-
<h4>Parameters</h4>
340+
<h4>Usage</h4>
341341
<ul>
342-
<li><code>degree</code> (int, optional): Polynomial degree for Bezier connections</li>
343-
<li><code>**kwargs</code>: Additional parameters for connection algorithm</li>
342+
<li><code>forest.connect()</code>: start with linear connections</li>
343+
<li><code>forest.connect(3)</code>: start optimization with cubic curves</li>
344+
<li><code>forest.connect(curve_type='NURBS')</code>: switch curve family</li>
344345
</ul>
345346
<h4>Notes</h4>
346-
<p>Creates a ForestConnection object that manages inter-tree connections using various
347-
algorithms (Bezier, NURBS, geodesic, etc.).</p>
347+
<p>The method instantiates a <code>ForestConnection</code> that orchestrates
348+
<code>TreeConnection</code> and <code>VesselConnection</code> objects to build
349+
collision-free connecting vessels.</p>
348350
</div>
349351
</div>
350352
</section>
@@ -373,11 +375,14 @@ <h4>Notes</h4>
373375
<div class="api-method-signature">
374376
<code>show(**kwargs)</code>
375377
</div>
376-
<p>Visualize the entire forest with different networks colored separately.</p>
378+
<p>Visualize the entire forest with PyVista.</p>
377379
<div class="api-method-params">
378380
<h4>Parameters</h4>
379381
<ul>
380-
<li><code>**kwargs</code>: PyVista plotting parameters</li>
382+
<li><code>colors</code> (list[str], optional): Cycle of colors for each tree</li>
383+
<li><code>plot_domain</code> (bool): Overlay the domain boundary (default: False)</li>
384+
<li><code>return_plotter</code> (bool): Return the PyVista plotter instead of showing</li>
385+
<li><code>**kwargs</code>: Additional PyVista plotting parameters</li>
381386
</ul>
382387
</div>
383388
</div>
@@ -425,10 +430,10 @@ <h3>Arterial-Venous Network</h3>
425430
f"Venous terminals: {forest.networks[1][0].n_terminals}")
426431

427432
# Connect within networks if multiple trees
428-
forest.connect(degree=3)
433+
forest.connect(3)
429434

430435
# Visualize with different colors
431-
forest.show(arterial_color='red', venous_color='blue')</code></pre>
436+
forest.show(colors=['red', 'blue'], plot_domain=True)</code></pre>
432437
</div>
433438

434439
<div class="api-example">
@@ -457,11 +462,11 @@ <h3>Multi-Tree Network with Connections</h3>
457462
forest.add(50)
458463

459464
# Create inter-tree connections
460-
forest.connect(degree=5) # Higher degree for smoother connections
465+
forest.connect(5) # Higher degree for smoother connections
461466

462467
# Access connection data
463468
if forest.connections:
464-
print(f"Number of connections: {len(forest.connections.paths)}")
469+
print(f"Tree connections solved: {len(forest.connections.tree_connections)}")
465470

466471
# Export connected network
467472
forest.export_solid(outdir='connected_network')</code></pre>
@@ -470,6 +475,7 @@ <h3>Multi-Tree Network with Connections</h3>
470475
<div class="api-example">
471476
<h3>Competitive Growth Pattern</h3>
472477
<pre data-copy><code class="language-python"># Enable competition between networks
478+
import numpy as np
473479
forest = Forest(
474480
domain=domain,
475481
n_networks=3, # Three competing networks
@@ -491,8 +497,15 @@ <h3>Competitive Growth Pattern</h3>
491497

492498
# Analyze competition results
493499
import matplotlib.pyplot as plt
494-
for i in range(3):
495-
plt.plot(stats[f'network_{i}'], label=f'Network {i}')
500+
# Track terminal counts over time
501+
terminal_history = []
502+
for _ in range(50):
503+
forest.add(1)
504+
terminal_history.append([forest.networks[i][0].n_terminals for i in range(3)])
505+
506+
terminal_history = np.array(terminal_history)
507+
for i in range(terminal_history.shape[1]):
508+
plt.plot(terminal_history[:, i], label=f'Network {i}')
496509
plt.xlabel('Growth Step')
497510
plt.ylabel('Number of Terminals')
498511
plt.legend()
@@ -621,4 +634,4 @@ <h4 class="sidebar-title">On This Page</h4>
621634
<script defer src="../script.js"></script>
622635
<script defer src="script_api.js"></script>
623636
</body>
624-
</html>
637+
</html>

‎docs/api/index_api.html‎

Lines changed: 77 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -152,22 +152,22 @@ <h4>Submodules</h4>
152152
<tr>
153153
<td><code>domain.core</code></td>
154154
<td>Core matrix operations</td>
155-
<td>AMatrix, HMatrix, MMatrix, NMatrix</td>
155+
<td>a_matrix(), h_matrix(), m_matrix(), n_matrix()</td>
156156
</tr>
157157
<tr>
158158
<td><code>domain.io</code></td>
159159
<td>Input/output operations</td>
160-
<td>read(), write(), export()</td>
160+
<td>read()</td>
161161
</tr>
162162
<tr>
163163
<td><code>domain.kernel</code></td>
164-
<td>Kernel functions and coordinate systems</td>
165-
<td>CoordinateSystem, Cost, Kernel</td>
164+
<td>Kernel functions and coordinate transforms</td>
165+
<td>Kernel, cost(), cart2sph(), sph2cart()</td>
166166
</tr>
167167
<tr>
168168
<td><code>domain.routines</code></td>
169169
<td>Computational routines</td>
170-
<td>allocate(), discretize(), tetrahedralize()</td>
170+
<td>allocate(), contour(), tetrahedralize(), boolean()</td>
171171
</tr>
172172
<tr>
173173
<td><code>domain.solver</code></td>
@@ -235,24 +235,24 @@ <h4>Connection Methods</h4>
235235
</thead>
236236
<tbody>
237237
<tr>
238-
<td><code>BezierConnection</code></td>
239-
<td>Bezier curve connections</td>
240-
<td>Smooth, controllable curves</td>
238+
<td><code>ForestConnection</code></td>
239+
<td>High-level connection manager</td>
240+
<td>Builds connections for each network</td>
241241
</tr>
242242
<tr>
243-
<td><code>CatmullRomConnection</code></td>
244-
<td>Catmull-Rom spline connections</td>
245-
<td>Interpolating through points</td>
243+
<td><code>TreeConnection</code></td>
244+
<td>Per-network connection solver</td>
245+
<td>Assigns and optimizes tree-to-tree links</td>
246246
</tr>
247247
<tr>
248-
<td><code>GeodesicConnection</code></td>
249-
<td>Geodesic path connections</td>
250-
<td>Shortest path on surfaces</td>
248+
<td><code>VesselConnection</code></td>
249+
<td>Single connection optimizer</td>
250+
<td>Generates connecting vessel segments</td>
251251
</tr>
252252
<tr>
253-
<td><code>NURBSConnection</code></td>
254-
<td>NURBS curve connections</td>
255-
<td>Precise geometric control</td>
253+
<td><code>Curve</code></td>
254+
<td>Curve factory</td>
255+
<td>Supports Bezier, Catmull-Rom, and NURBS shapes</td>
256256
</tr>
257257
</tbody>
258258
</table>
@@ -267,21 +267,28 @@ <h4>Main Classes</h4>
267267
</div>
268268
<div class="api-example">
269269
<h4>Example Usage</h4>
270-
<pre data-copy><code class="language-python">from svv.forest import Forest
271-
from svv.forest.connect import BezierConnection
270+
<pre data-copy><code class="language-python">import pyvista as pv
271+
from svv.domain import Domain
272+
from svv.forest import Forest
273+
274+
# Prepare a domain and build its implicit representation
275+
domain = Domain(pv.Cube())
276+
domain.create()
277+
domain.solve()
278+
domain.build()
272279

273-
# Create a forest and add trees
274-
forest = Forest()
275-
forest.add_tree(tree1)
276-
forest.add_tree(tree2)
280+
# Initialize a forest with two trees in one network
281+
trees_per_network = [2]
282+
forest = Forest(domain=domain, n_networks=1, n_trees_per_network=trees_per_network)
283+
forest.set_domain(domain)
284+
forest.set_roots() # Randomize root placement
285+
forest.add(50) # Grow 50 vessels per tree
277286

278-
# Connect trees using Bezier curves
279-
connection = BezierConnection(control_points=4)
280-
forest.connect_trees(tree1, tree2, method=connection)
287+
# Connect the trees (starting with cubic curves)
288+
forest.connect(3)
281289

282-
# Export the forest
283-
from svv.forest.export import export_solid
284-
export_solid(forest, 'forest_model.stl')</code></pre>
290+
# Export watertight solids for downstream simulation or fabrication
291+
forest.export_solid(outdir='forest_model')</code></pre>
285292
</div>
286293
</article>
287294

@@ -384,28 +391,21 @@ <h5>1D Models</h5>
384391
<div class="api-example">
385392
<h4>Example Usage</h4>
386393
<pre data-copy><code class="language-python">from svv.simulation import Simulation
387-
from svv.simulation.boundary_conditions import FlowBC, PressureBC
388-
from svv.simulation.fluid.rom.zero_d import zerod_tree
394+
from svv.simulation.fluid.rom.zero_d.zerod_tree import export_0d_simulation
389395

390-
# Set up simulation
391-
sim = Simulation(tree, dimension='0D')
396+
# Wrap a generated tree in a Simulation container
397+
sim = Simulation(tree, name='example_sim')
392398

393-
# Configure boundary conditions
394-
sim.add_boundary_condition('inlet', FlowBC(flow_rate=5.0))
395-
sim.add_boundary_condition('outlet', PressureBC(pressure=80.0))
399+
# Build CFD-ready meshes and identify boundary faces
400+
sim.build_meshes(fluid=True, tissue=False, boundary_layer=True)
401+
sim.extract_faces(crease_angle=60.0)
396402

397-
# Set fluid properties
398-
sim.set_parameters(
399-
viscosity=0.004, # Pa·s
400-
density=1060 # kg/m³
401-
)
402-
403-
# Run simulation
404-
results = sim.run(time_steps=1000, dt=0.001)
403+
# Construct and write an svFSI configuration
404+
sim.construct_3d_fluid_simulation()
405+
sim.write_3d_fluid_simulation()
405406

406-
# Analyze results
407-
print(f"Mean pressure: {results.pressure.mean():.2f} mmHg")
408-
print(f"Mean flow: {results.flow.mean():.2f} mL/s")</code></pre>
407+
# Export a matching 0D model for fast hemodynamic studies
408+
export_0d_simulation(tree, outdir='tree_0d')</code></pre>
409409
</div>
410410
</article>
411411

@@ -427,8 +427,10 @@ <h3><code>svv.utils</code></h3>
427427
<div class="api-submodules">
428428
<h4>Available Utilities</h4>
429429
<ul>
430-
<li><code>remeshing.remesh()</code> - Adaptive mesh refinement using MMG</li>
431-
<li><code>spatial.c_distance()</code> - Optimized distance calculations</li>
430+
<li><code>remeshing.remesh_surface()</code> - Remesh surface meshes with MMG</li>
431+
<li><code>remeshing.remesh_volume()</code> - Volume remeshing helpers</li>
432+
<li><code>spatial.minimum_segment_distance()</code> - Pairwise vessel distance checks</li>
433+
<li><code>spatial.minimum_self_segment_distance()</code> - Self-collision distance utility</li>
432434
</ul>
433435
</div>
434436
</article>
@@ -446,22 +448,15 @@ <h3><code>svv.visualize</code></h3>
446448

447449
<div class="api-example">
448450
<h4>Example Usage</h4>
449-
<pre data-copy><code class="language-python">from svv.visualize.tree import show, points
450-
from svv.visualize.forest import show as show_forest
451-
452-
# Visualize a single tree
453-
show(tree,
454-
color_by='radius',
455-
show_points=True,
456-
backend='matplotlib')
457-
458-
# Export point cloud
459-
points.export_points(tree, 'tree_points.vtk')
460-
461-
# Visualize entire forest
462-
show_forest(forest,
463-
highlight_connections=True,
464-
save_to='forest_viz.png')</code></pre>
451+
<pre data-copy><code class="language-python">from svv.visualize.tree.show import show as show_tree
452+
from svv.visualize.forest.show import show as show_forest
453+
454+
# Visualize a single tree with the enclosing domain
455+
show_tree(tree, color='crimson', plot_domain=True)
456+
457+
# Visualize an entire forest and save a screenshot
458+
plotter = show_forest(forest, colors=['red', 'royalblue'], plot_domain=True, return_plotter=True)
459+
plotter.screenshot('forest_viz.png')</code></pre>
465460
</div>
466461
</article>
467462
</main>
@@ -485,23 +480,29 @@ <h2>Common Examples</h2>
485480
<div class="api-example-grid">
486481
<div class="api-example-card">
487482
<h3>Generate a Vascular Tree</h3>
488-
<pre data-copy><code class="language-python">from svv.tree import Tree
483+
<pre data-copy><code class="language-python">import pyvista as pv
489484
from svv.domain import Domain
485+
from svv.tree import Tree
486+
487+
domain = Domain(pv.Cube())
488+
domain.create()
489+
domain.solve()
490+
domain.build()
491+
492+
tree = Tree()
493+
tree.set_domain(domain)
494+
tree.set_root()
495+
tree.n_add(100)
490496

491-
domain = Domain(size=(10, 10, 10))
492-
tree = Tree(domain, n_terminals=100)
493-
tree.generate(method='CCO')
494-
tree.export('vascular_tree.vtk')</code></pre>
497+
# Export watertight geometry for printing or meshing
498+
tree.export_solid(outdir='vascular_tree')</code></pre>
495499
</div>
496500

497501
<div class="api-example-card">
498502
<h3>Run 0D Simulation</h3>
499-
<pre data-copy><code class="language-python">from svv.simulation.fluid.rom.zero_d import zerod_tree
503+
<pre data-copy><code class="language-python">from svv.simulation.fluid.rom.zero_d.zerod_tree import export_0d_simulation
500504

501-
model = zerod_tree(tree)
502-
model.set_cardiac_output(5.0) # L/min
503-
results = model.solve()
504-
model.plot_results()</code></pre>
505+
export_0d_simulation(tree, outdir='tree_0d', steady=True)</code></pre>
505506
</div>
506507
</div>
507508
</section>
@@ -546,4 +547,4 @@ <h3>Units</h3>
546547
<script defer src="../script.js"></script>
547548
<script defer src="script_api.js"></script>
548549
</body>
549-
</html>
550+
</html>

0 commit comments

Comments
 (0)