Results and reports#

A job (and meshkit.read()) returns a MeshResult: the mesh as read-only buffers, and a report.

Buffers and ownership#

Array attributes are memoryview objects over arrays owned by native code. Each access returns a new view, and every view keeps the native storage alive, even after the result object is gone.

import numpy as np

xyz = np.asarray(result.vertices)          # float64 (N, 3), zero-copy, read-only
cells = np.asarray(result.cells)           # uint32 (M, 4), strided by cell
editable = np.array(result.vertices, copy=True)
  • Views are read-only; asking for a writable buffer raises BufferError. Copy to edit.

  • cells, cell_types and regions are strided over one cell array, and edges and edge_markers over one edge array. NumPy shares them as strided arrays; a consumer that demands a C-contiguous buffer gets a BufferError and must copy.

  • Cells are zero-based and counter-clockwise. cell_types holds 3 or 4; a triangle’s fourth index is unused.

  • vertex_ids and cell_ids are empty when the IDs are the implicit one-based sequence, and vertex_markers is empty when every marker is 0.

NumPy is optional: memoryview supports indexing, tolist() and the buffer protocol on its own.

Reports#

result.report is a dict. Start with status and complete:

status

Meaning

complete

Every requirement met.

complete_with_exceptions

A mesh is returned, but advisory requirements (such as the minimum target size) or other accepted exceptions were not met; see the conflict counts and examples.

infeasible

The request cannot be met, including invalid option values; no geometry.

resource_limit

A limit in options["limits"] was reached; no geometry.

cancelled

The job was cancelled; no geometry.

failed

Any other failure; no geometry.

complete is true for complete and complete_with_exceptions; the other fields explain the outcome.

Key

Meaning

code, message

Machine-readable reason and its text.

seconds, work

Elapsed time and work units used.

vertices, triangles, quads

Counts in the result.

algorithm_version, provider_identity

Algorithm version and the caller’s terrain identity, for provenance.

inserted, removed, removal_attempts, queue_peak

Refinement and coarsening activity.

below_minimum

Cells smaller than the minimum target (advisory).

edge_conflicts, size_conflicts, transition_conflicts

Edges shorter than minimum_edge, cells larger than their size limit, neighbours beyond adjacent_ratio.

terrain_conflicts, terrain_unknown

Cells whose terrain bound exceeds the tolerance, or could not be established.

largest_adjacent_ratio, largest_terrain_ratio

Worst measured values.

planned_patches, planning_retries, shared_sides

Quadrilateral planning outcome.

planning

Up to 256 decisions: source, reason, region, repair_rounds, required.

constraint_segments, constraint_audit_passed

Constraint recovery and its independent audit.

examples

Up to 64 failing checks: code, cell, measured, allowed. The counters above hold the totals.

resolved_options

The options the job actually used, defaults filled in.

A report from meshkit.read() has the same keys, with the job-specific counters at zero.

Progress events#

Job.poll() and the progress callback of meshkit.run() deliver events as dictionaries:

Key

Meaning

stage, message

Current stage and a short description.

percent

Progress of the stage, 0–100.

status

Run status, as in the report.

severity

"info", "warning" or "error".

vertices, triangles, quads

Counts so far.

sequence, job

Event sequence number and job number.

elapsed_ms

Milliseconds since the job started.

dropped

Events lost so far because the queue (2,048 events) was full.

The worker never waits for Python: when nobody polls, events beyond the queue are dropped and counted.