@saibolla/ada 0.1.2

package/skills/flowio/references/api_reference.md

@@ -0,0 +1,372 @@
+# FlowIO API Reference
+
+## Overview
+
+FlowIO is a Python library for reading and writing Flow Cytometry Standard (FCS) files. It supports FCS versions 2.0, 3.0, and 3.1 with minimal dependencies.
+
+## Installation
+
+```bash
+pip install flowio
+```
+
+Supports Python 3.9 and later.
+
+## Core Classes
+
+### FlowData
+
+The primary class for working with FCS files.
+
+#### Constructor
+
+```python
+FlowData(fcs_file,
+         ignore_offset_error=False,
+         ignore_offset_discrepancy=False,
+         use_header_offsets=False,
+         only_text=False,
+         nextdata_offset=None,
+         null_channel_list=None)
+```
+
+**Parameters:**
+- `fcs_file`: File path (str), Path object, or file handle
+- `ignore_offset_error` (bool): Ignore offset errors (default: False)
+- `ignore_offset_discrepancy` (bool): Ignore offset discrepancies between HEADER and TEXT sections (default: False)
+- `use_header_offsets` (bool): Use HEADER section offsets instead of TEXT section (default: False)
+- `only_text` (bool): Only parse the TEXT segment, skip DATA and ANALYSIS (default: False)
+- `nextdata_offset` (int): Byte offset for reading multi-dataset files
+- `null_channel_list` (list): List of PnN labels for null channels to exclude
+
+#### Attributes
+
+**File Information:**
+- `name`: Name of the FCS file
+- `file_size`: Size of the file in bytes
+- `version`: FCS version (e.g., '3.0', '3.1')
+- `header`: Dictionary containing HEADER segment information
+- `data_type`: Type of data format ('I', 'F', 'D', 'A')
+
+**Channel Information:**
+- `channel_count`: Number of channels in the dataset
+- `channels`: Dictionary mapping channel numbers to channel info
+- `pnn_labels`: List of PnN (short channel name) labels
+- `pns_labels`: List of PnS (descriptive stain name) labels
+- `pnr_values`: List of PnR (range) values for each channel
+- `fluoro_indices`: List of indices for fluorescence channels
+- `scatter_indices`: List of indices for scatter channels
+- `time_index`: Index of the time channel (or None)
+- `null_channels`: List of null channel indices
+
+**Event Data:**
+- `event_count`: Number of events (rows) in the dataset
+- `events`: Raw event data as bytes
+
+**Metadata:**
+- `text`: Dictionary of TEXT segment key-value pairs
+- `analysis`: Dictionary of ANALYSIS segment key-value pairs (if present)
+
+#### Methods
+
+##### as_array()
+
+```python
+as_array(preprocess=True)
+```
+
+Return event data as a 2-D NumPy array.
+
+**Parameters:**
+- `preprocess` (bool): Apply gain, logarithmic, and time scaling transformations (default: True)
+
+**Returns:**
+- NumPy ndarray with shape (event_count, channel_count)
+
+**Example:**
+```python
+flow_data = FlowData('sample.fcs')
+events_array = flow_data.as_array()  # Preprocessed data
+raw_array = flow_data.as_array(preprocess=False)  # Raw data
+```
+
+##### write_fcs()
+
+```python
+write_fcs(filename, metadata=None)
+```
+
+Export the FlowData instance as a new FCS file.
+
+**Parameters:**
+- `filename` (str): Output file path
+- `metadata` (dict): Optional dictionary of TEXT segment keywords to add/update
+
+**Example:**
+```python
+flow_data = FlowData('sample.fcs')
+flow_data.write_fcs('output.fcs', metadata={'$SRC': 'Modified data'})
+```
+
+**Note:** Exports as FCS 3.1 with single-precision floating-point data.
+
+## Utility Functions
+
+### read_multiple_data_sets()
+
+```python
+read_multiple_data_sets(fcs_file,
+                        ignore_offset_error=False,
+                        ignore_offset_discrepancy=False,
+                        use_header_offsets=False)
+```
+
+Read all datasets from an FCS file containing multiple datasets.
+
+**Parameters:**
+- Same as FlowData constructor (except `nextdata_offset`)
+
+**Returns:**
+- List of FlowData instances, one for each dataset
+
+**Example:**
+```python
+from flowio import read_multiple_data_sets
+
+datasets = read_multiple_data_sets('multi_dataset.fcs')
+print(f"Found {len(datasets)} datasets")
+for i, dataset in enumerate(datasets):
+    print(f"Dataset {i}: {dataset.event_count} events")
+```
+
+### create_fcs()
+
+```python
+create_fcs(filename,
+           event_data,
+           channel_names,
+           opt_channel_names=None,
+           metadata=None)
+```
+
+Create a new FCS file from event data.
+
+**Parameters:**
+- `filename` (str): Output file path
+- `event_data` (ndarray): 2-D NumPy array of event data (rows=events, columns=channels)
+- `channel_names` (list): List of PnN (short) channel names
+- `opt_channel_names` (list): Optional list of PnS (descriptive) channel names
+- `metadata` (dict): Optional dictionary of TEXT segment keywords
+
+**Example:**
+```python
+import numpy as np
+from flowio import create_fcs
+
+# Create synthetic data
+events = np.random.rand(10000, 5)
+channels = ['FSC-A', 'SSC-A', 'FL1-A', 'FL2-A', 'Time']
+opt_channels = ['Forward Scatter', 'Side Scatter', 'FITC', 'PE', 'Time']
+
+create_fcs('synthetic.fcs',
+           events,
+           channels,
+           opt_channel_names=opt_channels,
+           metadata={'$SRC': 'Synthetic data'})
+```
+
+## Exception Classes
+
+### FlowIOWarning
+
+Generic warning class for non-critical issues.
+
+### PnEWarning
+
+Warning raised when PnE values are invalid during FCS file creation.
+
+### FlowIOException
+
+Base exception class for FlowIO errors.
+
+### FCSParsingError
+
+Raised when there are issues parsing an FCS file.
+
+### DataOffsetDiscrepancyError
+
+Raised when the HEADER and TEXT sections provide different byte offsets for data segments.
+
+**Workaround:** Use `ignore_offset_discrepancy=True` parameter when creating FlowData instance.
+
+### MultipleDataSetsError
+
+Raised when attempting to read a file with multiple datasets using the standard FlowData constructor.
+
+**Solution:** Use `read_multiple_data_sets()` function instead.
+
+## FCS File Structure Reference
+
+FCS files consist of four segments:
+
+1. **HEADER**: Contains FCS version and byte locations of other segments
+2. **TEXT**: Key-value metadata pairs (delimited format)
+3. **DATA**: Raw event data (binary, floating-point, or ASCII)
+4. **ANALYSIS** (optional): Results from data processing
+
+### Common TEXT Segment Keywords
+
+- `$BEGINDATA`, `$ENDDATA`: Byte offsets for DATA segment
+- `$BEGINANALYSIS`, `$ENDANALYSIS`: Byte offsets for ANALYSIS segment
+- `$BYTEORD`: Byte order (1,2,3,4 for little-endian; 4,3,2,1 for big-endian)
+- `$DATATYPE`: Data type ('I'=integer, 'F'=float, 'D'=double, 'A'=ASCII)
+- `$MODE`: Data mode ('L'=list mode, most common)
+- `$NEXTDATA`: Offset to next dataset (0 if single dataset)
+- `$PAR`: Number of parameters (channels)
+- `$TOT`: Total number of events
+- `PnN`: Short name for parameter n
+- `PnS`: Descriptive stain name for parameter n
+- `PnR`: Range (max value) for parameter n
+- `PnE`: Amplification exponent for parameter n (format: "a,b" where value = a * 10^(b*x))
+- `PnG`: Amplification gain for parameter n
+
+## Channel Types
+
+FlowIO automatically categorizes channels:
+
+- **Scatter channels**: FSC (forward scatter), SSC (side scatter)
+- **Fluorescence channels**: FL1, FL2, FITC, PE, etc.
+- **Time channel**: Usually labeled "Time"
+
+Access indices via:
+- `flow_data.scatter_indices`
+- `flow_data.fluoro_indices`
+- `flow_data.time_index`
+
+## Data Preprocessing
+
+When calling `as_array(preprocess=True)`, FlowIO applies:
+
+1. **Gain scaling**: Multiply by PnG value
+2. **Logarithmic transformation**: Apply PnE exponential transformation if present
+3. **Time scaling**: Convert time values to appropriate units
+
+To access raw, unprocessed data: `as_array(preprocess=False)`
+
+## Best Practices
+
+1. **Memory efficiency**: Use `only_text=True` when only metadata is needed
+2. **Error handling**: Wrap file operations in try-except blocks for FCSParsingError
+3. **Multi-dataset files**: Always use `read_multiple_data_sets()` if unsure about dataset count
+4. **Offset issues**: If encountering offset errors, try `ignore_offset_discrepancy=True`
+5. **Channel selection**: Use null_channel_list to exclude unwanted channels during parsing
+
+## Integration with FlowKit
+
+For advanced flow cytometry analysis including compensation, gating, and GatingML support, consider using FlowKit library alongside FlowIO. FlowKit provides higher-level abstractions built on top of FlowIO's file parsing capabilities.
+
+## Example Workflows
+
+### Basic File Reading
+
+```python
+from flowio import FlowData
+
+# Read FCS file
+flow = FlowData('experiment.fcs')
+
+# Print basic info
+print(f"Version: {flow.version}")
+print(f"Events: {flow.event_count}")
+print(f"Channels: {flow.channel_count}")
+print(f"Channel names: {flow.pnn_labels}")
+
+# Get event data
+events = flow.as_array()
+print(f"Data shape: {events.shape}")
+```
+
+### Metadata Extraction
+
+```python
+from flowio import FlowData
+
+flow = FlowData('sample.fcs', only_text=True)
+
+# Access metadata
+print(f"Acquisition date: {flow.text.get('$DATE', 'N/A')}")
+print(f"Instrument: {flow.text.get('$CYT', 'N/A')}")
+
+# Channel information
+for i, (pnn, pns) in enumerate(zip(flow.pnn_labels, flow.pns_labels)):
+    print(f"Channel {i}: {pnn} ({pns})")
+```
+
+### Creating New FCS Files
+
+```python
+import numpy as np
+from flowio import create_fcs
+
+# Generate or process data
+data = np.random.rand(5000, 3) * 1000
+
+# Define channels
+channels = ['FSC-A', 'SSC-A', 'FL1-A']
+stains = ['Forward Scatter', 'Side Scatter', 'GFP']
+
+# Create FCS file
+create_fcs('output.fcs',
+           data,
+           channels,
+           opt_channel_names=stains,
+           metadata={
+               '$SRC': 'Python script',
+               '$DATE': '19-OCT-2025'
+           })
+```
+
+### Processing Multi-Dataset Files
+
+```python
+from flowio import read_multiple_data_sets
+
+# Read all datasets
+datasets = read_multiple_data_sets('multi.fcs')
+
+# Process each dataset
+for i, dataset in enumerate(datasets):
+    print(f"\nDataset {i}:")
+    print(f"  Events: {dataset.event_count}")
+    print(f"  Channels: {dataset.pnn_labels}")
+
+    # Get data array
+    events = dataset.as_array()
+    mean_values = events.mean(axis=0)
+    print(f"  Mean values: {mean_values}")
+```
+
+### Modifying and Re-exporting
+
+```python
+from flowio import FlowData
+
+# Read original file
+flow = FlowData('original.fcs')
+
+# Get event data
+events = flow.as_array(preprocess=False)
+
+# Modify data (example: apply custom transformation)
+events[:, 0] = events[:, 0] * 1.5  # Scale first channel
+
+# Note: Currently, FlowIO doesn't support direct modification of event data
+# For modifications, use create_fcs() instead:
+from flowio import create_fcs
+
+create_fcs('modified.fcs',
+           events,
+           flow.pnn_labels,
+           opt_channel_names=flow.pns_labels,
+           metadata=flow.text)
+```

package/skills/fluidsim/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: fluidsim
+description: Framework for computational fluid dynamics simulations using Python. Use when running fluid dynamics simulations including Navier-Stokes equations (2D/3D), shallow water equations, stratified flows, or when analyzing turbulence, vortex dynamics, or geophysical flows. Provides pseudospectral methods with FFT, HPC support, and comprehensive output analysis.
+license: CeCILL FREE SOFTWARE LICENSE AGREEMENT
+metadata:
+    skill-author: K-Dense Inc.
+---
+
+# FluidSim
+
+## Overview
+
+FluidSim is an object-oriented Python framework for high-performance computational fluid dynamics (CFD) simulations. It provides solvers for periodic-domain equations using pseudospectral methods with FFT, delivering performance comparable to Fortran/C++ while maintaining Python's ease of use.
+
+**Key strengths**:
+- Multiple solvers: 2D/3D Navier-Stokes, shallow water, stratified flows
+- High performance: Pythran/Transonic compilation, MPI parallelization
+- Complete workflow: Parameter configuration, simulation execution, output analysis
+- Interactive analysis: Python-based post-processing and visualization
+
+## Core Capabilities
+
+### 1. Installation and Setup
+
+Install fluidsim using uv with appropriate feature flags:
+
+```bash
+# Basic installation
+uv uv pip install fluidsim
+
+# With FFT support (required for most solvers)
+uv uv pip install "fluidsim[fft]"
+
+# With MPI for parallel computing
+uv uv pip install "fluidsim[fft,mpi]"
+```
+
+Set environment variables for output directories (optional):
+
+```bash
+export FLUIDSIM_PATH=/path/to/simulation/outputs
+export FLUIDDYN_PATH_SCRATCH=/path/to/working/directory
+```
+
+No API keys or authentication required.
+
+See `references/installation.md` for complete installation instructions and environment configuration.
+
+### 2. Running Simulations
+
+Standard workflow consists of five steps:
+
+**Step 1**: Import solver
+```python
+from fluidsim.solvers.ns2d.solver import Simul
+```
+
+**Step 2**: Create and configure parameters
+```python
+params = Simul.create_default_params()
+params.oper.nx = params.oper.ny = 256
+params.oper.Lx = params.oper.Ly = 2 * 3.14159
+params.nu_2 = 1e-3
+params.time_stepping.t_end = 10.0
+params.init_fields.type = "noise"
+```
+
+**Step 3**: Instantiate simulation
+```python
+sim = Simul(params)
+```
+
+**Step 4**: Execute
+```python
+sim.time_stepping.start()
+```
+
+**Step 5**: Analyze results
+```python
+sim.output.phys_fields.plot("vorticity")
+sim.output.spatial_means.plot()
+```
+
+See `references/simulation_workflow.md` for complete examples, restarting simulations, and cluster deployment.
+
+### 3. Available Solvers
+
+Choose solver based on physical problem:
+
+**2D Navier-Stokes** (`ns2d`): 2D turbulence, vortex dynamics
+```python
+from fluidsim.solvers.ns2d.solver import Simul
+```
+
+**3D Navier-Stokes** (`ns3d`): 3D turbulence, realistic flows
+```python
+from fluidsim.solvers.ns3d.solver import Simul
+```
+
+**Stratified flows** (`ns2d.strat`, `ns3d.strat`): Oceanic/atmospheric flows
+```python
+from fluidsim.solvers.ns2d.strat.solver import Simul
+params.N = 1.0  # Brunt-Väisälä frequency
+```
+
+**Shallow water** (`sw1l`): Geophysical flows, rotating systems
+```python
+from fluidsim.solvers.sw1l.solver import Simul
+params.f = 1.0  # Coriolis parameter
+```
+
+See `references/solvers.md` for complete solver list and selection guidance.
+
+### 4. Parameter Configuration
+
+Parameters are organized hierarchically and accessed via dot notation:
+
+**Domain and resolution**:
+```python
+params.oper.nx = 256  # grid points
+params.oper.Lx = 2 * pi  # domain size
+```
+
+**Physical parameters**:
+```python
+params.nu_2 = 1e-3  # viscosity
+params.nu_4 = 0     # hyperviscosity (optional)
+```
+
+**Time stepping**:
+```python
+params.time_stepping.t_end = 10.0
+params.time_stepping.USE_CFL = True  # adaptive time step
+params.time_stepping.CFL = 0.5
+```
+
+**Initial conditions**:
+```python
+params.init_fields.type = "noise"  # or "dipole", "vortex", "from_file", "in_script"
+```
+
+**Output settings**:
+```python
+params.output.periods_save.phys_fields = 1.0  # save every 1.0 time units
+params.output.periods_save.spectra = 0.5
+params.output.periods_save.spatial_means = 0.1
+```
+
+The Parameters object raises `AttributeError` for typos, preventing silent configuration errors.
+
+See `references/parameters.md` for comprehensive parameter documentation.
+
+### 5. Output and Analysis
+
+FluidSim produces multiple output types automatically saved during simulation:
+
+**Physical fields**: Velocity, vorticity in HDF5 format
+```python
+sim.output.phys_fields.plot("vorticity")
+sim.output.phys_fields.plot("vx")
+```
+
+**Spatial means**: Time series of volume-averaged quantities
+```python
+sim.output.spatial_means.plot()
+```
+
+**Spectra**: Energy and enstrophy spectra
+```python
+sim.output.spectra.plot1d()
+sim.output.spectra.plot2d()
+```
+
+**Load previous simulations**:
+```python
+from fluidsim import load_sim_for_plot
+sim = load_sim_for_plot("simulation_dir")
+sim.output.phys_fields.plot()
+```
+
+**Advanced visualization**: Open `.h5` files in ParaView or VisIt for 3D visualization.
+
+See `references/output_analysis.md` for detailed analysis workflows, parametric study analysis, and data export.
+
+### 6. Advanced Features
+
+**Custom forcing**: Maintain turbulence or drive specific dynamics
+```python
+params.forcing.enable = True
+params.forcing.type = "tcrandom"  # time-correlated random forcing
+params.forcing.forcing_rate = 1.0
+```
+
+**Custom initial conditions**: Define fields in script
+```python
+params.init_fields.type = "in_script"
+sim = Simul(params)
+X, Y = sim.oper.get_XY_loc()
+vx = sim.state.state_phys.get_var("vx")
+vx[:] = sin(X) * cos(Y)
+sim.time_stepping.start()
+```
+
+**MPI parallelization**: Run on multiple processors
+```bash
+mpirun -np 8 python simulation_script.py
+```
+
+**Parametric studies**: Run multiple simulations with different parameters
+```python
+for nu in [1e-3, 5e-4, 1e-4]:
+    params = Simul.create_default_params()
+    params.nu_2 = nu
+    params.output.sub_directory = f"nu{nu}"
+    sim = Simul(params)
+    sim.time_stepping.start()
+```
+
+See `references/advanced_features.md` for forcing types, custom solvers, cluster submission, and performance optimization.
+
+## Common Use Cases
+
+### 2D Turbulence Study
+
+```python
+from fluidsim.solvers.ns2d.solver import Simul
+from math import pi
+
+params = Simul.create_default_params()
+params.oper.nx = params.oper.ny = 512
+params.oper.Lx = params.oper.Ly = 2 * pi
+params.nu_2 = 1e-4
+params.time_stepping.t_end = 50.0
+params.time_stepping.USE_CFL = True
+params.init_fields.type = "noise"
+params.output.periods_save.phys_fields = 5.0
+params.output.periods_save.spectra = 1.0
+
+sim = Simul(params)
+sim.time_stepping.start()
+
+# Analyze energy cascade
+sim.output.spectra.plot1d(tmin=30.0, tmax=50.0)
+```
+
+### Stratified Flow Simulation
+
+```python
+from fluidsim.solvers.ns2d.strat.solver import Simul
+
+params = Simul.create_default_params()
+params.oper.nx = params.oper.ny = 256
+params.N = 2.0  # stratification strength
+params.nu_2 = 5e-4
+params.time_stepping.t_end = 20.0
+
+# Initialize with dense layer
+params.init_fields.type = "in_script"
+sim = Simul(params)
+X, Y = sim.oper.get_XY_loc()
+b = sim.state.state_phys.get_var("b")
+b[:] = exp(-((X - 3.14)**2 + (Y - 3.14)**2) / 0.5)
+sim.state.statephys_from_statespect()
+
+sim.time_stepping.start()
+sim.output.phys_fields.plot("b")
+```
+
+### High-Resolution 3D Simulation with MPI
+
+```python
+from fluidsim.solvers.ns3d.solver import Simul
+
+params = Simul.create_default_params()
+params.oper.nx = params.oper.ny = params.oper.nz = 512
+params.nu_2 = 1e-5
+params.time_stepping.t_end = 10.0
+params.init_fields.type = "noise"
+
+sim = Simul(params)
+sim.time_stepping.start()
+```
+
+Run with:
+```bash
+mpirun -np 64 python script.py
+```
+
+### Taylor-Green Vortex Validation
+
+```python
+from fluidsim.solvers.ns2d.solver import Simul
+import numpy as np
+from math import pi
+
+params = Simul.create_default_params()
+params.oper.nx = params.oper.ny = 128
+params.oper.Lx = params.oper.Ly = 2 * pi
+params.nu_2 = 1e-3
+params.time_stepping.t_end = 10.0
+params.init_fields.type = "in_script"
+
+sim = Simul(params)
+X, Y = sim.oper.get_XY_loc()
+vx = sim.state.state_phys.get_var("vx")
+vy = sim.state.state_phys.get_var("vy")
+vx[:] = np.sin(X) * np.cos(Y)
+vy[:] = -np.cos(X) * np.sin(Y)
+sim.state.statephys_from_statespect()
+
+sim.time_stepping.start()
+
+# Validate energy decay
+df = sim.output.spatial_means.load()
+# Compare with analytical solution
+```
+
+## Quick Reference
+
+**Import solver**: `from fluidsim.solvers.ns2d.solver import Simul`
+
+**Create parameters**: `params = Simul.create_default_params()`
+
+**Set resolution**: `params.oper.nx = params.oper.ny = 256`
+
+**Set viscosity**: `params.nu_2 = 1e-3`
+
+**Set end time**: `params.time_stepping.t_end = 10.0`
+
+**Run simulation**: `sim = Simul(params); sim.time_stepping.start()`
+
+**Plot results**: `sim.output.phys_fields.plot("vorticity")`
+
+**Load simulation**: `sim = load_sim_for_plot("path/to/sim")`
+
+## Resources
+
+**Documentation**: https://fluidsim.readthedocs.io/
+
+**Reference files**:
+- `references/installation.md`: Complete installation instructions
+- `references/solvers.md`: Available solvers and selection guide
+- `references/simulation_workflow.md`: Detailed workflow examples
+- `references/parameters.md`: Comprehensive parameter documentation
+- `references/output_analysis.md`: Output types and analysis methods
+- `references/advanced_features.md`: Forcing, MPI, parametric studies, custom solvers
+