ribbon package#

class 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

class ribbon.SpiralCircleInvolute(b, r0)[source]#

Bases: SpiralPolarBase

Spirals with polar equation: r = b * (1+theta^2)^(1/2), where b >= 0 is the radius of the circle.

The starting point is at r = r0 and theta = t0, where r0 must be > b.

The arclength s is measured from (r0, t0) in the direction of increasing radius.

For all points on this spiral r must be >= r0, theta must be >= t0, and s must be >= 0.

Parameters:

bfloat: The radius of circle, must be >= 0.
r0: Radial coordinate of the starting point of the spiral (must be > b).

Methods

`arclength_to_r`(s)	Returns the radial coordinates corresponding to the arclengths.
`arclength_to_theta`(s[, s0, t0])	Returns the angular coordinates corresponding to the arclengths.
`get_arclength`(v[, var, v0])	Returns the arclength at the given values of polar coordinates.
`get_cart_coords`(v[, var])	Returns the cartesian coordinates at the given values of polar coordinates or arclengths.
`get_curvature`(v[, var])	Returns the curvature at the given values of polar coordinates or arclengths.
`get_polar_coords`(v[, var])	Returns the polar coordinates at the given values of theta, r, or arclengths.
`get_tangent`(v[, var])	Returns the unit tangent vector at the given values of polar or arclength coordinates.
`r_to_theta`(r)	Returns the angular coordinates corresponding to the given radial coordinates.
`theta_to_r`(theta)	Returns the radial coordinates corresponding to the given angular coordinates.

theta_to_r(theta)[source]#

Returns the radial coordinates corresponding to the given angular coordinates.

Parameters:

thetaarray_like: Angular coordinates in radians.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray)

r_to_theta(r)[source]#

Returns the angular coordinates corresponding to the given radial coordinates.

Parameters:

rarray_like: Radial coordinates.

Returns:

float or ndarray: Angular coordinates in radians (float if input is scalar, else ndarray).

get_tangent(v, var='s')[source]#

Returns the unit tangent vector at the given values of polar or arclength coordinates.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

ndarray: Unit tangent vectors. Shape is (2,) if v is scalar, else (n,2) where n is the length of v.

arclength_to_r(s)#

Returns the radial coordinates corresponding to the arclengths.

Parameters:

sarray_like: Arclengths measured from the starting point (as set by the instance attribute r0) along the direction of increasing radius.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray).

arclength_to_theta(s, s0=0.0, t0=None)#

Returns the angular coordinates corresponding to the arclengths.

Parameters:

sarray_like: Arclengths measured from the starting point (as set by the instance attribute r0) along the direction of increasing radius.
s0float: Value of the arclength at angle t0.
t0float | None: Measure arclength from this value of the angular coordinate. If None, set to t0, which corresponds to the radial coordinate r0.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray).

get_arclength(v, var='theta', v0=None)#

Returns the arclength at the given values of polar coordinates.

Parameters:

varray_like: Value of the polar coordinates.
var{‘r’, ‘theta’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta'.
v0float or None: Origin of the arclength. If None, will be set to self.t0 if var = 'theta' or to self.r0 if var = 'r'.

Returns:

float or ndarray: Arclength (float if input is scalar, else ndarray).

get_cart_coords(v, var='s')#

Returns the cartesian coordinates at the given values of polar coordinates or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

x, ytuple: Cartesian coordinates. If v is a scalar, x and y are floats, else they are 1D *ndarray*s.

get_curvature(v, var='s')#

Returns the curvature at the given values of polar coordinates or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

float or ndarray: Curvatures (float if input is scalar, else ndarray).

get_polar_coords(v, var='s')#

Returns the polar coordinates at the given values of theta, r, or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

r, thetatuple: Polar coordinates. If v is a scalar, r and theta are floats, else they are 1D *ndarray*s.

class ribbon.SpiralArchimedesGeneral(b, n, r0)[source]#

Bases: SpiralArchimedesBase

Class implementing a general archimedean spiral with polar equation r = b * theta^n.

The starting point is at r = r0 and theta = t0. If n > 0, r0 >= 0, otherwise r0 > 0. The arclength s is measured from (r0, t0) in the direction of increasing radius.

For all points on this spiral r must be >= r0 and s must be >= 0. If n > 0, theta must be >= t0, otherwise theta <= t0.

Methods

`arclength_to_r`(s)	Returns the radial coordinates corresponding to the arclengths.
`arclength_to_theta`(s[, s0, t0])	Returns the angular coordinates corresponding to the arclengths.
`get_arclength`(v[, var, v0])	Returns the arclength at the given values of polar coordinates.
`get_cart_coords`(v[, var])	Returns the cartesian coordinates at the given values of polar coordinates or arclengths.
`get_curvature`(v[, var])	Returns the curvature at the given values of polar coordinates or arclengths.
`get_polar_coords`(v[, var])	Returns the polar coordinates at the given values of theta, r, or arclengths.
`get_tangent`(v[, var])	Returns the unit tangent vector at the given values of polar or arclength coordinates.
`r_to_theta`(r)	Returns the angular coordinates corresponding to the given radial coordinates.
`theta_to_r`(theta)	Returns the radial coordinates corresponding to the given angular coordinates.

arclength_to_r(s)#

Returns the radial coordinates corresponding to the arclengths.

Parameters:

sarray_like: Arclengths measured from the starting point (as set by the instance attribute r0) along the direction of increasing radius.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray).

arclength_to_theta(s, s0=0.0, t0=None)#

Returns the angular coordinates corresponding to the arclengths.

Parameters:

sarray_like: Arclengths measured from the starting point (as set by the instance attribute r0) along the direction of increasing radius.
s0float: Value of the arclength at angle t0.
t0float | None: Measure arclength from this value of the angular coordinate. If None, set to t0, which corresponds to the radial coordinate r0.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray).

get_arclength(v, var='theta', v0=None)#

Returns the arclength at the given values of polar coordinates.

Parameters:

varray_like: Value of the polar coordinates.
var{‘r’, ‘theta’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta'.
v0float or None: Origin of the arclength. If None, will be set to self.t0 if var = 'theta' or to self.r0 if var = 'r'.

Returns:

float or ndarray: Arclength (float if input is scalar, else ndarray).

get_cart_coords(v, var='s')#

Returns the cartesian coordinates at the given values of polar coordinates or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

x, ytuple: Cartesian coordinates. If v is a scalar, x and y are floats, else they are 1D *ndarray*s.

get_curvature(v, var='s')#

Returns the curvature at the given values of polar coordinates or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

float or ndarray: Curvatures (float if input is scalar, else ndarray).

get_polar_coords(v, var='s')#

Returns the polar coordinates at the given values of theta, r, or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

r, thetatuple: Polar coordinates. If v is a scalar, r and theta are floats, else they are 1D *ndarray*s.

get_tangent(v, var='s')#

Returns the unit tangent vector at the given values of polar or arclength coordinates.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

ndarray: Unit tangent vectors. Shape is (2,) if v is scalar, else (n,2) where n is the length of v.

r_to_theta(r)#

Returns the angular coordinates corresponding to the given radial coordinates.

Parameters:

rarray_like: Radial coordinates.

Returns:

float or ndarray: Angular coordinates in radians (float if input is scalar, else ndarray).

theta_to_r(theta)#

Returns the radial coordinates corresponding to the given angular coordinates.

Parameters:

thetaarray_like: Angular coordinates in radians.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray)

class ribbon.SpiralArchimedes(b, r0)[source]#

Bases: SpiralArchimedesBase

Class implementing an Archimedean spiral with polar equation r = b * theta.

The starting point is at r = r0 and theta = t0, where r0 >= 0. The arclength s is measured from (r0, t0) in the direction of increasing radius.

For all points on this spiral r must be >= r0, s must be >= 0, and theta must be >= t0.

Methods

`arclength_to_r`(s)	Returns the radial coordinates corresponding to the arclengths.
`arclength_to_theta`(s[, s0, t0])	Returns the angular coordinates corresponding to the arclengths.
`get_arclength`(v[, var, v0])	Returns the arclength at the given values of polar coordinates.
`get_cart_coords`(v[, var])	Returns the cartesian coordinates at the given values of polar coordinates or arclengths.
`get_curvature`(v[, var])	Returns the curvature at the given values of polar coordinates or arclengths.
`get_polar_coords`(v[, var])	Returns the polar coordinates at the given values of theta, r, or arclengths.
`get_tangent`(v[, var])	Returns the unit tangent vector at the given values of polar or arclength coordinates.
`r_to_theta`(r)	Returns the angular coordinates corresponding to the given radial coordinates.
`theta_to_r`(theta)	Returns the radial coordinates corresponding to the given angular coordinates.

arclength_to_r(s)#

Returns the radial coordinates corresponding to the arclengths.

Parameters:

sarray_like: Arclengths measured from the starting point (as set by the instance attribute r0) along the direction of increasing radius.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray).

arclength_to_theta(s, s0=0.0, t0=None)#

Returns the angular coordinates corresponding to the arclengths.

Parameters:

sarray_like: Arclengths measured from the starting point (as set by the instance attribute r0) along the direction of increasing radius.
s0float: Value of the arclength at angle t0.
t0float | None: Measure arclength from this value of the angular coordinate. If None, set to t0, which corresponds to the radial coordinate r0.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray).

get_arclength(v, var='theta', v0=None)#

Returns the arclength at the given values of polar coordinates.

Parameters:

varray_like: Value of the polar coordinates.
var{‘r’, ‘theta’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta'.
v0float or None: Origin of the arclength. If None, will be set to self.t0 if var = 'theta' or to self.r0 if var = 'r'.

Returns:

float or ndarray: Arclength (float if input is scalar, else ndarray).

get_cart_coords(v, var='s')#

Returns the cartesian coordinates at the given values of polar coordinates or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

x, ytuple: Cartesian coordinates. If v is a scalar, x and y are floats, else they are 1D *ndarray*s.

get_curvature(v, var='s')#

Returns the curvature at the given values of polar coordinates or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

float or ndarray: Curvatures (float if input is scalar, else ndarray).

get_polar_coords(v, var='s')#

Returns the polar coordinates at the given values of theta, r, or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

r, thetatuple: Polar coordinates. If v is a scalar, r and theta are floats, else they are 1D *ndarray*s.

get_tangent(v, var='s')#

Returns the unit tangent vector at the given values of polar or arclength coordinates.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

ndarray: Unit tangent vectors. Shape is (2,) if v is scalar, else (n,2) where n is the length of v.

r_to_theta(r)#

Returns the angular coordinates corresponding to the given radial coordinates.

Parameters:

rarray_like: Radial coordinates.

Returns:

float or ndarray: Angular coordinates in radians (float if input is scalar, else ndarray).

theta_to_r(theta)#

Returns the radial coordinates corresponding to the given angular coordinates.

Parameters:

thetaarray_like: Angular coordinates in radians.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray)

class ribbon.SpiralFermat(b, r0)[source]#

Bases: SpiralArchimedesBase

Class implementing a general archimedean spiral with polar equation r = b * theta^(1/2).

The starting point is at r = r0 and theta = t0, where r0 >= 0. The arclength s is measured from (r0, t0) in the direction of increasing radius.

For all points on this spiral r must be >= r0, s must be >= 0, and theta must be >= t0.

Parameters:

bfloat: Parameter in the polar equation. Must be > 0.
r0float: The spiral curve segment begins at (r = r0). Must be a non-negative value.

Methods

`arclength_to_r`(s)	Returns the radial coordinates corresponding to the arclengths.
`arclength_to_theta`(s[, s0, t0])	Returns the angular coordinates corresponding to the arclengths.
`get_arclength`(v[, var, v0])	Returns the arclength at the given values of polar coordinates.
`get_cart_coords`(v[, var])	Returns the cartesian coordinates at the given values of polar coordinates or arclengths.
`get_curvature`(v[, var])	Returns the curvature at the given values of polar coordinates or arclengths.
`get_polar_coords`(v[, var])	Returns the polar coordinates at the given values of theta, r, or arclengths.
`get_tangent`(v[, var])	Returns the unit tangent vector at the given values of polar or arclength coordinates.
`r_to_theta`(r)	Returns the angular coordinates corresponding to the given radial coordinates.
`theta_to_r`(theta)	Returns the radial coordinates corresponding to the given angular coordinates.

arclength_to_r(s)#

Returns the radial coordinates corresponding to the arclengths.

Parameters:

sarray_like: Arclengths measured from the starting point (as set by the instance attribute r0) along the direction of increasing radius.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray).

arclength_to_theta(s, s0=0.0, t0=None)#

Returns the angular coordinates corresponding to the arclengths.

Parameters:

sarray_like: Arclengths measured from the starting point (as set by the instance attribute r0) along the direction of increasing radius.
s0float: Value of the arclength at angle t0.
t0float | None: Measure arclength from this value of the angular coordinate. If None, set to t0, which corresponds to the radial coordinate r0.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray).

get_arclength(v, var='theta', v0=None)#

Returns the arclength at the given values of polar coordinates.

Parameters:

varray_like: Value of the polar coordinates.
var{‘r’, ‘theta’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta'.
v0float or None: Origin of the arclength. If None, will be set to self.t0 if var = 'theta' or to self.r0 if var = 'r'.

Returns:

float or ndarray: Arclength (float if input is scalar, else ndarray).

get_cart_coords(v, var='s')#

Returns the cartesian coordinates at the given values of polar coordinates or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

x, ytuple: Cartesian coordinates. If v is a scalar, x and y are floats, else they are 1D *ndarray*s.

get_curvature(v, var='s')#

Returns the curvature at the given values of polar coordinates or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

float or ndarray: Curvatures (float if input is scalar, else ndarray).

get_polar_coords(v, var='s')#

Returns the polar coordinates at the given values of theta, r, or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

r, thetatuple: Polar coordinates. If v is a scalar, r and theta are floats, else they are 1D *ndarray*s.

get_tangent(v, var='s')#

Returns the unit tangent vector at the given values of polar or arclength coordinates.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

ndarray: Unit tangent vectors. Shape is (2,) if v is scalar, else (n,2) where n is the length of v.

r_to_theta(r)#

Returns the angular coordinates corresponding to the given radial coordinates.

Parameters:

rarray_like: Radial coordinates.

Returns:

float or ndarray: Angular coordinates in radians (float if input is scalar, else ndarray).

theta_to_r(theta)#

Returns the radial coordinates corresponding to the given angular coordinates.

Parameters:

thetaarray_like: Angular coordinates in radians.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray)

class ribbon.SpiralHyperbolic(b, r0)[source]#

Bases: SpiralArchimedesBase

Class implementing a general archimedean spiral with polar equation r = b * theta^(-1).

The starting point is at r = r0 and theta = t0, where r0 > 0. The arclength s is measured from (r0, t0) in the direction of increasing radius.

For all points on this spiral r must be >= r0, s must be >= 0, and theta must be <= t0.

Parameters:

bfloat: Parameter in the polar equation. Must be > 0.
r0float: The spiral curve segment begins at (r = r0). Must be a non-negative value.

Methods

`arclength_to_r`(s)	Returns the radial coordinates corresponding to the arclengths.
`arclength_to_theta`(s[, s0, t0])	Returns the angular coordinates corresponding to the arclengths.
`get_arclength`(v[, var, v0])	Returns the arclength at the given values of polar coordinates.
`get_cart_coords`(v[, var])	Returns the cartesian coordinates at the given values of polar coordinates or arclengths.
`get_curvature`(v[, var])	Returns the curvature at the given values of polar coordinates or arclengths.
`get_polar_coords`(v[, var])	Returns the polar coordinates at the given values of theta, r, or arclengths.
`get_tangent`(v[, var])	Returns the unit tangent vector at the given values of polar or arclength coordinates.
`r_to_theta`(r)	Returns the angular coordinates corresponding to the given radial coordinates.
`theta_to_r`(theta)	Returns the radial coordinates corresponding to the given angular coordinates.

arclength_to_r(s)#

Returns the radial coordinates corresponding to the arclengths.

Parameters:

sarray_like: Arclengths measured from the starting point (as set by the instance attribute r0) along the direction of increasing radius.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray).

arclength_to_theta(s, s0=0.0, t0=None)#

Returns the angular coordinates corresponding to the arclengths.

Parameters:

sarray_like: Arclengths measured from the starting point (as set by the instance attribute r0) along the direction of increasing radius.
s0float: Value of the arclength at angle t0.
t0float | None: Measure arclength from this value of the angular coordinate. If None, set to t0, which corresponds to the radial coordinate r0.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray).

get_arclength(v, var='theta', v0=None)#

Returns the arclength at the given values of polar coordinates.

Parameters:

varray_like: Value of the polar coordinates.
var{‘r’, ‘theta’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta'.
v0float or None: Origin of the arclength. If None, will be set to self.t0 if var = 'theta' or to self.r0 if var = 'r'.

Returns:

float or ndarray: Arclength (float if input is scalar, else ndarray).

get_cart_coords(v, var='s')#

Returns the cartesian coordinates at the given values of polar coordinates or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

x, ytuple: Cartesian coordinates. If v is a scalar, x and y are floats, else they are 1D *ndarray*s.

get_curvature(v, var='s')#

Returns the curvature at the given values of polar coordinates or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

float or ndarray: Curvatures (float if input is scalar, else ndarray).

get_polar_coords(v, var='s')#

Returns the polar coordinates at the given values of theta, r, or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

r, thetatuple: Polar coordinates. If v is a scalar, r and theta are floats, else they are 1D *ndarray*s.

get_tangent(v, var='s')#

Returns the unit tangent vector at the given values of polar or arclength coordinates.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

ndarray: Unit tangent vectors. Shape is (2,) if v is scalar, else (n,2) where n is the length of v.

r_to_theta(r)#

Returns the angular coordinates corresponding to the given radial coordinates.

Parameters:

rarray_like: Radial coordinates.

Returns:

float or ndarray: Angular coordinates in radians (float if input is scalar, else ndarray).

theta_to_r(theta)#

Returns the radial coordinates corresponding to the given angular coordinates.

Parameters:

thetaarray_like: Angular coordinates in radians.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray)

class ribbon.SpiralLituus(b, r0)[source]#

Bases: SpiralArchimedesBase

Class implementing a general archimedean spiral with polar equation r = b * theta^(-1/2).

The starting point is at r = r0 and theta = t0, where r0 > 0. The arclength s is measured from (r0, t0) in the direction of increasing radius.

For all points on this spiral r must be >= r0, s must be >= 0, and theta must be <= t0.

Parameters:

bfloat: Parameter in the polar equation. Must be > 0.
r0float: The spiral curve segment begins at (r = r0). Must be a non-negative value.

Methods

`arclength_to_r`(s)	Returns the radial coordinates corresponding to the arclengths.
`arclength_to_theta`(s[, s0, t0])	Returns the angular coordinates corresponding to the arclengths.
`get_arclength`(v[, var, v0])	Returns the arclength at the given values of polar coordinates.
`get_cart_coords`(v[, var])	Returns the cartesian coordinates at the given values of polar coordinates or arclengths.
`get_curvature`(v[, var])	Returns the curvature at the given values of polar coordinates or arclengths.
`get_polar_coords`(v[, var])	Returns the polar coordinates at the given values of theta, r, or arclengths.
`get_tangent`(v[, var])	Returns the unit tangent vector at the given values of polar or arclength coordinates.
`r_to_theta`(r)	Returns the angular coordinates corresponding to the given radial coordinates.
`theta_to_r`(theta)	Returns the radial coordinates corresponding to the given angular coordinates.

arclength_to_r(s)#

Returns the radial coordinates corresponding to the arclengths.

Parameters:

sarray_like: Arclengths measured from the starting point (as set by the instance attribute r0) along the direction of increasing radius.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray).

arclength_to_theta(s, s0=0.0, t0=None)#

Returns the angular coordinates corresponding to the arclengths.

Parameters:

sarray_like: Arclengths measured from the starting point (as set by the instance attribute r0) along the direction of increasing radius.
s0float: Value of the arclength at angle t0.
t0float | None: Measure arclength from this value of the angular coordinate. If None, set to t0, which corresponds to the radial coordinate r0.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray).

get_arclength(v, var='theta', v0=None)#

Returns the arclength at the given values of polar coordinates.

Parameters:

varray_like: Value of the polar coordinates.
var{‘r’, ‘theta’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta'.
v0float or None: Origin of the arclength. If None, will be set to self.t0 if var = 'theta' or to self.r0 if var = 'r'.

Returns:

float or ndarray: Arclength (float if input is scalar, else ndarray).

get_cart_coords(v, var='s')#

Returns the cartesian coordinates at the given values of polar coordinates or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

x, ytuple: Cartesian coordinates. If v is a scalar, x and y are floats, else they are 1D *ndarray*s.

get_curvature(v, var='s')#

Returns the curvature at the given values of polar coordinates or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

float or ndarray: Curvatures (float if input is scalar, else ndarray).

get_polar_coords(v, var='s')#

Returns the polar coordinates at the given values of theta, r, or arclengths.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

r, thetatuple: Polar coordinates. If v is a scalar, r and theta are floats, else they are 1D *ndarray*s.

get_tangent(v, var='s')#

Returns the unit tangent vector at the given values of polar or arclength coordinates.

Parameters:

varray_like: Value of the polar coordinates or arclengths.
var{‘r’, ‘theta’, ‘s’}: Descriptor for v. Radial coordinates — 'r', angular coordinates — 'theta', and arclengths — 's'.

Returns:

ndarray: Unit tangent vectors. Shape is (2,) if v is scalar, else (n,2) where n is the length of v.

r_to_theta(r)#

Returns the angular coordinates corresponding to the given radial coordinates.

Parameters:

rarray_like: Radial coordinates.

Returns:

float or ndarray: Angular coordinates in radians (float if input is scalar, else ndarray).

theta_to_r(theta)#

Returns the radial coordinates corresponding to the given angular coordinates.

Parameters:

thetaarray_like: Angular coordinates in radians.

Returns:

float or ndarray: Radial coordinates (float if input is scalar, else ndarray)

class ribbon.SpiralPolynomial(coeffs)[source]#

Bases: SpiralCartesianBase

The Césaro equation \(\kappa = f(s)\), where \(f(s)\) is a polynomial in \(s\).

Parameters:

coeffsarray_like: Coefficients of the polynomial in order of ascending power, i.e. coeffs[i] is the coefficient of s^i.

Methods

`get_cart_coords`(s)	Returns the cartesian coordinates at the given values of arclengths.
`get_curvature`(s)	Returns the curvature at the given values of arclengths.
`get_tangent`(s)	Returns the unit tangent vector at the given values of polar or arclength coordinates.

Warning

Polynomials with degree greater than 2 often result in self-intersecting, or at least self-touching spirals.

get_tangent(s)[source]#

Returns the unit tangent vector at the given values of polar or arclength coordinates.

Parameters:

sarray_like: Value of the polar coordinates or arclengths.

Returns:

ndarray: Unit tangent vectors. Shape is (2,) if s is scalar, else (n,2) where n is the length of s.

get_curvature(s)[source]#

Returns the curvature at the given values of arclengths.

Parameters:

sarray_like: Arclengths.

Returns:

float or ndarray: Curvatures (float if input is scalar, else ndarray).

get_cart_coords(s)[source]#

Returns the cartesian coordinates at the given values of arclengths.

Parameters:

sarray_like: Arclengths.

Returns:

x, ytuple: Cartesian coordinates. If s is a scalar, x and y are floats, else they are 1D ndarray.

class ribbon.SpiralCornu(a)[source]#

Bases: SpiralCartesianBase

The Césaro equation is \(\kappa = as\), where \(a > 0\).

Parameters:

afloat: Proportionality constant between curvature and arclength. Must be > 0.

Methods

`get_cart_coords`(s)	Returns the cartesian coordinates at the given values of arclengths.
`get_curvature`(s)	Returns the curvature at the given values of arclengths.
`get_tangent`(s)	Returns the unit tangent vector at the given values of polar or arclength coordinates.

get_tangent(s)[source]#

Returns the unit tangent vector at the given values of polar or arclength coordinates.

Parameters:

sarray_like: Value of the polar coordinates or arclengths.

Returns:

ndarray: Unit tangent vectors. Shape is (2,) if s is scalar, else (n,2) where n is the length of s.

get_curvature(s)[source]#

Returns the curvature at the given values of arclengths.

Parameters:

sarray_like: Arclengths.

Returns:

float or ndarray: Curvatures (float if input is scalar, else ndarray).

get_cart_coords(s)[source]#

Returns the cartesian coordinates at the given values of arclengths.

Parameters:

sarray_like: Arclengths.

Returns:

x, ytuple: Cartesian coordinates. If s is a scalar, x and y are floats, else they are 1D ndarray.

class ribbon.SpiralNielsen(a, b)[source]#

Bases: SpiralCartesianBase

The Césaro equation is \(\kappa = a e^{bs}\), where \(a > 0, b \neq 0\).

Parameters:

afloat: Parameter in the Césaro equation. Must be > 0.
bfloat: Parameter in the Césaro equation. Must be non-zero.

Methods

`get_cart_coords`(s)	Returns the cartesian coordinates at the given values of arclengths.
`get_curvature`(s)	Returns the curvature at the given values of arclengths.
`get_tangent`(s)	Returns the unit tangent vector at the given values of polar or arclength coordinates.

get_tangent(s)[source]#

Returns the unit tangent vector at the given values of polar or arclength coordinates.

Parameters:

sarray_like: Value of the polar coordinates or arclengths.

Returns:

ndarray: Unit tangent vectors. Shape is (2,) if s is scalar, else (n,2) where n is the length of s.

get_curvature(s)[source]#

Returns the curvature at the given values of arclengths.

Parameters:

sarray_like: Arclengths.

Returns:

float or ndarray: Curvatures (float if input is scalar, else ndarray).

get_cart_coords(s)[source]#

Returns the cartesian coordinates at the given values of arclengths.

Parameters:

sarray_like: Arclengths.

Returns:

x, ytuple: Cartesian coordinates. If s is a scalar, x and y are floats, else they are 1D ndarray.

ribbon.write_xyz(x, y, z, atom_symbol='C', filename='out.xyz', title='')[source]#

Writes atom positions to a XYZ file.

Parameters:

x, y, z1D array_like: x, y, and z coordinates of the atoms. All three must have the same length.
atom_symbolstr: Atom symbol. If more than two characters, will be trucated to the first two characters.
filenamepath_like: Name of output file (XYZ format) with extension ‘.xyz’.
titlestr: A title string for the XYZ file.

Returns:

None

ribbon.double_spiral(spiral, L, ds=0.5, same=False, end=1, f=0.0)[source]#

Create a double spiral from a single spiral.

The two spirals may be joined at either of the two ends. In addition, before joining, a the curvature of fraction of the arclength of both spirals may be linearized (if f > 0). Linearization is done by replacing a length fL of the curve by a Cornu spiral, whose curvature varies linearly with arclength, such that there is no discontinuity in the curvature of the resulting double spiral.

Parameters:

spiralSpiralPolarBase | SpiralCartesianBase: A spiral object
Lfloat: Arclength of spiral. The double spiral will have arclength 2L.
dsfloat: Spacing along the arclength.
samebool: Whether the spirals are on the same side or not.
end0 | 1: If 0, the s=0 end. If 1, the s=L end.
ffloat: Fraction of the arclength L over which the curvature will be linearized.

Returns:

s_ds, kappa_ds, x_ds, y_dstuple of 1D ndarrays: The arclength coordinates (s_ds), curvatures (kappa_ds), x-coordinates (x_ds), and y-coordinates (y_ds) of the double spiral.

Warning

Linearization may not always be necessary, and in some cases may lead to significant changes in the derivative of the curvature along the arclength.
Depending on the parameters of the spiral and which end is chosen for joining, the double spiral may self-intersect.

ribbon.extrude(xcoords, ycoords, zdist, dz)[source]#

Creates a sheet of monoatomic thickness by extruding a spiral and returns the positions of the atoms of the sheet.

Parameters:

xcoords, ycoords1D array_like: X & Y coordinates of the points on the planar curve.
zdistfloat: Extrusion distance (along z-direction)
dzfloat: Spacing along the z-direction

Returns:

X, Y, Ztuple of 1D ndarrays: Coordinates of the atoms of the sheet.

ribbon package#

Submodules#