Skip to content

Geometry Helpers

The voids.geom sub-package provides functions for normalizing characteristic pore and throat sizes and computing hydraulic conductances.

Characteristic Size

voids.geom.characteristic

area_equivalent_diameter 

area_equivalent_diameter(area)

Return the circular-equivalent diameter associated with an area array.

Parameters:

Name Type Description Default
area ndarray

Cross-sectional area array.

 required

Returns:

Type Description
ndarray

Diameter defined by d = 2 * sqrt(area / pi).
Source code in src/voids/geom/characteristic.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
def area_equivalent_diameter(area: np.ndarray) -> np.ndarray:
    """Return the circular-equivalent diameter associated with an area array.

    Parameters
    ----------
    area :
        Cross-sectional area array.

    Returns
    -------
    numpy.ndarray
        Diameter defined by ``d = 2 * sqrt(area / pi)``.
    """

    area = np.asarray(area, dtype=float)
    return np.asarray(2.0 * np.sqrt(area / np.pi))

normalize_characteristic_size 

normalize_characteristic_size(values, *, field_name)

Normalize a size-like field to a characteristic diameter surrogate.

Parameters:

Name Type Description Default
values ndarray

Raw size-like field values.

 required
field_name str | None

Source field name, used to convert radii and areas to diameters.

 required

Returns:

Type Description
ndarray

Characteristic-size array interpreted as a diameter-like quantity.
Source code in src/voids/geom/characteristic.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def normalize_characteristic_size(
    values: np.ndarray,
    *,
    field_name: str | None,
) -> np.ndarray:
    """Normalize a size-like field to a characteristic diameter surrogate.

    Parameters
    ----------
    values :
        Raw size-like field values.
    field_name :
        Source field name, used to convert radii and areas to diameters.

    Returns
    -------
    numpy.ndarray
        Characteristic-size array interpreted as a diameter-like quantity.
    """

    arr = np.asarray(values, dtype=float)
    if field_name == "radius_inscribed":
        return 2.0 * arr
    if field_name == "area":
        return area_equivalent_diameter(arr)
    return arr

characteristic_size 

characteristic_size(
    store,
    *,
    expected_shape=None,
    fields=_CHARACTERISTIC_SIZE_FIELDS,
)

Return a preferred characteristic size array from a pore/throat store.

Parameters:

Name Type Description Default
store Mapping[str, object]

Mapping such as net.pore or net.throat.

 required
expected_shape tuple[int, ...] | None

Optional expected array shape.

 None
fields tuple[str, ...]

Ordered field priority. The default is diameter_equivalent -> diameter_inscribed -> radius_inscribed -> area.

 _CHARACTERISTIC_SIZE_FIELDS

Returns:

Type Description
tuple

Pair (values, label) where values is a characteristic-size array and label is the originating field name.

Raises:

Type Description
KeyError

If none of the requested fields exists.
ValueError

If a selected field does not match expected_shape.
Source code in src/voids/geom/characteristic.py 
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def characteristic_size(
    store: Mapping[str, object],
    *,
    expected_shape: tuple[int, ...] | None = None,
    fields: tuple[str, ...] = _CHARACTERISTIC_SIZE_FIELDS,
) -> tuple[np.ndarray, str]:
    """Return a preferred characteristic size array from a pore/throat store.

    Parameters
    ----------
    store :
        Mapping such as ``net.pore`` or ``net.throat``.
    expected_shape :
        Optional expected array shape.
    fields :
        Ordered field priority. The default is
        ``diameter_equivalent -> diameter_inscribed -> radius_inscribed -> area``.

    Returns
    -------
    tuple
        Pair ``(values, label)`` where ``values`` is a characteristic-size array
        and ``label`` is the originating field name.

    Raises
    ------
    KeyError
        If none of the requested fields exists.
    ValueError
        If a selected field does not match ``expected_shape``.
    """

    for field_name in fields:
        if field_name not in store:
            continue
        arr = normalize_characteristic_size(
            np.asarray(store[field_name], dtype=float), field_name=field_name
        )
        if expected_shape is not None and arr.shape != expected_shape:
            raise ValueError(f"field '{field_name}' must have shape {expected_shape}")
        return arr, field_name
    raise KeyError(f"Need one of the characteristic size fields: {fields}")

Hydraulic Geometry

voids.geom.hydraulic

generic_poiseuille_conductance 

generic_poiseuille_conductance(
    net, viscosity, *, throat_viscosity=None
)

Compute throat conductance using a circular Poiseuille approximation.

Parameters:

Name Type Description Default
net Network

Network containing throat geometry or precomputed hydraulic conductance.

 required
viscosity float | ndarray | None

Dynamic viscosity.

 required

Returns:

Type Description
ndarray

Conductance array for all throats.

Raises:

Type Description
ValueError

If viscosity is non-positive or if precomputed conductance is negative.
KeyError

If required geometry is missing.
Notes

When no precomputed conductance is supplied, the model uses

g = pi * r**4 / (8 * mu * L)

with radius inferred from either throat.diameter_inscribed or throat.area.

Source code in src/voids/geom/hydraulic.py 
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
def generic_poiseuille_conductance(
    net: Network,
    viscosity: float | np.ndarray | None,
    *,
    throat_viscosity: float | np.ndarray | None = None,
) -> np.ndarray:
    """Compute throat conductance using a circular Poiseuille approximation.

    Parameters
    ----------
    net :
        Network containing throat geometry or precomputed hydraulic conductance.
    viscosity :
        Dynamic viscosity.

    Returns
    -------
    numpy.ndarray
        Conductance array for all throats.

    Raises
    ------
    ValueError
        If viscosity is non-positive or if precomputed conductance is negative.
    KeyError
        If required geometry is missing.

    Notes
    -----
    When no precomputed conductance is supplied, the model uses

    ``g = pi * r**4 / (8 * mu * L)``

    with radius inferred from either ``throat.diameter_inscribed`` or
    ``throat.area``.
    """

    if "hydraulic_conductance" in net.throat:
        g = np.asarray(net.throat["hydraulic_conductance"], dtype=float)
        if (g < 0).any():
            raise ValueError("throat.hydraulic_conductance contains negative values")
        return g.copy()

    selected_viscosity = throat_viscosity if throat_viscosity is not None else viscosity
    if selected_viscosity is None:
        raise ValueError("Need either viscosity or throat_viscosity")
    mu_t = _broadcast_viscosity(selected_viscosity, (net.Nt,))

    _require(net, "throat", ("length",))
    L = np.asarray(net.throat["length"], dtype=float)
    if "diameter_inscribed" in net.throat:
        d = np.asarray(net.throat["diameter_inscribed"], dtype=float)
    elif "area" in net.throat:
        d = _diameter_from_area(np.asarray(net.throat["area"], dtype=float))
    else:
        raise KeyError(
            "Need throat.diameter_inscribed or throat.area (or precomputed hydraulic_conductance)"
        )
    r = 0.5 * d
    return np.asarray((np.pi * r**4) / (8.0 * mu_t * L), dtype=float)

hagen_poiseuille_conductance 

hagen_poiseuille_conductance(
    net,
    viscosity,
    *,
    pore_viscosity=None,
    throat_viscosity=None,
)

Compute the Hagen-Poiseuille conduit conductance.

When pore-throat-pore conduit lengths and pore/throat areas are available, the model computes the harmonic series conductance of the pore-1, throat, and pore-2 segments, with each segment using g = A**2 / (8 * pi * mu * L). If that conduit decomposition is unavailable, it falls back to the single throat circular Poiseuille model, which is the same segment law applied to one throat segment.

Source code in src/voids/geom/hydraulic.py 
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
def hagen_poiseuille_conductance(
    net: Network,
    viscosity: float | np.ndarray | None,
    *,
    pore_viscosity: float | np.ndarray | None = None,
    throat_viscosity: float | np.ndarray | None = None,
) -> np.ndarray:
    """Compute the Hagen-Poiseuille conduit conductance.

    When pore-throat-pore conduit lengths and pore/throat areas are available,
    the model computes the harmonic series conductance of the pore-1, throat,
    and pore-2 segments, with each segment using
    ``g = A**2 / (8 * pi * mu * L)``. If that conduit decomposition is
    unavailable, it falls back to the single throat circular Poiseuille model,
    which is the same segment law applied to one throat segment.
    """

    if "hydraulic_conductance" in net.throat:
        return generic_poiseuille_conductance(net, viscosity, throat_viscosity=throat_viscosity)
    try:
        return _hagen_poiseuille_conduit(
            net,
            viscosity,
            pore_viscosity=pore_viscosity,
            throat_viscosity=throat_viscosity,
        )
    except KeyError:
        return generic_poiseuille_conductance(net, viscosity, throat_viscosity=throat_viscosity)

valvatne_blunt_throat_conductance 

valvatne_blunt_throat_conductance(
    net, viscosity, *, throat_viscosity=None
)

Compute shape-aware throat conductance using throat geometry only.

Parameters:

Name Type Description Default
net Network

Network containing throat length and cross-sectional geometry.

 required
viscosity float | ndarray | None

Dynamic viscosity.

 required

Returns:

Type Description
ndarray

Shape-aware throat conductance array.

Raises:

Type Description
ValueError

If viscosity is not positive.
KeyError

If required throat geometry is unavailable.
Source code in src/voids/geom/hydraulic.py 
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
def valvatne_blunt_throat_conductance(
    net: Network,
    viscosity: float | np.ndarray | None,
    *,
    throat_viscosity: float | np.ndarray | None = None,
) -> np.ndarray:
    """Compute shape-aware throat conductance using throat geometry only.

    Parameters
    ----------
    net :
        Network containing throat length and cross-sectional geometry.
    viscosity :
        Dynamic viscosity.

    Returns
    -------
    numpy.ndarray
        Shape-aware throat conductance array.

    Raises
    ------
    ValueError
        If viscosity is not positive.
    KeyError
        If required throat geometry is unavailable.
    """

    if "hydraulic_conductance" in net.throat:
        return generic_poiseuille_conductance(net, viscosity, throat_viscosity=throat_viscosity)
    selected_viscosity = throat_viscosity if throat_viscosity is not None else viscosity
    if selected_viscosity is None:
        raise ValueError("Need either viscosity or throat_viscosity")
    _broadcast_viscosity(selected_viscosity, (net.Nt,))
    return _throat_only_shape_factor_conductance(
        net,
        viscosity,
        throat_viscosity=throat_viscosity,
    )

valvatne_blunt_conductance 

valvatne_blunt_conductance(
    net,
    viscosity,
    *,
    pore_viscosity=None,
    throat_viscosity=None,
)

Compute a shape-factor-aware single-phase conductance following Valvatne-Blunt.

Parameters:

Name Type Description Default
net Network

Network containing throat and, ideally, pore geometry.

 required
viscosity float | ndarray | None

Dynamic viscosity.

 required

Returns:

Type Description
ndarray

Throat conductance array.

Raises:

Type Description
ValueError

If viscosity is not positive.
Notes

This implements the single-phase geometric closure used in the Imperial College Valvatne-Blunt style network model:

  • segment conductance is evaluated as g = k * G * A**2 / (mu * L)
  • k = 3/5 for triangular ducts
  • k = 0.5623 for square ducts
  • k = 1/2 for circular ducts

The selection logic is:

  1. If throat.hydraulic_conductance is explicitly present, return it.
  2. Else, if conduit lengths and pore/throat shape data are available, compute a harmonic pore1-core-pore2 conductance.
  3. Else, if throat-only shape data are available, use a throat-only model.
  4. Else, warn and fall back to circular Poiseuille conductance.

This is still a single-phase closure; corner films and multiphase occupancy are intentionally out of scope here.

Source code in src/voids/geom/hydraulic.py 
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
def valvatne_blunt_conductance(
    net: Network,
    viscosity: float | np.ndarray | None,
    *,
    pore_viscosity: float | np.ndarray | None = None,
    throat_viscosity: float | np.ndarray | None = None,
) -> np.ndarray:
    """Compute a shape-factor-aware single-phase conductance following Valvatne-Blunt.

    Parameters
    ----------
    net :
        Network containing throat and, ideally, pore geometry.
    viscosity :
        Dynamic viscosity.

    Returns
    -------
    numpy.ndarray
        Throat conductance array.

    Raises
    ------
    ValueError
        If viscosity is not positive.

    Notes
    -----
    This implements the single-phase geometric closure used in the Imperial
    College Valvatne-Blunt style network model:

    - segment conductance is evaluated as ``g = k * G * A**2 / (mu * L)``
    - ``k = 3/5`` for triangular ducts
    - ``k = 0.5623`` for square ducts
    - ``k = 1/2`` for circular ducts

    The selection logic is:

    1. If ``throat.hydraulic_conductance`` is explicitly present, return it.
    2. Else, if conduit lengths and pore/throat shape data are available, compute a
       harmonic pore1-core-pore2 conductance.
    3. Else, if throat-only shape data are available, use a throat-only model.
    4. Else, warn and fall back to circular Poiseuille conductance.

    This is still a single-phase closure; corner films and multiphase occupancy are
    intentionally out of scope here.
    """

    if "hydraulic_conductance" in net.throat:
        return generic_poiseuille_conductance(net, viscosity, throat_viscosity=throat_viscosity)

    _resolve_pore_throat_viscosities(
        net,
        viscosity,
        pore_viscosity=pore_viscosity,
        throat_viscosity=throat_viscosity,
    )

    try:
        return _valvatne_conduit_baseline(
            net,
            viscosity,
            pore_viscosity=pore_viscosity,
            throat_viscosity=throat_viscosity,
        )
    except KeyError:
        pass

    try:
        return _throat_only_shape_factor_conductance(
            net,
            viscosity,
            throat_viscosity=throat_viscosity,
        )
    except KeyError:
        warnings.warn(
            "Insufficient geometry for shape-factor model; falling back to generic_poiseuille",
            RuntimeWarning,
            stacklevel=2,
        )
        return generic_poiseuille_conductance(net, viscosity, throat_viscosity=throat_viscosity)

valvatne_blunt_baseline_conductance 

valvatne_blunt_baseline_conductance(
    net,
    viscosity,
    *,
    pore_viscosity=None,
    throat_viscosity=None,
)

Backward-compatible alias for :func:valvatne_blunt_conductance.

Source code in src/voids/geom/hydraulic.py 
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
def valvatne_blunt_baseline_conductance(
    net: Network,
    viscosity: float | np.ndarray | None,
    *,
    pore_viscosity: float | np.ndarray | None = None,
    throat_viscosity: float | np.ndarray | None = None,
) -> np.ndarray:
    """Backward-compatible alias for :func:`valvatne_blunt_conductance`."""

    return valvatne_blunt_conductance(
        net,
        viscosity,
        pore_viscosity=pore_viscosity,
        throat_viscosity=throat_viscosity,
    )

auto_conductance 

auto_conductance(
    net,
    viscosity,
    *,
    pore_viscosity=None,
    throat_viscosity=None,
)

Compute conductance using the richest available built-in model.

The selection hierarchy is:

  1. precomputed throat.hydraulic_conductance
  2. OpenPNM-style throat.hydraulic_size_factors
  3. explicit shape-factor pore-throat-pore valvatne_blunt
  4. circular conduit hagen_poiseuille
  5. throat-only valvatne_blunt_throat
  6. fallback generic_poiseuille
Source code in src/voids/geom/hydraulic.py 
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
def auto_conductance(
    net: Network,
    viscosity: float | np.ndarray | None,
    *,
    pore_viscosity: float | np.ndarray | None = None,
    throat_viscosity: float | np.ndarray | None = None,
) -> np.ndarray:
    """Compute conductance using the richest available built-in model.

    The selection hierarchy is:

    1. precomputed ``throat.hydraulic_conductance``
    2. OpenPNM-style ``throat.hydraulic_size_factors``
    3. explicit shape-factor pore-throat-pore ``valvatne_blunt``
    4. circular conduit ``hagen_poiseuille``
    5. throat-only ``valvatne_blunt_throat``
    6. fallback ``generic_poiseuille``
    """

    selected = _select_auto_conductance_model(net)
    if selected == "hydraulic_size_factors":
        return _hydraulic_size_factor_conductance(
            net,
            viscosity,
            pore_viscosity=pore_viscosity,
            throat_viscosity=throat_viscosity,
        )
    return throat_conductance(
        net,
        viscosity,
        model=selected,
        pore_viscosity=pore_viscosity,
        throat_viscosity=throat_viscosity,
    )

available_conductance_models 

available_conductance_models()

Return the names of built-in hydraulic conductance models.

Returns:

Type Description
tuple of str

Available model names.
Source code in src/voids/geom/hydraulic.py 
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
def available_conductance_models() -> tuple[str, ...]:
    """Return the names of built-in hydraulic conductance models.

    Returns
    -------
    tuple of str
        Available model names.
    """

    return (
        "auto",
        "generic_poiseuille",
        "hagen_poiseuille",
        "valvatne_blunt_throat",
        "valvatne_blunt",
        "valvatne_blunt_baseline",
    )

throat_conductance 

throat_conductance(
    net,
    viscosity,
    model="generic_poiseuille",
    *,
    pore_viscosity=None,
    throat_viscosity=None,
)

Dispatch to a throat hydraulic conductance model.

Parameters:

Name Type Description Default
net Network

Network containing the required geometry.

 required
viscosity float | ndarray | None

Dynamic viscosity.

 required
model str

Conductance model name.

 'generic_poiseuille'

Returns:

Type Description
ndarray

Throat conductance array.

Raises:

Type Description
ValueError

If model is unknown.
Source code in src/voids/geom/hydraulic.py 
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
def throat_conductance(
    net: Network,
    viscosity: float | np.ndarray | None,
    model: str = "generic_poiseuille",
    *,
    pore_viscosity: float | np.ndarray | None = None,
    throat_viscosity: float | np.ndarray | None = None,
) -> np.ndarray:
    """Dispatch to a throat hydraulic conductance model.

    Parameters
    ----------
    net :
        Network containing the required geometry.
    viscosity :
        Dynamic viscosity.
    model :
        Conductance model name.

    Returns
    -------
    numpy.ndarray
        Throat conductance array.

    Raises
    ------
    ValueError
        If ``model`` is unknown.
    """

    if model == "auto":
        return auto_conductance(
            net,
            viscosity,
            pore_viscosity=pore_viscosity,
            throat_viscosity=throat_viscosity,
        )
    if model == "generic_poiseuille":
        return generic_poiseuille_conductance(net, viscosity, throat_viscosity=throat_viscosity)
    if model == "hagen_poiseuille":
        return hagen_poiseuille_conductance(
            net,
            viscosity,
            pore_viscosity=pore_viscosity,
            throat_viscosity=throat_viscosity,
        )
    if model == "valvatne_blunt_throat":
        return valvatne_blunt_throat_conductance(
            net,
            viscosity,
            throat_viscosity=throat_viscosity,
        )
    if model == "valvatne_blunt":
        return valvatne_blunt_conductance(
            net,
            viscosity,
            pore_viscosity=pore_viscosity,
            throat_viscosity=throat_viscosity,
        )
    if model == "valvatne_blunt_baseline":
        return valvatne_blunt_conductance(
            net,
            viscosity,
            pore_viscosity=pore_viscosity,
            throat_viscosity=throat_viscosity,
        )
    raise ValueError(f"Unknown conductance model '{model}'")

throat_conductance_with_sensitivities 

throat_conductance_with_sensitivities(
    net,
    viscosity,
    model="generic_poiseuille",
    *,
    pore_viscosity=None,
    throat_viscosity=None,
    pore_dviscosity_dpressure=None,
    throat_dviscosity_dpressure=None,
)

Return throat conductance and endpoint pressure sensitivities.

Notes

The returned arrays are (g, dg_dpi, dg_dpj) where i and j are the pore indices in net.throat_conns[:, 0] and net.throat_conns[:, 1].

Source code in src/voids/geom/hydraulic.py 
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
def throat_conductance_with_sensitivities(
    net: Network,
    viscosity: float | np.ndarray | None,
    model: str = "generic_poiseuille",
    *,
    pore_viscosity: float | np.ndarray | None = None,
    throat_viscosity: float | np.ndarray | None = None,
    pore_dviscosity_dpressure: float | np.ndarray | None = None,
    throat_dviscosity_dpressure: float | np.ndarray | None = None,
) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
    """Return throat conductance and endpoint pressure sensitivities.

    Notes
    -----
    The returned arrays are ``(g, dg_dpi, dg_dpj)`` where ``i`` and ``j`` are
    the pore indices in ``net.throat_conns[:, 0]`` and ``net.throat_conns[:, 1]``.
    """

    conns = net.throat_conns
    i_idx = conns[:, 0]
    j_idx = conns[:, 1]

    if "hydraulic_conductance" in net.throat:
        g = generic_poiseuille_conductance(net, viscosity, throat_viscosity=throat_viscosity)
        zeros = np.zeros_like(g, dtype=float)
        return g, zeros, zeros

    if model == "auto":
        selected = _select_auto_conductance_model(net)
        if selected == "hydraulic_size_factors":
            return _hydraulic_size_factor_sensitivities(
                net,
                viscosity,
                pore_viscosity=pore_viscosity,
                throat_viscosity=throat_viscosity,
                pore_dviscosity_dpressure=pore_dviscosity_dpressure,
                throat_dviscosity_dpressure=throat_dviscosity_dpressure,
            )
        return throat_conductance_with_sensitivities(
            net,
            viscosity,
            model=selected,
            pore_viscosity=pore_viscosity,
            throat_viscosity=throat_viscosity,
            pore_dviscosity_dpressure=pore_dviscosity_dpressure,
            throat_dviscosity_dpressure=throat_dviscosity_dpressure,
        )

    if model == "generic_poiseuille":
        selected_viscosity = throat_viscosity if throat_viscosity is not None else viscosity
        if selected_viscosity is None:
            raise ValueError("Need either viscosity or throat_viscosity")
        mu_t = _broadcast_viscosity(selected_viscosity, (net.Nt,))
        dmu_t = (
            _broadcast_finite(
                throat_dviscosity_dpressure,
                (net.Nt,),
                name="throat_dviscosity_dpressure",
            )
            if throat_dviscosity_dpressure is not None
            else np.zeros(net.Nt, dtype=float)
        )
        _require(net, "throat", ("length",))
        L = np.asarray(net.throat["length"], dtype=float)
        if "diameter_inscribed" in net.throat:
            d = np.asarray(net.throat["diameter_inscribed"], dtype=float)
        elif "area" in net.throat:
            d = _diameter_from_area(np.asarray(net.throat["area"], dtype=float))
        else:
            raise KeyError(
                "Need throat.diameter_inscribed or throat.area (or precomputed hydraulic_conductance)"
            )
        r = 0.5 * d
        g = (np.pi * r**4) / (8.0 * mu_t * L)
        dg_dmu = -g / mu_t
        factor = 0.5 * dmu_t
        return g, dg_dmu * factor, dg_dmu * factor

    if model == "hagen_poiseuille":
        try:
            if not _conduit_lengths_available(net):
                raise KeyError("Missing conduit lengths (pore1_length, core_length, pore2_length)")
            At = _get_entity_area(net, "throat")
            Ap = _get_entity_area(net, "pore")
        except KeyError:
            return throat_conductance_with_sensitivities(
                net,
                viscosity,
                model="generic_poiseuille",
                pore_viscosity=pore_viscosity,
                throat_viscosity=throat_viscosity,
                pore_dviscosity_dpressure=pore_dviscosity_dpressure,
                throat_dviscosity_dpressure=throat_dviscosity_dpressure,
            )

        mu_p, mu_t = _resolve_pore_throat_viscosities(
            net,
            viscosity,
            pore_viscosity=pore_viscosity,
            throat_viscosity=throat_viscosity,
        )
        dmu_p = (
            _broadcast_finite(
                pore_dviscosity_dpressure,
                (net.Np,),
                name="pore_dviscosity_dpressure",
            )
            if pore_dviscosity_dpressure is not None
            else np.zeros(net.Np, dtype=float)
        )
        dmu_t = (
            _broadcast_finite(
                throat_dviscosity_dpressure,
                (net.Nt,),
                name="throat_dviscosity_dpressure",
            )
            if throat_dviscosity_dpressure is not None
            else np.zeros(net.Nt, dtype=float)
        )
        Lt = np.asarray(net.throat["core_length"], dtype=float)
        gt = _segment_conductance_hagen_poiseuille(At, Lt, mu_t)
        dgt_dmu = np.zeros_like(gt, dtype=float)
        positive_t = np.isfinite(gt) & (gt > 0.0)
        dgt_dmu[positive_t] = -gt[positive_t] / mu_t[positive_t]
        dgt_dpi = dgt_dmu * (0.5 * dmu_t)
        dgt_dpj = dgt_dmu * (0.5 * dmu_t)

        L1 = np.asarray(net.throat["pore1_length"], dtype=float)
        L2 = np.asarray(net.throat["pore2_length"], dtype=float)
        g1 = _segment_conductance_hagen_poiseuille(Ap[i_idx], L1, mu_p[i_idx])
        g2 = _segment_conductance_hagen_poiseuille(Ap[j_idx], L2, mu_p[j_idx])
        dg1_dmu = np.zeros_like(g1, dtype=float)
        dg2_dmu = np.zeros_like(g2, dtype=float)
        positive_1 = np.isfinite(g1) & (g1 > 0.0)
        positive_2 = np.isfinite(g2) & (g2 > 0.0)
        dg1_dmu[positive_1] = -g1[positive_1] / mu_p[i_idx][positive_1]
        dg2_dmu[positive_2] = -g2[positive_2] / mu_p[j_idx][positive_2]
        dg1_dpi = dg1_dmu * dmu_p[i_idx]
        dg2_dpj = dg2_dmu * dmu_p[j_idx]

        g = _harmonic_combine_segments(g1, gt, g2)
        dg_dpi = _harmonic_sensitivity(g, (g1, gt, g2), (dg1_dpi, dgt_dpi, np.zeros_like(g2)))
        dg_dpj = _harmonic_sensitivity(g, (g1, gt, g2), (np.zeros_like(g1), dgt_dpj, dg2_dpj))
        return g, dg_dpi, dg_dpj

    if model == "valvatne_blunt_throat":
        selected_viscosity = throat_viscosity if throat_viscosity is not None else viscosity
        if selected_viscosity is None:
            raise ValueError("Need either viscosity or throat_viscosity")
        mu_t = _broadcast_viscosity(selected_viscosity, (net.Nt,))
        dmu_t = (
            _broadcast_finite(
                throat_dviscosity_dpressure,
                (net.Nt,),
                name="throat_dviscosity_dpressure",
            )
            if throat_dviscosity_dpressure is not None
            else np.zeros(net.Nt, dtype=float)
        )
        _require(net, "throat", ("length",))
        A = _get_entity_area(net, "throat")
        G = _get_entity_shape_factor(net, "throat", area=A)
        L = np.asarray(net.throat["length"], dtype=float)
        g = _segment_conductance_valvatne_blunt(A, G, L, mu_t)
        dg_dmu = np.zeros_like(g, dtype=float)
        positive = np.isfinite(g) & (g > 0.0)
        dg_dmu[positive] = -g[positive] / mu_t[positive]
        factor = 0.5 * dmu_t
        return g, dg_dmu * factor, dg_dmu * factor

    if model in {"valvatne_blunt", "valvatne_blunt_baseline"}:
        mu_p, mu_t = _resolve_pore_throat_viscosities(
            net,
            viscosity,
            pore_viscosity=pore_viscosity,
            throat_viscosity=throat_viscosity,
        )
        dmu_p = (
            _broadcast_finite(
                pore_dviscosity_dpressure,
                (net.Np,),
                name="pore_dviscosity_dpressure",
            )
            if pore_dviscosity_dpressure is not None
            else np.zeros(net.Np, dtype=float)
        )
        dmu_t = (
            _broadcast_finite(
                throat_dviscosity_dpressure,
                (net.Nt,),
                name="throat_dviscosity_dpressure",
            )
            if throat_dviscosity_dpressure is not None
            else np.zeros(net.Nt, dtype=float)
        )
        try:
            if not _conduit_lengths_available(net):
                raise KeyError("Missing conduit lengths (pore1_length, core_length, pore2_length)")
            At = _get_entity_area(net, "throat")
            Gt = _get_entity_shape_factor(net, "throat", area=At)
            Lt = np.asarray(net.throat["core_length"], dtype=float)
            gt = _segment_conductance_valvatne_blunt(At, Gt, Lt, mu_t)
            dgt_dmu = np.zeros_like(gt, dtype=float)
            positive_t = np.isfinite(gt) & (gt > 0.0)
            dgt_dmu[positive_t] = -gt[positive_t] / mu_t[positive_t]
            dgt_dpi = dgt_dmu * (0.5 * dmu_t)
            dgt_dpj = dgt_dmu * (0.5 * dmu_t)

            Ap = _get_entity_area(net, "pore")
            Gp = _get_entity_shape_factor(net, "pore", area=Ap)
            L1 = np.asarray(net.throat["pore1_length"], dtype=float)
            L2 = np.asarray(net.throat["pore2_length"], dtype=float)
            g1 = _segment_conductance_valvatne_blunt(Ap[i_idx], Gp[i_idx], L1, mu_p[i_idx])
            g2 = _segment_conductance_valvatne_blunt(Ap[j_idx], Gp[j_idx], L2, mu_p[j_idx])
            dg1_dmu = np.zeros_like(g1, dtype=float)
            dg2_dmu = np.zeros_like(g2, dtype=float)
            positive_1 = np.isfinite(g1) & (g1 > 0.0)
            positive_2 = np.isfinite(g2) & (g2 > 0.0)
            dg1_dmu[positive_1] = -g1[positive_1] / mu_p[i_idx][positive_1]
            dg2_dmu[positive_2] = -g2[positive_2] / mu_p[j_idx][positive_2]
            dg1_dpi = dg1_dmu * dmu_p[i_idx]
            dg2_dpj = dg2_dmu * dmu_p[j_idx]

            g = _harmonic_combine_segments(g1, gt, g2)
            dg_dpi = _harmonic_sensitivity(g, (g1, gt, g2), (dg1_dpi, dgt_dpi, np.zeros_like(g2)))
            dg_dpj = _harmonic_sensitivity(g, (g1, gt, g2), (np.zeros_like(g1), dgt_dpj, dg2_dpj))
            return g, dg_dpi, dg_dpj
        except KeyError:
            try:
                A = _get_entity_area(net, "throat")
                G = _get_entity_shape_factor(net, "throat", area=A)
                L = np.asarray(net.throat["length"], dtype=float)
                g = _segment_conductance_valvatne_blunt(A, G, L, mu_t)
                dg_dmu = np.zeros_like(g, dtype=float)
                positive = np.isfinite(g) & (g > 0.0)
                dg_dmu[positive] = -g[positive] / mu_t[positive]
                factor = 0.5 * dmu_t
                return g, dg_dmu * factor, dg_dmu * factor
            except KeyError:
                warnings.warn(
                    "Insufficient geometry for shape-factor model; falling back to generic_poiseuille",
                    RuntimeWarning,
                    stacklevel=2,
                )
                return throat_conductance_with_sensitivities(
                    net,
                    viscosity,
                    model="generic_poiseuille",
                    pore_viscosity=pore_viscosity,
                    throat_viscosity=throat_viscosity,
                    pore_dviscosity_dpressure=pore_dviscosity_dpressure,
                    throat_dviscosity_dpressure=throat_dviscosity_dpressure,
                )

    raise ValueError(f"Unknown conductance model '{model}'")