bentopy 0.2.0a10__cp313-cp313-manylinux_2_34_x86_64.whl

core/config.rs

@@ -0,0 +1,362 @@
+use anyhow::Result;
+
+use std::path::PathBuf;
+
+pub mod bent;
+mod compartment_combinations;
+pub mod legacy;
+
+pub mod defaults {
+    pub const TITLE: &str = "Bentopy system";
+    /// Bead radius for voxelization in nm.
+    pub const BEAD_RADIUS: f64 = 0.20;
+    pub const PERIODIC: bool = true;
+    pub const MAX_TRIES_MULT: u64 = 1000;
+    pub const MAX_TRIES_ROT_DIV: u64 = 100;
+}
+
+/// Avogadro's number (per mol).
+const N_A: f64 = 6.0221415e23;
+
+pub type CompartmentID = String;
+pub type Dimensions = [f32; 3];
+pub type Point = [f32; 3];
+
+impl Config {
+    /// Parse a `.bent` input file.
+    pub fn parse_bent(path: &str, s: &str) -> Result<Self> {
+        bent::parse_config(path, s)
+    }
+
+    /// Parse a legacy `.json` input file.
+    pub fn parse_legacy_json(_s: &str) -> Result<Self> {
+        todo!()
+    }
+}
+
+#[derive(Debug, Default, Clone, PartialEq)]
+pub enum RearrangeMethod {
+    #[default]
+    Moment,
+    Volume,
+    BoundingSphere,
+    None,
+}
+
+#[derive(Debug, Default, PartialEq)]
+pub struct General {
+    pub title: Option<String>,
+    pub seed: Option<u64>,
+    pub bead_radius: Option<f64>,
+    pub max_tries_mult: Option<u64>,
+    pub max_tries_rot_div: Option<u64>,
+    pub rearrange_method: Option<RearrangeMethod>,
+}
+
+#[derive(Debug, Default, PartialEq)]
+pub struct Space {
+    pub dimensions: Option<Dimensions>,
+    pub resolution: Option<f64>,
+    pub periodic: Option<bool>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+#[allow(dead_code)]
+pub enum Expr<T> {
+    Term(T),
+    Not(Box<Self>),
+    Or(Box<Self>, Box<Self>),
+    And(Box<Self>, Box<Self>),
+}
+
+impl<T: std::fmt::Display> std::fmt::Display for Expr<T> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Term(t) => t.fmt(f),
+            Self::Not(expr) => write!(f, "not {expr}"),
+            Self::Or(l, r) => write!(f, "({l} or {r})"),
+            Self::And(l, r) => write!(f, "({l} and {r})"),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Axis {
+    X,
+    Y,
+    Z,
+}
+
+impl TryFrom<char> for Axis {
+    type Error = &'static str;
+
+    fn try_from(c: char) -> Result<Self, Self::Error> {
+        match c {
+            'x' => Ok(Self::X),
+            'y' => Ok(Self::Y),
+            'z' => Ok(Self::Z),
+            _ => Err("unknown axis"),
+        }
+    }
+}
+
+impl std::fmt::Display for Axis {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::X => 'x',
+            Self::Y => 'y',
+            Self::Z => 'z',
+        }
+        .fmt(f)
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Op {
+    LessThan,
+    GreaterThan,
+}
+
+impl Op {
+    fn reverse(self) -> Self {
+        match self {
+            Self::LessThan => Self::GreaterThan,
+            Self::GreaterThan => Self::LessThan,
+        }
+    }
+}
+
+impl TryFrom<char> for Op {
+    type Error = &'static str;
+
+    fn try_from(c: char) -> Result<Self, Self::Error> {
+        match c {
+            '<' => Ok(Self::LessThan),
+            '>' => Ok(Self::GreaterThan),
+            _ => Err("unknown operator"),
+        }
+    }
+}
+
+impl std::fmt::Display for Op {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::LessThan => '<',
+            Self::GreaterThan => '>',
+        }
+        .fmt(f)
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Limit {
+    pub axis: Axis,
+    pub op: Op,
+    pub value: f64,
+}
+
+impl std::fmt::Display for Limit {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let Limit { axis, op, value } = self;
+        write!(f, "{axis} {op} {value}")
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum Quantity {
+    /// Copy number.
+    Number(u64),
+    /// Molarity (mol/L).
+    Concentration(f64),
+}
+
+impl Quantity {
+    /// Determine the number of segments that is implied by this [`Quantity`].
+    ///
+    /// In case this `Quantity` is a [`Quantity::Concentration`], the number of segments is
+    /// lazily determined from the provided `volume`, and rounded.
+    ///
+    /// The value returned by `volume` must be in cubic nanometers (nm³).
+    pub fn bake<F: Fn() -> f64>(&self, volume: F) -> u64 {
+        match *self {
+            Quantity::Number(n) => n,
+            Quantity::Concentration(c) => {
+                let v = volume() * 1e-24; // From nm³ to L.
+                let n = N_A * c * v;
+                f64::round(n) as u64
+            }
+        }
+    }
+
+    /// Returns whether the contained value can be interpreted as resulting in zero placements.
+    ///
+    /// When the quantity is a `Number(0)` or `Concentration(0.0)`, the baked number is certainly
+    /// zero. When `Number(n)` for `n > 0`, the baked number is certainly not zero.
+    ///
+    /// But, in case of a positive concentration, whether the final number is zero or not depends
+    /// on the associated volume.
+    ///
+    /// If the concentration is smaller than zero, it is treated as a zero.
+    pub fn is_zero(&self) -> bool {
+        match *self {
+            Quantity::Number(n) => n == 0,
+            Quantity::Concentration(c) => c <= 0.0,
+        }
+    }
+}
+
+impl std::fmt::Display for Quantity {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Number(count) => count.fmt(f),
+            Self::Concentration(conc) => write!(f, "{conc}M"),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct Segment {
+    pub name: String,
+    pub tag: Option<String>, // Should be 5-character ArrayString.
+    pub quantity: Quantity,
+    pub path: PathBuf,
+    pub compartment_ids: Box<[String]>,
+    pub rules: Box<[String]>,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct Compartment {
+    pub id: CompartmentID,
+    pub mask: Mask,
+}
+
+impl Compartment {
+    /// Returns whether this [`Compartment`] is dependent on other compartments.
+    pub fn is_predefined(&self) -> bool {
+        match &self.mask {
+            Mask::All | Mask::Voxels(_) | Mask::Shape(_) | Mask::Limits(_) => true,
+            Mask::Within { .. } | Mask::Combination(_) => false,
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum Mask {
+    All,
+    Voxels(PathBuf),
+    Shape(Shape),
+    Limits(Expr<Limit>),
+    // These are constructed by referencing previously defined masks.
+    Within { distance: f32, id: CompartmentID },
+    Combination(Expr<CompartmentID>),
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub enum Shape {
+    Sphere { center: Anchor, radius: f32 }, // Consider the f64 situation.
+    Cuboid { start: Anchor, end: Anchor },
+    // TODO: More?
+}
+
+impl std::fmt::Display for Shape {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Sphere { center, radius } => {
+                write!(f, "sphere at {center} with radius {radius}")
+            }
+            Self::Cuboid { start, end } => write!(f, "cuboid from {start} to {end}"),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum Anchor {
+    Start,
+    Center,
+    End,
+    Point(Point),
+}
+
+impl std::fmt::Display for Anchor {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Start => "start".fmt(f),
+            Self::Center => "center".fmt(f),
+            Self::End => "end".fmt(f),
+            Self::Point([x, y, z]) => write!(f, "{x}, {y}, {z}"),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct Constraint {
+    pub id: String,
+    pub rule: Rule,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub enum Rule {
+    RotationAxes(Axes),
+}
+
+#[derive(Debug, PartialEq)]
+pub struct Config {
+    pub general: General,
+    pub space: Space,
+    pub includes: Vec<PathBuf>,
+    pub constraints: Vec<Constraint>,
+    pub compartments: Vec<Compartment>,
+    pub segments: Vec<Segment>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct Axes {
+    pub x: bool,
+    pub y: bool,
+    pub z: bool,
+}
+
+impl Default for Axes {
+    fn default() -> Self {
+        Self {
+            x: true,
+            y: true,
+            z: true,
+        }
+    }
+}
+
+impl Axes {
+    pub fn list(&self) -> Box<[Axis]> {
+        let mut v = Vec::with_capacity(3);
+        if self.x {
+            v.push(Axis::X);
+        }
+        if self.y {
+            v.push(Axis::Y);
+        }
+        if self.z {
+            v.push(Axis::Z);
+        }
+        v.into_boxed_slice()
+    }
+}
+
+impl std::str::FromStr for Axes {
+    type Err = String;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let len = s.len();
+        if len > 3 {
+            return Err(format!(
+                "an axes string may consist of at most 3 characters, '{s}' has {len} characters"
+            ));
+        }
+
+        Ok(Self {
+            x: s.contains('x'),
+            y: s.contains('y'),
+            z: s.contains('z'),
+        })
+    }
+}

core/mod.rs

@@ -0,0 +1,4 @@
+pub mod config;
+pub mod placement;
+pub mod utilities;
+pub mod version;

core/placement.rs

@@ -0,0 +1,100 @@
+use std::path::PathBuf;
+
+use glam::Mat3;
+use serde::{Deserialize, Serialize};
+
+use crate::core::config::Dimensions;
+
+type Rotation = Mat3;
+type Position = [f32; 3];
+type RowMajorRotation = [[f32; 3]; 3];
+
+/// A list of instance-based [`Placement`]s of structures in a space.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PlacementList {
+    pub title: String,
+    pub size: Dimensions,
+    #[serde(flatten)]
+    pub meta: Option<Meta>,
+    pub topol_includes: Vec<String>,
+    pub placements: Vec<Placement>,
+}
+
+/// Additional information about the packed structure that is stored in the [`PlacementList`].
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+pub struct Meta {
+    pub seed: u64,
+    pub max_tries_mult: u64,
+    pub max_tries_per_rotation_divisor: u64,
+    pub bead_radius: f32,
+}
+
+/// A set of positions associated with some structure.
+///
+/// The structure is named and is stored at the provided `path`.
+///
+/// Positions are stored in [`Batch`]es.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Placement {
+    pub name: String,
+    /// A tag that will replace the associated structure's `resname` field, if present.
+    pub tag: Option<String>,
+    /// Path to the segment's molecule file.
+    pub path: PathBuf,
+    pub batches: Vec<Batch>,
+}
+
+impl Placement {
+    /// Creates a new [`Placement`].
+    pub fn new(name: String, tag: Option<String>, path: PathBuf) -> Self {
+        Self {
+            name,
+            tag,
+            path,
+            batches: Default::default(),
+        }
+    }
+
+    /// Returns the optional tag of this [`Placement`].
+    pub fn tag(&self) -> Option<&str> {
+        self.tag.as_deref()
+    }
+
+    /// Push a new [`Batch`] onto this [`Placement`].
+    pub fn push(&mut self, batch: Batch) {
+        self.batches.push(batch)
+    }
+}
+
+/// A set of positions that share a specific rotation.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Batch {
+    /// Rotations are stored in row-major order, since they are stored like that in the placement
+    /// list.
+    pub rotation: RowMajorRotation,
+    /// Positions in nm.
+    pub positions: Vec<Position>,
+}
+
+impl Batch {
+    /// Create a new [`Batch`] from a rotation and a set of positions.
+    ///
+    /// - The locations of the `positions` must be provided in nm. Any resolution adjustments
+    ///   must be applied by the caller.
+    /// - The provided `rotation` is internally converted and stored in row-major order.
+    pub fn new(rotation: Rotation, positions: Vec<Position>) -> Self {
+        Self {
+            rotation: rotation.transpose().to_cols_array_2d(),
+            positions,
+        }
+    }
+
+    /// Returns the 3×3 rotation matrix of this [`Batch`].
+    ///
+    /// The rotation matrix is returned in column-major order.
+    pub fn rotation(&self) -> Mat3 {
+        // Because the batch rotation is stored in a row-major order, and the initializer we use
+        // here assumes column-major order, we need to transpose the matrix before using it.
+        Mat3::from_cols_array_2d(&self.rotation).transpose()
+    }
+}

core/utilities.rs

@@ -0,0 +1 @@
+pub const CLEAR_LINE: &str = "\u{1b}[2K\r";

core/version.rs

@@ -0,0 +1,32 @@
+//! Provide additional version information, including the current git hash.
+
+pub struct Version {
+    pkg_version: &'static str,
+    git_version: &'static str,
+}
+
+impl std::fmt::Display for Version {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let Self {
+            pkg_version,
+            git_version,
+        } = self;
+        write!(f, "{pkg_version} ({git_version})")
+    }
+}
+
+// This makes it possible to use it as the version that Clap displays for a command.
+impl From<Version> for clap::builder::Str {
+    fn from(version: Version) -> Self {
+        version.to_string().into()
+    }
+}
+
+pub const VERSION: Version = Version {
+    pkg_version: env!("CARGO_PKG_VERSION"),
+    git_version: git_version::git_version!(
+        args = ["--broken", "--always", "--exclude", "*"],
+        prefix = "git:",
+        fallback = "release"
+    ),
+};

init/example.bent

@@ -0,0 +1,74 @@
+# This is an example of a bentopy input file.
+# Change the <placeholders> to the values relevant for your system.
+# Some advanced options exist for the general and space sections that are not
+# listed here. You can find more information about these in our documentation.
+
+[ general ]
+title <system-description>
+seed  <seed>
+
+[ space ]
+# Points or dimensions are given as comma-separated tuples of three numbers.
+# Whitespace between the commas and the numbers is optional.
+dimensions <x>, <y>, <z> 
+# All dimensions and sizes in bentopy are given in nanometers.
+resolution <voxel-size>
+
+[ includes ]
+# You can list the itp files that should be included in the topology files.
+# This is optional. For example:
+#   "forcefield/forcefield.itp"
+#   "forcefield/forcefield_solvents.itp"
+#   "structures/*.itp"
+<itp-includes...>
+
+[ compartments ]
+# At least one compartment must be defined.
+# You can select the whole space.
+<id> is all
+# Load from existing voxel mask (npz).
+<id> from <voxel-mask-path>
+# Or create them using analytical functions.
+<id> as sphere at center with radius <radius>
+<id> as sphere at <x>, <y>, <z> with radius <radius>
+<id> as cuboid from <x>, <y>, <z> to <x>, <y>, <z>
+# Like the center point anchor, you can also use start and end anchors.
+<id> as cuboid from start to end
+# Placements can be limited to geometric limits. These can be phrased as a
+# single inequality, such as:
+#   x > 40
+# or using boolean expressions (just like compartment combinations):
+#   20 < x and x < 80 and not z > 20
+<id> where <limits-expression>
+# Placements can be further restricted to a certain distance from some compartment.
+<id> within 5.0 of <compartment-id>
+# Compartments can be combined.
+# The available operators are `and`, `or`, and `not`.
+# Expressions can be grouped using parentheses. For example:
+#   not a or (b and c)
+<id> combines <combination-expression>
+
+[ constraints ]
+# The rotational axes of a placement can be restricted. Axes are provided as a
+# comma-separated list. Random rotations are only applied to the listed axes.
+# The rotation over the axes that are not listed will be the same as in the
+# original structure file for a segment.
+<rule-id> rotates <axes>
+
+[ segments ]
+# On each line, a segment is defined as follows:
+# - Name (match naming in itp files to write a correct topology file).
+# - Optionally, a tag (max 5 characters, preceded by a colon).
+# - Quantity:
+#   - concentration (number, with M or mM, uM/µM, nM, pM suffix),
+#   - copy number (integer, no suffix).
+# - Path to the structure file (gro, pdb).
+# - Names of its compartments (comma-separated).
+# - Optionally, the names of the rules it should uphold (comma-separated).
+<name>:<tag> <quantity> from <structure-path> in <compartment-ids> satisfies <rules>
+# If desired, newlines (and other whitespace) between fields is allowed, making
+# it possible to write segment declarations like this example:
+#   3lyz:inside
+#       1uM
+#       from "structures/3lyz.pdb"
+#       in sphere