model.deeplearn.initializer package

Submodules

model.deeplearn.initializer.fibonacci_shell_initializer module

class model.deeplearn.initializer.fibonacci_shell_initializer.FibonacciShellInitializer(shells=3, radii=[0, 0.5, 1.0], points_per_shell=[1, 7, 13], deformable=False, **kwargs)

Bases: Initializer

Author:

Alberto M. Esmoris Pena

A Fibonacci shell initializer initializes the structure space matrix representing the support points of a kernel, i.e., its structure space. It will generate a structure space matrix \(\pmb{Q} \in \mathbb{R}^{m_q \times 3}\). This matrix represents \(m_q\) points in a 3D Euclidean space inside a ball of radius \(r\) such that the distances between points are maximized and the points are distributed along spherical shells inside the big sphere.

The initialization is governed by the number of shells \(S \in \mathbb{Z}_{>0}\), the radii for the shells \(\pmb{r} \in \mathbb{R}^{S}_{\geq 0}\), and the number of points per shell \(\pmb{n} \in \mathbb{Z}^{S}_{>0}\).

Now, let \(\pmb{q}_{k*}^{(s)} \in \mathbb{R}^{3}\) be the \(k\)-th point which is assumed to belong to the \(1 \leq s \leq S\) spherical shell. Its coordinates will be given by:

\[\begin{split}\pmb{q}_{k*}^{(s)} = \left[\begin{array}{c} \cos(\alpha_k) \sin(\beta_k) \\ \sin(\alpha_k) \sin(\beta_k) \\ \cos(\beta_k) \end{array}\right] \;,\quad \alpha_k = \dfrac{4 \pi k}{1 + \sqrt{5}} \;,\quad \beta_k = \arccos\left(1 - \dfrac{2k}{n_s}\right)\end{split}\]

The above procedure exploits the concept of Fibonacci grid to provide an initial point distribution that is latter refined through energy minimization. More concretely, each point is considered to exert a repulsive force on each other leading to the energy function

\[E(\pmb{Q}) = \sum_{k=1}^{m_q}\sum_{l \neq k}{ \lVert\pmb{q}_{l*}-\pmb{q}_{k*}\rVert^{-1} } .\]

The initialization ends with the conjugate gradient method used to solve the following minimization problem

\[\begin{split}\min_{\pmb{Q} \in \mathbb{R}^{m_q \times 3}} \quad & E(\pmb{Q}) \\ \text{s.t.} \quad \;\; & \left\lVert \pmb{q}_{k*}^{(s)} \right\rVert = r_s\end{split}\]

Variables:

• shells (int) – The number of spherical shells.

• radii (np.ndarray or list of int) – The radius for each shell.

• points_per_shell (np.ndarray or list of int) – The number of points for each shell.

• deformable (bool) – Whether to allow the neural network to update the structure space of the kernel (i.e., the coordinates of the kernel points) or not.

__init__(shells=3, radii=[0, 0.5, 1.0], points_per_shell=[1, 7, 13], deformable=False, **kwargs)

Initialize the member attributes of the initializer.

__call__(shape=None, dtype='float32')

The initializer’s computation logic.

Parameters:

• shape – The shape of the variable to initializer.

• dtype – The type of value.

Returns:

The initialized variable.

static fibonacci_initialization(points, radius)

Compute the Fibonacci grid-based initialization.

Parameters:

• points – The number of points in the shell being initialized.

• radius – The radius of the shell being initialized.

Returns:

The structure space of the initialized shell.

Return type:

np.ndarray

energy_f(x)

Compute the energy model \(E\).

Parameters:

x (np.ndarray) – The vectorized structure space matrix.

Returns:

The energy model.

static energy_df(x)

Compute the gradient of the energy model \(\nabla E\).

Parameters:

x (np.ndarray) – The vectorized structure space matrix.

Returns:

The gradient of the energy model.

energy_constraint(x)

Force the constraint that each point belongs to its spherical shell.

Parameters:

x (np.ndarray) – The vectorized structure space matrix.

Returns:

The points of the energy model constrained to be at their corresponding spherical shells.

Return type:

np.ndarray

model.deeplearn.initializer.initializer module

class model.deeplearn.initializer.initializer.Initializer(**kwargs)

Bases: Initializer

Author:

Alberto M. Esmoris Pena

An initializer can be seen as a routine that initializes the internal state of a layer from a neural network. Typically, initializers receive the shape of the expected output tensor as a parameter.

The Initializer class provides an interface that must be realized by any class that must assume the role of a regularizer inside a neural network.

__init__(**kwargs)

Initialize the member attributes of the initializer.

Parameters:

kwargs – The key-word specification to parametrize the initializer.

__call__(shape, dtype=None)

The initializer’s computation logic.

Parameters:

• shape – The shape of the variable to initializer.

• dtype – The type of value.

Returns:

The initialized variable.

get_config()

The dictionary specifying how to serialize the initializer.

Returns:

The dictionary with the necessary data to serialize the initializer.

Return type:

dict

model.deeplearn.initializer.kernel_point_ball_initializer module

class model.deeplearn.initializer.kernel_point_ball_initializer.KernelPointBallInitializer(target_radius=1.0, num_points=19, deformable=False, **kwargs)

Bases: Initializer

Author:

Alberto M. Esmoris Pena

A kernel point ball initializer initializes the structure space matrix representing the support points of a kernel. It will generate a structure space matrix \(\pmb{Q} \in \mathbb{R}^{m_q \times 3}\). This matrix represents \(m_q\) points in a 3D Euclidean space inside a ball of radius \(r\) such that the distances between points is maximized.

The points are distributed inside a ball solving an energy minimization problem for an energy model:

\[E = \sum_{i=1}^{m_q}{\biggl( \lVert\pmb{q}_{i*}\rVert^2 + \sum_{j=1,j\neq{i}}^{m_q}{ \lVert{ \pmb{q}_{i*} - \pmb{q}_{j*} }\rVert^{-1} } \biggr)}\]

Note for a 3D space, the gradient of this energy model is defined as:

\[\begin{split}\nabla_{\pmb{Q}}E = \left[\begin{array}{ccc} \dfrac{\partial E}{\partial q_{1x}} & \dfrac{\partial E}{\partial q_{1y}} & \dfrac{\partial E}{\partial q_{1z}} \\ \vdots & \vdots & \vdots \\ \dfrac{\partial E}{\partial q_{m_q x}} & \dfrac{\partial E}{\partial q_{m_q y}} & \dfrac{\partial E}{\partial q_{m_q z}} & \end{array}\right]\end{split}\]

For then, any partial derivative in the gradient can be computed as:

\[\dfrac{\partial E}{\partial q_{ik}} = 2 \left[ q_{ik} + \sum_{j=1,j\neq{i}}^{m_q}{\dfrac{ q_{jk} - q_{ik} }{ \lVert{\pmb{q}_{i*} - \pmb{q}_{j*}}\rVert^3 }} \right]\]

Intuitively, this model can be thought as if every point caused a repulsive force on the others while the zero point imposes an attractive force on all the points. The minimization of the energy through a conjugate gradient method leads to the desired disposition of the points in \(\pmb{Q}\).

Variables:

• target_radius (float) – The radius of the ball to which the kernel points belong (\(r\)).

• num_points (int) – The number of points representing the kernel \(m_q\).

• deformable (bool) – Whether to allow the neural network to update the structure space of the kernel (i.e., the coordinates of the kernel points) or not.

__init__(target_radius=1.0, num_points=19, deformable=False, **kwargs)

Initialize the member attributes of the initializer.

Parameters:

• target_radius (float) – The radius of the kernel’s ball.

• num_points (int) – The number of kernel points.

• deformable (bool) – True to make the kernel points trainable by the neural network, False otherwise.

__call__(shape=None, dtype='float32')

Initialize a ball-like structure space matrix representing the support points of a kernel.

Parameters:

shape – The shape parameter is ignored as the dimensionality of the initialized matrix depends on the arguments used to build the initializer.

Returns:

The structure space matrix for a ball-like kernel point \(\pmb{Q} \in \mathbb{R}^{m_q \times 3}\).

Return type:

tf.Tensor

static energy_f(x)

Compute the energy model.

Parameters:

x (np.ndarray) – The vectorized matrix of input points.

Returns:

The energy.

static energy_df(x)

Compute the gradient of the energy model.

Parameters:

x (np.ndarray) – The vectorized matrix of input points.

Returns:

The gradient of the energy.

model.deeplearn.initializer.kernel_point_structure_initializer module

class model.deeplearn.initializer.kernel_point_structure_initializer.KernelPointStructureInitializer(initialization_type='concentric_ellipsoids', max_radii=(1, 1, 1), radii_resolution=4, angular_resolutions=(1, 2, 4, 8), trainable=True, name='Q', **kwargs)

Bases: Initializer

Author:

Alberto M. Esmoris Pena

A kernel point structure initializer initializes the structure space matrix representing the support points of a kernel. It will generate a structure space matrix for the kernel \(\pmb{Q} \in \mathbb{R}^{K \times n_x}\). This matrix has \(K\) rows representing \(K\) points in a \(n_x\)-dimensional space, typically 3D, i.e., \(n_x=3\).

Variables:

• max_radii (np.ndarray of float) – The radius of the last ellipsoid along each axis \(\pmb{r}^* \in \mathbb{R}^{n_x}\).

• radii_resolution (int) – How many concentric ellipsoids must be considered \(n \in \mathbb{Z}_{>0}\) (the first one is the center point, the last one is the biggest outer ellipsoid).

• angular_resolutions (np.ndarray of int) – How many angles consider for each ellipsoid \((m_1, \ldots, m_n)\).

• trainable (bool) – Flag to control whether \(\pmb{Q}\) is trainable or not.

• name (str) – The name for the initialized tensor.

__init__(initialization_type='concentric_ellipsoids', max_radii=(1, 1, 1), radii_resolution=4, angular_resolutions=(1, 2, 4, 8), trainable=True, name='Q', **kwargs)

Initialize the member attributes of the initializer.

Parameters:

kwargs – The key-word specification to parametrize the initializer.

__call__(shape=None, dtype='float32')

Initialize a structure space matrix representing the support points of a kernel.

Parameters:

shape – The shape parameter is ignored as the dimensionality of the initialized matrix depends on the arguments used to build the initializer.

Returns:

The structure space matrix for a point-based kernel \(\pmb{Q} \in \mathbb{R}^{K \times n_x}\).

Return type:

tf.Tensor

sample_concentric_ellipsoids()

The structure matrix of the kernel \(\pmb{Q} \in \mathbb{R}^{3}\) is initialized for the 3D case assuming three parameters:

\(n\) The radii resolution.

\(r_x^*, r_y^*, r_z^*\) The max radii.

\(m_1, \ldots, m_n\) The angular resolution for each radius.

First, the axis-wise radii for given ellipsoid are defined as:

\[\begin{split}r_{xk} = \frac{k-1}{n-1} r_x^* \\ r_{yk} = \frac{k-1}{n-1} r_y^* \\ r_{zk} = \frac{k-1}{n-1} r_z^*\end{split}\]

Where \(k=0,...,n-1\) represents the \(n\) concentric ellipsoids with \(k=0\) being the central point and \(k=n-1\) the biggest ellipsoid, i.e., from smaller to bigger.

For then, it is possible to define two angles \(\alpha \in [0, \pi]\) and \(\beta \in [0, 2\pi]\) such that:

\[\alpha_{kj} = \frac{j-1}{m_k - 1} \pi \;,\;\; \beta_{kj} = \frac{j-1}{m_k -1} 2\pi\]

Where \(j=0, \ldots, m_k-1\) for each \(k\).

Finally, the rows in \(\pmb{Q}\) that represent the kernel’s structure can be computed as follows:

\[\begin{split}\left[\begin{array}{c} x \\ y \\ z \end{array}\right]^\intercal = \left[\begin{array}{c} r_{xk} \sin(\alpha_{kj}) \cos(\beta_{kj}) \\ r_{yk} \sin(\alpha_{kj}) \sin(\beta_{kj}) \\ r_{zk} \cos(\alpha_{kj}) \end{array}\right]^\intercal\end{split}\]

Returns:

\(\pmb{Q} \in \mathbb{R}^{K \times n_x}\)

Return type:

tf.Tensor

sample_concentric_grids()

In the concentric grids strategy the angular resolution is understood as the edge resolution \(r_e\).

One grid will be generated for each radius in the radii resolution specification. More concretely, each grid will have a length side of twice the radius and a number of points equal to \(r_e^3\) for the 3D case. Note that a radius is given for each axis such that rectangular grids are supported in general, not only voxel grids (those correspond to all axis having the same radius).

Returns:

Points sampled from concentric grids.

Return type:

tf.Tensor

sample_concentric_rectangulars()

In the concentric rectangular prisms strategy the angular resolution is understood as the edge resolution \(r_e\).

One rectangular prism will be generated for each radius in the radii resolution specification. More concretely, each rectangular prism will have a length side of twice the radius and a number of points equal to \(6r_e^2-12r_3+8\) for the 3D case. Note that a radius is given for each axis such that rectangular prisms are supported in general, not only voxels (those correspond to all axis having the same radius).

Returns:

Points sampled from concentric rectangular prisms.

Return type:

tf.Tensor

sample_concentric_cylinders()

In the concentric cylinders strategy the angular resolution \(r_a\) is used directly to sample along the \(z\)-axis.

One cylinder will be generated for each radius in the radii resolution specification. More concretely, each cylinder will have a number of points equal to \(r_a^2r_r\) where \(r_r\) is the radius of the disk for the current cylinder.

Returns:

Points sampled from concentric cylinders.

Return type:

tf.Tensor

sample_cone()

In the cone strategy angular resolution \(r_a\) is used directly to sample along the \(z\)-axis.

The cone will be generated as parametric circles which angular resolution and radius increases as they get far from the zero.

More concretely, the cone will have a number of points as shown below:

\[1 + \sum_{i=1}^{r_a}{\left\lceil r_a \dfrac{\lvert{z_i}\rvert}{z^*} \right\rceil}\]

Where \(z^*\) is the maximum height for the cone.

Returns:

Points sampled from concentric cones.

Return type:

tf.Tensor

compute_num_kernel_points()

Compute the expected number of support points for the kernel considering the attributes of the initializer.

Returns:

Expected number of support points.

Return type:

int

Module contents

author:

Alberto M. Esmoris Pena

The layer package contains the logic to handle the initializer of a neural network.