sim_field_topology.h File Reference

Phase-topology extraction helpers for complex simulation fields. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "field.h"

Include dependency graph for sim_field_topology.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	SimFieldTopologyCell
	Per-cell phase-topology measurement. More...
struct	SimFieldTopologySummary
	Aggregate counts reported by a topology extraction pass. More...
struct	SimFieldTopologyConfig
	Tunable thresholds used by phase-topology extraction. More...

Typedefs
typedef enum SimFieldTopologySeamMask	SimFieldTopologySeamMask
	Bit mask describing which edges of a cell cross a phase seam.
typedef enum SimFieldTopologyCellFlag	SimFieldTopologyCellFlag
	Flags describing confidence and validity for a topology cell.
typedef struct SimFieldTopologyCell	SimFieldTopologyCell
	Per-cell phase-topology measurement.
typedef struct SimFieldTopologySummary	SimFieldTopologySummary
	Aggregate counts reported by a topology extraction pass.
typedef struct SimFieldTopologyConfig	SimFieldTopologyConfig
	Tunable thresholds used by phase-topology extraction.

Enumerations
enum	SimFieldTopologySeamMask { SIM_FIELD_TOPOLOGY_SEAM_BOTTOM = 1u << 0 , SIM_FIELD_TOPOLOGY_SEAM_RIGHT = 1u << 1 , SIM_FIELD_TOPOLOGY_SEAM_TOP = 1u << 2 , SIM_FIELD_TOPOLOGY_SEAM_LEFT = 1u << 3 }
	Bit mask describing which edges of a cell cross a phase seam. More...
enum	SimFieldTopologyCellFlag { SIM_FIELD_TOPOLOGY_CELL_VALID = 1u << 0 , SIM_FIELD_TOPOLOGY_CELL_AMBIGUOUS , SIM_FIELD_TOPOLOGY_CELL_CORE_OFFSET_VALID , SIM_FIELD_TOPOLOGY_CELL_NONFINITE = 1u << 3 }
	Flags describing confidence and validity for a topology cell. More...

Functions
void	sim_field_topology_config_default (SimFieldTopologyConfig *out_config)
	Fill a topology configuration with default thresholds.
bool	sim_field_topology_dimensions (const struct SimField *field, size_t *out_width, size_t *out_height)
	Resolve the 2D topology dimensions for a field.
bool	sim_field_topology_extract (const struct SimField *field, SimFieldTopologyCell *out_cells, size_t cell_capacity, SimFieldTopologySummary *out_summary, const SimFieldTopologyConfig *config, size_t *out_width, size_t *out_height)
	Extract phase winding and seam data from a field.
void	sim_field_topology_cell_pack_rgba8 (const SimFieldTopologyCell *cell, uint8_t out_texel[4])
	Pack one topology cell into an RGBA8 texel.

Detailed Description

Phase-topology extraction helpers for complex simulation fields.

The topology pass interprets the fastest-varying field dimension as image width and folds all remaining elements into rows. For complex fields with at least a 2x2 grid, each non-border cell records local phase winding, phase-seam crossings, ambiguity flags, and an optional singularity core estimate.

Enumeration Type Documentation

SimFieldTopologyCellFlag

enum SimFieldTopologyCellFlag

Flags describing confidence and validity for a topology cell.

Enumerator
SIM_FIELD_TOPOLOGY_CELL_VALID	Cell was evaluated from input samples.
SIM_FIELD_TOPOLOGY_CELL_AMBIGUOUS	Cell is near a threshold, low magnitude, or numerically uncertain.
SIM_FIELD_TOPOLOGY_CELL_CORE_OFFSET_VALID	Core offset fields contain a localized singularity estimate.
SIM_FIELD_TOPOLOGY_CELL_NONFINITE	One or more source samples were non-finite.

SimFieldTopologySeamMask

enum SimFieldTopologySeamMask

Bit mask describing which edges of a cell cross a phase seam.

Enumerator
SIM_FIELD_TOPOLOGY_SEAM_BOTTOM	Bottom edge exceeds the seam threshold.
SIM_FIELD_TOPOLOGY_SEAM_RIGHT	Right edge exceeds the seam threshold.
SIM_FIELD_TOPOLOGY_SEAM_TOP	Top edge exceeds the seam threshold.
SIM_FIELD_TOPOLOGY_SEAM_LEFT	Left edge exceeds the seam threshold.

Function Documentation

sim_field_topology_cell_pack_rgba8()

void sim_field_topology_cell_pack_rgba8	(	const SimFieldTopologyCell *	cell,
		uint8_t	out_texel[4]
	)

Pack one topology cell into an RGBA8 texel.

Parameters

	cell	Cell to pack; NULL is treated as a zero-valued cell.
[out]	out_texel	Receives charge, seam/flag bits, and core-offset channels.

R encodes charge mapped from [-1, +1] into [0, 255]. G stores flags in the high nibble and seam bits in the low nibble. B and A store core X/Y offsets biased into [0, 255], or 128 when no core offset is valid.

sim_field_topology_config_default()

void sim_field_topology_config_default

(

SimFieldTopologyConfig *

out_config

)

Fill a topology configuration with default thresholds.

Parameters

[out]

out_config

Receives defaults when non-NULL.

sim_field_topology_dimensions()

bool sim_field_topology_dimensions	(	const struct SimField *	field,
		size_t *	out_width,
		size_t *	out_height
	)

Resolve the 2D topology dimensions for a field.

Parameters

	field	Field whose layout is inspected.
[out]	out_width	Receives the fastest-varying dimension when non-NULL.
[out]	out_height	Receives the flattened row count when non-NULL.

Returns

true when the field layout has a nonzero element count and width.

sim_field_topology_extract()

bool sim_field_topology_extract	(	const struct SimField *	field,
		SimFieldTopologyCell *	out_cells,
		size_t	cell_capacity,
		SimFieldTopologySummary *	out_summary,
		const SimFieldTopologyConfig *	config,
		size_t *	out_width,
		size_t *	out_height
	)

Extract phase winding and seam data from a field.

Parameters

	field	Field to inspect; only complex-double fields produce valid topology.
[out]	out_cells	Optional cell buffer with one entry per resolved field element.
	cell_capacity	Number of entries available in out_cells.
[out]	out_summary	Optional aggregate topology counts.
	config	Optional extraction thresholds; defaults are used when NULL.
[out]	out_width	Optional resolved width.
[out]	out_height	Optional resolved height.

Returns

true when the field could be inspected; check SimFieldTopologySummary::valid to distinguish an unsupported/non-complex field from a topology-bearing result.

The last row and last column do not form full 2x2 cells and are written as zeroed cells when out_cells is provided.