fix: #1023 - [E3-F1-P3] Create ParticleDataBuilder with validation and unit conversion

[Gorkowski]

Target Branch: main

Fixes #1023 | Workflow: 2559ce7f

Summary

Adds a fluent ParticleDataBuilder that centralizes unit conversion, batch dimension handling, and optional zero-initialization before deferring to ParticleData for validation. Every setter converts inputs once (preserving float64), automatically inserts missing batch dimensions, and propagates defaults for concentration/charge/volume so callers only configure what changes from their existing data. The builder and docs now point to more structured usage while a dedicated test suite exercises conversions, broadcasting, zero-init, validation errors, invalid-unit paths, and dtype guarantees.

What Changed

New Components

• particula/particles/particle_data_builder.py - Implements the fluent builder with documented setters, unit conversion via get_unit_conversion, count inference, broadcasting helpers, zero-init support, and final build() that hands validated arrays to ParticleData.
• particula/particles/tests/particle_data_builder_test.py - Covers mass/density/concentration/volume conversions, auto-batch dimension behavior, zero-initialization constraints, invalid-unit errors, and ensures every numeric output is float64.
• .trash/scripts/particle_data_builder_snippet.py + .trash/scripts/test_particle_data_builder_snippet.py - Small runnable snippet that exercises the builder flow and records the demonstration as part of the repository’s utility scripts.

Modified Components

• particula/particles/__init__.py - Now exports ParticleDataBuilder alongside ParticleData so downstream users can import the builder directly from the package.

Tests Added/Updated

• particula/particles/tests/particle_data_builder_test.py - Pytest module validates every conversion, broadcast, zero-init, validation, and dtype scenario described above, keeping the new builder well-covered.

How It Works

Individual set_* calls accept scalars or arrays, convert them once to SI units with get_unit_conversion, and enforce float64 dtype. Mass arrays infer counts used for zero-init defaults while concentration/charge/volume singal their shapes to the helper that broadcasts or repeats values as needed. Once every required component exists, build() either reuses the caller-provided arrays or creates defaults before handing them to ParticleData.

┌─────────────┐
│ set_* inputs │
└────┬────────┘
     ▼
┌─────────────┐
│ convert to   │
│ SI + float64 │
└────┬────────┘
     ▼
┌─────────────┐
│ auto-batch   │
│ / zero-init  │
│ / defaults   │
└────┬────────┘
     ▼
┌─────────────┐
│ ParticleData │
│ validation   │
└─────────────┘

Implementation Notes

• Why this approach: Centralizing conversions and broadcasting in one builder keeps downstream code from duplicating unit handling or reshaping logic.
• Zero-init path: When masses are not supplied, counts drive zeroed masses while density and volume default helpers guarantee every box has a scalar.
• Package export: The builder is now re-exported from particula/particles/__init__.py, keeping the public API consistent.

Testing

• Unit tests: pytest particula/particles/tests/particle_data_builder_test.py