ribbon.ribbon module#

class ribbon.ribbon.Ribbon(length, width, thickness, gspl, gspw, gspt, ngpl=None, ngpw=None, ngpt=None)[source]#

Bases: object

Parameters:

lengthfloat: Length of the ribbon.
widthfloat: Width of the ribbon.
thicknessfloat: Thickness of the ribbon. If zero, the ribbon is a 2D surface in 3-space.
gsplfloat | None: Grid spacing in the length direction. If None, specify the number of grid points using the keyword argument ngpl.
gspwfloat | None: Grid spacing in the width direction. If None, specify the number of grid points using the keyword argument ngpw.
gsptfloat | None: Grid spacing in the thickness direction. Ignored if thickness = 0. If thickness != 0 and gspt = None, specify the number of grid points using the keyword argument ngpt.
ngplint | None, optional: Number of grid points in the length direction. Must be > 4. Used only if gspl = None.
ngpwint | None, optional: Number of grid points in the width direction. Must be > 4. Used only if gspw = None.
ngptint | None, optional: Number of grid points in the thickness direction. Must be > 2. Used only if thickness != 0 and gspt = None.

Attributes:

lengthfloat: Length of the ribbon.
widthfloat: Width of the ribbon.
thicknessfloat: Thickness of the ribbon. If zero, the ribbon is a 2D surface in 3-space.
lm, nfloat or callable: Curvature along length, width, and thickness directions, respectively. If any of the curvatures is callable, it should be of the form y = f (x), where x (float) is the arclength coordinate and y (float) is the curvature.
profile_curvedict: Specification of the profile curve.
u, v, w1d ndarray: Coordinates of the reference grid along length, width, and thickness directions, respectively.
mline(n,3) ndarray: Coordinates of the grid points on the ribbon midline in current configuration.
msurf(m,n,3) ndarray: Coordinates of the grid points on the ribbon midsurface in the current configuration.
grid(m,n,p,3) ndarray: Coordinates of the grid points of the ribbon in the current configuration.
atom_refpos(n,3) ndarray: Atom coordinates in the reference state.
atom_pos(n,3) ndarray: Atom coordinates in the current configuration.

Methods

`create`([orient_along])	Constructs the ribbon and orients it along orient_along.
`create_helix`(s, parametrization, params, ...)	Creates a helix with constant curvatures.
`create_helix_var`(s, parametrization, params, ...)	Creates a helix with non-constant curvatures.
`get_gauss_curvature`()	Returns the gaussian curvature along the ribbon midline.
`get_mean_curvature`()	Returns the mean curvature along the ribbon midline.
`get_pitch`()	Returns the pitch along the ribbon midline.
`get_radius`()	Returns the radius along the ribbon midline.
`get_theta`()	Returns the angle (in radians) between the principal curvature direction and the lengthwise direction along the ribbon midline.
`set_atom_refpos`(atom_refpos[, copy, atom_pos])	Setter for the reference positions of atoms.
`set_shape`(shape, **kwargs)	Setter for the ribbon shape.
`translate_to_center`()	Translates grids and current atom positions so as to bring the center of the ribbon midline at (0,0,0).

set_atom_refpos(atom_refpos, copy=True, atom_pos=None)[source]#

Setter for the reference positions of atoms.

Parameters:

atom_refpos(n,3) ndarray: Atom positions in the reference state. Must be within the domain [0, length] x [-width/2, width/2] x [-thickness/2, thickness/2].
copybool: Whether to make a copy of the input array atom_refpos.
atom_pos(n,3) ndarray: External buffer for atom_pos. If None, an array will be created.

Returns:

None

set_shape(shape, **kwargs)[source]#

Setter for the ribbon shape.

Parameters:

shapestr

kwargsdict

Shape parameters for each shape as key-value pairs.

HelicalRibbon

‘pitch’. float. Must be non-zero. Positive for
right-handed, negative for left-handed.
‘radius’. float. Must be non-zero.

Helicoid

‘pitch’. float. Must be non-zero. Positive for

right-handed, negative for left-handed.

Torus

‘Radius’. float. Must be non-zero.
‘radius’. float. Must be non-zero.

Cylinder

‘radius’. float. Must be non-zero.

Planar

No parameters required.

General

‘pitch’. float. Must be non-zero. Positive for right-handed,
negative for left-handed.
‘radius’. float. Must be non-zero.
‘profile’. str. Type of the profile curve.
‘profile_params’. dict. Parameters of the profile curve.

Returns:

None

get_radius()[source]#

Returns the radius along the ribbon midline.

Returns:

float or tuple of 1D ndarrays: Radius along the ribbon midline. If all curvatures are constants, a float is returned. If any of the curvatures is callable, a tuple (x,y) is returned, where x contains the arclength coordinates of the ribbon midline and y contains the corresponding radii.

get_pitch()[source]#

Returns the pitch along the ribbon midline.

Returns:

float or tuple of 1D ndarrays: Pitch along the the ribbons midline. If all curvatures are constants, a float is returned. If any of the curvatures is callable, a tuple (x,y) is returned, where x contains the arclength coordinates of the ribbon midline and y contains the corresponding pitch values.

get_gauss_curvature()[source]#

Returns the gaussian curvature along the ribbon midline.

Returns:

float or tuple of 1D ndarrays: Gaussian curvature along the ribbons midline. If all curvatures are constants, a float is returned. If any of the curvatures is callable, a tuple (x,y) is returned, where x contains the arclength coordinates of the ribbon midline and y contains the corresponding gaussian curvatures.

get_mean_curvature()[source]#

Returns the mean curvature along the ribbon midline.

Returns:

float or tuple of 1D ndarrays: Mean curvature along the ribbons midline. If all curvatures are constants, a float is returned. If any of the curvatures is callable, a tuple (x,y) is returned, where x contains the arclength coordinates of the ribbon midline and y contains the corresponding mean curvatures.

get_theta()[source]#

Returns the angle (in radians) between the principal curvature direction and the lengthwise direction along the ribbon midline.

Returns:

float or tuple of 1D ndarrays: Angle (in radians). If all curvatures are constants, a float is returned. If any of the curvatures is callable, a tuple (x,y) is returned, where x contains the arclength coordinates of the ribbon midline and y contains the corresponding angle.

translate_to_center()[source]#

Translates grids and current atom positions so as to bring the center of the ribbon midline at (0,0,0).

Returns:

None

create(orient_along=None)[source]#

Constructs the ribbon and orients it along orient_along.

Parameters:

orient_along(3,) array_like or None: If the curvatures of the ribbon midline are constant, the ribbon axis will be oriented along orient_along. This does not need to be a unit vector. If None, the orientation will be remain as is.

Returns:

None

static create_helix(s, parametrization, params, axis, coords, d1=None, d2=None, d3=None)[source]#

Creates a helix with constant curvatures.

Parameters:

s1d array_like: Arclength.
parametrization‘rp’ | ‘lm’: If ‘rp’, helix parameters are radius and pitch. If ‘lm’, the parameters are the curvatures l and m (twist). Use rp for common use-cases.
paramstuple: If parametrization = ‘rp’, params = (radius, pitch). If parametrization = ‘lm’, params = (lm, ), where lm is a tuple (l,m).
axis(3,) ndarray: On return, the contains the unit vector along the helix axis.
coords(n, 3) ndarray: On return, contains the cartesian coordinates of the helix. n must equal the length of s.
d1, d2, d3(n, 3) ndarray | None: On return, contains the d1 ( equivalently d2 and d3) director vector of the helix. n must equal the length of s. If None, the corresponding director is not returned.

Returns:

None

static create_helix_var(s, parametrization, params, axis, coords, d1=None, d2=None, d3=None)[source]#

Creates a helix with non-constant curvatures.

Parameters:

s1d array_like: Arclength.
parametrization‘rp’ | ‘lm’: If ‘rp’, helix parameters are radius and pitch. If ‘lm’, the parameters are the curvatures l and m (twist). Use rp for common use-cases.
paramstuple: If parametrization = ‘rp’, params = (radius, pitch), where at least one of radius and pitch must be a callable. If parametrization = ‘lm’, params = (lm, ), where lm is a callble returning a tuple (l,m).
axis(3,) ndarray: On return, the contains the unit vector along the helix axis.
coords(n, 3) ndarray: On return, contains the cartesian coordinates of the helix. n must equal the length of s.
d1, d2, d3(n, 3) ndarray | None: On return, contains the d1 ( equivalently d2 and d3) director vector of the helix. n must equal the length of s. If None, the corresponding director is not returned.

Returns:

None