ufjc.utility

A module for basic single-chain model utilities.

This module consist of the class BasicUtility which contains attributes and methods that are meant to be inherited and utilized as basic utilities by an arbitrary single-chain model class.

Example

Create a freely-jointed chain single-chain model class FJC that inherits the BasicUtility class in order to utilize the Langevin function for the nondimensional isotensional mechanical response:

>>> from ufjc.utility import BasicUtility
>>> class FJC(BasicUtility):
...     def __init__(self):
...        BasicUtility.__init__(self)
...     def gamma(self, eta):
...         return self.langevin(eta)
>>> model = FJC()
>>> model.gamma([0, 0.23, 1e88])
array([0.        , 0.07639764, 1.        ])

class BasicUtility

Bases: object

The single-chain model basic utilities class.

This class contains attributes and methods that are meant to be inherited and utilized as basic utilities by an arbitrary single-chain model class.

minimum float

Helps avoid overflow when dividing by small numbers.

maximum_float

Helps avoid overflow in function evaluations.

maximum_exponent

Helps avoid overflow in exponential functions.

coth(eta)

The hyperbolic cotangent function.

This function essentially serves as a wrapper for the algebraic inverse of numpy.tanh that avoids the singularity from evaluating at zero.

Parameters:

eta (array_like) – The argument(s) of the hyperbolic cotangent function.

Returns:

The hyperbolic cotangent(s).

Return type:

numpy.ndarray

Example

Compute the hyperbolic cotangent for several argument values:

>>> from ufjc.utility import BasicUtility
>>> BasicUtility().coth([0, 0.23, np.inf])
array([4.49423284e+307, 4.42422373e+000, 1.00000000e+000])

inv_fun_1D(y, f, power=1, guess=None, **kwargs)

Function to invert a mathematical function.

This function returns the argument x given a function f(x) and y, the query value of the function, i.e. y = f(x).

Note

This function is only meant for bijective f(x).

Parameters:

• y (array_like) – The value(s) of the function y.

• f (function) – The function f(x).

• guess (list, optional) – A list of two initial guesses.

• **kwargs – Arbitrary keyword arguments. Passed to root_scalar.

Returns:

The corresponding argument(s) x.

Return type:

numpy.ndarray

Example

Invert a polynomial function:

>>> from ufjc.utility import BasicUtility
>>> f = lambda x: 1 + x**2/8 + x**3/23
>>> BasicUtility().inv_fun_1D([55, 88], f)
array([ 9.8712079, 11.7121826])

inv_langevin(gamma)

The inverse Langevin function.

This function computes the inverse of the Langevin function given its query value.

Parameters:

gamma (array_like) – The value(s) of the Langevin function.

Returns:

The argument(s) of the Langevin function.

Return type:

numpy.ndarray

Example

Check that \(\mathcal{L}^{-1}[\mathcal{L}(\eta)] = \eta\,\):

>>> import numpy as np
>>> from ufjc.utility import BasicUtility
>>> def check_langevin(eta):
...     langevin = BasicUtility().langevin
...     inv_langevin = BasicUtility().inv_langevin
...     return np.isclose(inv_langevin(langevin(eta))[0], eta)
>>> check_langevin(np.random.rand())
True

langevin(eta)

The Langevin function.

This function computes and returns the Langevin function of the argument eta, which is

\[\mathcal{L}(\eta) = \coth(\eta) - 1/\eta.\]

It also avoids dividing by zero at zero argument.

Parameters:

eta (array_like) – The argument(s) of the Langevin function.

Returns:

The evaluated Langevin function(s).

Return type:

numpy.ndarray

Example

Compute the Langevin function for several argument values:

>>> from ufjc.utility import BasicUtility
>>> BasicUtility().langevin([0, 1, 8, np.inf])
array([0.        , 0.31303529, 0.87500023, 1.        ])

log_over_sinh(eta)

The natural logarithm of the argument over the hyperbolic sine.

This function avoids overflow when calculating the natural logarithm of the ratio of the argument to the hyperbolic sine of the argument,

\[f(\eta) = \ln\left[\frac{\eta}{\sinh(\eta)}\right].\]

It also returns zero for zero argument.

Parameters:

eta (array_like) – The argument(s) of the function.

Returns:

The value(s) of the function.

Return type:

numpy.ndarray

Example

Compute the function for several argument values:

>>> from ufjc.utility import BasicUtility
>>> BasicUtility().log_over_sinh([0, 0.23, 888])
array([ 0.00000000e+00, -8.80117196e-03, -8.80517881e+02])

np_array(input)

Function to return input as a numpy array.

This function essentially serves as a wrapper for numpy.array that returns non-array type inputs as shape (1,) numpy arrays rather than shape () numpy arrays, which is useful for indexing.

Parameters:

input (array_like) – Anything passable to numpy.array.

Returns:

The input as an index-able numpy array.

Return type:

numpy.ndarray

Example

Compare attempts to index the numpy array of an integer:

>>> import numpy as np
>>> from ufjc.utility import BasicUtility
>>> try:
...     np.array(8)[0]
... except IndexError:
...     print('Error indexing 0-dimensional array.')
... finally:
...     BasicUtility().np_array(8)[0]
Error indexing 0-dimensional array.
8