fieldcompare#

fieldcompare provides functionality to compare field data, where field data are collections of fields (each consisting of a name and an associated array of values) defined on domains. An example would be discrete numerical solutions (fields) defined on a computational mesh (domain). This top-level module exposes central classes in this context, mostly operating on the protocols defined in the “protocols” module. Implementations of these protocols can be found in the submodules.

class fieldcompare.DefaultFieldComparisonCallback(verbosity=1, use_colors=True, stream=sys.stdout)#

Bases: object

Writes default status messages for each field comparison to the given stream.

Parameters:

• verbosity (int) – Integer to control the verbosity of the written output (optional). Default: 2

• use_colors (bool) – Switch on/off colors.

• stream (TextIO) – Stream to write to (optional). Defaults to stdout.

__call__(result)#

Write info on the performed field comparison into the given stream.

Parameters:

result (FieldComparison) –

Return type:

None

class fieldcompare.FieldDataComparator(source, reference, field_inclusion_filter=lambda _: ..., field_exclusion_filter=lambda _: ..., missing_sources_is_error=True, missing_references_is_error=True)#

Bases: object

Compares all fields in two given objects of FieldData.

Parameters:

• source (FieldData) – Field data to be compared.

• reference (FieldData) – Reference field data to compare against.

• field_inclusion_filter (Callable[[str], bool]) – Filter to select the fields to be compared (optional).

• field_exclusion_filter (Callable[[str], bool]) – Filter to exclude fields from being compared (optional).

• missing_sources_is_error (bool) –

• missing_references_is_error (bool) –

__call__(predicate_selector=None, fieldcomp_callback=None)#

Compare all fields in the field data objects using the given predicates.

Parameters:

• predicate_selector (Callable[[Field, Field], Callable[[Any, Any], PredicateResult]] | None) – Selector function taking the two fields to be compared, returning a predicate to be used for comparing the field values. Default: DefaultEquality.

• fieldcomp_callback (Callable[[FieldComparison], Any] | None) – Function that is invoked with the results of individual field comparison results as soon as they are available (e.g. to print intermediate output). Defaults to DefaultFieldComparisonCallback.

Return type:

FieldComparisonSuite

class fieldcompare.FieldComparisonSuite(domain_eq_check, comparisons=None)#

Bases: object

Stores the results of a field data comparison.

Parameters:

• domain_eq_check (PredicateResult) – Result of the domain equality check

• comparisons (list[FieldComparison] | None) – Results of all performed field comparisons.

__bool__()#

Return true if the suite is considered to have passed successfully.

Return type:

bool

__iter__()#

Return an iterator over all contained field comparison results.

Return type:

Iterator[FieldComparison]

property report: str#

Return information about performed comparisons.

property domain_equality_check: PredicateResult#

Return the result of the domain equality check.

property passed: list[fieldcompare._field_data_comparison.FieldComparison]#

Return a range over all passed comparisons.

property failed: list[fieldcompare._field_data_comparison.FieldComparison]#

Return a range over all failed comparisons.

property skipped: list[fieldcompare._field_data_comparison.FieldComparison]#

Return a range over all skipped comparisons.

property num_failed: int#

Return the number of failed field comparisons

property num_skipped: int#

Return the number of skipped field comparisons

property num_passed: int#

Return the number of passed field comparisons

class fieldcompare.FieldComparison#

Bases: object

Stores information on the results of a single field comparison.

Parameters:

• name (str) –

• status (FieldComparisonStatus) –

• result (FieldComparisonResult) –

• predicate (str) –

• report (str) –

• cpu_time (float | None) –

name: str#

status: FieldComparisonStatus#

result: FieldComparisonResult#

predicate: str#

report: str#

cpu_time: float | None = None#

__bool__()#

This operator raises an exception to avoid accidental misuse

Return type:

bool

property passed: bool#

property failed: bool#

property skipped: bool#

class fieldcompare.FieldComparisonStatus(value)#

Bases: Enum

Represents the status of a field comparison

passed = 1#

failed = 2#

skipped = 3#

__bool__()#

This operator raises an exception to avoid accidental misuse

Return type:

bool

class fieldcompare.FieldComparisonResult(value)#

Bases: Enum

The result of a field comparison

equal = 1#

unequal = 2#

error = 3#

missing_source = 4#

missing_reference = 5#

filtered = 6#

__bool__()#

This operator raises an exception to avoid accidental misuse

Return type:

bool

class fieldcompare.FieldDataSequence(source)#

Bases: object

Represents a sequence of FieldData (e.g. a time series)

Parameters:

source (Source) –

class Source(*args, **kwargs)#

Bases: Protocol

Interface for sources, providing access to the data of the steps of the sequence

reset()#

Go back to the first step in the sequence

Return type:

None

step()#

Move to the next step in the sequence and return true if succeeded

Return type:

bool

get()#

Return the data of this step

Return type:

FieldData

property number_of_steps: int#

Return the number of steps in the sequence

__iter__()#

Return an iterator over all steps in the sequence

Return type:

Iterator

property number_of_steps: int#

Return the number of steps in the sequence

fieldcompare.field_comparison_report(comparison, use_colors=True, verbosity=1)#

Returns a report for a given FieldComparison.

Parameters:

• comparison (FieldComparison) – The comparison result.

• use_colors (bool) – Switch on/off colors.

• verbosity (int) – Control the verbosity of the report.

Return type:

str

fieldcompare.protocols#

Definitions of the interfaces used by fieldcompare

class fieldcompare.protocols.DynamicTolerance(*args, **kwargs)#

Bases: Protocol

Interface for tolerances that depend on the array values to be compared.

__call__(first, second)#

Return a tolerance to be used for comparing the two given arrays.

Parameters:

• first (ndarray) –

• second (ndarray) –

Return type:

float | ndarray

class fieldcompare.protocols.PredicateResult(*args, **kwargs)#

Bases: Protocol

Return value from predicate functions.

__bool__()#

Return true if the predicate evaluated to true.

Return type:

bool

property report: str#

Return a report of the predicate evaluation.

class fieldcompare.protocols.Domain(*args, **kwargs)#

Bases: Protocol

Represents a domain on which fields are defined.

equals(other)#

Check if this domain is equal to the given one.

Parameters:

other (Domain) – Domain against which to check for equality.

Return type:

PredicateResult

class fieldcompare.protocols.Field(*args, **kwargs)#

Bases: Protocol

Represents a single field.

property name: str#

Return the name of the field.

property values: ndarray#

Return the field values.

class fieldcompare.protocols.FieldData(*args, **kwargs)#

Bases: Protocol

Contains the fields defined on a domain.

property domain: Any#

Return the domain these fields are defined on.

__iter__()#

Return an iterator over the contained fields.

Return type:

Iterator[Field]

diff_to(other)#

Return the field data that contains the difference to the given field data

Return type:

FieldData

class fieldcompare.protocols.FieldDataSequence(*args, **kwargs)#

Bases: Protocol

Represents a sequence of fields, for instance, a time series.

property number_of_steps: int#

Return the number of steps in the sequence.

__iter__()#

Return an iterator over the field data of the sequence.

Return type:

Iterator[FieldData]