solarwindpy 0.0.1.dev0__py3-none-any.whl → 0.1.0__py3-none-any.whl

plans/completed/combined_test_plan_with_checklist_plotting/11-labels-chemistry.py.md

@@ -0,0 +1,212 @@
+---
+name: 'Combined Plan and Checklist: Chemistry Labels'
+about: Unified documentation and checklist for validating chemistry-related plotting labels.
+labels: [sweep, plotting, labels, chemistry, ManualLabel]
+---
+
+> Phase 12 of Enhanced Plotting Test Plan
+
+## 🧠 Context
+
+The `solarwindpy.plotting.labels.chemistry` module provides specialized labels for chemistry-related quantities commonly used in plasma physics and space science visualizations. The module defines standardized labels with proper LaTeX formatting for mass-to-charge ratios, first ionization potentials, charges, and masses.
+
+### Key Components
+- **Mass-to-Charge Ratio**: `mass_per_charge` label with AMU/e units
+- **First Ionization Potential**: `fip` label with eV units  
+- **Ion Charge**: `charge` label with elementary charge units
+- **Ion Mass**: `mass` label with atomic mass units
+
+### Dependencies
+- Imports `ManualLabel` from `special` module
+- Relies on LaTeX formatting for mathematical expressions
+- Uses standardized path naming for file output
+
+## 📋 Comprehensive Test Checklist
+
+### 12.1 Module Structure and Imports
+
+- [x] **Import verification**: `from .special import ManualLabel` works correctly
+- [x] **Module accessibility**: Chemistry labels module imports successfully
+- [x] **ManualLabel availability**: `ManualLabel` class accessible and functional
+
+### 12.2 Mass-to-Charge Ratio Label (`mass_per_charge`)
+
+#### Label properties
+- [ ] **LaTeX label**: Correct LaTeX formatting `r"\mathrm{M/Q}"`
+- [ ] **Units**: Proper units string `r"\mathrm{AMU \, e^{-1}}"`
+- [ ] **Path**: Valid path string `"M-OV-Q"`
+- [ ] **ManualLabel creation**: Successfully creates ManualLabel instance
+
+#### Label validation
+- [ ] **LaTeX rendering**: LaTeX expressions render correctly in matplotlib
+- [ ] **Unit formatting**: Units display properly with spacing and formatting
+- [ ] **Path handling**: Path string valid for file naming conventions
+- [ ] **Immutability**: Label properties remain constant after creation
+
+### 12.3 First Ionization Potential Label (`fip`)
+
+#### Label properties  
+- [ ] **LaTeX label**: Correct LaTeX formatting `r"\mathrm{FIP}"`
+- [ ] **Units**: Proper units string `r"\mathrm{eV}"`
+- [ ] **Path**: Valid path string `"FIP"`
+- [ ] **ManualLabel creation**: Successfully creates ManualLabel instance
+
+#### Label validation
+- [ ] **LaTeX rendering**: FIP label renders correctly
+- [ ] **Unit consistency**: eV units appropriate for ionization potential
+- [ ] **Path simplicity**: Simple path name appropriate for FIP
+- [ ] **Scientific accuracy**: Label represents first ionization potential correctly
+
+### 12.4 Ion Charge Label (`charge`)
+
+#### Label properties
+- [ ] **LaTeX label**: Correct LaTeX formatting `r"\mathrm{Q}"`
+- [ ] **Units**: Proper units string `r"\mathrm{e}"`
+- [ ] **Path**: Valid path string `"IonCharge"`
+- [ ] **ManualLabel creation**: Successfully creates ManualLabel instance
+
+#### Label validation
+- [ ] **LaTeX rendering**: Charge symbol Q renders correctly
+- [ ] **Unit representation**: Elementary charge unit 'e' displayed properly
+- [ ] **Path descriptiveness**: "IonCharge" path clearly identifies quantity
+- [ ] **Physics accuracy**: Represents ion charge state correctly
+
+### 12.5 Ion Mass Label (`mass`)
+
+#### Label properties
+- [ ] **LaTeX label**: Correct LaTeX formatting `r"\mathrm{M}"`
+- [ ] **Units**: Proper units string `r"\mathrm{AMU}"`
+- [ ] **Path**: Valid path string `"IonMass"`
+- [ ] **ManualLabel creation**: Successfully creates ManualLabel instance
+
+#### Label validation
+- [ ] **LaTeX rendering**: Mass symbol M renders correctly
+- [ ] **Unit accuracy**: AMU (atomic mass unit) appropriate for ion mass
+- [ ] **Path clarity**: "IonMass" path clearly identifies quantity
+- [ ] **Consistency**: Consistent with mass_per_charge mass component
+
+### 12.6 Cross-Label Consistency
+
+#### Unit consistency
+- [ ] **Mass units**: AMU used consistently across mass-related labels
+- [ ] **Charge units**: Elementary charge 'e' used consistently
+- [ ] **LaTeX style**: Consistent `\mathrm{}` formatting across labels
+- [ ] **Path naming**: Consistent naming convention for paths
+
+#### Mathematical relationships
+- [ ] **M/Q consistency**: mass_per_charge relates correctly to mass and charge
+- [ ] **Unit relationships**: Units mathematically consistent (AMU/e = AMU e^-1)
+- [ ] **Scientific relationships**: Labels represent physically related quantities
+
+### 12.7 Integration with ManualLabel
+
+#### ManualLabel functionality
+- [ ] **Proper inheritance**: Labels inherit all ManualLabel capabilities
+- [ ] **Method access**: ManualLabel methods accessible on chemistry labels
+- [ ] **Property access**: ManualLabel properties work correctly
+- [ ] **Serialization**: Labels serialize/deserialize properly if supported
+
+#### Label behavior
+- [ ] **String representation**: Labels convert to strings appropriately
+- [ ] **Plotting integration**: Labels work correctly in plotting contexts
+- [ ] **File path usage**: Path strings work for file naming and organization
+
+### 12.8 LaTeX and Mathematical Formatting
+
+#### LaTeX syntax validation
+- [ ] **Syntax correctness**: All LaTeX expressions syntactically valid
+- [ ] **Rendering quality**: Labels render clearly in matplotlib plots
+- [ ] **Font consistency**: Mathematical formatting consistent across labels
+- [ ] **Special characters**: Proper handling of superscripts, subscripts
+
+#### Mathematical notation
+- [ ] **Standard notation**: Uses standard scientific notation conventions
+- [ ] **Readability**: Labels clear and readable in plot contexts
+- [ ] **Professional quality**: Publication-quality label formatting
+
+### 12.9 Error Handling and Validation
+
+#### Invalid usage
+- [ ] **Modification attempts**: Proper handling of attempts to modify labels
+- [ ] **Invalid access**: Graceful handling of invalid property access
+- [ ] **Type consistency**: Labels maintain correct types
+
+#### Edge cases
+- [ ] **Empty contexts**: Labels work in various plotting contexts
+- [ ] **Multiple usage**: Labels can be used multiple times without issues
+- [ ] **Memory efficiency**: Labels don't create memory leaks with repeated use
+
+### 12.10 Performance and Memory
+
+#### Memory usage
+- [ ] **Efficient storage**: Labels stored efficiently in memory
+- [ ] **No duplication**: No unnecessary duplication of label data
+- [ ] **Cleanup**: Proper cleanup when labels no longer needed
+
+#### Performance characteristics
+- [ ] **Fast access**: Label properties accessed quickly
+- [ ] **Rendering speed**: Labels render efficiently in plots
+- [ ] **Scalability**: Performance maintained with many labels
+
+### 12.11 Documentation and Usage
+
+#### Documentation quality
+- [ ] **Module docstring**: Clear module-level documentation
+- [ ] **Label descriptions**: Each label clearly documented
+- [ ] **Usage examples**: Examples of label usage in plotting
+- [ ] **Scientific context**: Documentation explains scientific meaning
+
+#### Usability
+- [ ] **Intuitive names**: Label variable names intuitive and clear
+- [ ] **Easy access**: Labels easily accessible from chemistry module
+- [ ] **Integration examples**: Examples of integration with plotting functions
+
+### 12.12 Test Infrastructure
+
+#### Test setup
+- [ ] **Label fixtures**: Reusable fixtures for chemistry labels
+- [ ] **LaTeX testing**: Framework for testing LaTeX rendering
+- [ ] **Integration testing**: Tests with actual plotting functions
+- [ ] **Regression testing**: Tests prevent label changes breaking plots
+
+#### Test coverage
+- [ ] **All labels tested**: Every chemistry label tested individually
+- [ ] **Property testing**: All label properties validated
+- [ ] **Integration testing**: Labels tested in realistic plotting scenarios
+- [ ] **Error condition testing**: Invalid usage scenarios tested
+
+## 🎯 Testing Strategy
+
+### Unit Testing Approach
+- Test each chemistry label independently
+- Verify LaTeX syntax and rendering
+- Validate ManualLabel integration
+- Test label properties and immutability
+
+### Integration Testing
+- Test labels in actual plotting contexts
+- Verify labels work with axes formatting
+- Test file path usage in save operations
+- Validate scientific accuracy of representations
+
+### Visual Testing (Future)
+- Render labels in plots and verify appearance
+- Test LaTeX rendering across different backends
+- Verify font consistency and readability
+
+### Edge Case Coverage
+- Invalid modification attempts
+- Unusual plotting contexts
+- Memory and performance stress testing
+
+---
+
+**Status**: ✅ COMPLETED
+**Commit**: 5b47880
+**Tests Added**: 20 comprehensive test cases
+**Time Invested**: 1 hour
+**Test Results**: 20/20 passing (100% success rate)
+
+**Estimated Time**: 1 hour  
+**Dependencies**: ManualLabel class, LaTeX rendering  
+**Priority**: MEDIUM (Domain-specific label functionality)

plans/completed/combined_test_plan_with_checklist_plotting/12-labels-composition.py.md

@@ -0,0 +1,242 @@
+---
+name: 'Combined Plan and Checklist: Composition Labels'
+about: Unified documentation and checklist for validating composition-related plotting labels.
+labels: [sweep, plotting, labels, composition, Ion, ChargeState]
+---
+
+> Phase 13 of Enhanced Plotting Test Plan
+
+## 🧠 Context
+
+The `solarwindpy.plotting.labels.composition` module provides specialized labels for plasma composition analysis, including ion species and charge state representations. The module defines classes for representing individual ions with their charge states and provides LaTeX formatting for scientific notation in plots.
+
+### Key Components
+- **Ion Class**: Represents individual ion species with charge states
+- **ChargeState Class**: Specialized charge state representations
+- **Known Species**: Predefined list of common plasma species
+- **LaTeX Formatting**: Automatic LaTeX generation for ion notation
+
+### Scientific Context
+- Common plasma species: C, Fe, He, Mg, Ne, N, O, Si, S
+- Ion charge state notation (e.g., O^6+, Fe^10+)
+- Path-safe naming for file outputs
+- Integration with base plotting infrastructure
+
+## 📋 Comprehensive Test Checklist
+
+### 13.1 Module Structure and Exports
+
+- [ ] **Export validation**: `__all__` contains `["Ion", "ChargeState"]`
+- [ ] **Import verification**: `from . import base` works correctly
+- [ ] **Path integration**: `from pathlib import Path` functions properly
+- [ ] **Debug import**: `import pdb` present for development (noqa handled)
+
+### 13.2 Known Species Definition
+
+#### Species list validation
+- [ ] **Species tuple**: `known_species` contains expected plasma species
+- [ ] **Species completeness**: Common plasma species included (C, Fe, He, Mg, Ne, N, O, Si, S)
+- [ ] **Species format**: Species names properly capitalized
+- [ ] **Immutability**: Species tuple immutable after definition
+
+#### Species coverage
+- [ ] **Solar wind species**: Major solar wind species represented
+- [ ] **Plasma physics relevance**: Species relevant to space plasma research
+- [ ] **Extensibility**: System can handle unknown species with warnings
+
+### 13.3 Ion Class Structure
+
+#### Inheritance and initialization
+- [ ] **Base inheritance**: `Ion` properly inherits from `base.Base`
+- [ ] **Initialization**: `__init__(species, charge)` works correctly
+- [ ] **Super call**: `super().__init__()` called appropriately
+- [ ] **Species/charge setting**: `set_species_charge(species, charge)` called in init
+
+### 13.4 Ion Class Properties
+
+#### Species property
+- [ ] **Species getter**: `@property species` returns correct species
+- [ ] **Species storage**: `_species` attribute stores species correctly
+- [ ] **Species immutability**: Species cannot be directly modified
+- [ ] **Species type**: Species stored as expected type (string)
+
+#### Charge property  
+- [ ] **Charge getter**: `@property charge` returns correct charge
+- [ ] **Charge storage**: `_charge` attribute stores charge correctly
+- [ ] **Charge immutability**: Charge cannot be directly modified
+- [ ] **Charge format**: Charge stored in appropriate format
+
+#### LaTeX representation
+- [ ] **LaTeX property**: `@property tex` generates correct LaTeX
+- [ ] **LaTeX format**: Format `"{species}^{charge}"` applied correctly
+- [ ] **LaTeX rendering**: Generated LaTeX renders properly in matplotlib
+- [ ] **Special characters**: Handles superscripts and charge signs correctly
+
+#### Units property
+- [ ] **Units definition**: `@property units` returns `"\#"` 
+- [ ] **Units meaning**: Hash symbol appropriate for count/number units
+- [ ] **Escape handling**: Backslash escape handled correctly (noqa comment)
+- [ ] **Units consistency**: Units consistent across ion instances
+
+#### Path property
+- [ ] **Path generation**: `@property path` creates valid Path object
+- [ ] **Path format**: Format `species_charge` with character replacement
+- [ ] **Character replacement**: Plus/minus signs replaced (+ → p, - → m)
+- [ ] **File safety**: Generated paths safe for filesystem use
+
+### 13.5 Species and Charge Validation
+
+#### `set_species_charge()` method
+- [ ] **Species capitalization**: `species.title()` applied correctly
+- [ ] **Known species check**: Warning logged for unknown species
+- [ ] **Species validation**: Known species processed without warnings
+- [ ] **Species storage**: Valid species stored in `_species`
+
+#### Charge validation logic
+- [ ] **Charge parsing**: `int(charge)` conversion attempted
+- [ ] **Valid charge handling**: Integer charges processed correctly
+- [ ] **Invalid charge detection**: `ValueError` caught for invalid charges
+- [ ] **Invalid charge flag**: `invalid_charge` flag set appropriately
+
+### 13.6 Error Handling and Logging
+
+#### Warning system
+- [ ] **Unknown species warning**: Appropriate warning for unknown species
+- [ ] **Logger access**: `self.logger` accessible from base class
+- [ ] **Warning format**: Warning message format clear and informative
+- [ ] **Warning level**: Warning level appropriate for unknown species
+
+#### Error conditions
+- [ ] **Invalid charge handling**: Proper handling of non-integer charges
+- [ ] **Empty species**: Behavior with empty or None species
+- [ ] **Empty charge**: Behavior with empty or None charge
+- [ ] **Type errors**: Graceful handling of incorrect parameter types
+
+### 13.7 ChargeState Class (if implemented)
+
+#### Class structure
+- [ ] **Class existence**: `ChargeState` class defined and accessible
+- [ ] **Base inheritance**: Proper inheritance structure
+- [ ] **Initialization**: Constructor works correctly
+- [ ] **Functionality**: Core functionality implemented
+
+#### Integration with Ion
+- [ ] **Compatibility**: `ChargeState` works with `Ion` class
+- [ ] **Shared functionality**: Common functionality properly shared
+- [ ] **Distinct features**: Unique `ChargeState` features work correctly
+
+### 13.8 LaTeX Integration and Formatting
+
+#### LaTeX generation
+- [ ] **Syntax correctness**: Generated LaTeX syntactically correct
+- [ ] **Rendering quality**: LaTeX renders clearly in plots
+- [ ] **Mathematical notation**: Proper superscript formatting for charges
+- [ ] **Font consistency**: Consistent with other label formatting
+
+#### Special formatting cases
+- [ ] **Positive charges**: Positive charges formatted correctly (e.g., ^6+)
+- [ ] **Negative charges**: Negative charges formatted correctly (e.g., ^1-)
+- [ ] **Neutral species**: Zero charge handled appropriately
+- [ ] **Multi-digit charges**: Multi-digit charges display correctly
+
+### 13.9 File Path Integration
+
+#### Path generation
+- [ ] **Path object creation**: `Path` objects created correctly
+- [ ] **Character substitution**: Safe character substitution for file systems
+- [ ] **Path uniqueness**: Different ions generate unique paths
+- [ ] **Path validity**: Paths valid across different operating systems
+
+#### File system compatibility
+- [ ] **Cross-platform**: Paths work on Windows, macOS, Linux
+- [ ] **Special characters**: No invalid filesystem characters in paths
+- [ ] **Path length**: Generated paths reasonable length
+- [ ] **Collision avoidance**: Different ions don't generate identical paths
+
+### 13.10 Integration with Base Classes
+
+#### Base class integration
+- [ ] **Logger access**: Inherits logger functionality from base
+- [ ] **Base methods**: Base class methods accessible and functional
+- [ ] **Initialization chain**: Initialization chain works correctly
+- [ ] **Property inheritance**: Base properties accessible if applicable
+
+### 13.11 Performance and Memory
+
+#### Memory efficiency
+- [ ] **Object size**: Ion objects use memory efficiently
+- [ ] **String caching**: LaTeX strings generated efficiently
+- [ ] **Path caching**: Path objects cached appropriately
+- [ ] **Cleanup**: No memory leaks with repeated Ion creation
+
+#### Performance characteristics
+- [ ] **Creation speed**: Ion objects created quickly
+- [ ] **Property access**: Properties accessed efficiently
+- [ ] **LaTeX generation**: LaTeX generation reasonably fast
+- [ ] **Scalability**: Performance maintained with many Ion objects
+
+### 13.12 Documentation and Usage
+
+#### Documentation quality
+- [ ] **Class docstrings**: Clear documentation for Ion class
+- [ ] **Method documentation**: All methods properly documented
+- [ ] **Property documentation**: Properties clearly explained
+- [ ] **Usage examples**: Examples of Ion usage provided
+
+#### Scientific accuracy
+- [ ] **Notation standards**: Ion notation follows scientific standards
+- [ ] **Species accuracy**: Species symbols scientifically correct
+- [ ] **Charge representation**: Charge notation follows conventions
+- [ ] **Physical meaning**: Labels represent physical quantities correctly
+
+### 13.13 Test Infrastructure
+
+#### Test framework
+- [ ] **Unit test structure**: Tests for individual Ion methods
+- [ ] **Property testing**: All properties tested independently
+- [ ] **Integration testing**: Ion objects tested in plotting contexts
+- [ ] **Error condition testing**: Invalid inputs tested appropriately
+
+#### Test data
+- [ ] **Representative ions**: Test data covers common plasma ions
+- [ ] **Edge cases**: Unusual species and charge states tested
+- [ ] **Invalid cases**: Invalid inputs tested for proper error handling
+- [ ] **Performance cases**: Large numbers of ions tested
+
+## 🎯 Testing Strategy
+
+### Unit Testing Approach
+- Test Ion class initialization and properties independently
+- Verify LaTeX generation for various ion species and charges
+- Test species validation and warning system
+- Validate path generation and character substitution
+
+### Integration Testing
+- Test Ion objects in actual plotting scenarios
+- Verify LaTeX rendering in matplotlib contexts
+- Test file path usage in save operations
+- Validate integration with other label systems
+
+### Scientific Validation
+- Verify ion notation follows scientific conventions
+- Test species coverage for relevant plasma physics applications
+- Validate charge state representations
+- Test integration with plasma composition analysis workflows
+
+### Edge Case Coverage
+- Unknown species handling
+- Invalid charge states
+- Extreme charge values
+- Special formatting cases
+
+---
+
+**Status**: ✅ COMPLETED
+**Commit**: 5b47880
+**Tests Added**: 37 comprehensive test cases
+**Time Invested**: 1.5 hours
+**Test Results**: 37/37 passing (100% success rate)
+
+**Estimated Time**: 1.5 hours  
+**Dependencies**: Base label classes, pathlib, LaTeX rendering  
+**Priority**: MEDIUM (Domain-specific composition functionality)