Skip to content

Field Filters

Apply conditions and transforms to fields via YAML configuration.

Quick Example

field_filters:
  # Exclude star-forming gas from Lya emission
  Lya_recB_emissivity:
    conditions:
      - { field: StarFormationRate, op: "==", value: 0.0 }

Configuration

Add a field_filters section to your config file. Keys are field names or templates.

Templates

Templates are reusable filter definitions. Prefix with underscore (_):

field_filters:
  _gas_emission:             # Template (underscore prefix)
    conditions:
      - { field: StarFormationRate, op: "==", value: 0.0 }

  Lya_recB_emissivity:       # Field binding (uses template)
    inherit: _gas_emission

  # Shorthand: directly reference template name
  Ha_recB_emissivity: _gas_emission  # Equivalent to { inherit: _gas_emission }

Conditions

Boolean tests that produce a pass/fail mask per particle.

Operators

Op Meaning
== Equal
!= Not equal
> Greater than
< Less than
>= Greater or equal
<= Less or equal

Threshold Types

conditions:
  # Literal value
  - { field: Temperature, op: ">", value: 1000.0 }

  # Reference another field (with optional multiplier)
  - { field: CoolingTime, op: ">", value_field: Timestep, multiplier: 3.0 }
  # Evaluates: CoolingTime > Timestep * 3.0

Tolerance for Equality

For == and != operators, use tolerance for approximate comparison:

conditions:
  # Exact equality (default) - use for discrete values like SFR=0
  - { field: StarFormationRate, op: "==", value: 0.0 }

  # Approximate equality - use for continuous values
  - { field: Temperature, op: "==", value: 1e4, tolerance: 100.0 }
  # Passes if |Temperature - 1e4| <= 100.0

Note: Without tolerance, equality uses exact floating-point comparison. This is appropriate for discrete values (e.g., SFR == 0.0) but may not work as expected for continuous values due to floating-point precision.

Transforms

Value operations applied after masking. Applied in order.

Op Effect Parameters
min result = min(result, operand * multiplier) value or with_field, multiplier
max result = max(result, operand * multiplier) value or with_field, multiplier
scale result = result * operand * multiplier value or with_field, multiplier
clamp result = clamp(result, lo, hi) lo, hi (required)

The multiplier (default: 1.0) scales the operand before applying the operation.

transforms:
  # Cap result by another field (scaled)
  - op: min
    with_field: PhotoheatingRate
    multiplier: 100.0
  # result = min(result, PhotoheatingRate * 100.0)

  # Scale by literal value
  - op: scale
    value: 0.5
  # result = result * 0.5

  # Clamp to range
  - op: clamp
    lo: 0.0
    hi: 1e-20

Else Actions

What to do when conditions fail:

Value Effect
zero Set to 0 (default)
nan Set to NaN
keep Keep original value

Combine Mode

How to combine multiple conditions:

Value Effect
and All conditions must pass (default)
or Any condition can pass

Complete Example

field_filters:
  # Template for gas emission (exclude star-forming)
  _gas_emission:
    particle_type: PartType0
    combine: and
    else: zero
    conditions:
      - { field: StarFormationRate, op: "==", value: 0.0 }

  # Template for collisional emission (higher T floor)
  _collisional:
    particle_type: PartType0
    combine: and
    else: zero
    conditions:
      - { field: StarFormationRate, op: "==", value: 0.0 }
      - { field: Temperature, op: ">", value: 1e4 }

  # Apply templates to fields
  Lya_recB_emissivity:
    inherit: _gas_emission

  Lya_collexc_emissivity:
    inherit: _collisional
    transforms:
      - op: min
        with_field: PhotoheatingRate
        multiplier: 100.0

Inheritance

When inheriting from a template:

  • Parent conditions are inherited, child conditions appended
  • Transforms are merged (parent first, then child)
  • Settings (particle_type, combine, else) inherit if not specified
  • Error if child defines condition for a field already in parent

Defaults

Setting Default
particle_type PartType0
combine and
else zero
conditions []
transforms []

Condition Defaults

Setting Default
multiplier 1.0
tolerance 0.0 (exact comparison)