solarwindpy 0.1.0__tar.gz

solarwindpy-0.1.0/.claude/README.md

@@ -0,0 +1,58 @@
+# SolarWindPy Claude Code Configuration
+
+This directory contains project-specific configuration for Claude Code that is shared across the team.
+
+## Files
+
+- **`settings.json`**: Team-shared Claude Code settings including permissions, system prompt, and tool configuration
+- **`CLAUDE.md`**: Quick reference for development commands and workflows  
+- **`agents.md`**: Comprehensive agent system for specialized development roles and validation
+- **`README.md`**: This file
+
+## Usage
+
+When working in this repository, Claude Code will automatically load the configuration from this directory, providing:
+
+1. **Pre-configured development commands** (pytest, black, flake8, conda, git)
+2. **Security settings** that protect sensitive files (.env, secrets, tokens)
+3. **Specialized development agents** for physics validation, data architecture, testing, and more
+4. **Project-specific system prompt** with SolarWindPy context
+
+## Configuration Benefits
+
+- **Consistent behavior** across all team members and computers
+- **Version controlled** configuration that evolves with the project
+- **Security-focused** permissions that protect sensitive data
+- **Domain-specific** guidance for solar wind physics and scientific computing
+- **Automated quality assurance** with testing and formatting requirements
+
+## Development Workflow
+
+### Branch-First Development (NEW!)
+
+**CRITICAL:** Claude now uses a branch-first development workflow:
+
+1. **Before any development**, Claude lists unmerged branches: `git branch -r --no-merged master`
+2. **Asks user** to specify branch, search for appropriate branch, or create new branch
+3. **Never works directly on master** - all development happens on feature branches
+4. **Creates descriptive branches** using pattern: `claude/YYYY-MM-DD-HH-MM-SS-module-feature-description`
+
+### Quality Requirements
+
+The configuration enforces these requirements:
+1. All tests must pass (`pytest -q`)
+2. Code must be formatted (`black solarwindpy/`)
+3. No linting errors (`flake8`)
+4. NumPy-style docstrings required
+5. Target ≥95% code coverage
+6. **NEW:** Include "Generated with Claude Code" in commit messages
+
+### File Overview
+
+- **`settings.json`**: Updated with branch-first workflow systemPrompt
+- **`agents.md`**: Enhanced with git workflow requirements for all agents
+- **`CLAUDE.md`**: Comprehensive branching workflow documentation
+- **`WORKFLOW_TEMPLATE.md`**: Step-by-step template for feature development
+- **`README.md`**: This overview file
+
+See `CLAUDE.md` for complete branching workflow and `WORKFLOW_TEMPLATE.md` for detailed development process.

solarwindpy-0.1.0/.claude/WORKFLOW_TEMPLATE.md

@@ -0,0 +1,152 @@
+# Claude Code Workflow Template
+
+## Feature Development Workflow
+
+This template provides a step-by-step process for Claude Code feature development with proper branch management.
+
+### Step 1: Branch Assessment
+
+**Claude automatically runs:**
+```bash
+git branch -r --no-merged master
+```
+
+**Claude asks user:**
+> "Which branch should I use? Please specify branch name, or say 'search' if you want me to help find an appropriate branch, or say 'new' to create a new branch"
+
+### Step 2: User Response Options
+
+#### Option A: Specify Existing Branch
+**User says:** `origin/existing-branch-name`
+**Claude does:**
+```bash
+git checkout existing-branch-name
+git pull origin existing-branch-name
+```
+
+#### Option B: Search for Appropriate Branch  
+**User says:** `search`
+**Claude does:**
+1. Examines branch names and recent commits
+2. Presents 3-5 most relevant branches with descriptions
+3. Asks user to choose or create new branch
+
+#### Option C: Create New Branch
+**User says:** `new`
+**Claude creates:**
+```bash
+TIMESTAMP=$(date +"%Y-%m-%d-%H-%M-%S")
+BRANCH_NAME="claude/${TIMESTAMP}-module-feature-description"
+git checkout -b ${BRANCH_NAME}
+git push -u origin ${BRANCH_NAME}
+```
+
+### Step 3: Development Work
+
+**Claude follows standard development:**
+1. Write/modify code following SolarWindPy conventions
+2. Write comprehensive tests
+3. Update documentation as needed
+4. Ensure physics validation (units, calculations)
+
+### Step 4: Quality Assurance
+
+**Before any commit:**
+```bash
+pytest -q                    # All tests must pass
+black solarwindpy/          # Format code  
+flake8                      # Check linting
+```
+
+### Step 5: Commit with Attribution
+
+**Commit format:**
+```bash
+git add .
+git commit -m "feat(module): descriptive summary
+
+Detailed description of changes and rationale.
+
+Generated with Claude Code
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+### Step 6: Push and Track
+
+**Push branch:**
+```bash
+git push origin <branch-name>
+```
+
+### Step 7: Completion Notice
+
+**Claude provides:**
+- Summary of changes made
+- Branch name for user reference  
+- Reminder that user should create PR when ready
+- Any additional validation needed
+
+## Branch Naming Examples
+
+### Good Branch Names
+- `claude/2025-08-08-14-30-00-fitfunctions-add-robust-fitting`
+- `claude/2025-08-08-15-15-00-plotting-improve-histogram-performance`
+- `claude/2025-08-08-16-00-00-core-plasma-fix-thermal-speed-calc`
+- `claude/2025-08-08-17-45-00-tests-increase-coverage-instabilities`
+
+### Branch Components
+- `claude/` - Identifier for Claude-generated branches
+- `YYYY-MM-DD-HH-MM-SS` - Timestamp for uniqueness
+- `module` - Primary module being modified (core, plotting, fitfunctions, etc.)
+- `feature-description` - Brief description with hyphens
+
+## Emergency Procedures
+
+### If Working on Wrong Branch
+```bash
+git stash                           # Save current work
+git checkout correct-branch         # Switch to correct branch
+git stash pop                       # Restore work
+```
+
+### If Need to Merge Latest Master
+```bash
+git checkout master
+git pull origin master
+git checkout feature-branch
+git merge master                    # Resolve conflicts if any
+```
+
+### If Branch Becomes Obsolete
+```bash
+git checkout master
+git branch -d local-branch-name
+git push origin --delete remote-branch-name
+```
+
+## Quality Gates
+
+### Pre-Commit Checklist
+- [ ] All tests pass (`pytest -q`)
+- [ ] Code formatted (`black solarwindpy/`)
+- [ ] No linting errors (`flake8`)
+- [ ] Physics validation complete (units, calculations)
+- [ ] Documentation updated if needed
+- [ ] Commit message follows Conventional Commits format
+
+### Pre-PR Checklist  
+- [ ] Branch pushed to origin
+- [ ] All quality gates passed
+- [ ] Feature complete and tested
+- [ ] Ready for user review and merge
+
+## Benefits Summary
+
+This workflow ensures:
+- ✅ **No master branch conflicts** - All work isolated to feature branches
+- ✅ **No premature CI triggers** - GitHub Actions only run on complete features
+- ✅ **Parallel development support** - Multiple features can be developed simultaneously  
+- ✅ **Clear audit trail** - Every Claude contribution tracked and attributed
+- ✅ **Clean git history** - Each feature gets dedicated branch and PR
+- ✅ **Review-ready code** - All changes go through proper validation before merge

solarwindpy-0.1.0/.claude/agent-routing.json

@@ -0,0 +1,199 @@
+{
+  "description": "Domain-specific agent routing configuration for SolarWindPy development",
+  "version": "1.0.0",
+  "routing": {
+    "filePatterns": {
+      "solarwindpy/core/plasma.py": ["DataFrameArchitect"],
+      "solarwindpy/core/ions.py": ["DataFrameArchitect"],
+      "solarwindpy/core/base.py": ["PhysicsValidator"],
+      "solarwindpy/core/units_constants.py": ["PhysicsValidator"],
+      "solarwindpy/core/vector.py": ["PhysicsValidator"],
+      "solarwindpy/core/tensor.py": ["PhysicsValidator"],
+      "solarwindpy/core/spacecraft.py": ["DataFrameArchitect"],
+      "solarwindpy/instabilities/*.py": ["PhysicsValidator", "NumericalStabilityGuard"],
+      "solarwindpy/plotting/*.py": ["PlottingEngineer"],
+      "solarwindpy/fitfunctions/*.py": ["FitFunctionSpecialist", "NumericalStabilityGuard"],
+      "tests/*.py": ["TestEngineer"],
+      ".claude/hooks/*.py": ["TestEngineer"],
+      ".claude/hooks/*.sh": ["TestEngineer"],
+      "*.md": ["UnifiedPlanCoordinator"],
+      "plans/*.md": ["UnifiedPlanCoordinator"]
+    },
+    "keywordTriggers": {
+      "plan": ["UnifiedPlanCoordinator"],
+      "planning": ["UnifiedPlanCoordinator"],
+      "implement": ["UnifiedPlanCoordinator"],
+      "plot": ["PlottingEngineer"],
+      "visualization": ["PlottingEngineer"],
+      "figure": ["PlottingEngineer"],
+      "physics": ["PhysicsValidator"],
+      "units": ["PhysicsValidator"],
+      "thermal": ["PhysicsValidator"],
+      "alfven": ["PhysicsValidator"],
+      "dataframe": ["DataFrameArchitect"],
+      "multiindex": ["DataFrameArchitect"],
+      "pandas": ["DataFrameArchitect"],
+      "test": ["TestEngineer"],
+      "coverage": ["TestEngineer"],
+      "pytest": ["TestEngineer"],
+      "fit": ["FitFunctionSpecialist"],
+      "curve": ["FitFunctionSpecialist"],
+      "regression": ["FitFunctionSpecialist"],
+      "optimization": ["FitFunctionSpecialist"],
+      "numerical": ["NumericalStabilityGuard"],
+      "stability": ["NumericalStabilityGuard"],
+      "precision": ["NumericalStabilityGuard"]
+    },
+    "contextTriggers": {
+      "multiStepTask": ["UnifiedPlanCoordinator"],
+      "complexImplementation": ["UnifiedPlanCoordinator"],
+      "physicsConcepts": ["PhysicsValidator"],
+      "dataAnalysis": ["DataFrameArchitect"],
+      "visualizationTasks": ["PlottingEngineer"],
+      "testingTasks": ["TestEngineer"],
+      "fittingTasks": ["FitFunctionSpecialist"],
+      "numericalTasks": ["NumericalStabilityGuard"]
+    }
+  },
+  "agents": {
+    "UnifiedPlanCoordinator": {
+      "description": "Planning, implementation, and cross-plan coordination",
+      "capabilities": ["planning", "implementation", "coordination", "project_management"],
+      "priority": 1,
+      "usagePatterns": [
+        "Multi-step tasks requiring planning",
+        "Complex implementations with multiple components",
+        "Cross-module coordination",
+        "Project-level decision making"
+      ]
+    },
+    "PhysicsValidator": {
+      "description": "Physics correctness, unit validation, scientific accuracy",
+      "capabilities": ["physics_validation", "unit_checking", "scientific_accuracy", "constraint_validation"],
+      "priority": 2,
+      "usagePatterns": [
+        "Physics calculations and formulas",
+        "Unit consistency checking",
+        "Scientific constraint validation",
+        "Thermal speed and Alfvén speed calculations"
+      ]
+    },
+    "DataFrameArchitect": {
+      "description": "MultiIndex operations, pandas optimization",
+      "capabilities": ["dataframe_design", "multiindex_operations", "pandas_optimization", "memory_efficiency"],
+      "priority": 2,
+      "usagePatterns": [
+        "DataFrame structure design",
+        "MultiIndex operations and queries",
+        "Memory optimization for large datasets",
+        "Data manipulation and transformation"
+      ]
+    },
+    "NumericalStabilityGuard": {
+      "description": "Numerical validation, edge cases, stability",
+      "capabilities": ["numerical_stability", "precision_analysis", "edge_case_handling", "algorithm_optimization"],
+      "priority": 2,
+      "usagePatterns": [
+        "Numerical computation stability",
+        "Floating point precision issues",
+        "Algorithm optimization for stability",
+        "Edge case validation"
+      ]
+    },
+    "PlottingEngineer": {
+      "description": "Visualization, matplotlib, publication-quality figures",
+      "capabilities": ["data_visualization", "matplotlib_expertise", "publication_graphics", "interactive_plots"],
+      "priority": 2,
+      "usagePatterns": [
+        "Creating scientific visualizations",
+        "Publication-quality figure generation",
+        "Interactive plotting and dashboards",
+        "Data presentation and storytelling"
+      ]
+    },
+    "FitFunctionSpecialist": {
+      "description": "Curve fitting, statistical analysis, data modeling",
+      "capabilities": ["curve_fitting", "statistical_analysis", "model_optimization", "data_modeling"],
+      "priority": 2,
+      "usagePatterns": [
+        "Curve fitting and regression analysis",
+        "Statistical model development",
+        "Parameter optimization",
+        "Data modeling and prediction"
+      ]
+    },
+    "TestEngineer": {
+      "description": "Test coverage, quality assurance, testing strategies",
+      "capabilities": ["test_strategy", "coverage_analysis", "quality_assurance", "automated_testing"],
+      "priority": 3,
+      "usagePatterns": [
+        "Test design and implementation",
+        "Coverage analysis and improvement",
+        "Quality assurance processes",
+        "Testing strategy development"
+      ]
+    }
+  },
+  "routingLogic": {
+    "priorities": {
+      "1": "Always suggest for matching patterns",
+      "2": "Suggest when domain expertise is clearly needed",
+      "3": "Suggest for specific technical tasks"
+    },
+    "fallback": {
+      "default": "UnifiedPlanCoordinator",
+      "reason": "Comprehensive planning and coordination capabilities"
+    },
+    "coordination": {
+      "multipleMatches": "Suggest primary agent based on task complexity",
+      "handoffProtocol": "UnifiedPlanCoordinator manages transitions between specialists",
+      "conflictResolution": "Priority-based with user preference consideration"
+    }
+  },
+  "integrationHooks": {
+    "preTaskAnalysis": {
+      "description": "Analyze task requirements and suggest appropriate agents",
+      "implementation": "Parse user input for file patterns, keywords, and context clues"
+    },
+    "dynamicRouting": {
+      "description": "Route tasks to appropriate agents based on analysis",
+      "implementation": "Match patterns against routing configuration and suggest agents"
+    },
+    "agentHandoff": {
+      "description": "Coordinate transitions between different domain specialists",
+      "implementation": "UnifiedPlanCoordinator manages complex workflows requiring multiple agents"
+    }
+  },
+  "usageExamples": {
+    "planning": {
+      "input": "Help me plan the implementation of dark mode for the plotting module",
+      "routing": ["UnifiedPlanCoordinator", "PlottingEngineer"],
+      "rationale": "Planning task with plotting domain expertise needed"
+    },
+    "physics": {
+      "input": "Fix the thermal speed calculation in the Ion class",
+      "routing": ["PhysicsValidator"],
+      "rationale": "Physics calculation requiring unit and formula validation"
+    },
+    "dataframe": {
+      "input": "Optimize the MultiIndex operations in plasma.py",
+      "routing": ["DataFrameArchitect"],
+      "rationale": "DataFrame optimization requiring pandas expertise"
+    },
+    "visualization": {
+      "input": "Create publication-quality plots for the solar wind analysis",
+      "routing": ["PlottingEngineer"],
+      "rationale": "Visualization task requiring matplotlib expertise"
+    },
+    "testing": {
+      "input": "Improve test coverage for the instabilities module",
+      "routing": ["TestEngineer"],
+      "rationale": "Testing task requiring coverage analysis expertise"
+    },
+    "complex": {
+      "input": "Implement a new plasma instability analysis with visualization and testing",
+      "routing": ["UnifiedPlanCoordinator", "PhysicsValidator", "PlottingEngineer", "TestEngineer"],
+      "rationale": "Multi-domain task requiring coordination and multiple specialists"
+    }
+  }
+}

solarwindpy-0.1.0/.claude/agents/agent-dataframe-architect.md

@@ -0,0 +1,153 @@
+---
+name: DataFrameArchitect  
+description: Manages pandas MultiIndex data structures and ensures efficient memory usage
+priority: high
+tags:
+  - pandas
+  - data-structure
+  - memory
+  - core
+applies_to:
+  - solarwindpy/core/**/*.py
+---
+
+# DataFrameArchitect Agent
+
+## Purpose
+Maintains the integrity and efficiency of pandas DataFrame structures throughout the SolarWindPy codebase, focusing on the MultiIndex architecture and memory optimization.
+
+**Use PROACTIVELY for all DataFrame operations, MultiIndex manipulations, memory optimization, and data structure design decisions.**
+
+## Key Responsibilities
+
+### MultiIndex Structure
+- Enforce the three-level MultiIndex: ("M", "C", "S") 
+  - M: Measurement type (n, v, w, b, etc.)
+  - C: Component (x, y, z for vectors, empty for scalars)
+  - S: Species (p1, p2, a, etc., empty for magnetic field)
+- Validate index hierarchy consistency
+- Ensure proper level naming and ordering
+
+### Memory Optimization
+- Use DataFrame.xs() for views instead of copies
+- Monitor memory usage with .memory_usage(deep=True)
+- Implement chunking strategies for large datasets
+- Optimize dtype selection (float32 vs float64)
+- Clean up temporary DataFrames promptly
+
+### DateTime Indices
+- Ensure datetime indices (typically "Epoch") are properly formatted
+- Validate timezone awareness consistency
+- Check for duplicate timestamps
+- Maintain chronological ordering
+- Handle timestamp precision appropriately
+
+### Data Alignment
+- Validate alignment when combining plasma/spacecraft data
+- Ensure consistent index ranges across related DataFrames
+- Handle resampling and interpolation properly
+- Manage missing data with NaN (never 0 or -999)
+
+### Performance Patterns
+```python
+# Good: Using views
+plasma_data = df.xs('v', level='M')  # Returns view
+
+# Bad: Creating unnecessary copies
+plasma_data = df[df.index.get_level_values('M') == 'v'].copy()
+
+# Good: Efficient selection
+ion_data = df.xs('p1', level='S', axis=1)
+
+# Bad: Inefficient iteration
+ion_data = df[[col for col in df.columns if col[2] == 'p1']]
+```
+
+## Data Structure Standards
+
+### Column Naming Convention
+```python
+# Standard MultiIndex columns
+columns = pd.MultiIndex.from_tuples([
+    ('n', '', 'p1'),    # Proton density
+    ('v', 'x', 'p1'),   # Proton velocity x
+    ('v', 'y', 'p1'),   # Proton velocity y
+    ('v', 'z', 'p1'),   # Proton velocity z
+    ('w', '', 'p1'),    # Proton thermal speed
+    ('b', 'x', ''),     # Magnetic field x
+    ('b', 'y', ''),     # Magnetic field y
+    ('b', 'z', ''),     # Magnetic field z
+])
+```
+
+### Index Requirements
+- Primary index must be DatetimeIndex
+- No duplicate index values allowed
+- Maintain nanosecond precision where needed
+- Support for multi-day continuous data
+
+## Common Pitfalls
+
+### SettingWithCopyWarning
+```python
+# Bad: Chained assignment
+df[df['col'] > 0]['col'] = 1
+
+# Good: Using .loc
+df.loc[df['col'] > 0, 'col'] = 1
+```
+
+### Memory Leaks
+```python
+# Bad: Keeping references to large DataFrames
+temp_df = large_df.copy()
+result = temp_df.groupby(...).mean()
+# temp_df still in memory
+
+# Good: Clean up explicitly
+temp_df = large_df.copy()
+result = temp_df.groupby(...).mean()
+del temp_df
+```
+
+## Validation Checks
+
+1. **Structure Validation**
+   - MultiIndex levels are correctly named
+   - All required measurements present
+   - Species columns are complete sets
+
+2. **Memory Validation**
+   - No unnecessary data duplication
+   - Appropriate dtype usage
+   - View vs copy usage is correct
+
+3. **Index Validation**
+   - DateTime index is monotonic
+   - No missing timestamps in expected ranges
+   - Proper handling of data gaps
+
+## Integration Points
+
+- Coordinates with **PhysicsValidator** for data consistency
+- Provides structure for **TestEngineer** test cases
+- Optimizes data for **PerformanceOptimizer**
+- Ensures compatibility with **PlottingEngineer**
+
+## Best Practices
+
+1. Always use MultiIndex access methods (.xs, .loc with tuples)
+2. Prefer views over copies when possible
+3. Document any data structure modifications
+4. Test with both single-point and multi-day datasets
+5. Monitor memory usage in data processing pipelines
+
+## Error Messages
+
+Provide clear error messages for structure violations:
+```python
+if 'M' not in df.columns.names:
+    raise ValueError(
+        "DataFrame must have MultiIndex columns with 'M' level. "
+        "Expected levels: ['M', 'C', 'S'], got: {df.columns.names}"
+    )