Parameter reference¶

The parameters object for every analysis the API runs. The authoritative, current schema for your team is always GET /analysis-types/. This page explains what each parameter does to the computation.

Every analysis takes a segmented image: 0 for solid and one other value, such as 1 or 255, for pore. See Segmented images.

Required means required. Send every parameter marked required, even when it has a suggested value. Optional parameters fall back to their default. Unknown keys are dropped.

Backends (queue_name) have stable identifiers, such as porespy, walberla or kabs-taichi; send one that GET /analysis-types/ lists. An identifier stays the same whatever hardware runs the job, which compute_tier chooses. Older names for the same backends are still accepted.

`permeability`¶

What it computes →

Parameter	Type	Required	Default	Allowed	Effect
`direction`	string	yes		`x` `y` `z`	Flow direction.
`queue_name`	string	yes		`walberla` `kabs-taichi` `palabos` `kabs-xlb-jax` `kabs-xlb-warp`	Backend. They differ.
`max_iterations`	integer	yes	20000 suggested	≥ 1; waLBerla ≤ 1 000 000	Iteration cap. A waLBerla job asking for more than 1 000 000 is refused with `400` and `details.max_iterations`.
`velocity_tolerance`	number		0.001	0.0001–0.001	Velocity-change criterion (not Palabos).
`permeability_tolerance`	number		0.001	0.0001–0.001	Permeability-change criterion.
`flux_profile_tolerance`	number		0.0001	0.0001–0.001	Plane-flux criterion (waLBerla only).
`compute_tier`	string		`auto`	`auto` or a tier key for the backend	Hardware.

tolerance is still accepted as an old name for velocity_tolerance. Convergence is checked every 500 iterations.

Palabos is available to PoreStore staff only, and runs only on a compute tier you name, never on auto.

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "permeability",
  "parameters": {"direction": "x", "queue_name": "walberla", "max_iterations": 20000}
}

`diffusivity`¶

What it computes →

Parameter	Type	Required	Default	Allowed	Effect
`direction`	string	yes		`x` `y` `z`	Direction of transport.
`queue_name`	string	yes		`tortuosity-jl` `taufactor`	Backend: Tortuosity.jl or TauFactor.
`target_relative_error`	number	yes	0.001 suggested	≥ 1e-6	Target accuracy: the largest relative error you accept in the tortuosity, measured as the flux balance error, the spread of the plane fluxes. 0.001 is 0.1%.
`solver_tolerance`	number	for Tortuosity.jl	1e-5 suggested	≥ 1e-6	Solver tolerance: the linear solver's relative residual for the first solve.
`max_iterations`	integer	for TauFactor	10000 suggested	1–1 000 000	Iteration cap.
`compute_tier`	string		`auto`	`auto` or a tier key for the backend	Hardware.

flux_tolerance is still accepted as an old name for target_relative_error. solver_tolerance and max_iterations have suggested values in the schema, but the API doesn't fill them in: leave out the one your backend needs and the request is refused with 400.

TauFactor iterates until the flux balance error is below target_relative_error or it reaches max_iterations. Tortuosity.jl solves once to solver_tolerance, then, if the flux balance error is still above target_relative_error, keeps solving for at most half as long again, in up to two more rounds. A job that runs out of that allowance still completes, and reports the accuracy it reached in final_relative_flux_error.

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "diffusivity",
  "parameters": {
    "direction": "x", "queue_name": "tortuosity-jl",
    "target_relative_error": 0.001, "solver_tolerance": 0.00001
  }
}

`conductivity`¶

What it computes →

The same parameters as diffusivity: direction, queue_name, target_relative_error, solver_tolerance (Tortuosity.jl), max_iterations (TauFactor) and compute_tier. The phase is always solid, and the job's parameters record it as phase: "solid".

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "conductivity",
  "parameters": {
    "direction": "x", "queue_name": "tortuosity-jl",
    "target_relative_error": 0.001, "solver_tolerance": 0.00001
  }
}

`poresize`¶

What it computes →

Parameter	Type	Required	Default	Allowed	Effect
`steps`	integer		25	≥ 2	Radius steps: number of radii tried by the local-thickness filter.
`queue_name`	string	yes		`porespy`	Backend.

The histogram bins are chosen for you: one per voxel of radius, up to 200 bins. Sending sizes is refused with 400.

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "poresize",
  "parameters": {"steps": 25, "queue_name": "porespy"}
}

`hg_porosimetry`¶

What it computes →

Parameter	Type	Required	Default	Allowed	Effect
`steps`	integer	yes	25 suggested	≥ 2	Pressure steps per curve.
`queue_name`	string	yes		`porespy`	Backend.

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "hg_porosimetry",
  "parameters": {"steps": 25, "queue_name": "porespy"}
}

`radial_density`¶

What it computes →

Parameter	Type	Required	Default	Allowed	Effect
`queue_name`	string	yes		`porespy`	Backend.
`phase`	string		`pore`	`pore` `solid`	Phase to measure.

The bins are chosen for you, as for poresize: one per voxel of radius, up to 200 bins, so the two distributions line up. Sending bins or log is refused with 400.

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "radial_density",
  "parameters": {"queue_name": "porespy"}
}

`chord_length_distribution`¶

What it computes →

Parameter	Type	Required	Default	Allowed	Effect
`bins`	integer	yes	25 suggested	≥ 2	Histogram bins per axis.
`queue_name`	string	yes		`porespy`	Backend.
`phase`	string		`pore`	`pore` `solid`	Phase to measure.

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "chord_length_distribution",
  "parameters": {"bins": 25, "queue_name": "porespy"}
}

`porosity_profile`¶

What it computes →

Parameter	Type	Required	Default	Allowed	Effect
`axis`	string or integer	yes	`all` suggested	`all` `0` `1` `2`	Axis to profile along.
`queue_name`	string	yes		`porespy`	Backend.

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "porosity_profile",
  "parameters": {"axis": "all", "queue_name": "porespy"}
}

`rev_porosity`¶

What it computes →

Parameter	Type	Required	Default	Allowed	Effect
`queue_name`	string	yes		`porespy`	Backend.

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "rev_porosity",
  "parameters": {"queue_name": "porespy"}
}

`porosity_connectivity` beta¶

What it computes →

Parameter	Type	Required	Default	Allowed	Effect
`queue_name`	string	yes		`porespy`	Backend.

Connectivity and phases are fixed. The job takes a single image, not a batch.

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "porosity_connectivity",
  "parameters": {"queue_name": "porespy"}
}

`interfacial_surface_area` beta¶

What it computes →

Parameter	Type	Required	Default	Allowed	Effect
`queue_name`	string	yes		`porespy`	Backend.
`cleanup_singletons`	boolean		false		Before measuring, flip interior pore and solid voxels that have no face neighbour of their own phase, in one pass. Listed only for teams with the cleanup option.

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "interfacial_surface_area",
  "parameters": {"queue_name": "porespy"}
}

`network_extraction` beta¶

What it computes →

Available to PoreStore staff only for now.

Parameter	Type	Required	Default	Allowed	Effect
`method`	string	yes	`snow2` suggested	`snow2` `magnet`	Extraction method.
`queue_name`	string	yes		`porespy`	Backend.
`boundary_width`	integer	SNOW2	3 suggested	≥ 0	Boundary-pore layer thickness.
`accuracy`	string	SNOW2	`standard` suggested	`standard` `high`	Voxel counts or marching cubes.
`sigma`	number	SNOW2	0.4 suggested	≥ 0	Gaussian sigma: smoothing of the distance transform.
`r_max`	integer	SNOW2	4 suggested	≥ 1	Peak filter radius.
`l_max`	integer	MAGNET	7 suggested	≥ 1	Throat max-filter length, for splitting long throats.
`s`	integer		auto	≥ 1	MAGNET junction merge threshold.
`surface`	boolean		false		MAGNET: trim floating surface solids first.
`throat_junctions`	string		none	`maximum filter` `fast marching`	MAGNET throat junction mode.
`throat_area`	boolean		false		MAGNET: compute throat area.
`n_walkers`	integer	with `throat_area`	10 suggested	≥ 1	Throat area walkers.
`step_size`	number	with `throat_area`	0.5 suggested	≥ 0	Throat area step size.
`max_n_steps`	integer		unlimited	≥ 1	Throat area max steps.

"SNOW2", "MAGNET" and "with throat_area" in the Required column mean required when that method or option is chosen. The suggested values are the app's starting values, and the API doesn't fill them in: leave out one that's required and the request is refused with 400 naming the field.

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "network_extraction",
  "parameters": {
    "method": "snow2", "boundary_width": 3, "accuracy": "standard", "sigma": 0.4,
    "r_max": 4, "queue_name": "porespy"
  }
}

`network_validation` beta¶

What it computes →

Available to PoreStore staff only for now.

Parameter	Type	Required	Default	Allowed	Effect
`network_job`	UUID	yes		a completed `network_extraction` job on the same image	Extracted network to simulate.
`direction`	string	yes		`x` `y` `z`	Flow direction, also used for diffusion.
`pore_diameter_key`	string	yes	`pore.equivalent_diameter`	a pore diameter property	Pore size used.
`throat_diameter_key`	string	yes	`throat.equivalent_diameter`	a throat diameter property	Throat size used.
`shape_model`	string	yes	`cones_and_cylinders`	see shape models	Geometry shape model of the conduits.
`queue_name`	string	yes		`porespy`	Backend.

The Default column gives the app's starting values. The API doesn't fill them in: send pore_diameter_key, throat_diameter_key and shape_model every time. A diameter key the network doesn't have is refused, and the error lists the ones it has.

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "network_validation",
  "parameters": {
    "network_job": "…", "direction": "x",
    "pore_diameter_key": "pore.equivalent_diameter",
    "throat_diameter_key": "throat.equivalent_diameter",
    "shape_model": "cones_and_cylinders", "queue_name": "porespy"
  }
}

network_job is the ID of a completed network_extraction job on the same image. The job's stored parameters record it as network_job_id.

`sem_view`, `xray_view`¶

What they compute →

Parameter	Type	Required	Default	Effect
`force_regenerate`	boolean		false	Rebuild the fields even if the image has them.

Example request body for POST /analysis-jobs/:

{
  "image_id": "…",
  "analysis_type": "sem_view",
  "parameters": {}
}

For X-Ray View, send "analysis_type": "xray_view" with the same parameters.

Compute tiers¶

Permeability, diffusivity and conductivity take a compute_tier. A tier key names the hardware and its memory, never who runs it:

Key	Hardware
`auto`	Let PoreStore choose. The job runs on an idle `gpu-48gb-rtx-8000` GPU when one is free and fits the image, otherwise straight away on the smallest of the tiers below that fits it.
`gpu-48gb-a40-a6000`	48 GB GPU · A40/A6000
`gpu-141gb-h200`	141 GB GPU · H200
`gpu-48gb-rtx-8000`	48 GB GPU · RTX 8000. A job sent here explicitly waits up to an hour for a free GPU, then fails.
`cpu-188gb-10-cores` beta	188 GB CPU · 10 cores. Palabos only.

Not every backend offers every tier, and the largest image each tier takes depends on the backend. GET /analysis-types/ lists both for your team, and a submission whose tier can't take the image is refused with 400. Compute and hardware explains how tiers are chosen.

Parameter reference¶

permeability¶

diffusivity¶

conductivity¶

poresize¶

hg_porosimetry¶

radial_density¶

chord_length_distribution¶

porosity_profile¶

rev_porosity¶

porosity_connectivity beta¶

interfacial_surface_area beta¶

network_extraction beta¶

network_validation beta¶

sem_view, xray_view¶

Compute tiers¶

`permeability`¶

`diffusivity`¶

`conductivity`¶

`poresize`¶

`hg_porosimetry`¶

`radial_density`¶

`chord_length_distribution`¶

`porosity_profile`¶

`rev_porosity`¶

`porosity_connectivity` beta¶

`interfacial_surface_area` beta¶

`network_extraction` beta¶

`network_validation` beta¶

`sem_view`, `xray_view`¶