.. _physics-galacticFilter: Galactic Filter =============== Object providing boolean filters that select or reject galaxies (nodes) based on their properties. Filters are used to restrict output analyses, apply selection criteria matching observational surveys, or limit processing to specific galaxy populations. Multiple filters can be combined using logical ``and``, ``or``, and ``not`` operations to build complex selection functions. **Default implementation:** ``galacticFilterAlways`` Methods ------- ``passes`` → ``logical`` Return true if the given ``node`` passes the filter. * ``type(treeNode), intent(inout), target :: node`` .. _physics-galacticFilterAll: ``galacticFilterAll`` --------------------- Implements a logical ``AND`` combination of multiple :galacticus-class:`galacticFilterClass` objects, passing only nodes that satisfy every filter in the list, enabling construction of complex selection criteria by composing simpler filters. .. _physics-galacticFilterAlways: ``galacticFilterAlways`` ------------------------ A trivial filter that unconditionally passes every node regardless of its properties, used as a default or placeholder when all nodes should be included in an analysis and also as a null object in testing filter infrastructure. **(Default implementation)** .. _physics-galacticFilterAny: ``galacticFilterAny`` --------------------- Implements a logical ``OR`` combination of multiple :galacticus-class:`galacticFilterClass` objects, passing nodes that satisfy at least one filter in the list, enabling flexible union-based selection criteria from simpler component filters. .. _physics-galacticFilterAnyDescendantNode: ``galacticFilterAnyDescendantNode`` ----------------------------------- Applies a :galacticus-class:`galacticFilterClass` to all descendant nodes of a given node and passes if any descendant satisfies the filter, enabling selection of nodes based on the properties of their descendants in the merger tree. **Parameters** * ``[allowSelf]`` (boolean) — If true, the node itself is considered as a descendant, otherwise the node itself is excluded from the descendant node search. * ``[branchOnly]`` (boolean; default ``.false.``) — If true, follow descendants only to the end of the branch. Otherwise, follow them to the end of the entire merger tree. .. _physics-galacticFilterAnySatelliteNode: ``galacticFilterAnySatelliteNode`` ---------------------------------- Applies a filter to satellite nodes of the given node and returns true if *any* satellite node passes. .. _physics-galacticFilterBasicMass: ``galacticFilterBasicMass`` --------------------------- A high-pass filter for basic mass. Halos with a basic mass mass greater than or equal to a fixed threshold, :math:`M_0=`\ ``[massThreshold]``. **Parameters** * ``[massThreshold]`` (real) — The parameter :math:`M_0` (in units of :math:`\mathrm{M}_\odot`) appearing in the basic mass threshold for the basic mass galactic filter class. .. _physics-galacticFilterBlackHoleMass: ``galacticFilterBlackHoleMass`` ------------------------------- A galactic high-pass filter for black hole mass. Galaxies with a central black hole mass greater than or equal to a fixed threshold, :math:`M_{\bullet,0}=`\ ``[massThreshold]``, are passed. **Parameters** * ``[massThreshold]`` (real) — The parameter :math:`M_0` (in units of :math:`\mathrm{M}_\odot`) appearing in the black hole mass threshold for the black hole mass galactic filter class. .. _physics-galacticFilterBranchMostMassive: ``galacticFilterBranchMostMassive`` ----------------------------------- Selects only the most massive progenitor branch (main branch) halo among a node's siblings at each timestep, filtering out secondary progenitors to focus analyses on the primary mass growth channel of a merger tree. .. _physics-galacticFilterChildNode: ``galacticFilterChildNode`` --------------------------- Applies a filter to a child node of the given node. The ``[childRank]`` parameter specifies which child to use---a rank of 1 means the first child, a rank of :math:`N` means the sibling of the :math:`N-1` rank child. If a child of the specified rank does not exist this filter fails to pass. **Parameters** * ``[childRank]`` (integer) — The rank of the child to use---a rank of 1 means the first child, a rank of :math:`N` means the sibling of the :math:`N-1` rank child. .. _physics-galacticFilterConstrainedBranch: ``galacticFilterConstrainedBranch`` ----------------------------------- Passes only nodes that lie on constrained branches of a merger tree, i.e., branches whose merger history was constructed to match some applied constraint rather than generated stochastically, enabling targeted analysis of constrained vs. unconstrained halo populations. .. _physics-galacticFilterDescendantNode: ``galacticFilterDescendantNode`` -------------------------------- Evaluates a wrapped :galacticus-class:`galacticFilterClass` not on the current node but on its descendant node, enabling selection criteria based on the future state of a halo's evolution rather than its current properties. **Parameters** * ``[redshiftDescendant]`` (real) — The redshift of the descendant node to which to apply the filter. * ``[allowSelf]`` (boolean) — If true, the node itself is considered as a possible descendant, otherwise the node itself is excluded from the descendant node search. .. _physics-galacticFilterFormationTime: ``galacticFilterFormationTime`` ------------------------------- A filter which removes recently-formed halos. Halos with a formation time greater than the current time minus :math:`\Delta t=`\ ``[timeRecent]`` are removed. **Parameters** * ``[timeRecent]`` (real) — The parameter :math:`\Delta t` (in units of Gyr) appearing in the formation time galactic filter class. .. _physics-galacticFilterGasFractionISM: ``galacticFilterGasFractionISM`` -------------------------------- Passes nodes whose ISM gas fraction (the ratio of ISM gas mass to stellar mass) exceeds a specified threshold, enabling selection of gas-rich galaxies. **Parameters** * ``[fractionGasThreshold]`` (real) — The ISM gas fraction above which to pass. .. _physics-galacticFilterHaloAlwaysIsolated: ``galacticFilterHaloAlwaysIsolated`` ------------------------------------ Passes only nodes that have never been a satellite throughout their entire merger tree history, selecting halos that have always resided as isolated field halos without ever experiencing a period of satellite status in a larger host halo. .. _physics-galacticFilterHaloIsolated: ``galacticFilterHaloIsolated`` ------------------------------ Passes only nodes that are currently isolated halos (host halos that are not satellites of any larger structure at the current epoch), selecting field halos to exclude substructure when analyzing host halo populations. .. _physics-galacticFilterHaloMass: ``galacticFilterHaloMass`` -------------------------- A high-pass filter for basic mass. Halos with a halo mass greater than or equal to a fixed threshold, :math:`M_0=`\ ``[massThreshold]``. **Parameters** * ``[massThreshold]`` (real) — The parameter :math:`M_0` (in units of :math:`\mathrm{M}_\odot`) appearing in the mass threshold for the halo mass galactic filter class. .. _physics-galacticFilterHaloMassRange: ``galacticFilterHaloMassRange`` ------------------------------- Passes nodes whose halo mass (under a specified virial density contrast definition) falls within the range [``massLow``, ``massHigh``), enabling selection of halos by mass. **Parameters** * ``[massLow]`` (real) — The minimum halo mass (in :math:`\mathrm{M}_\odot`) that a node must have to pass the filter; nodes with mass below this threshold are rejected. * ``[massHigh]`` (real) — The maximum halo mass (in :math:`\mathrm{M}_\odot`) that a node must have to pass the filter; nodes with mass above this threshold are rejected. .. _physics-galacticFilterHaloNotIsolated: ``galacticFilterHaloNotIsolated`` --------------------------------- Passes only nodes that are currently satellites (non-isolated), selecting subhalos orbiting within a larger host halo at the current epoch, useful for environmental studies of satellite galaxy populations. .. _physics-galacticFilterHierarchyDepthMaximum: ``galacticFilterHierarchyDepthMaximum`` --------------------------------------- Passes only nodes up to a specified maximum depth in the subhalo hierarchy, filtering out sub-subhalos and higher-order substructure beyond a given level of nesting, useful when analyses should not extend beyond a certain hierarchy depth. **Parameters** * ``[depthHierarchyLargest]`` (integer) — The largest value of hierarchy maximum depth to pass. .. _physics-galacticFilterHighPass: ``galacticFilterHighPass`` -------------------------- A high-pass galactic filter that passes only nodes for which a scalar property, extracted via ``[nodePropertyExtractor]``, equals or exceeds the specified ``[threshold]`` value. This allows selection of galaxies or halos above any quantitative threshold in any extractable property. **Parameters** * ``[threshold]`` (real) — The threshold value above which to pass. .. _physics-galacticFilterHostMassRange: ``galacticFilterHostMassRange`` ------------------------------- Passes nodes whose host halo basic mass, :math:`M_\mathrm{host}`, falls within the range ``[massMinimum]``\ :math:`\le M_\mathrm{host}<`\ ``[massMaximum]``. This selects subhalos or galaxies hosted by halos of a specified mass interval, enabling mass-binned analyses of galaxy populations in their environmental context. **Parameters** * ``[massMinimum]`` (real) — The minimum mass of host halo to pass. * ``[massMaximum]`` (real) — The maximum mass of host halo to pass. * ``[useFinalHost]`` (boolean) — If true, the final host (i.e. the isolated host halo in the subhalo hierarchy) is used for filtering, otherwise the immediate host is used. .. _physics-galacticFilterIntervalPass: ``galacticFilterIntervalPass`` ------------------------------ An interval pass galactic filter that passes only nodes for which a scalar property, extracted via ``[nodePropertyExtractor]``, lies within the interval [``[thresholdLow]``, ``[thresholdHigh]``]. This enables selection of galaxies or halos within any bounded range of an extractable property. **Parameters** * ``[thresholdLow]`` (real) — The low threshold value above which to pass. * ``[thresholdHigh]`` (real) — The high threshold value below which to pass. .. _physics-galacticFilterISMMass: ``galacticFilterISMMass`` ------------------------- A galactic high-pass filter for ISM mass. Galaxies with a combined disk plus spheroid ISM mass greater than or equal to a fixed threshold, :math:`M_\mathrm{ISM,0}=`\ ``[massThreshold]``. **Parameters** * ``[massThreshold]`` (real) — The parameter :math:`M_0` (in units of :math:`\mathrm{M}_\odot`) appearing in the ISM mass threshold for the ISM mass galactic filter class. .. _physics-galacticFilterIsolatedHostNode: ``galacticFilterIsolatedHostNode`` ---------------------------------- Evaluates a wrapped :galacticus-class:`galacticFilterClass` on the isolated (top-level) host halo of the current node rather than on the node itself, enabling selection of satellites based on properties of their ultimate host environment. .. _physics-galacticFilterLabelled: ``galacticFilterLabelled`` -------------------------- Tests whether the given node has been assigned the label specified by ``[label]``. This filter passes only nodes that carry the designated label, enabling targeted selection of nodes based on categorical metadata attached during tree construction or post-processing. **Parameters** * ``[label]`` (string) — The label string that a node must carry in order to pass this filter; only nodes assigned this exact label during tree construction or post-processing will be selected. .. _physics-galacticFilterLightcone: ``galacticFilterLightcone`` --------------------------- Passes nodes that fall within a lightcone geometry as defined by a :galacticus-class:`geometryLightconeClass` object, enabling mock catalog construction by selecting only galaxies observable within the survey volume. .. _physics-galacticFilterLowPass: ``galacticFilterLowPass`` ------------------------- A low-pass galactic filter that passes only nodes for which a scalar property, extracted via ``[nodePropertyExtractor]``, is less than or equal to the specified ``[threshold]`` value. This allows selection of galaxies or halos below any quantitative threshold in any extractable property. **Parameters** * ``[threshold]`` (real) — The threshold value below which to pass. .. _physics-galacticFilterMainBranch: ``galacticFilterMainBranch`` ---------------------------- Passes only nodes that lie on the main progenitor branch of their merger tree (the branch of most massive progenitors tracing the primary assembly history), filtering out secondary merger branches for analyses focused on main branch evolution. .. _physics-galacticFilterMergerRatio: ``galacticFilterMergerRatio`` ----------------------------- An interval pass filter that selects halos whose merger mass ratio falls within the range [``[ratioLow]``, ``[ratioHigh]``]. The merger ratio quantifies the relative mass of merging progenitors, enabling selection of major or minor merger events within a specified mass-ratio interval. **Parameters** * ``[ratioLow]`` (real) — The low ratio value above which to pass. * ``[ratioHigh]`` (real) — The high ratio value below which to pass. .. _physics-galacticFilterNodeMajorMergerRecent: ``galacticFilterNodeMajorMergerRecent`` --------------------------------------- A low-pass filter for time since the last major node merger. Halos with a time of the last major node merger greater than or equal to the current time minus :math:`\Delta t=`\ ``[timeRecent]`` are passed. **Parameters** * ``[timeRecent]`` (real) — The parameter :math:`\Delta t` (in units of Gyr) appearing in the recent node major merger galactic filter class. .. _physics-galacticFilterNot: ``galacticFilterNot`` --------------------- Implements logical negation of a wrapped :galacticus-class:`galacticFilterClass`, passing nodes that the wrapped filter would reject and rejecting those it would pass, enabling complement-based selection criteria without defining explicit inverse filters. .. _physics-galacticFilterNull: ``galacticFilterNull`` ---------------------- A filter which simply returns the result of another filter. This is intended for use in filter pipelines where it may be useful to optionally switch in this filter or a :galacticus-class:`galacticFilterNull` filter (for example). .. _physics-galacticFilterOutputTimes: ``galacticFilterOutputTimes`` ----------------------------- A filter that passes nodes only if their cosmic time coincides with one of the requested simulation output times, within a relative tolerance specified by ``[toleranceRelative]``. This ensures that only nodes snapshotted at designated output epochs are included in post-processing analyses. **Parameters** * ``[toleranceRelative]`` (real; default ``0.0d0``) — The fractional tolerance to allow when comparing the time at which a node exists to output times. .. _physics-galacticFilterParentNode: ``galacticFilterParentNode`` ---------------------------- Applies a filter to a parent node of the given node. If a parent of the specified rank does not exist this filter fails to pass. .. _physics-galacticFilterPrimaryDescendantNode: ``galacticFilterPrimaryDescendantNode`` --------------------------------------- Applies a delegate galactic filter to all primary descendant nodes of the given node along the main progenitor branch and passes if any such primary descendant satisfies that filter. The ``[allowSelf]`` parameter controls whether the node itself is included among the candidates tested. **Parameters** * ``[allowSelf]`` (boolean) — If true, the node itself is considered as a descendant, otherwise the node itself is excluded from the descendant node search. .. _physics-galacticFilterRadiusEffective: ``galacticFilterRadiusEffective`` --------------------------------- A galactic high-pass filter for stellar mass effective radius. Galaxies with a stellar mass effective radius greater than or equal to a fixed threshold, :math:`R_{\mathrm{eff},0}=`\ ``[radiusEffectiveThreshold]``, are passed. **Parameters** * ``[radiusThreshold]`` (real) — The parameter :math:`R_{\mathrm{eff},0}` (in units of Mpc) appearing in the stellar mass effective radius threshold. .. _physics-galacticFilterRootNode: ``galacticFilterRootNode`` -------------------------- Passes only root nodes (the final descendant at the present day, with no further descendants), selecting the base of each merger tree that represents the surviving halo at the final output time, for present-epoch galaxy property analyses. .. _physics-galacticFilterSpheroidStellarMass: ``galacticFilterSpheroidStellarMass`` ------------------------------------- A galactic high-pass filter for stellar mass. Galaxies with a spheroid stellar mass greater than or equal to a fixed threshold, :math:`M_{\star,0}=`\ ``[massThreshold]``. **Parameters** * ``[massThreshold]`` (real) — The parameter :math:`M_0` (in units of :math:`\mathrm{M}_\odot`) appearing in the stellar mass threshold for the spheroid stellar mass galactic filter class. .. _physics-galacticFilterStarFormationRate: ``galacticFilterStarFormationRate`` ----------------------------------- A galactic high-pass filter for star formation rate. Galaxies with a combined disk, spheroid, plus :term:`NSC` star formation rate greater than or equal to a mass-dependent threshold. The threshold is given by .. math:: \log_{10} \left( { \dot{\phi}_\mathrm{t} \over \mathrm{M}_\odot\,\hbox{Gyr}^{-1}} \right) = \alpha_0 + \alpha_1 \left( \log_{10} M_\star - \log_{10} M_0 \right), where :math:`M_0=`\ ``[logM0]``, :math:`\alpha_0=`\ ``[logSFR0]``, and :math:`\alpha_1=`\ ``[logSFR1]``. **Methods** * ``tabulate`` — Tabulate the virial density contrast as a function of mass and time. * ``restoreTable`` — Restore a tabulated solution from file. * ``storeTable`` — Store a tabulated solution to file. **Parameters** * ``[logM0]`` (real; default ``10.0d0``) — The parameter :math:`\log_{10} M_0` (with :math:`M_0` in units of :math:`\mathrm{M}_\odot`) appearing in the star formation rate threshold expression for the star formation rate galactic filter class. * ``[logSFR0]`` (real; default ``9.0d0``) — The parameter :math:`\alpha_0` appearing in the star formation rate threshold expression for the star formation rate galactic filter class. * ``[logSFR1]`` (real; default ``0.0d0``) — The parameter :math:`\alpha_1` appearing in the star formation rate threshold expression for the star formation rate galactic filter class. .. _physics-galacticFilterStarFormationRateNonParametric: ``galacticFilterStarFormationRateNonParametric`` ------------------------------------------------ A galactic (high- or low-pass) filter for star formation rate. Galaxies with a combined disk, spheroid, plus :term:`NSC` star formation rate are passed if they are above or below (for ``[filterType]``\ :math:`=`\ ``highPass`` or ``lowPass`` respectively) a mass-dependent threshold. The threshold is linearly interpolated in log(``[rateStarFormation]``) vs. log(``[massStellar]``). **Parameters** * ``[filterType]`` (string; one of ``lowPass``, ``highPass``) — Specifies whether the filter passes galaxies below (``lowPass``) or above (``highPass``) the mass-dependent star formation rate threshold, controlling whether quiescent or star-forming galaxies are selected. * ``[massStellar]`` (real) — The list of stellar masses at which the star formation rate threshold is specified. * ``[rateStarFormation]`` (real) — The list of star formation rate thresholds for each stellar mass. .. _physics-galacticFilterStellarAbsoluteMagnitudes: ``galacticFilterStellarAbsoluteMagnitudes`` ------------------------------------------- A galactic low-pass (i.e. bright-pass) filter for stellar absolute magnitudes. Galaxies with absolute magnitude in each band, :math:`i`, less than or equal to a fixed threshold, :math:`M_{0,i}=`\ ``[absoluteMagnitudeThreshold]``. **Parameters** * ``[absoluteMagnitudeThreshold]`` (real) — The parameter :math:`M_0` appearing in the stellar absolute magnitude threshold for the stellar absolute magnitude galactic filter class. .. _physics-galacticFilterStellarApparentMagnitudes: ``galacticFilterStellarApparentMagnitudes`` ------------------------------------------- A galactic low-pass (i.e. bright-pass) filter for stellar apparent magnitudes. Galaxies with apparent magnitude in each band, :math:`i`, less than or equal to a fixed threshold, :math:`m_{0,i}=`\ ``[apparentMagnitudeThreshold]``. **Parameters** * ``[apparentMagnitudeThreshold]`` (real) — The parameter :math:`m_0` appearing in the stellar apparent magnitude threshold for the stellar apparent magnitude galactic filter class. .. _physics-galacticFilterStellarMass: ``galacticFilterStellarMass`` ----------------------------- A galactic high-pass filter for stellar mass. Galaxies with a combined disk, spheroid, plus :term:`NSC` stellar mass greater than or equal to a fixed threshold, :math:`M_{\star,0}=`\ ``[massThreshold]``. **Parameters** * ``[massThreshold]`` (real) — The parameter :math:`M_0` (in units of :math:`\mathrm{M}_\odot`) appearing in the stellar mass threshold for the stellar mass galactic filter class. .. _physics-galacticFilterStellarMassMorphology: ``galacticFilterStellarMassMorphology`` --------------------------------------- A galactic high-pass filter for stellar mass-weighted morphology (i.e. spheroid-to-total ratio). Galaxies with a spheroid-to-total ratio (by stellar mass) greater than or equal to a fixed threshold, :math:`R_{\star,0}=`\ ``[spheroidToTotalThreshold]``. **Parameters** * ``[spheroidToTotalRatioThreshold]`` (real) — The parameter :math:`R_0` appearing in the stellar mass-weight morphology threshold for the stellar mass-weighted morphology galactic filter class. .. _physics-galacticFilterStreamImpact: ``galacticFilterStreamImpact`` ------------------------------ A filter for subhalos that could impact a stream during the timestep. We consider a subhalo, at time :math:`t=0` (defined as the current time), at position :math:`\mathbf{r}` and moving with velocity :math:`\mathbf{v}`. The time of closest approach to a point :math:`\mathbf{r}^\prime` is given by .. math:: t_\mathrm{impact} = (\mathbf{v}\cdot \mathbf{r}^\prime - \mathbf{v}\cdot \mathbf{r})/v^2. We want to keep subhalos which may impact upon a stream of radius :math:`r^\prime` during the timestep, allowing for arbitrary rotations of the subhalo system. Therefore, we must find the minimum and maximum possible values of :math:`t_\mathrm{impact}` when considering all points on the sphere of radius :math:`r^\prime`. These extrema clearly occur when :math:`\mathbf{r}^\prime` is aligned, or anti-aligned with :math:`\mathbf{v}`, i.e.: .. math:: t_\mathrm{impact, min/max} = (\pm v r^\prime - \mathbf{v}\cdot \mathbf{r})/v^2. **Parameters** * ``[radiusOrbitalStream]`` (real) — The orbital radius of the stream (which is assumed to be on a circular orbit). .. _physics-galacticFilterStreamKick: ``galacticFilterStreamKick`` ---------------------------- A filter for the velocity kick imparted by subhalos to a stellar stream. We compute an upper limit on the velocity kick a subhalo can impart on the stream, for any orientation along a sphere of radius ``[radiusOrbitalStream]``, and filter out any subhalos that do not create a total velocity kick greater than ``[cutoffVelocityKick]``. **Parameters** * ``[radiusOrbitalStream]`` (real) — The orbital radius of the stream (which is assumed to be on a circular orbit). * ``[speedOrbitalStream]`` (real) — The orbital speed of the stream (which is assumed to be on a circular orbit). * ``[cutoffVelocityKick]`` (real) — The minimum velocity kick (in km/s) that a subhalo must be able to impart on the stream for the node to pass; subhalos whose maximum kick falls below this threshold are rejected. .. _physics-galacticFilterSurveyGeometry: ``galacticFilterSurveyGeometry`` -------------------------------- A galactic filter that passes only nodes whose sky position and distance fall within the footprint of a specified survey geometry object. The ``[positionType]`` parameter selects whether the node's intrinsic or orbital position is used when evaluating inclusion within the survey volume. **Parameters** * ``[positionType]`` (string; one of ``position``, ``orbital``; default ``position``) — The type of position to use in survey geometry filters. .. _physics-galacticFilterTreeHosted: ``galacticFilterTreeHosted`` ---------------------------- Passes only nodes that are currently hosted in a merger tree, filtering out any unhosted nodes that may exist outside the tree structure.