bentopy 0.2.0a10__cp313-cp313-manylinux_2_34_x86_64.whl

pack/session.rs

@@ -0,0 +1,176 @@
+use glam::U64Vec3;
+use rand::seq::SliceRandom;
+
+use crate::Location;
+use crate::mask::{Dimensions, Position};
+use crate::state::{Rng, Space, Voxels};
+
+pub struct Session<'s> {
+    inner: &'s mut Space,
+    locations: &'s mut Locations,
+    target: usize,
+}
+
+impl<'s> Session<'s> {
+    pub fn new(inner: &'s mut Space, locations: &'s mut Locations, target: usize) -> Self {
+        Self {
+            inner,
+            locations,
+            target,
+        }
+    }
+
+    pub fn target(&self) -> usize {
+        self.target
+    }
+}
+
+impl Session<'_> {
+    pub fn resolution(&self) -> f32 {
+        self.inner.resolution
+    }
+
+    pub fn dimensions(&self) -> Dimensions {
+        self.inner.dimensions
+    }
+
+    pub fn periodic(&self) -> bool {
+        self.inner.periodic
+    }
+
+    /// Returns a location if available.
+    ///
+    /// This function also takes a reference to a random number generator, since the internal
+    /// [`Locations`] type may shuffle its indices on demand.
+    ///
+    /// If the background for this [`Session`] does not have any free locations left, the session
+    /// must be ended. This case is indicated with a `None` return value.
+    pub fn pop_location(&mut self, rng: &mut Rng) -> Option<Location> {
+        // TODO: Consider having the shuffle guess that is passed to pop be dynamic with the number
+        // of placements that have already occurred. We could update that number as we go.
+        if let Some(location) = self.locations.pop(rng, self.target) {
+            return Some(location);
+        }
+
+        // We're out of locations. We'll try and renew once.
+        self.locations.renew(
+            self.inner
+                .session_background
+                .linear_indices_where::<false>(),
+        );
+
+        // If the result is still `None`, there is nothing we can do anymore.
+        self.locations.pop(rng, self.target)
+    }
+
+    /// Returns `true` if no collisions are encountered between the [`Space`] and the provided
+    /// [`Voxels`] at some `position`.
+    ///
+    /// If a collision is found, the function exits early with a `false` value.
+    pub fn check_collisions(&self, voxels: &Voxels, position: Position) -> bool {
+        let occupied_indices = voxels.indices_where::<true>().map(U64Vec3::from_array);
+        let position = U64Vec3::from_array(position);
+
+        occupied_indices
+            .map(|p| (p + position).to_array())
+            .all(|idx| !self.inner.session_background.get_periodic(idx))
+    }
+
+    pub fn stamp(&mut self, voxels: &Voxels, location: Position) {
+        let location = U64Vec3::from_array(location);
+        for idx in voxels
+            .indices_where::<true>()
+            .map(|idx| U64Vec3::from_array(idx) + location)
+        {
+            self.inner
+                .global_background
+                .set_periodic(idx.to_array(), true);
+            self.inner
+                .session_background
+                .set_periodic(idx.to_array(), true);
+        }
+    }
+
+    pub fn exit_session(&mut self) {
+        // Not really doing anything here anymore.
+    }
+
+    pub const fn position(&self, location: Location) -> Option<Position> {
+        self.inner.session_background.spatial_idx(location)
+    }
+}
+
+impl<'s> Drop for Session<'s> {
+    fn drop(&mut self) {
+        self.exit_session();
+    }
+}
+
+pub struct Locations {
+    /// Linear indices into the background map.
+    indices: Vec<Location>,
+    used: usize,
+    threshold: usize,
+
+    /// The number of shuffled elements that may be popped from the end of `indices`.
+    cursor: usize,
+}
+
+impl Locations {
+    /// Threshold of spare capacity at which the `locations` [`Vec`] ought to be shrunk.
+    const SHRINK_THRESHOLD: usize = (100 * 1024_usize.pow(2)) / std::mem::size_of::<Location>();
+    /// Value that determines the threshold at which the locations will be renewed.
+    const RENEW_THRESHOLD: f64 = 0.1;
+
+    pub fn new() -> Self {
+        Self {
+            indices: Vec::new(),
+            used: 0,
+            threshold: 0,
+            cursor: 0,
+        }
+    }
+
+    /// Renew the locations from an iterator of locations.
+    pub fn renew(&mut self, locations: impl Iterator<Item = Location>) {
+        let indices = &mut self.indices;
+        indices.clear();
+        indices.extend(locations);
+        // Shrink the `locations` if the spare capacity is getting out of hand.
+        if indices.spare_capacity_mut().len() > Self::SHRINK_THRESHOLD {
+            indices.shrink_to_fit();
+        }
+        self.used = 0;
+        self.cursor = 0;
+        // We want to make sure that the threshold is rounded down, such that it eventually could
+        // reach 0, indicating the enclosing Session is exhausted. See `pop`.
+        self.threshold = (indices.len() as f64 * Self::RENEW_THRESHOLD).floor() as usize
+    }
+
+    fn shuffle(&mut self, rng: &mut Rng, shuffle_guess: usize) {
+        let (shuffled, _unshuffled) = self.indices.partial_shuffle(rng, shuffle_guess);
+        self.cursor = shuffled.len();
+    }
+
+    /// Pop a location.
+    ///
+    /// This function also takes a reference to a random number generator, since this type may
+    /// shuffle its indices on demand. The `shuffle_guess` suggests the number of items that ought
+    /// to be shuffled in that scenario.
+    ///
+    /// A `None` value indicates that this [`Locations`] object must be [renewed](`Self::renew`),
+    /// not necessarily that all locations have been popped.
+    pub fn pop(&mut self, rng: &mut Rng, shuffle_guess: usize) -> Option<Location> {
+        if self.used >= self.threshold {
+            return None; // Indicate a renewal is needed.
+        }
+        if self.cursor == 0 {
+            self.shuffle(rng, shuffle_guess);
+        }
+        let location = self.indices.pop()?;
+        self.used += 1;
+        assert!(self.cursor > 0);
+        self.cursor -= 1;
+        Some(location)
+    }
+}

pack/state/combinations.rs

@@ -0,0 +1,31 @@
+use bentopy::core::config::{CompartmentID, Expr};
+
+use crate::{mask::Mask, state::Compartment};
+
+pub fn execute(expr: &Expr<CompartmentID>, compartments: &[Compartment]) -> anyhow::Result<Mask> {
+    let output = match expr {
+        Expr::Term(id) => {
+            let compartment = compartments
+                .iter()
+                .find(|c| &c.id == id)
+                .ok_or(anyhow::anyhow!("mask with id {id:?} not (yet) defined"))?;
+            compartment.mask.clone()
+        }
+        Expr::Not(expr) => !execute(expr, compartments)?,
+        // TODO: This is quite a horrible, no-good transliteration of the legacy_execute function.
+        // There is some much here that can be improved upon, in terms of memory efficiency, for
+        // example.
+        Expr::Or(lhs, rhs) => {
+            let mut m = execute(lhs, compartments)?;
+            m &= execute(rhs, compartments)?;
+            m
+        }
+        Expr::And(lhs, rhs) => {
+            let mut m = execute(lhs, compartments)?;
+            m |= execute(rhs, compartments)?;
+            m
+        }
+    };
+
+    Ok(output)
+}

pack/state/compartment.rs

@@ -0,0 +1,44 @@
+use bentopy::core::config::{CompartmentID, Expr, Limit};
+
+use crate::mask::{Dimensions, Mask};
+
+pub struct Compartment {
+    pub id: CompartmentID,
+    pub mask: Mask,
+}
+
+pub fn distill_limits(expr: &Expr<Limit>, dimensions: Dimensions, resolution: f64) -> Mask {
+    fn apply_limit(mut mask: Mask, limit: &Limit, resolution: f64) -> Mask {
+        let &Limit { axis, op, value } = limit;
+        match op {
+            bentopy::core::config::Op::LessThan => {
+                mask.apply_function(|pos| value < pos[axis as usize] as f64 * resolution)
+            }
+            bentopy::core::config::Op::GreaterThan => {
+                mask.apply_function(|pos| value > pos[axis as usize] as f64 * resolution)
+            }
+        }
+
+        mask
+    }
+
+    // TODO: This is naive. Also wrong perhaps. Let's test this thuroughly.
+    fn d(expr: &Expr<Limit>, dimensions: Dimensions, resolution: f64) -> Mask {
+        match expr {
+            Expr::Term(limit) => apply_limit(Mask::new(dimensions), limit, resolution),
+            Expr::Not(expr) => !d(expr, dimensions, resolution),
+            Expr::Or(lhs, rhs) => {
+                let mut m = d(lhs, dimensions, resolution);
+                m &= d(rhs, dimensions, resolution);
+                m
+            }
+            Expr::And(lhs, rhs) => {
+                let mut m = d(lhs, dimensions, resolution);
+                m |= d(rhs, dimensions, resolution);
+                m
+            }
+        }
+    }
+
+    d(expr, dimensions, resolution)
+}

pack/state/mask.rs

@@ -0,0 +1,196 @@
+use std::path::Path;
+
+use anyhow::{Context, Result, bail};
+use bentopy::core::config::{self, legacy::Shape as LegacyConfigShape};
+use glam::{U64Vec3, UVec3, Vec3};
+
+use crate::mask::{Dimensions, Mask};
+
+impl Mask {
+    /// All dimensions in terms of voxels.
+    pub(crate) fn legacy_create_from_shape(
+        shape: LegacyConfigShape,
+        dimensions: Dimensions,
+        center: Option<UVec3>,
+        radius: Option<u32>,
+    ) -> Self {
+        let [w, h, d] = dimensions.map(|v| v as usize);
+        let min_dim = dimensions.into_iter().min().unwrap() as u32; // Has non-zero length.
+        let r = radius.unwrap_or(min_dim / 2);
+        assert!(
+            min_dim >= r,
+            "the provided radius ({r} voxels) must not exceed the space's smallest dimension ({min_dim} voxels)"
+        );
+        let c = center.unwrap_or(UVec3::splat(r)).as_ivec3();
+        assert!(U64Vec3::from_array(dimensions).cmpge(c.as_u64vec3()).all());
+        let r2 = r.pow(2);
+
+        // TODO: We can use some nice iterator tricks to avoid allocating a big Vec<bool> here.
+        // TODO: Profile to see whether we can help the inlining along.
+        let mut cells = Vec::with_capacity(w * h * d);
+        for z in 0..d as i32 {
+            for y in 0..h as i32 {
+                for x in 0..w as i32 {
+                    let cell = match shape {
+                        LegacyConfigShape::Spherical => {
+                            // TODO: Profile and inspect asm to see whether this inlines well.
+                            ((x - c.x).pow(2) as u32)
+                                + ((y - c.y).pow(2) as u32)
+                                + ((z - c.z).pow(2) as u32)
+                                >= r2
+                        }
+                        LegacyConfigShape::Cuboid | LegacyConfigShape::None => false,
+                    };
+                    cells.push(cell);
+                }
+            }
+        }
+        let cells = cells.into_boxed_slice();
+
+        Self::from_cells(dimensions, &cells)
+    }
+
+    // TODO: Still shitty version. Will be better with a rewrite.
+    pub(crate) fn create_cuboid(
+        dimensions: [u64; 3],
+        resolution: f32,
+        start: config::Anchor,
+        end: config::Anchor,
+    ) -> Self {
+        let [w, h, d] = dimensions.map(|v| v as usize);
+        let dimensions = U64Vec3::from_array(dimensions);
+
+        let start = match start {
+            config::Anchor::Start => U64Vec3::ZERO,
+            config::Anchor::Center => dimensions / 2,
+            config::Anchor::End => dimensions,
+            config::Anchor::Point(point) => (Vec3::from(point) / resolution).as_u64vec3(),
+        };
+        let end = match end {
+            config::Anchor::Start => U64Vec3::ZERO,
+            config::Anchor::Center => dimensions / 2,
+            config::Anchor::End => dimensions,
+            config::Anchor::Point(point) => (Vec3::from(point) / resolution).as_u64vec3(),
+        };
+        // TODO: Consider if we want to do this here, or make the correct ordering an invariant.
+        let (start, end) = (U64Vec3::min(start, end), U64Vec3::max(start, end));
+
+        assert!(
+            dimensions.cmpge(start).all(),
+            "start ({start}) must be within the space dimensions ({dimensions})"
+        );
+        assert!(
+            dimensions.cmpge(end).all(),
+            "end ({end}) must be within the space dimensions ({dimensions})"
+        );
+
+        // TODO: We can use some nice iterator tricks to avoid allocating a big Vec<bool> here.
+        // TODO: Profile to see whether we can help the inlining along.
+        let mut cells = vec![true; w * h * d];
+        for z in 0..d {
+            for y in 0..h {
+                for x in 0..w {
+                    let idx = x + w * y + w * h * z;
+                    let free = (start.x..end.x).contains(&(x as u64))
+                        && (start.y..end.y).contains(&(y as u64))
+                        && (start.z..end.z).contains(&(z as u64));
+                    cells[idx] = !free;
+                }
+            }
+        }
+        let cells = cells.into_boxed_slice();
+
+        Self::from_cells(dimensions.into(), &cells)
+
+        // TODO: Go with something along these lines. Likely faster and more memory efficient.
+        // let mut mask = Self::new(dimensions);
+        // mask.apply_function(|[x,y,z]| );
+    }
+
+    pub(crate) fn create_from_shape(
+        dimensions: [u64; 3],
+        resolution: f32,
+        shape: config::Shape,
+    ) -> Mask {
+        // TODO: The current implementation just giving the helm over to legacy_create_from_shape
+        // is very sad and will be corrected.
+        match shape {
+            config::Shape::Sphere { center, radius } => {
+                let center = match center {
+                    config::Anchor::Center => (U64Vec3::from(dimensions) / 2).as_uvec3(),
+                    config::Anchor::Point(point) => (Vec3::from(point) / resolution).as_uvec3(),
+                    config::Anchor::Start => UVec3::ZERO,
+                    config::Anchor::End => U64Vec3::from(dimensions).as_uvec3(),
+                };
+                let radius = (radius / resolution) as u32;
+                Self::legacy_create_from_shape(
+                    LegacyConfigShape::Spherical,
+                    dimensions,
+                    Some(center),
+                    Some(radius),
+                )
+            }
+            config::Shape::Cuboid { start, end } => {
+                Self::create_cuboid(dimensions, resolution, start, end)
+            }
+        }
+        // LegacyConfigMask::Analytical {
+        //     shape,
+        //     center,
+        //     radius,
+        // } => {
+        //     if verbose {
+        //         eprintln!("\tConstructing a {shape} mask...");
+        //     }
+        //     let center = center.map(|c| (Vec3::from_array(c) / resolution).as_uvec3());
+        //     let radius = radius.map(|r| (r / resolution) as u32);
+        //     Mask::legacy_create_from_shape(shape, dimensions, center, radius)
+        // }
+    }
+
+    pub(crate) fn load_from_path<P: AsRef<Path>>(path: P) -> Result<Self> {
+        let mut npz = npyz::npz::NpzArchive::open(path)?;
+        // FIXME: This error could be handled more gracefully.
+        let first_name = npz
+            .array_names()
+            .next()
+            .context("There should be at least one array in the mask voxel map")?
+            .to_string();
+        let array = npz.by_name(&first_name)?.unwrap(); // We just asserted the name exists.
+        let Ok(size): Result<[u64; 3], _> = array.shape().to_vec().try_into() else {
+            let shape = array.shape();
+            bail!("a voxel map must have three dimensions, found {shape:?}");
+        };
+        if size.iter().any(|d| d == &0) {
+            bail!("a voxel map must have non-zero sized dimensions, found {size:?}")
+        }
+
+        let order = array.order();
+        let mut cells: Box<[bool]> = array.into_vec()?.into_boxed_slice();
+        cells.iter_mut().for_each(|cell| *cell = !(*cell));
+        let cells = match order {
+            npyz::Order::C => {
+                // We need to re-order the cells to get them into the expected Fortran ordering.
+                let mut reordered = Vec::with_capacity(cells.len());
+                reordered.resize(cells.len(), false);
+                let mut cells = IntoIterator::into_iter(cells);
+                let mut reordered = reordered.into_boxed_slice();
+                let [w, h, d] = size;
+                assert_eq!(cells.len() as u64, w * h * d);
+                for x in 0..w {
+                    for y in 0..h {
+                        for z in 0..d {
+                            // We know that cells and reordered have the same size, and we have
+                            // asserted that `size` corresponds to the same length.
+                            reordered[(x + y * w + z * w * h) as usize] = cells.next().unwrap();
+                        }
+                    }
+                }
+                reordered
+            }
+            npyz::Order::Fortran => cells,
+        };
+
+        Ok(Self::from_cells(size, &cells))
+    }
+}

pack/state/pack.rs

@@ -0,0 +1,187 @@
+use std::io;
+
+pub(crate) use glam::Mat3;
+use rand::Rng as _;
+
+use crate::session::Locations;
+use crate::state::State;
+use crate::{CLEAR_LINE, Summary};
+use bentopy::core::placement::{Batch, Placement};
+
+impl State {
+    pub fn pack(&mut self, log: &mut impl io::Write) -> anyhow::Result<(Vec<Placement>, Summary)> {
+        let start = std::time::Instant::now();
+        let mut locations = Locations::new();
+        let mut placements = Vec::new();
+        let mut summary = Summary::new();
+
+        let state = self;
+        let n_segments = state.segments.len();
+        for (i, segment) in state.segments.iter_mut().enumerate() {
+            if segment.quantity.is_zero() {
+                write!(
+                    log,
+                    "{prefix}({i:>3}/{n_segments}) Skipping attempt to pack 0 instances of segment '{name}'.{suffix}",
+                    prefix = if state.verbose { "" } else { CLEAR_LINE },
+                    i = i + 1,
+                    name = segment.name,
+                    suffix = if state.verbose { "\n" } else { "" }
+                )?;
+                continue;
+            }
+
+            write!(
+                log,
+                "{prefix}({i:>3}/{n_segments}) Attempting to pack {target:>5} instances of segment '{name}'.{suffix}",
+                prefix = if state.verbose { "" } else { CLEAR_LINE },
+                i = i + 1,
+                target = segment.quantity,
+                name = segment.name,
+                suffix = if state.verbose { "\n" } else { "" }
+            )?;
+
+            // Prepare the session.
+            let start_session = std::time::Instant::now();
+            let mut session = state.space.enter_session(
+                segment.compartments.iter().cloned(),
+                &mut locations,
+                segment.quantity,
+            );
+
+            // Set up the placement record for this segment.
+            let mut placement = Placement::new(
+                segment.name.clone(),
+                segment.tag.clone(),
+                segment.path.clone(),
+            );
+
+            let mut hits = 0;
+            let mut tries = 0; // The number of unsuccessful tries.
+            let mut tries_per_rotation = 0;
+            // The maximum number of unsuccessful tries.
+            let max_tries = state.general.max_tries_multiplier * session.target() as u64;
+            // The number of
+            let max_tries_per_rotation = max_tries / state.general.max_tries_per_rotation_divisor;
+            let mut batch_positions = Vec::new();
+            'placement: while hits < session.target() {
+                if tries >= max_tries {
+                    if state.verbose {
+                        writeln!(log, "Exiting after {tries} unsuccessful tries.")?;
+                    }
+                    break 'placement; // "When you try your best, but you don't succeed."
+                }
+
+                // TODO: This can become more efficient for successive placement failures.
+                // TODO: Also, this should become a method on Segment.
+                let resolution = session.resolution();
+                let voxels = match segment.voxels() {
+                    Some(voxels) => voxels,
+                    None => {
+                        segment.voxelize(resolution, state.general.bead_radius);
+                        segment.voxels().unwrap() // We just voxelized.
+                    }
+                };
+
+                // FIXME: Do all this math with glam::U64Vec?
+                let [bx, by, bz] = session.dimensions();
+                let [sx, sy, sz] = voxels.dimensions();
+                if sx > bx || sy > by || sz > bz {
+                    tries += 1;
+
+                    // What about another rotation?
+                    let rotation = Mat3::from_quat(state.rng.random());
+                    segment.set_rotation(rotation);
+                    tries_per_rotation = 0; // Reset the counter.
+                    if state.verbose {
+                        eprintln!("\tNew rotation. The previous rotation would never have fit.")
+                    }
+
+                    continue 'placement; // Segment voxels size exceeds the size of the background.
+                }
+                let [maxx, maxy, maxz] = [bx - sx, by - sy, bz - sz];
+
+                // Pick a random location.
+                let position = 'location: loop {
+                    let candidate = match session.pop_location(&mut state.rng) {
+                        Some(location) => location,
+                        None => {
+                            // We've gone through all the locations.
+                            // TODO: This is rather unlikely, but must be dealt with correctly. I think
+                            // this may require a nice custom type that does some internal mutabilty
+                            // trickery.
+                            // For now, we'll just break here.
+                            break 'placement;
+                        }
+                    };
+
+                    // Convert the linear index location to a spatial index.
+                    let position = session.position(candidate).unwrap();
+
+                    // If we are not packing in a periodic manner, we skip candidate positions that
+                    // would necessitate periodic behavior. When a location passes this point, it is
+                    // valid for non-periodic placement.
+                    if !session.periodic() {
+                        // Check if the segment will fit in the background, given this position.
+                        let [x, y, z] = position;
+                        if x >= maxx || y >= maxy || z >= maxz {
+                            continue 'location;
+                        }
+                    }
+
+                    // All seems good, so we continue to see if this position will be accepted.
+                    break position;
+                };
+
+                // Reject if it would cause a collision.
+                if !session.check_collisions(voxels, position) {
+                    tries += 1;
+                    tries_per_rotation += 1;
+                    if tries_per_rotation >= max_tries_per_rotation {
+                        let rotation = Mat3::from_quat(state.rng.random());
+                        segment.set_rotation(rotation);
+                        tries_per_rotation = 0; // Reset the counter.
+                    }
+                    continue 'placement; // Reject due to collision.
+                }
+
+                // We found a good spot. Stomp on those stamps!
+                session.stamp(voxels, position);
+                // Transform the location to nm.
+                batch_positions.push(position.map(|v| v as f32 * session.resolution()));
+
+                // Let's write out the batch and rotate the segment again.
+                // TODO: Perhaps we'll need a little transpose here.
+                let batch = Batch::new(segment.rotation(), batch_positions.clone());
+                placement.push(batch);
+                batch_positions.clear();
+
+                let rotation = Mat3::from_quat(state.rng.random());
+                segment.set_rotation(rotation);
+                tries_per_rotation = 0; // Reset the counter.
+
+                hits += 1;
+            }
+            let duration = start_session.elapsed().as_secs_f64();
+
+            if state.verbose {
+                let total = start.elapsed().as_secs();
+                writeln!(
+                    log,
+                    "                      Packed {hits:>5} instances in {duration:6.3} s. [{total} s] <{:.4} of max_tries, {:.4} of target>",
+                    tries as f32 / max_tries as f32,
+                    tries as f32 / session.target() as f32
+                )?;
+            }
+
+            // Save the batches.
+            summary.push(segment.name.clone(), session.target(), hits, duration);
+            placements.push(placement);
+        }
+
+        if !state.verbose {
+            writeln!(log)?; // Go down one line to prevent overwriting the last line.
+        }
+
+        Ok((placements, summary))
+    }
+}