MultiMM 2.0.1__tar.gz → 2.0.2__tar.gz

{multimm-2.0.1/src/MultiMM.egg-info → multimm-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MultiMM
-Version: 2.0.1
+Version: 2.0.2
 Summary: A tool for chromatin modeling from nucleosomes to chromosomal territories.
 Author-email: Sebastian Korsak <s.korsak@datascience.edu.pl>
 License: GNU General Public License v3.0
@@ -75,116 +75,215 @@ pip install MultiMM
 
 PyPI software: https://pypi.org/project/MultiMM/.
 
-## Mathematical Model
+### Model Overview
 
-We model chromatin as a coarse-grained polymer confined inside the nucleus. The system is described by an effective energy functional
+We model chromatin as a coarse-grained polymer where the total energy $E$ is decomposed into a set of physically motivated interaction terms capturing polymer mechanics, epigenetic organization, and structural constraints. Each term encodes a distinct biological mechanism, allowing the model to reproduce both local polymer behavior and large-scale genome organization such as compartments and loops.
 
-$$E = E_{\text{pol}} + E_{\text{lamina}} + E_{\text{loop}} + E_{\text{block}}$$
+At a generic level, the system is governed by a total energy of the form
+
+$$E = E_{\text{backbone}} + E_{\text{block-copolymer}} + E_{\text{loops}} + E_{\text{excluded}} + E_{\text{confinement}} + E_{\text{chromosomal}}$$
+
+where each contribution controls a different aspect of chromatin folding:
+
+* $E_{\text{backbone}}$: enforces polymer connectivity and stiffness through bonded and angular interactions, ensuring a realistic chain-like structure
+* $E_{\text{block-copolymer}}$: captures compartment and subcompartment segregation via state-dependent attractive interactions between beads
+* $E_{\text{loops}}$: introduces long-range constraints between genomic loci, mimicking loop extrusion or experimentally observed contacts
+* $E_{\text{excluded}}$: accounts for steric repulsion, preventing unphysical overlaps between beads
+* $E_{\text{confinement}}$: imposes nuclear geometry through spherical confinement and lamina interactions
+* $E_{\text{chromosomal}}$: promotes large-scale organization such as chromosome territories and global compaction
+
+Together, these terms define a minimal yet flexible energy landscape where local polymer physics and global genomic features emerge in a unified framework.
 
-Each bead represents a chromatin segment of fixed genomic length. The equilibrium structure is obtained by energy minimization or short relaxation dynamics.
 
 ### Polymer Backbone
 
-Polymer connectivity, stiffness, and excluded volume are enforced by the following potential energy terms:
+The backbone contribution $E_{\text{backbone}}$ encodes the connectivity and local rigidity of the polymer chain. It is composed of two standard terms: harmonic bonds enforcing nearest-neighbor distances, and harmonic angle potentials controlling chain stiffness.
 
-$$
-E_{\text{pol}} = E_{\text{bond}} + E_{\text{bend}} + E_{\text{rep}}
-$$
+The bond (connectivity) term is given by
 
-where
+$$E_{\text{bond}} = \sum_{i} \frac{k_b}{2} \left( r_{i,i+1} - r_0 \right)^2$$
 
-$$
-E_{\text{bond}} = \sum_i k_b (r_{i,i+1} - \ell)^2
-$$
+where $r_{i,i+1} = |\mathbf{r}_{i+1} - \mathbf{r}_i|$ is the distance between consecutive beads, $r_0$ is the equilibrium bond length, and $k_b$ is the bond stiffness. This term ensures that the polymer remains connected and fluctuates around a preferred contour length.
 
-is the harmonic bond potential that keeps consecutive beads at distance ≈ ℓ,
+The stiffness (bending) term is defined as
 
-$$
-E_{\text{bend}} = \sum_i k_s (\theta_i - \pi)^2
-$$
+$$E_{\text{angle}} = \sum_{i} \frac{k_\theta}{2} \left( \theta_i - \theta_0 \right)^2$$
 
-is the bending energy that controls chain stiffness (θᵢ is the angle between bonds i−1→i and i→i+1),
+where $\theta_i$ is the angle formed by three consecutive beads $(i, i+1, i+2)$, $\theta_0$ is the preferred angle, and $k_\theta$ controls the bending rigidity. This term penalizes sharp bends and sets the persistence length of the polymer.
+
+Altogether, the backbone energy reads
+
+$$E_{\text{backbone}} = E_{\text{bond}} + E_{\text{angle}}$$
+
+which corresponds to a discretized worm-like chain model with harmonic stretching and bending fluctuations.
 
-and
 
-$$
-E_{\text{rep}} = \sum_{i < j} \epsilon \left( \frac{\sigma}{r_{ij}} \right)^\alpha
-$$
 
-is the purely repulsive long-range interaction that enforces excluded volume.
+### Loop Interactions
 
-The first term fixes bond lengths, the second controls bending rigidity, and the third prevents unphysical monomer overlap.
+The loop contribution $E_{\text{loops}}$ introduces long-range interactions between pairs of beads $(m,n)$, representing loop extrusion or experimentally detected contacts. Each loop acts as an effective tether that constrains the spatial distance between distant genomic loci.
 
+The default model uses a harmonic potential
 
-### Looping Interactions
+$$E_{\text{loops}}^{\text{harmonic}} = \sum_{(m,n)} \frac{k}{2} \left( r_{mn} - r_0 \right)^2$$
 
-Chromatin loops detected experimentally are modeled as harmonic restraints
+where $r_{mn} = |\mathbf{r}_n - \mathbf{r}_m|$, $r_0$ is the preferred loop length, and $k$ is the stiffness. This formulation strongly penalizes deviations from $r_0$, effectively enforcing fixed-distance loops and providing a simple baseline model.
 
-$$E_{\text{loop}} =
-k_\ell \sum_{(i,j)\in \text{loops}} (r_{ij} - d_{ij})^2 .$$
+To allow more physical flexibility, two alternative bounded interactions are introduced. The first is a soft FENE-like potential
 
-The equilibrium loop length depends on interaction strength $S_{ij}$ as
+$$E_{\text{loops}}^{\text{fene}} = \sum_{(m,n)} \frac{k (r_{mn} - r_0)^2}{1 + \alpha (r_{mn} - r_0)^2}$$
 
-$$d_{ij} \propto S_{ij}^{-2/3},
-\qquad
-d_{ij} \in [0.1, 0.2] .$$
+which behaves harmonically near equilibrium but saturates at large extensions. This avoids unphysical divergence and models loops as extensible but finite-strength tethers.
+
+The second alternative is a Gaussian tether
+
+$$E_{\text{loops}}^{\text{gaussian}} = \sum_{(m,n)} k \left( 1 - e^{-(r_{mn} - r_0)^2 / \sigma^2} \right)$$
+
+which defines a fully smooth, bounded potential well. Close to $r_0$ it is approximately harmonic, while at large distances it saturates to a constant energy, effectively allowing loop breaking without instability.
 
-For single cell data all loops have the same equilibrium distance.
 
 ### Block Copolymer Compartmentalization
 
-Long range compartmentalization is described by a Gaussian attraction between beads of the same compartment
+The block-copolymer contribution $E_{\text{block}}$ encodes epigenetic segregation via state-dependent pairwise interactions. Each bead carries a label $s_i$ representing its compartment or subcompartment identity. These labels selectively activate interactions, driving chromatin phase separation into distinct domains.
 
-$$
-E_{\text{block}} = \sum_c E_c \exp\left(-\frac{r^2}{2 r_0^2}\right)
-$$
+**Compartment level (A/B):** Interactions follow a Gaussian attractive potential:
+
+```math
+E_{\text{comp}} = -\sum \epsilon(s_i,s_j) \exp\left( -\frac{r_{ij}^2}{2r_c^2} \right)
+```
+
+where $r_{ij}$ is the distance between beads and $r_c$ is the interaction range. The coupling $\epsilon(s_i,s_j)$ is attractive for like compartments (A–A, B–B) and weak or repulsive otherwise, reproducing large-scale A/B segregation seen in Hi-C data.
+
+**Subcompartment level:** The model is extended to multiple epigenetic states $\alpha,\beta$:
+
+```math
+E_{\text{sub}} = -\sum \epsilon_{\alpha\beta} \exp\left( -\frac{r_{ij}^2}{2r_{sc}^2} \right) \quad \text{for } s_i=\alpha,\ s_j=\beta
+```
+
+where $r_{sc}$ controls the shorter interaction range. This promotes finer microphase separation inside A/B compartments, creating richer internal chromatin organization.
+
+At the **chromosome level**, a weak self-attraction is introduced to promote territorial segregation:
+
+```math
+E_{\text{chrom}} = \sum \delta_{\chi_i,\chi_j} V(r_{ij})
+```
+
+where $\chi_i$ denotes chromosome identity and $V(r)$ is a soft attractive potential acting only between beads of the same chromosome. In the default polynomial form,
+
+```math
+V(r) = dE \left(k_C r^4 - r^3 + r^2\right)
+```
+
+This stabilizes globular chromosome conformations and enhances intra-chromosomal clustering while suppressing inter-chromosomal mixing, supporting the emergence of chromosome territories.
+
+Beyond the Gaussian baseline, alternative kernels (e.g. Yukawa, power-law, and threshold interactions) modify the effective interaction range and decay profile, allowing systematic exploration of how the functional form of epigenetic attraction shapes chromatin organization.
+
+
+* The Yukawa form replaces the Gaussian decay with a screened Coulomb-like interaction
+
+$$V(r) \sim -\frac{e^{-r/\lambda}}{r}$$
+
+introducing a longer-ranged but exponentially screened attraction. This allows compartmental domains to communicate over larger genomic distances and can enhance domain coarsening.
 
-Only beads sharing the same compartment label interact. The interaction strength satisfies $|E_B| > |E_A|$, enforcing stronger attraction for inactive chromatin. The interaction range is
+* The power-law interaction
 
-$$r_0 = \frac{R_2 - R_1}{20}.$$
+$$V(r) \sim -\frac{1}{r^\alpha + \epsilon}$$
 
-Subcompartments are treated by assigning distinct energy levels.
+removes a characteristic length scale entirely, producing scale-free interactions. This is useful for probing whether compartmental organization can emerge from purely algebraic long-range correlations.
 
-### Nuclear Geometry and Lamina
+* For subcompartments, the theta (contact) model
 
-Chromatin is confined between two concentric spherical boundaries with radii $R_1$ (nucleolus) and $R_2$ (lamina). Soft boundary conditions are imposed by
+$$V(r) \sim -\Theta(r_c - r)$$
 
-$$E_{\text{bc}} =
-C\bigl[\max(0,r-R_2)^2 + \max(0,R_1-r)^2\bigr].$$
+reduces interactions to a hard cutoff contact rule, where only sufficiently close loci interact. This provides a minimal, binary version of epigenetic attraction, useful as a null model for testing the necessity of smooth potentials.
 
-#### B Compartment Lamina Attraction
+* For chromosome-level organization, the alternatives modify the confinement landscape: Gaussian attraction produces smooth globular collapse, while the saturating form
 
-Inactive compartments are attracted to the nuclear lamina via
+$$V(r) \sim -\frac{1}{1 + k_C r^2}$$
+
+limits the strength of long-range attraction, preventing over-collapse and allowing more flexible chromosome territories.
+
+
+### Nuclear Geometry and Lamina Interactions
+
+The lamina-related contribution introduces spatial confinement and peripheral anchoring of specific chromatin states, effectively coupling genome organization to nuclear geometry.
+
+The spherical container defines a soft nuclear boundary by penalizing excursions outside a radial shell. The energy is
+
+$$E_{\text{container}} = C \sum_i \left[ \max(0, r_i - R_2)^2 + \max(0, R_1 - r_i)^2 \right]$$
+
+where $r_i$ is the radial distance of bead $i$ from the nuclear center. This creates a confined annular domain between radii $R_1$ and $R_2$, representing the accessible nuclear volume and preventing unphysical collapse or escape.
+
+On top of this geometric confinement, the lamina interaction introduces state-dependent attraction of B-type chromatin to the nuclear periphery:
+
+$$E_{\text{lamina}} = - \sum_i B(s_i), V(r_i)$$
+
+where $s_i$ is the compartment state and $B(s_i)$ selects B-compartment beads. The function $V(r)$ encodes different radial potentials depending on the model choice:
+
+The sinusoidal shell (default) creates a sharp peripheral preference within the shell
+
+$$V(r) = \sin^8\left(\frac{\pi (r - R_1)}{R_2 - R_1}\right) - 1$$
+
+while Gaussian shells localize attraction around the two boundaries $R_1$ and $R_2$
+
+$$V(r) \sim -\left[e^{-(r-R_1)^2/(2\sigma^2)} + e^{-(r-R_2)^2/(2\sigma^2)}\right]$$
+
+The harmonic shell instead pulls B-chromatin toward the mid-shell radius $r_0=\frac{R_1+R_2}{2}$,
+
+$$V(r) \sim (r - r_0)^2$$
+
+and the logistic form creates smooth attractive walls near both boundaries using sigmoidal transitions.
+
+Together, these terms implement a minimal physical model of nuclear architecture where confinement defines the available volume, and lamina attraction biases epigenetically marked chromatin toward the nuclear periphery.
+
+
+### Nucleosome Scale Interpolation
+
+After coarse grained optimization, nucleosome positions are interpolated using a beads on the string zigzag model. Each nucleosome is represented as a helix with 1.65 DNA turns. The number of nucleosomes per bead is derived from normalized ATAC Seq signal, enforcing nucleosome rich regions in low accessibility chromatin.
+
+
+## Internal parameter definitions
+
+All geometric and interaction scales are now derived from a single microscopic length scale, the polymer bond length $b_0 =$ POL_HARMONIC_BOND_R0, ensuring consistent density and eliminating arbitrary global normalization factors.
+
+The nuclear confinement is modeled as a dense polymer globule with constant monomer density. In this regime, the outer nuclear radius follows the standard scaling law
 
 $$
-E_{Bl} = B \left( \sin^8 \frac{r-R_1}{R_2-R_1} - 1 \right) 
-\left[ \delta(s+1) + \delta(s+2) \right]
+R_2 = b_0  N^{1/3},
 $$
 
-This potential has minima near both inner and outer boundaries.
+which enforces $N / R_2^3 \approx \text{const}$ and guarantees physically consistent compaction as system size changes. The inner compartment (nucleolus-like region) is defined via a fixed volume fraction $f$ of the nuclear volume, leading to
 
-#### Chromosome Size Dependent Nucleolar Attraction
+$$
+R_1 = R_2  f^{1/3}.
+$$
 
-Smaller chromosomes experience a weak attraction toward the nucleolus
+This construction ensures that compartment organization scales in a volume-preserving manner rather than through independent geometric tuning.
+
+The compartment interaction length scale $r_c$ (previously $r_{\text{comp}}$) is no longer tied to geometric confinement. Instead, it represents the physical decay length of short-range attractive interactions between chromatin compartments and nuclear structures. It is defined directly from the polymer bond length as
 
 $$
-E_G = G s_c \left( \sin\frac{r-R_1}{\ell_G} - \left(\frac{r-R_1}{\ell_G}\right)^2 \right)
+r_c \sim \mathcal{O}(b_0),
 $$
 
-where $s_c \in [0,1]$ encodes chromosome size ranking.
+typically chosen as a small multiple of $b_0$ (e.g. $r_c \approx 1.5 b_0$), ensuring that interactions remain local and comparable to nearest-neighbor connectivity along the polymer backbone.
 
-### Optional Chromosome Globularization
+Loop constraints are encoded through bond-specific equilibrium distances $r_0^{(i)}$, which may either be globally fixed or informed by experimental loop length data $d_i$. This introduces controlled heterogeneity in loop architecture:
 
-When loop or compartment information is insufficient, an optional weak confining potential can be applied
+$$
+r_0^{(i)} \in (r_0^{\text{global}}, d_i),
+$$
 
-$$E_{\text{chrom}} =
-\sum E_n \left(k_C r^4 - b r^3 + c r^2\right).$$
+allowing loops to interpolate between polymer-native scales and experimentally inferred constraints.
 
-This term has no direct biological interpretation and is disabled by default.
+Each bead carries discrete state variables such as compartment identity $s_i$ and chromosome label $\chi_i$. These variables do not directly define geometry but modulate interactions through selection rules of the form
 
-### Nucleosome Scale Interpolation
+$$
+E_{ij} \propto \delta(s_i, s_j) \quad E_{ij} \propto \delta(\chi_i, \chi_j),
+$$
+
+ensuring that only compatible epigenetic or chromosomal states contribute to attractive or repulsive terms. Together, these elements couple polymer physics, nuclear confinement, and epigenetic structure into a unified multiscale chromatin framework.
 
-After coarse grained optimization, nucleosome positions are interpolated using a beads on the string zigzag model. Each nucleosome is represented as a helix with 1.65 DNA turns. The number of nucleosomes per bead is derived from normalized ATAC Seq signal, enforcing nucleosome rich regions in low accessibility chromatin.
 
 
 ## Input Data
@@ -438,7 +537,7 @@ Below is a categorized description of the simulation arguments and their default
 | SC_SCALE                     | float        | 1000.0      | kJ/mol/nm^2   | Scaling factor for the spherical container. |
 | CHB_USE_CHROMOSOMAL_BLOCKS   | bool         | False       | None          | Use chromosomal blocks. |
 | CHB_KC                       | float        | 0.3         | nm^(-4)       | Block copolymer width parameter. |
-| CHB_DE                       | float        | 1e-5        | kJ/mol        | Energy factor for chromosomal blocks. |
+| CHB_DE                       | float        | 1e-4        | kJ/mol        | Energy factor for chromosomal blocks. |
 | SCB_USE_SUBCOMPARTMENT_BLOCKS| bool         | False       | None          | Use subcompartment blocks. |
 | SCB_DISTANCE                 | float        | None        | nm            | Equilibrium distance for subcompartment blocks. |
 | SCB_EA1                      | float        | 1.0         | kJ/mol        | Energy strength for A1 compartment. |
@@ -465,6 +564,17 @@ Below is a categorized description of the simulation arguments and their default
 | POINTS_PER_NUC               | int          | 20          | None          | Number of points in a nucleosome helix. |
 | PHI_NORM                     | float        | pi/5        | None          | Zig-zag angle for nucleosome helix. |
 
+#### Functional Form Switches (Forcefield Modes) - Experimental
+| Argument Name      | Type | Default    | Options                                             | Description                                                                                                                                                            |
+| ------------------ | ---- | ---------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| EV_FORCE_TYPE      | str  | powerlaw   | powerlaw, soft_lj, gaussian_core                    | Controls excluded volume repulsion functional form (from hard-scale repulsion to soft-core melt-like behavior).                                                        |
+| COB_FORCE_TYPE     | str  | gaussian   | gaussian, yukawa, powerlaw, theta                   | Sets compartment A/B interaction kernel (short-range Gaussian segregation, screened Yukawa, scale-free powerlaw, or hard contact model).                               |
+| SCB_FORCE_TYPE     | str  | gaussian   | gaussian, yukawa, powerlaw, theta                   | Subcompartment interaction kernel with finer epigenetic state resolution (same functional family as compartments but higher specificity).                              |
+| BLAMINA_FORCE_TYPE | str  | sin        | sin, gaussian_shell, harmonic_shell, logistic_shell | Defines lamina interaction profile for B-type compartments (oscillatory shell, localized Gaussian layers, harmonic attraction, or smooth boundary walls).              |
+| LE_LOOP_FORCE_TYPE | str  | harmonic   | harmonic, fene_soft, gaussian_tether                | Loop constraint model (linear spring, bounded FENE-like spring, or smooth Gaussian tether).                                                                            |
+| CHB_FORCE_TYPE     | str  | polynomial | polynomial, gaussian, saturating                    | Chromosome-level self-attraction kernel controlling global compaction into chromosome territories.                                                                     |
+| CENTRAL_FORCE_TYPE | str  | harmonic   | harmonic, gaussian, logistic                        | Central nucleolar attraction model controlling radial bias of chromosomes toward nucleus center; encodes size-dependent positioning and nucleolar enrichment strength. |
+
 
 ## Output Directory
 The output directory is organized in the following folders,

{multimm-2.0.1 → multimm-2.0.2}/README.md

@@ -39,116 +39,215 @@ pip install MultiMM
 
 PyPI software: https://pypi.org/project/MultiMM/.
 
-## Mathematical Model
+### Model Overview
 
-We model chromatin as a coarse-grained polymer confined inside the nucleus. The system is described by an effective energy functional
+We model chromatin as a coarse-grained polymer where the total energy $E$ is decomposed into a set of physically motivated interaction terms capturing polymer mechanics, epigenetic organization, and structural constraints. Each term encodes a distinct biological mechanism, allowing the model to reproduce both local polymer behavior and large-scale genome organization such as compartments and loops.
 
-$$E = E_{\text{pol}} + E_{\text{lamina}} + E_{\text{loop}} + E_{\text{block}}$$
+At a generic level, the system is governed by a total energy of the form
+
+$$E = E_{\text{backbone}} + E_{\text{block-copolymer}} + E_{\text{loops}} + E_{\text{excluded}} + E_{\text{confinement}} + E_{\text{chromosomal}}$$
+
+where each contribution controls a different aspect of chromatin folding:
+
+* $E_{\text{backbone}}$: enforces polymer connectivity and stiffness through bonded and angular interactions, ensuring a realistic chain-like structure
+* $E_{\text{block-copolymer}}$: captures compartment and subcompartment segregation via state-dependent attractive interactions between beads
+* $E_{\text{loops}}$: introduces long-range constraints between genomic loci, mimicking loop extrusion or experimentally observed contacts
+* $E_{\text{excluded}}$: accounts for steric repulsion, preventing unphysical overlaps between beads
+* $E_{\text{confinement}}$: imposes nuclear geometry through spherical confinement and lamina interactions
+* $E_{\text{chromosomal}}$: promotes large-scale organization such as chromosome territories and global compaction
+
+Together, these terms define a minimal yet flexible energy landscape where local polymer physics and global genomic features emerge in a unified framework.
 
-Each bead represents a chromatin segment of fixed genomic length. The equilibrium structure is obtained by energy minimization or short relaxation dynamics.
 
 ### Polymer Backbone
 
-Polymer connectivity, stiffness, and excluded volume are enforced by the following potential energy terms:
+The backbone contribution $E_{\text{backbone}}$ encodes the connectivity and local rigidity of the polymer chain. It is composed of two standard terms: harmonic bonds enforcing nearest-neighbor distances, and harmonic angle potentials controlling chain stiffness.
 
-$$
-E_{\text{pol}} = E_{\text{bond}} + E_{\text{bend}} + E_{\text{rep}}
-$$
+The bond (connectivity) term is given by
 
-where
+$$E_{\text{bond}} = \sum_{i} \frac{k_b}{2} \left( r_{i,i+1} - r_0 \right)^2$$
 
-$$
-E_{\text{bond}} = \sum_i k_b (r_{i,i+1} - \ell)^2
-$$
+where $r_{i,i+1} = |\mathbf{r}_{i+1} - \mathbf{r}_i|$ is the distance between consecutive beads, $r_0$ is the equilibrium bond length, and $k_b$ is the bond stiffness. This term ensures that the polymer remains connected and fluctuates around a preferred contour length.
 
-is the harmonic bond potential that keeps consecutive beads at distance ≈ ℓ,
+The stiffness (bending) term is defined as
 
-$$
-E_{\text{bend}} = \sum_i k_s (\theta_i - \pi)^2
-$$
+$$E_{\text{angle}} = \sum_{i} \frac{k_\theta}{2} \left( \theta_i - \theta_0 \right)^2$$
 
-is the bending energy that controls chain stiffness (θᵢ is the angle between bonds i−1→i and i→i+1),
+where $\theta_i$ is the angle formed by three consecutive beads $(i, i+1, i+2)$, $\theta_0$ is the preferred angle, and $k_\theta$ controls the bending rigidity. This term penalizes sharp bends and sets the persistence length of the polymer.
+
+Altogether, the backbone energy reads
+
+$$E_{\text{backbone}} = E_{\text{bond}} + E_{\text{angle}}$$
+
+which corresponds to a discretized worm-like chain model with harmonic stretching and bending fluctuations.
 
-and
 
-$$
-E_{\text{rep}} = \sum_{i < j} \epsilon \left( \frac{\sigma}{r_{ij}} \right)^\alpha
-$$
 
-is the purely repulsive long-range interaction that enforces excluded volume.
+### Loop Interactions
 
-The first term fixes bond lengths, the second controls bending rigidity, and the third prevents unphysical monomer overlap.
+The loop contribution $E_{\text{loops}}$ introduces long-range interactions between pairs of beads $(m,n)$, representing loop extrusion or experimentally detected contacts. Each loop acts as an effective tether that constrains the spatial distance between distant genomic loci.
 
+The default model uses a harmonic potential
 
-### Looping Interactions
+$$E_{\text{loops}}^{\text{harmonic}} = \sum_{(m,n)} \frac{k}{2} \left( r_{mn} - r_0 \right)^2$$
 
-Chromatin loops detected experimentally are modeled as harmonic restraints
+where $r_{mn} = |\mathbf{r}_n - \mathbf{r}_m|$, $r_0$ is the preferred loop length, and $k$ is the stiffness. This formulation strongly penalizes deviations from $r_0$, effectively enforcing fixed-distance loops and providing a simple baseline model.
 
-$$E_{\text{loop}} =
-k_\ell \sum_{(i,j)\in \text{loops}} (r_{ij} - d_{ij})^2 .$$
+To allow more physical flexibility, two alternative bounded interactions are introduced. The first is a soft FENE-like potential
 
-The equilibrium loop length depends on interaction strength $S_{ij}$ as
+$$E_{\text{loops}}^{\text{fene}} = \sum_{(m,n)} \frac{k (r_{mn} - r_0)^2}{1 + \alpha (r_{mn} - r_0)^2}$$
 
-$$d_{ij} \propto S_{ij}^{-2/3},
-\qquad
-d_{ij} \in [0.1, 0.2] .$$
+which behaves harmonically near equilibrium but saturates at large extensions. This avoids unphysical divergence and models loops as extensible but finite-strength tethers.
+
+The second alternative is a Gaussian tether
+
+$$E_{\text{loops}}^{\text{gaussian}} = \sum_{(m,n)} k \left( 1 - e^{-(r_{mn} - r_0)^2 / \sigma^2} \right)$$
+
+which defines a fully smooth, bounded potential well. Close to $r_0$ it is approximately harmonic, while at large distances it saturates to a constant energy, effectively allowing loop breaking without instability.
 
-For single cell data all loops have the same equilibrium distance.
 
 ### Block Copolymer Compartmentalization
 
-Long range compartmentalization is described by a Gaussian attraction between beads of the same compartment
+The block-copolymer contribution $E_{\text{block}}$ encodes epigenetic segregation via state-dependent pairwise interactions. Each bead carries a label $s_i$ representing its compartment or subcompartment identity. These labels selectively activate interactions, driving chromatin phase separation into distinct domains.
 
-$$
-E_{\text{block}} = \sum_c E_c \exp\left(-\frac{r^2}{2 r_0^2}\right)
-$$
+**Compartment level (A/B):** Interactions follow a Gaussian attractive potential:
+
+```math
+E_{\text{comp}} = -\sum \epsilon(s_i,s_j) \exp\left( -\frac{r_{ij}^2}{2r_c^2} \right)
+```
+
+where $r_{ij}$ is the distance between beads and $r_c$ is the interaction range. The coupling $\epsilon(s_i,s_j)$ is attractive for like compartments (A–A, B–B) and weak or repulsive otherwise, reproducing large-scale A/B segregation seen in Hi-C data.
+
+**Subcompartment level:** The model is extended to multiple epigenetic states $\alpha,\beta$:
+
+```math
+E_{\text{sub}} = -\sum \epsilon_{\alpha\beta} \exp\left( -\frac{r_{ij}^2}{2r_{sc}^2} \right) \quad \text{for } s_i=\alpha,\ s_j=\beta
+```
+
+where $r_{sc}$ controls the shorter interaction range. This promotes finer microphase separation inside A/B compartments, creating richer internal chromatin organization.
+
+At the **chromosome level**, a weak self-attraction is introduced to promote territorial segregation:
+
+```math
+E_{\text{chrom}} = \sum \delta_{\chi_i,\chi_j} V(r_{ij})
+```
+
+where $\chi_i$ denotes chromosome identity and $V(r)$ is a soft attractive potential acting only between beads of the same chromosome. In the default polynomial form,
+
+```math
+V(r) = dE \left(k_C r^4 - r^3 + r^2\right)
+```
+
+This stabilizes globular chromosome conformations and enhances intra-chromosomal clustering while suppressing inter-chromosomal mixing, supporting the emergence of chromosome territories.
+
+Beyond the Gaussian baseline, alternative kernels (e.g. Yukawa, power-law, and threshold interactions) modify the effective interaction range and decay profile, allowing systematic exploration of how the functional form of epigenetic attraction shapes chromatin organization.
+
+
+* The Yukawa form replaces the Gaussian decay with a screened Coulomb-like interaction
+
+$$V(r) \sim -\frac{e^{-r/\lambda}}{r}$$
+
+introducing a longer-ranged but exponentially screened attraction. This allows compartmental domains to communicate over larger genomic distances and can enhance domain coarsening.
 
-Only beads sharing the same compartment label interact. The interaction strength satisfies $|E_B| > |E_A|$, enforcing stronger attraction for inactive chromatin. The interaction range is
+* The power-law interaction
 
-$$r_0 = \frac{R_2 - R_1}{20}.$$
+$$V(r) \sim -\frac{1}{r^\alpha + \epsilon}$$
 
-Subcompartments are treated by assigning distinct energy levels.
+removes a characteristic length scale entirely, producing scale-free interactions. This is useful for probing whether compartmental organization can emerge from purely algebraic long-range correlations.
 
-### Nuclear Geometry and Lamina
+* For subcompartments, the theta (contact) model
 
-Chromatin is confined between two concentric spherical boundaries with radii $R_1$ (nucleolus) and $R_2$ (lamina). Soft boundary conditions are imposed by
+$$V(r) \sim -\Theta(r_c - r)$$
 
-$$E_{\text{bc}} =
-C\bigl[\max(0,r-R_2)^2 + \max(0,R_1-r)^2\bigr].$$
+reduces interactions to a hard cutoff contact rule, where only sufficiently close loci interact. This provides a minimal, binary version of epigenetic attraction, useful as a null model for testing the necessity of smooth potentials.
 
-#### B Compartment Lamina Attraction
+* For chromosome-level organization, the alternatives modify the confinement landscape: Gaussian attraction produces smooth globular collapse, while the saturating form
 
-Inactive compartments are attracted to the nuclear lamina via
+$$V(r) \sim -\frac{1}{1 + k_C r^2}$$
+
+limits the strength of long-range attraction, preventing over-collapse and allowing more flexible chromosome territories.
+
+
+### Nuclear Geometry and Lamina Interactions
+
+The lamina-related contribution introduces spatial confinement and peripheral anchoring of specific chromatin states, effectively coupling genome organization to nuclear geometry.
+
+The spherical container defines a soft nuclear boundary by penalizing excursions outside a radial shell. The energy is
+
+$$E_{\text{container}} = C \sum_i \left[ \max(0, r_i - R_2)^2 + \max(0, R_1 - r_i)^2 \right]$$
+
+where $r_i$ is the radial distance of bead $i$ from the nuclear center. This creates a confined annular domain between radii $R_1$ and $R_2$, representing the accessible nuclear volume and preventing unphysical collapse or escape.
+
+On top of this geometric confinement, the lamina interaction introduces state-dependent attraction of B-type chromatin to the nuclear periphery:
+
+$$E_{\text{lamina}} = - \sum_i B(s_i), V(r_i)$$
+
+where $s_i$ is the compartment state and $B(s_i)$ selects B-compartment beads. The function $V(r)$ encodes different radial potentials depending on the model choice:
+
+The sinusoidal shell (default) creates a sharp peripheral preference within the shell
+
+$$V(r) = \sin^8\left(\frac{\pi (r - R_1)}{R_2 - R_1}\right) - 1$$
+
+while Gaussian shells localize attraction around the two boundaries $R_1$ and $R_2$
+
+$$V(r) \sim -\left[e^{-(r-R_1)^2/(2\sigma^2)} + e^{-(r-R_2)^2/(2\sigma^2)}\right]$$
+
+The harmonic shell instead pulls B-chromatin toward the mid-shell radius $r_0=\frac{R_1+R_2}{2}$,
+
+$$V(r) \sim (r - r_0)^2$$
+
+and the logistic form creates smooth attractive walls near both boundaries using sigmoidal transitions.
+
+Together, these terms implement a minimal physical model of nuclear architecture where confinement defines the available volume, and lamina attraction biases epigenetically marked chromatin toward the nuclear periphery.
+
+
+### Nucleosome Scale Interpolation
+
+After coarse grained optimization, nucleosome positions are interpolated using a beads on the string zigzag model. Each nucleosome is represented as a helix with 1.65 DNA turns. The number of nucleosomes per bead is derived from normalized ATAC Seq signal, enforcing nucleosome rich regions in low accessibility chromatin.
+
+
+## Internal parameter definitions
+
+All geometric and interaction scales are now derived from a single microscopic length scale, the polymer bond length $b_0 =$ POL_HARMONIC_BOND_R0, ensuring consistent density and eliminating arbitrary global normalization factors.
+
+The nuclear confinement is modeled as a dense polymer globule with constant monomer density. In this regime, the outer nuclear radius follows the standard scaling law
 
 $$
-E_{Bl} = B \left( \sin^8 \frac{r-R_1}{R_2-R_1} - 1 \right) 
-\left[ \delta(s+1) + \delta(s+2) \right]
+R_2 = b_0  N^{1/3},
 $$
 
-This potential has minima near both inner and outer boundaries.
+which enforces $N / R_2^3 \approx \text{const}$ and guarantees physically consistent compaction as system size changes. The inner compartment (nucleolus-like region) is defined via a fixed volume fraction $f$ of the nuclear volume, leading to
 
-#### Chromosome Size Dependent Nucleolar Attraction
+$$
+R_1 = R_2  f^{1/3}.
+$$
 
-Smaller chromosomes experience a weak attraction toward the nucleolus
+This construction ensures that compartment organization scales in a volume-preserving manner rather than through independent geometric tuning.
+
+The compartment interaction length scale $r_c$ (previously $r_{\text{comp}}$) is no longer tied to geometric confinement. Instead, it represents the physical decay length of short-range attractive interactions between chromatin compartments and nuclear structures. It is defined directly from the polymer bond length as
 
 $$
-E_G = G s_c \left( \sin\frac{r-R_1}{\ell_G} - \left(\frac{r-R_1}{\ell_G}\right)^2 \right)
+r_c \sim \mathcal{O}(b_0),
 $$
 
-where $s_c \in [0,1]$ encodes chromosome size ranking.
+typically chosen as a small multiple of $b_0$ (e.g. $r_c \approx 1.5 b_0$), ensuring that interactions remain local and comparable to nearest-neighbor connectivity along the polymer backbone.
 
-### Optional Chromosome Globularization
+Loop constraints are encoded through bond-specific equilibrium distances $r_0^{(i)}$, which may either be globally fixed or informed by experimental loop length data $d_i$. This introduces controlled heterogeneity in loop architecture:
 
-When loop or compartment information is insufficient, an optional weak confining potential can be applied
+$$
+r_0^{(i)} \in (r_0^{\text{global}}, d_i),
+$$
 
-$$E_{\text{chrom}} =
-\sum E_n \left(k_C r^4 - b r^3 + c r^2\right).$$
+allowing loops to interpolate between polymer-native scales and experimentally inferred constraints.
 
-This term has no direct biological interpretation and is disabled by default.
+Each bead carries discrete state variables such as compartment identity $s_i$ and chromosome label $\chi_i$. These variables do not directly define geometry but modulate interactions through selection rules of the form
 
-### Nucleosome Scale Interpolation
+$$
+E_{ij} \propto \delta(s_i, s_j) \quad E_{ij} \propto \delta(\chi_i, \chi_j),
+$$
+
+ensuring that only compatible epigenetic or chromosomal states contribute to attractive or repulsive terms. Together, these elements couple polymer physics, nuclear confinement, and epigenetic structure into a unified multiscale chromatin framework.
 
-After coarse grained optimization, nucleosome positions are interpolated using a beads on the string zigzag model. Each nucleosome is represented as a helix with 1.65 DNA turns. The number of nucleosomes per bead is derived from normalized ATAC Seq signal, enforcing nucleosome rich regions in low accessibility chromatin.
 
 
 ## Input Data
@@ -402,7 +501,7 @@ Below is a categorized description of the simulation arguments and their default
 | SC_SCALE                     | float        | 1000.0      | kJ/mol/nm^2   | Scaling factor for the spherical container. |
 | CHB_USE_CHROMOSOMAL_BLOCKS   | bool         | False       | None          | Use chromosomal blocks. |
 | CHB_KC                       | float        | 0.3         | nm^(-4)       | Block copolymer width parameter. |
-| CHB_DE                       | float        | 1e-5        | kJ/mol        | Energy factor for chromosomal blocks. |
+| CHB_DE                       | float        | 1e-4        | kJ/mol        | Energy factor for chromosomal blocks. |
 | SCB_USE_SUBCOMPARTMENT_BLOCKS| bool         | False       | None          | Use subcompartment blocks. |
 | SCB_DISTANCE                 | float        | None        | nm            | Equilibrium distance for subcompartment blocks. |
 | SCB_EA1                      | float        | 1.0         | kJ/mol        | Energy strength for A1 compartment. |
@@ -429,6 +528,17 @@ Below is a categorized description of the simulation arguments and their default
 | POINTS_PER_NUC               | int          | 20          | None          | Number of points in a nucleosome helix. |
 | PHI_NORM                     | float        | pi/5        | None          | Zig-zag angle for nucleosome helix. |
 
+#### Functional Form Switches (Forcefield Modes) - Experimental
+| Argument Name      | Type | Default    | Options                                             | Description                                                                                                                                                            |
+| ------------------ | ---- | ---------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| EV_FORCE_TYPE      | str  | powerlaw   | powerlaw, soft_lj, gaussian_core                    | Controls excluded volume repulsion functional form (from hard-scale repulsion to soft-core melt-like behavior).                                                        |
+| COB_FORCE_TYPE     | str  | gaussian   | gaussian, yukawa, powerlaw, theta                   | Sets compartment A/B interaction kernel (short-range Gaussian segregation, screened Yukawa, scale-free powerlaw, or hard contact model).                               |
+| SCB_FORCE_TYPE     | str  | gaussian   | gaussian, yukawa, powerlaw, theta                   | Subcompartment interaction kernel with finer epigenetic state resolution (same functional family as compartments but higher specificity).                              |
+| BLAMINA_FORCE_TYPE | str  | sin        | sin, gaussian_shell, harmonic_shell, logistic_shell | Defines lamina interaction profile for B-type compartments (oscillatory shell, localized Gaussian layers, harmonic attraction, or smooth boundary walls).              |
+| LE_LOOP_FORCE_TYPE | str  | harmonic   | harmonic, fene_soft, gaussian_tether                | Loop constraint model (linear spring, bounded FENE-like spring, or smooth Gaussian tether).                                                                            |
+| CHB_FORCE_TYPE     | str  | polynomial | polynomial, gaussian, saturating                    | Chromosome-level self-attraction kernel controlling global compaction into chromosome territories.                                                                     |
+| CENTRAL_FORCE_TYPE | str  | harmonic   | harmonic, gaussian, logistic                        | Central nucleolar attraction model controlling radial bias of chromosomes toward nucleus center; encodes size-dependent positioning and nucleolar enrichment strength. |
+
 
 ## Output Directory
 The output directory is organized in the following folders,

{multimm-2.0.1 → multimm-2.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "MultiMM"
-version = "2.0.1"
+version = "2.0.2"
 description = "A tool for chromatin modeling from nucleosomes to chromosomal territories."
 readme = "README.md"
 authors = [