Analysis tools¶

The SDK follows PoreStore's UI categories and submits existing analyses through /api/v1/. Scientific work runs on PoreStore's compute services. Each function returns a Job, accepts an uploaded Image or image ID, and uses the image's client or the configured default connection. An explicit client= remains available for scripts that connect to multiple teams or services.

Coverage and parameters¶

The following table lists the supported entry points. API slugs are useful when inspecting client.analysis_types() or saved job metadata; callers normally use the Python function. Parameter examples are optional settings, except direction for a transport calculation. Defaults, limits, backend routing and validation remain authoritative on the service.

queue_name and compute_tier can be supplied where the current service schema allows them. A setting accepted by one solver may be invalid for another. client.analysis_types() returns the available analyses and their parameters_schema; it also reflects account-specific beta restrictions. The SDK forwards scientific arguments and does not keep a second set of defaults. Unknown or unavailable arguments raise the normal API error before submission.

Conductivity measures relative transport through the solid phase. It is dimensionless, analogous to relative diffusivity through the pore space; it is not an absolute material conductivity. Directions are "x", "y" and "z", subject to image dimensionality and solver availability.

Porosity profiles accept an integer axis, rather than transport's direction strings. axis="all" requests every available axis. Chord lengths always use all axes of a 3-D image. Their bins control histogram resolution. Radial density chooses radius bins automatically, so bins and log are invalid there. Pore size accepts steps; arbitrary sizes are not supported by that analysis.

The service fixes the pore-size method, interfacial smoothing controls, connectivity convention and included phases, and REV sample count. These are not additional notebook tuning knobs. The optional isolated-voxel cleanup for interfacial area and solid-phase chord/radial measurements retain their existing beta audiences. Supplying a keyword does not grant access to a restricted tool or option. Image readiness, dimensionality, resource and billing checks remain on the server. Matching and reading historical jobs retain their existing permissions even when a beta closes; launching new work checks current access.

Submit additional measurements¶

This example uses a ready 3-D segmented image. Set credentials in the environment or .env in the current working directory as described in the README. These calls can submit paid jobs when no exact match exists; choose the analyses needed for the study rather than submitting the entire example automatically.

import porestore

client = porestore.configure()
image = porestore.Image.from_id("your-image-id")

conductivity = porestore.tools.transport.conductivity(
    im=image,
    direction="x",
    target_relative_error=0.001,
)
pore_size = porestore.tools.structure.pore_size(im=image, steps=30)
profile = porestore.tools.structure.porosity_profile(im=image, axis=0)
interface = porestore.tools.structure.interfacial_surface_area(im=image)
chords = porestore.tools.statistics.chord_length_distribution(
    im=image,
    bins=30,
    phase="pore",
)
radial = porestore.tools.statistics.radial_density(im=image, phase="pore")
connectivity = porestore.tools.statistics.connectivity(im=image)
rev = porestore.tools.rev.porosity(im=image)

print("Pore-size job:", pore_size.id, pore_size.status)

A new job is returned after registration, without waiting for calculation. Retrieve its result explicitly, or recover it later by ID:

result = pore_size.get_result(wait=True, timeout=1800, poll_interval=10)
result.solution  # Expandable notebook table, including nested scientific details.

recovered = porestore.Job.from_id(pore_size.id)
print(recovered.get_result().solution)

All measurements use the existing Result and Solution interfaces. Curves, profiles, sampled volumes and connectivity summaries retain the fields, values and units returned by the API. The SDK does not invent a common scalar value or recalculate physical units. Result-cache identity includes image metadata and voxel size so updated dimensional results can be fetched correctly. Network array downloads retain the separate explicit method described in the README.

Matching, refresh and recovery¶

Every entry point uses the same exact-job matching behavior. The service normalizes supplied settings using its current form defaults and routing, then looks for jobs with the same image ID, analysis type and canonical arguments. This includes jobs launched from the website. Completed stored results are preferred, then active jobs, then other matches; job.reused indicates reuse. A completed match retrieves its stored result through the ordinary result API. A lookup or result-access failure raises an error rather than submitting work.

refresh=True explicitly requests another calculation, even when a match exists. It is an SDK execution option and never becomes a scientific argument:

fresh = porestore.tools.structure.pore_size(im=image, steps=30, refresh=True)

The same raw settings can match omitted server defaults; differing scientific settings, backends or service-controlled algorithm values do not silently reuse a different calculation. A failed matching job remains visible. Use an explicit refresh when a new attempt is intended.

Submissions retain the existing retry and idempotency behavior. An optional idempotency_key= allows deliberate recovery of an uncertain request. Reusing that key identifies the same submission, including when refresh=True; omit it for independently forced runs. See the README for exception and recovery details.

Metrics convenience and image metadata¶

For scripts that collect measurements together, porestore.tools.metrics exports pore_size, porosity_profile, interfacial_surface_area, chord_length_distribution, radial_density, connectivity, and rev_porosity. These exports call the same analyses with the same parameters, fingerprints and results. Switching namespaces does not request a new scientific calculation.

job = porestore.tools.metrics.pore_size(im=image, steps=30)
# Reuses the Structure job above unless refresh=True is requested.

Image metadata can already include ingestion measurements. Access them as an expandable mapping without downloading the image or starting a job:

image.metrics  # Snapshot from the most recent image metadata response.
image.refresh()
image.metrics  # Updated snapshot; available keys depend on the image.

Local images and remote images without metrics return an empty Solution. Metrics values and units are preserved exactly as returned by the image API. This property does not replace the Job/Result interface for an analysis.

Remaining scope¶

The eight additional analyses cover every currently implemented Transport, Structure, Statistics and REV entry in the application catalogue. Grain size, REV diffusivity and REV permeability are UI roadmap entries without backend analyses, so the SDK does not expose placeholder functions for them. Image processing and visualization are separate work. Network extraction retains its existing interface; this increment does not modify its algorithms or artifacts.