subhaloscript 1.0.10__tar.gz → 1.1.1__tar.gz

{subhaloscript-1.0.10 → subhaloscript-1.1.1}/.claude/skills/galacticus-analysis/SKILL.md

@@ -3,7 +3,7 @@
 **SubScript** is a Python library providing ergonomic utility functions for analyzing Galacticus semi-analytic model outputs. 
 
 **Repository:** https://github.com/cgannonucm/SubScript
-**Package:** `subhaloscript` (v1.0.10)
+**Package:** `subhaloscript` (v1.1.1)
 **Author:** Charles Gannon (cgannon@ucmerced.edu)
 
 ---
@@ -101,10 +101,13 @@ ParamKeys.mass_halo_enclosed_current       # Enclosed mass within radius
 ### Structural Properties
 ```python
 ParamKeys.rvir                             # Virial radius
-ParamKeys.scale_radius                     # Scale radius (r_s) for density profile
+ParamKeys.scale_radius / ParamKeys.rscale  # Scale radius (r_s) for density profile
 ParamKeys.density_profile_radius           # Array of radii for density profile
 ParamKeys.density_profile                  # Array of densities at radii
 ParamKeys.concentration                    # Concentration parameter
+ParamKeys.tnfw_rt                          # Tidal truncation radius (truncated NFW)
+ParamKeys.tnfw_p0                          # Density normalization (truncated NFW)
+ParamKeys.dark_matter_profile_scale        # Dark matter profile scale
 ```
 
 ### Classification & Hierarchy
@@ -134,6 +137,7 @@ ParamKeys.node_index                       # Unique node identifier (with indexS
 ParamKeys.parent_index                     # Index of parent node
 ParamKeys.satellite_index                  # Index if this is a satellite
 ParamKeys.sibling_index                    # Index of sibling node
+ParamKeys.subsampling_weight               # Subsampling weight for node
 ```
 
 ### Tree Metadata
@@ -516,7 +520,9 @@ result = projected_subhalo_count(gout, normvector=np.identity(3))
 
 ## Time-Series Analysis: Tracking
 
-Extract properties of individual subhalos across all Galacticus snapshots:
+Extract properties of individual subhalos across all Galacticus snapshots.
+
+> **Prefer `subhalo_timeseries()`** when extracting time-series for subhalos in a full tree. It wraps `track_subhalos()` + `track_subhalo()` with automatic disk caching, making repeated runs significantly faster. Use the lower-level `track_subhalos()` / `track_subhalo()` directly only when you need fine-grained control over which nodes to track or which parameters to extract.
 
 ### track_subhalos() - Extract Full Time-Series
 
@@ -573,6 +579,43 @@ plt.xlabel('Redshift')
 plt.ylabel('Bound Mass [M_☉]')
 ```
 
+### subhalo_timeseries() - Cached Full-Tree Time-Series
+
+Convenience wrapper that extracts and **caches** time-series for every subhalo in a tree:
+
+```python
+from subscript.subhalo_timeseries import subhalo_timeseries
+
+# Extract (or load from cache) all subhalo time-series for tree 0
+result = subhalo_timeseries(gout, tree_index=0)
+
+# Force recompute, ignoring cache
+result = subhalo_timeseries(gout, tree_index=0, refresh=True)
+
+# result structure:
+# result[node_id]['data']   -> dict of {param_key: time_series_array}
+# result[node_id]['zsnaps'] -> corresponding redshift array
+
+# Plot bound-mass evolution for a single subhalo
+import matplotlib.pyplot as plt
+from subscript.defaults import ParamKeys
+
+for node_id, ts in result.items():
+    plt.plot(ts['zsnaps'], ts['data'][ParamKeys.mass_bound])
+
+plt.xlabel('Redshift')
+plt.ylabel('Bound Mass [M_☉]')
+plt.show()
+```
+
+**Cache behaviour:**
+- Cache file is written to the same directory as the HDF5 file
+- Filename: `{stem}-{sha256[:16]}-tree{tree_index}.pkl`
+- Cache is invalidated automatically when the file content changes (hash-based)
+- Pass `refresh=True` to force recomputation
+
+**Requirements:** same as `track_subhalos()` — Galacticus must be run with `<nodeOperator value="indexShift" />`.
+
 ---
 
 ## Batch Processing: Macros
@@ -646,11 +689,83 @@ with h5py.File('analysis_results.hdf5', 'w') as f:
 ```python
 from subscript.defaults import Meta
 
-# Cache HDF5 reads in memory (default: True, faster but uses memory)
-Meta.cache = True
-
 # Disable deprecation warnings for old filter names
 Meta.disableDepreciatedWarning = False
+
+# Units system (see Astropy Units Integration below)
+Meta.units_enable = False          # Enable/disable astropy units (default: False)
+Meta.units_in_si = None            # Dict mapping keys → astropy SI units
+Meta.units_in_si_conversion = None # Dict mapping keys → numerical SI conversion factors
+Meta.unit_bases = [apu.Msun, apu.kpc, apu.Myr]  # Base units for decomposition
+```
+
+---
+
+## Astropy Units Integration
+
+SubScript supports optional astropy units on all node properties via `subscript.units`.
+
+### Quick Setup
+
+```python
+import h5py
+from subscript.units import enableUnitsFromGalacticus
+
+gout = h5py.File('galacticus.hdf5')
+
+# Read unitsInSI from the HDF5 file and enable units globally
+enableUnitsFromGalacticus(gout)
+
+# Now all nodedata() calls return astropy Quantities in the base unit system
+# Default bases: [Msun, kpc, Myr]
+```
+
+### Functions
+
+#### `galacticus_units_si(gal_out)` — Extract SI conversion factors
+
+Reads the `unitsInSI` attribute from every dataset in the final output's `nodeData` group and returns a dict of `{property_name: conversion_factor}`.
+
+```python
+from subscript.units import galacticus_units_si
+
+units_si = galacticus_units_si(gout)
+# units_si['basicMass'] → 1.989e30  (kg per unit stored in file)
+```
+
+#### `enableUnits(units_in_si_conversion, units_in_si=UNITS_IN_SI, base_units=Meta.unit_bases)` — Enable units manually
+
+```python
+from subscript.units import enableUnits, UNITS_IN_SI
+from subscript.units import galacticus_units_si
+
+conversion = galacticus_units_si(gout)
+enableUnits(conversion)
+# Meta.units_enable is now True; node properties return astropy Quantities
+```
+
+#### `enableUnitsFromGalacticus(galacticus_output, ...)` — Enable from file
+
+Convenience wrapper that calls `galacticus_units_si()` then `enableUnits()` in one step.
+
+### `UNITS_IN_SI` — Default unit map
+
+Pre-built dict mapping all `ParamKeys` to their astropy SI units:
+
+```python
+from subscript.units import UNITS_IN_SI
+from astropy import units as apu
+
+# Examples:
+# UNITS_IN_SI[ParamKeys.mass_basic]  → apu.kg
+# UNITS_IN_SI[ParamKeys.x]           → apu.m
+# UNITS_IN_SI[ParamKeys.rvir]        → apu.m
+# UNITS_IN_SI[ParamKeys.satellite_tidal_field] → 1/apu.s**2
+```
+
+When units are enabled, `NodeProperties.__getitem__` automatically converts values:
+```python
+out_quantity = (raw_value * conversion_factor * si_unit).decompose(base_units)
 ```
 
 ---
@@ -831,7 +946,7 @@ result = subhalo_statistics(
 
 ## Units & Conventions
 
-- **Default coordinates**: Comoving (not physical)
+- **Default coordinates**: physical (not comoving)
 - **Distance**: Megaparsecs (Mpc) unless otherwise noted
 - **Mass**: Solar masses (M_☉)
 - **Time**: Gigayears (Gyr) or Billions of years
@@ -841,9 +956,6 @@ For cosmological conversions, use `colossus`:
 from colossus.cosmology import cosmology
 cosmo = cosmology.setCosmology("planck18")
 
-# Convert comoving to physical distance
-physical_distance = comoving_distance / (1 + z)
-
 # Convert kpc to arcsec at redshift z
 rad_to_arcsec = 2.06E5
 kpc_to_arcsec = (1E-3 / cosmo.angularDiameterDistance(z)) * rad_to_arcsec
@@ -868,13 +980,6 @@ A: tracking.py requires Galacticus to output node indices consistently across sn
 <nodeOperator value="indexShift" />
 ```
 
-**Q: Memory issues with large files**
-A: Disable caching:
-```python
-from subscript.defaults import Meta
-Meta.cache = False
-```
-
 **Q: Deprecation warnings for old filter names**
 A: Use new filter names (e.g., `subhalos()` instead of `nfilter_subhalos()`)
 
@@ -890,12 +995,29 @@ pandas
 scipy
 h5py
 scikit-learn
+astropy
 ```
 
 ---
 
 ## References
 
+### Comprehensive Function Reference
+
+📄 **`references/subscript_functions.md`**
+
+Complete documentation of all SubScript functions organized by module:
+- **Function signatures** with full parameter descriptions
+- **Return types** and data structures
+- **Usage examples** for each function
+- **Implementation notes** and performance considerations
+- **Complete parameter key reference** (50+ available properties)
+- **Summary table** of all functions by category
+
+Use this document for detailed function lookup and integration into custom analysis workflows.
+
+### Other Resources
+
 - **Public Repository**: https://github.com/cgannonucm/SubScript
 - **Galacticus**: https://github.com/galacticusorg/galacticus
 - **Example Notebooks**: See `example-notebooks/` in the repository