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 }

Gas velocities (Gadget)

For Gadget snapshots, filter VelocityX, VelocityY, and VelocityZ under pointcloud_voronoi.field_filters. For example, disable bulk velocities with:

pointcloud_voronoi:
  field_filters:
    _zero_velocity:
      transforms:
        - { op: scale, value: 0.0 }
    VelocityX: _zero_velocity
    VelocityY: _zero_velocity
    VelocityZ: _zero_velocity

Emission and transport use these filtered components. Thermal broadening is unchanged. Use value: 0.5 to halve bulk velocities, or omit these filters to keep the snapshot velocities. Components are filtered in cm/s after the snapshot unit conversion; the packed Velocities field remains unchanged.

This applies to the component recipes derived from Velocities. Loaders that supply their own component fields, such as Tipsy and octree loaders, retain their existing behavior.

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 — fine for discrete values (e.g. SFR == 0.0), unreliable for continuous ones.

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)