Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

7.8 KB
Raw Blame
//! Two-stage adaptive allocation. Independent pilot samples choose a bounded
//! production budget; pilot radiance is discarded, never stopped into the final
//! mean. Error thresholds guide allocation, not a certified convergence bound.
use super::{ErrorCode, JobError, Result};
use serde::{Deserialize, Serialize};

#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct AdaptiveSampling {
    pub pilot_samples: u32,
    pub min_samples: u32,
    pub relative_error: f64,
    pub absolute_error: f64,
    pub coverage_error: f64,
}
impl Default for AdaptiveSampling {
    fn default() -> Self {
        Self { pilot_samples: 32, min_samples: 32, relative_error: 0.05, absolute_error: 0.002, coverage_error: 0.01 }
    }
}
impl AdaptiveSampling {
    pub fn validate(self, maximum: u32) -> Result<()> {
        if !(16..=256).contains(&self.pilot_samples)
            || !(16..=maximum).contains(&self.min_samples)
            || maximum > 4096
            || !self.relative_error.is_finite()
            || !(0.0..=1.0).contains(&self.relative_error)
            || !self.absolute_error.is_finite()
            || !(1e-6..=1e6).contains(&self.absolute_error)
            || !self.coverage_error.is_finite()
            || !(0.001..=0.25).contains(&self.coverage_error)
        {
            return Err(JobError::new(
                ErrorCode::InvalidRequest,
                "adaptive allocation needs 16..256 pilots, 16..maximum production samples, relative error 0..1, absolute error 0.000001..1000000 and coverage error 0.001..0.25",
            ));
        }
        Ok(())
    }
    /// Independent f64 allocation oracle for the native f32 implementation.
    /// Nonfinite pilot estimates select the cap rather than false convergence.
    pub fn target(self, mean: [f64; 4], m2: [f64; 4], maximum: u32) -> Result<u32> {
        self.validate(maximum)?;
        let mut target = self.min_samples;
        for (channel, (mean, m2)) in mean.into_iter().zip(m2).enumerate() {
            if !mean.is_finite() || !m2.is_finite() || mean < 0.0 || m2 < 0.0 {
                return Ok(maximum);
            }
            let tolerance = if channel == 3 { self.coverage_error } else { self.absolute_error + self.relative_error * mean };
            let ratio = (m2 / f64::from(self.pilot_samples - 1)).sqrt() / tolerance;
            let estimate = ratio.min(f64::from(maximum).sqrt()).powi(2).ceil() as u32;
            target = target.max(estimate.min(maximum));
        }
        Ok(target)
    }
}

#[derive(Clone, Debug, PartialEq, Serialize)]
pub struct SamplingReport {
    pub pilot_samples_per_pixel: u32,
    pub minimum_production_samples: u32,
    pub maximum_production_samples: u32,
    pub production_samples: u64,
    pub primary_path_evaluations: u64,
    pub pixels_at_cap: u64,
    pub transmission_strata: u32,
}

/// Display progress for an adaptive checkpoint. Production iterations do not imply
/// a uniform sample count: each pixel stops at its own independently chosen budget.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum PreviewStage {
    Pilot,
    Production,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
pub struct AdaptivePreview {
    pub stage: PreviewStage,
    pub completed: u32,
    pub target: u32,
    pub pilot_samples: u32,
    pub minimum_production_samples: u32,
    pub maximum_production_samples: u32,
}
impl AdaptivePreview {
    /// Derived only from captured sampling options and an absolute completed pass.
    pub fn at(options: super::JobOptions, completed: u32) -> Result<Option<Self>> {
        let Some(adaptive) = options.adaptive else { return Ok(None) };
        options.preview_target()?;
        Ok(Some(Self::captured(adaptive, options.samples, completed)?))
    }
    /// The same captured statistical policy is shared by native CPU and GPU jobs.
    /// The completed ordinal spans pilots plus production; it is not a per-pixel count.
    pub fn captured(adaptive: AdaptiveSampling, maximum: u32, completed: u32) -> Result<Self> {
        adaptive.validate(maximum)?;
        let target = adaptive
            .pilot_samples
            .checked_add(maximum)
            .ok_or_else(|| JobError::new(ErrorCode::LimitExceeded, "adaptive checkpoint target overflow"))?;
        if completed == 0 || completed > target {
            return Err(JobError::new(ErrorCode::InvalidRequest, "checkpoint exceeds captured sampling passes"));
        }
        Ok({
            let pilot = completed <= adaptive.pilot_samples;
            Self {
                stage: if pilot { PreviewStage::Pilot } else { PreviewStage::Production },
                completed: if pilot { completed } else { completed - adaptive.pilot_samples },
                target: if pilot { adaptive.pilot_samples } else { maximum },
                pilot_samples: adaptive.pilot_samples,
                minimum_production_samples: adaptive.min_samples,
                maximum_production_samples: maximum,
            }
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn zero_variance_uses_minimum_but_coverage_and_chroma_can_require_the_cap() {
        let p = AdaptiveSampling::default();
        assert_eq!(p.target([1.0; 4], [0.0; 4], 128).unwrap(), 32);
        assert_eq!(p.target([1.0; 4], [0.0, 0.0, 0.0, 31.0], 128).unwrap(), 128);
        assert_eq!(p.target([1.0; 4], [31.0, 0.0, 0.0, 0.0], 128).unwrap(), 128);
        assert_eq!(p.target([1.0; 4], [f64::INFINITY; 4], 128).unwrap(), 128);
    }
    #[test]
    fn standard_error_allocation_matches_independent_closed_form() {
        let p = AdaptiveSampling { relative_error: 0.0, absolute_error: 0.1, ..Default::default() };
        assert_eq!(p.target([1.0; 4], [31.0 * 0.64, 0.0, 0.0, 0.0], 128).unwrap(), 64);
        for invalid in [f64::NAN, f64::INFINITY, -1.0, 1.01] {
            assert!(AdaptiveSampling { relative_error: invalid, ..p }.validate(128).is_err());
        }
        assert!(p.validate(16).is_err());
        assert!(AdaptiveSampling { pilot_samples: 1, ..p }.validate(128).is_err());
        assert!(AdaptiveSampling { absolute_error: 0.0, ..p }.validate(128).is_err());
        assert!(serde_json::from_str::<AdaptiveSampling>(r#"{"noise_guarantee":true}"#).is_err());
    }

    #[test]
    fn adaptive_checkpoint_metadata_tracks_pilots_and_variable_production_iterations() {
        for maximum in [16, 64, 4096] {
            for pilots in [16, 32, 256] {
                let options = super::super::JobOptions {
                    samples: maximum,
                    adaptive: Some(AdaptiveSampling { pilot_samples: pilots, min_samples: 16, ..Default::default() }),
                    ..Default::default()
                };
                let total = options.preview_target().unwrap();
                assert_eq!(total, pilots + maximum);
                assert!(AdaptivePreview::at(options, 0).is_err());
                assert!(AdaptivePreview::at(options, total + 1).is_err());
                for ordinal in 1..=total {
                    let info = AdaptivePreview::at(options, ordinal).unwrap().unwrap();
                    assert_eq!(info.pilot_samples, pilots);
                    assert_eq!((info.minimum_production_samples, info.maximum_production_samples), (16, maximum));
                    if ordinal <= pilots {
                        assert_eq!((info.stage, info.completed, info.target), (PreviewStage::Pilot, ordinal, pilots));
                    } else {
                        assert_eq!((info.stage, info.completed, info.target), (PreviewStage::Production, ordinal - pilots, maximum));
                    }
                }
            }
        }
        assert!(
            AdaptivePreview::at(super::super::JobOptions::default(), 4096).unwrap().is_none(),
            "CPU profile checkpoints do not use GPU sampling options"
        );
    }
}