.. _truncated-octahedron:

truncated_octahedron
=======================================================

Truncated Octahedron.

=========== ============================================================ ============ =============
Parameter   Description                                                  Units        Default value
=========== ============================================================ ============ =============
scale       Scale factor or Volume fraction                              None                     1
background  Source background                                            |cm^-1|              0.001
sld         Octahedron scattering length density                         |1e-6Ang^-2|           126
sld_solvent Solvent scattering length density                            |1e-6Ang^-2|           9.4
length_a    half height along a axis                                     |Ang|                  400
b2a_ratio   Ratio b/a                                                    None                     1
c2a_ratio   Ratio c/a                                                    None                     1
truncation  truncation ratio, 0 for octahedron and 0.5 for cuboctahedron None                     0
theta       c axis to beam angle                                         degree                   0
phi         rotation about beam                                          degree                   0
psi         rotation about c axis                                        degree                   0
=========== ============================================================ ============ =============

The returned value is scaled to units of |cm^-1| |sr^-1|, absolute scale.


This model provides the form factor P(q) for a general octahedron.
It can be a regular octahedron shape with all edges of the same length.
Or a general shape with different elongations along the three perpendicular two-fold axes.
It includes the possibility to add an adjustable square truncation at each of the six vertices.
This model includes the general cuboctahedron shape for the maximum value of truncation.
The form factor expression is obtained by analytical integration over the volume of the shape.
This model is constructed in a similar way as the rectangular prism model.
It contains both the form factor for a reference orientation and the 1D form factor after orientation average (Gauss-Legendre).

**Definition**

The general octahedron is defined by its dimensions along its three perpendicular two-fold axes along x, y and z directions.
*length_a*, *length_b* and *length_c* are the distances from the center of the general octahedron to its 6 vertices.

Coordinates of the six vertices are:
    (*length_a*, 0, 0),
    (*-length_a*, 0, 0),
    (0, *length_b*, 0),
    (0, *-length_b*, 0),
    (0, 0, *length_c*),
    (0, 0, *-length_c*)

Truncation adds a square facet for each vertex that is perpendicular to a 2-fold axis.
The resulting shape consists of six squares and eight hexagons, which may be irregular depending on the three dimensions.
The user-defined parameter `t` is the truncation ratio and is defined as: 0 ≤ t ≤ 0.5, 0 corresponding to no truncation
(full octahedron) and 0.5 corresponding to the maximum truncation (cuboctahedron).
For the following formulas, we will use the notation *t_inv = 1 - t*.
Indeed, a square facet crosses the x, y, z directions at distances equal to *t_inv length_a*, *t_inv length_b* and *t_inv length_c*.

A regular octahedron corresponds to:

.. math::

    length_a = length_b = length_c, \quad t = 0

A regular cuboctahedron shape with 6 squares and 8 triangles corresponds to:

.. math:: 

    length_a = length_b = length_c, \quad t  = \frac{1}{2}

The model contains 4 parameters: *length_a*, the two ratios *b2a_ratio* and *c2a_ratio* and *t*:

.. math::

    b2a_{\text{ratio}} = \frac{length_b}{length_a}, \quad
    c2a_{\text{ratio}} = \frac{length_c}{length_a}, \quad

    0 ≤ t ≤ \frac{1}{2}



For a regular shape:

.. math::

    b2a_{\text{ratio}} = c2a_{\text{ratio}} = 1

Volume of the general shape including truncation is given by:

.. math::

    V = \frac{4}{3}\, length_{\text{a}}^{3}\, b2a_{\text{ratio}}\, c2a_{\text{ratio}}\,\bigl(1 - 3t^{3}\bigr)

The general octahedron is made of eight triangular faces. The three edge lengths
are:

.. math::

    A_{\text{edge}}^{2} = length_{\text{a}}^{2} + length_{\text{b}}^{2},\qquad
    B_{\text{edge}}^{2} = length_{\text{a}}^{2} + length_{\text{c}}^{2},\qquad
    C_{\text{edge}}^{2} = length_{\text{b}}^{2} + length_{\text{c}}^{2}

For a regular shape (no elongation):

.. math::

    b2a_{\text{ratio}} = c2a_{\text{ratio}} = 1,\qquad
    A_{\text{edge}} = B_{\text{edge}} = C_{\text{edge}} = length_{\text{a}} \sqrt{2},\qquad
    length_{\text{a}} = length_{\text{b}} = length_{\text{c}} = A_{\text{edge}} / \sqrt{2}

.. math::

    V = \frac{4}{3} \, length_{\text{a}}^{3} \, \bigl(1 - 3 t^3 \bigr)

The reference orientation of the shape is: a along x, b along y and c along z.
Amplitude of the form factor AP for the reference orientation of the shape reads 

.. math::

    AP(q,\theta,\phi) = \frac{6}{1 - 3t^3}\,(AA + BB + CC)

.. math::

    AA = \frac{1}{2\,(q_y^2 - q_z^2)\,(q_y^2 - q_x^2)}\Big[(q_y - q_x)\sin\big(q_y t - q_x t_{\text{inv}}\big)
    + (q_y + q_x)\sin\big(q_y t + q_x t_{\text{inv}}\big)\Big]
    + \frac{1}{2\,(q_z^2 - q_x^2)\,(q_z^2 - q_y^2)}\Big[(q_z - q_x)\sin\big(q_z t - q_x t_{\text{inv}}\big)
    + (q_z + q_x)\sin\big(q_z t + q_x t_{\text{inv}}\big)\Big]

.. math::

    BB = \frac{1}{2\,(q_z^2 - q_x^2)\,(q_z^2 - q_y^2)}\Big[(q_z - q_y)\sin\big(q_z t - q_y t_{\text{inv}}\big)
    + (q_z + q_y)\sin\big(q_z t + q_y t_{\text{inv}}\big)\Big]
    + \frac{1}{2\,(q_x^2 - q_y^2)\,(q_x^2 - q_z^2)}\Big[(q_x - q_y)\sin\big(q_x t - q_y t_{\text{inv}}\big)
    + (q_x + q_y)\sin\big(q_x t + q_y t_{\text{inv}}\big)\Big]

.. math::

    CC = \frac{1}{2\,(q_x^2 - q_y^2)\,(q_x^2 - q_z^2)}\Big[(q_x - q_z)\sin\big(q_x t - q_z t_{\text{inv}}\big)
    + (q_x + q_z)\sin\big(q_x t + q_z t_{\text{inv}}\big)\Big]
    + \frac{1}{2\,(q_y^2 - q_z^2)\,(q_y^2 - q_x^2)}\Big[(q_y - q_z)\sin\big(q_y t - q_z t_{\text{inv}}\big)
    + (q_y + q_z)\sin\big(q_y t + q_z t_{\text{inv}}\big)\Big]

Capital Qx Qy Qz are the three components in [A-1] of the scattering vector.
qx qy qz are rescaled components (no unit) for computing AA, BB and CC terms.

.. math::

    Q_x = q\,\sin\theta\,\cos\phi, \qquad
    Q_y = q\,\sin\theta\,\sin\phi, \qquad
    Q_z = q\,\cos\theta

.. math::

    q_x = Q_x \, length_{\text{a}},\qquad
    q_y = Q_y \, length_{\text{b}},\qquad
    q_z = Q_z \, length_{\text{c}}


θ is the angle between the scattering vector and the z axis.
ϕ is the rotation angle in the xy plane.

The octahedron is in its reference orientation, with the c-axis aligned along z and the a-axis aligned along x.

The 1D form factor P(q) corresponds to the orientation average with all the possible orientations having the same probability.
Instead of rotating the shape through all the possible orientations in the integral,
it is equivalent to integrate the 3D scattering vector over a sphere of radius q with the shape in its reference orientation.

.. math::

    P(q) =  \frac{2}{\pi} \int_0^{\frac{\pi}{2}} \,
    \int_0^{\frac{\pi}{2}} A_P^2(q) \, \sin\theta \, d\theta \, d\phi

And the 1D scattering intensity is calculated as

.. math::

    I(q) = \text{scale} \times V \times (\rho_\text{p} -
    \rho_\text{solvent})^2 \times P(q)

where V is the volume of the truncated octahedron, ρ
is the scattering length inside the volume, ρ *solvent*
is the scattering length of the solvent, and (if the data are in absolute
units) *scale* represents the volume fraction (which is unitless).


.. figure:: img/octa-truncated.png

    Truncated octahedron shape for different truncation.

.. figure:: img/octahedrons_intensity_plot.png

    Scattering intensity of a cuboctahedron (t=0.5) and a regular octahedron (t=0) of a = 300 Angstroms.

**Validation**

Validation of the code is made using numerical checks.
Comparisons with Debye formula calculations were made using DebyeCalculator library (https://github.com/FrederikLizakJohansen/DebyeCalculator).
Good agreement was found at q < 0.1 1/Angstrom.


.. figure:: img/truncated_octahedron_autogenfig.png

    1D and 2D plots corresponding to the default parameters of the model.


**Source**

:download:`truncated_octahedron.py <src/truncated_octahedron.py>`
$\ \star\ $ :download:`truncated_octahedron.c <src/truncated_octahedron.c>`
$\ \star\ $ :download:`gauss20.c <src/gauss20.c>`

**References**

1. Wei-Ren Chen et al. "Scattering functions of Platonic solids".
   In: Journal of Applied Crystallography - J APPL CRYST 44 (June 2011).
   DOI: 10.1107/S0021889811011691

2. Croset, Bernard, "Form factor of any polyhedron: a general compact
   formula and its singularities" In: J. Appl. Cryst. (2017). 50, 1245–1255
   https://doi.org/10.1107/S1600576717010147

3. Wuttke, J. Numerically stable form factor of any polygon and polyhedron
   J Appl Cryst 54, 580-587 (2021)
   https://doi.org/10.1107/S160057672100171

**Authorship and Verification**

* **Authors:** Marianne Imperor-Clerc (marianne.imperor@cnrs.fr)
             Helen Ibrahim (helenibrahim1@outlook.com)
             Sara Mokhtari (smokhtari@insa-toulouse.fr)

* **Last Modified by:** MIC **Date:** 11 December 2025

* **Last Reviewed by:** SM **Date:** 10 December 2025


