Skip to content

surface.py

Surfaces 


              flowchart TD
              erosionfront.geomorphic.surface.Surfaces[Surfaces]

              

              click erosionfront.geomorphic.surface.Surfaces href "" "erosionfront.geomorphic.surface.Surfaces"

Surface-type enumeration.

Attributes

SL: str = "straight-line" Segmented flat-ramp-flat straight-line model. ERF: str = "error-function" Smooth-step model computed using an error function. SCA: str = "semicircular-arc" 180º half-circle arc, i.e., with 50% overhang. SCA: str = "quartercircular-arc" 90º quarter-circle arc.

SurfaceMethods dataclass 

SurfaceMethods(
    type: str = "",
    label: str = "",
    n_pts: int = 1001,
    height: float = 1,
    steepness: float = 10,
    x_left: float = -1,
    x_right: float = +1,
    x_center: float = 0,
    do_anchor_ends: bool = True,
    x: NDArray | None = None,
    z: NDArray | None = None,
)

Base class providing geometric tools for surface model classes.

Parameters

n_pts: int = 1001 Number of sample points along the surface. height: float = 1 Maximum height of surface function above zero base-level. steepness: float = 10 Steepness factor used in straight-line and error-function surfaces. x_left: float = -1 Left-most x coordinate for sampling x_right: float = +1 Right-most x coordinate for sampling. x_center: float = 0 Central x coordinate in error-function surface (point of symmetry). do_anchor_ends: bool = True Fix the left and right end z-values at 0 and height respectively.

Attributes

type: str = "" Surface type (long-form). One of: straight-line, error-function, semicircular-arc, quartercircular-arc. Set by choose_surface. label: str = "" Surface type (short-form). Set by choose_surface. n_pts: int = 1001 Number of sample points along the surface. height: float = 1 Maximum height of surface function above zero base-level. steepness: float = 10 Steepness factor used in straight-line and error-function surfaces. x_left: float = -1 Left-most x coordinate for sampling x_right: float = +1 Right-most x coordinate for sampling. x_center: float = 0 Central x coordinate in error-function surface (point of symmetry). do_anchor_ends: bool = True Fix the left and right end z-values at 0 and height respectively. x: NDArray | None = None Sample x coordinates along the surface. z: NDArray | None = None Sample z coordinates along the surface.

Methods:

  • __post_init__ –

    Complete instantiation by computing surface angle β along the curve.

  • get_points_xz –

    Stack x,z arrays of N points into a single (N,2) array.

__post_init__ 

__post_init__() -> None

Complete instantiation by computing surface angle β along the curve.

Attributes

β: NDArray Angle of surface computed by taking arctan of gradient of x and z coordinates wrt index.

Source code in erosionfront/geomorphic/surface.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
def __post_init__(self) -> None:
    """
    Complete instantiation by computing surface angle β along the curve.

    Attributes
    ----------
    β: NDArray
        Angle of surface computed by taking arctan of gradient of x and z
        coordinates wrt index.
    """
    if self.do_anchor_ends:
        if self.z is not None:
            self.z[0] = min(0, self.z[0])
            self.z[-1] = max(self.height, self.z[-1])
        else:
            raise ValueError("z array not assigned yet")
    if self.type not in Surfaces._value2member_map_.keys():
        raise ValueError("Invalid surface type")
    surface_types: dict = {
        Surfaces.SL : "SL",
        Surfaces.ERF : "ERF",
        Surfaces.SCA : "SCA",
        Surfaces.QCA : "QCA",
    }
    self.label = surface_types[self.type]
    self.β: NDArray \
        = np.arctan2(np.gradient(self.z), np.gradient(self.x)) #type: ignore

get_points_xz 

get_points_xz() -> NDArray

Stack x,z arrays of N points into a single (N,2) array.

Attributes

Uses x and z array attributes.

Returns

NDArray: (x,z) point vector array with shape (N,2).

Source code in erosionfront/geomorphic/surface.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def get_points_xz(self) -> NDArray:
    """
    Stack x,z arrays of N points into a single (N,2) array.

    Attributes
    ----------
    Uses x and z array attributes.

    Returns
    -------
    NDArray:
        (x,z) point vector array with shape (N,2).
    """
    return np.vstack([self.x, self.z]).T   #type: ignore

StraightLineSurface dataclass 

StraightLineSurface(
    type: str = "",
    label: str = "",
    n_pts: int = 1001,
    height: float = 1,
    steepness: float = 10,
    x_left: float = -1,
    x_right: float = +1,
    x_center: float = 0,
    do_anchor_ends: bool = True,
    x: NDArray | None = None,
    z: NDArray | None = None,
)


              flowchart TD
              erosionfront.geomorphic.surface.StraightLineSurface[StraightLineSurface]
              erosionfront.geomorphic.surface.SurfaceMethods[SurfaceMethods]

                              erosionfront.geomorphic.surface.SurfaceMethods --> erosionfront.geomorphic.surface.StraightLineSurface
                


              click erosionfront.geomorphic.surface.StraightLineSurface href "" "erosionfront.geomorphic.surface.StraightLineSurface"
              click erosionfront.geomorphic.surface.SurfaceMethods href "" "erosionfront.geomorphic.surface.SurfaceMethods"

Synthesize a very simple straight line surface.

Attributes

Modifies x,z atributes. See Methods parent class for more details.

Returned by: Used by:

Methods:

  • __post_init__ –

    Generate x and z arrays for the surface.

  • get_points_xz –

    Stack x,z arrays of N points into a single (N,2) array.

__post_init__ 

__post_init__() -> None

Generate x and z arrays for the surface.

Attributes

Uses model parameter attributes and modifies x,z array attributes.

Source code in erosionfront/geomorphic/surface.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
def __post_init__(self) -> None:
    """
    Generate x and z arrays for the surface.        

    Attributes
    ----------
    Uses model parameter attributes and modifies x,z array attributes.
    """
    self.x = np.linspace(self.x_left, self.x_right, self.n_pts)
    x_offset: float = -0.5/self.steepness
    self.z = (self.x-x_offset)*self.steepness * self.height
    self.z[self.z>self.height] = self.height
    self.z[self.z<0] = 0
    super().__post_init__()

get_points_xz 

get_points_xz() -> NDArray

Stack x,z arrays of N points into a single (N,2) array.

Attributes

Uses x and z array attributes.

Returns

NDArray: (x,z) point vector array with shape (N,2).

Source code in erosionfront/geomorphic/surface.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def get_points_xz(self) -> NDArray:
    """
    Stack x,z arrays of N points into a single (N,2) array.

    Attributes
    ----------
    Uses x and z array attributes.

    Returns
    -------
    NDArray:
        (x,z) point vector array with shape (N,2).
    """
    return np.vstack([self.x, self.z]).T   #type: ignore

ErrorFunctionSurface dataclass 

ErrorFunctionSurface(
    type: str = "",
    label: str = "",
    n_pts: int = 1001,
    height: float = 1,
    steepness: float = 10,
    x_left: float = -1,
    x_right: float = +1,
    x_center: float = 0,
    do_anchor_ends: bool = True,
    x: NDArray | None = None,
    z: NDArray | None = None,
    trend: float = 0,
)


              flowchart TD
              erosionfront.geomorphic.surface.ErrorFunctionSurface[ErrorFunctionSurface]
              erosionfront.geomorphic.surface.SurfaceMethods[SurfaceMethods]

                              erosionfront.geomorphic.surface.SurfaceMethods --> erosionfront.geomorphic.surface.ErrorFunctionSurface
                


              click erosionfront.geomorphic.surface.ErrorFunctionSurface href "" "erosionfront.geomorphic.surface.ErrorFunctionSurface"
              click erosionfront.geomorphic.surface.SurfaceMethods href "" "erosionfront.geomorphic.surface.SurfaceMethods"

Synthesize a smoothed-step surface profile using an error function.

Parameters

gradient: float = 0 do_anchor_ends: bool = True

Attributes

Set by parameters.

Returned by: Used by:

Methods:

  • __post_init__ –

    Generate x and z arrays for the model surface.

  • get_points_xz –

    Stack x,z arrays of N points into a single (N,2) array.

  • shape_fn –

    Compute z(x) value(s) for a error-function surface profile.

__post_init__ 

__post_init__() -> None

Generate x and z arrays for the model surface.

Attributes

Uses model parameter attributes and modifies x,z array attributes.

Source code in erosionfront/geomorphic/surface.py 
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
def __post_init__(self) -> None:
    """
    Generate x and z arrays for the model surface.        

    Attributes
    ----------
    Uses model parameter attributes and modifies x,z array attributes.
    """
    self.x = np.linspace(self.x_left, self.x_right, self.n_pts,)
    self.z = (
        self.height * np.array(
            self.shape_fn(
                self.x, self.x_center, self.steepness, self.trend
            )
        )
    )
    super().__post_init__()

get_points_xz 

get_points_xz() -> NDArray

Stack x,z arrays of N points into a single (N,2) array.

Attributes

Uses x and z array attributes.

Returns

NDArray: (x,z) point vector array with shape (N,2).

Source code in erosionfront/geomorphic/surface.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def get_points_xz(self) -> NDArray:
    """
    Stack x,z arrays of N points into a single (N,2) array.

    Attributes
    ----------
    Uses x and z array attributes.

    Returns
    -------
    NDArray:
        (x,z) point vector array with shape (N,2).
    """
    return np.vstack([self.x, self.z]).T   #type: ignore

shape_fn staticmethod 

shape_fn(x: float | NDArray, x0: float, s: float, t: float) -> float | NDArray

Compute z(x) value(s) for a error-function surface profile.

Parameters

x: float | NDArray x0: float s: float t: float

Returns

float | NDArray: Array (or single value) for z(x) for erf-type step function.

Source code in erosionfront/geomorphic/surface.py 
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
@staticmethod
def shape_fn(
        x: float | NDArray, 
        x0: float, 
        s: float, 
        t: float,
    ) -> float | NDArray:
    """
    Compute z(x) value(s) for a error-function surface profile.

    Parameters
    ----------
    x: float | NDArray
    x0: float
    s: float
    t: float

    Returns
    -------
    float | NDArray:
        Array (or single value) for z(x) for erf-type step function.
    """
    return ((1 + erf((x-x0)*s))/2 + x*t)

SemiCircularArcSurface dataclass 

SemiCircularArcSurface(
    type: str = "",
    label: str = "",
    n_pts: int = 1001,
    height: float = 1,
    steepness: float = 10,
    x_left: float = -1,
    x_right: float = +1,
    x_center: float = 0,
    do_anchor_ends: bool = True,
    x: NDArray | None = None,
    z: NDArray | None = None,
)


              flowchart TD
              erosionfront.geomorphic.surface.SemiCircularArcSurface[SemiCircularArcSurface]
              erosionfront.geomorphic.surface.SurfaceMethods[SurfaceMethods]

                              erosionfront.geomorphic.surface.SurfaceMethods --> erosionfront.geomorphic.surface.SemiCircularArcSurface
                


              click erosionfront.geomorphic.surface.SemiCircularArcSurface href "" "erosionfront.geomorphic.surface.SemiCircularArcSurface"
              click erosionfront.geomorphic.surface.SurfaceMethods href "" "erosionfront.geomorphic.surface.SurfaceMethods"

Synthesize a circular arc surface.

Attributes

Modifies x,z atributes. See Methods parent class for more details.

Returned by: Used by:

Methods:

  • __post_init__ –

    Generate x and z arrays for the surface.

  • get_points_xz –

    Stack x,z arrays of N points into a single (N,2) array.

__post_init__ 

__post_init__() -> None

Generate x and z arrays for the surface.

Attributes

Uses model parameter attributes and modifies x,z array attributes.

Source code in erosionfront/geomorphic/surface.py 
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
def __post_init__(self) -> None:
    """
    Generate x and z arrays for the surface.

    Attributes
    ----------
    Uses model parameter attributes and modifies x,z array attributes.
    """
    radius: float = self.height/2
    n_pts_left: int = int(
        (0-self.x_left)/(self.x_right-self.x_left+np.pi*radius) 
        * self.n_pts
    )
    n_pts_arc: int = int(
        np.pi*radius/(self.x_right-self.x_left+np.pi*radius) 
        * self.n_pts
    )
    n_pts_right: int = int(
        (self.x_right-0)/(self.x_right-self.x_left+np.pi*radius) 
        * self.n_pts
    )
    θ: NDArray = np.linspace(0, np.pi, n_pts_arc,)
    self.x = np.hstack([
        np.linspace(self.x_left, 0, n_pts_left,),
        np.sin(θ)*radius,
        np.linspace(0, self.x_right, n_pts_right)
    ])
    self.z = np.hstack([
        np.zeros(n_pts_left,),
        (1-np.cos(θ))*radius,
        np.ones(n_pts_right)*radius*2
    ])
    super().__post_init__()

get_points_xz 

get_points_xz() -> NDArray

Stack x,z arrays of N points into a single (N,2) array.

Attributes

Uses x and z array attributes.

Returns

NDArray: (x,z) point vector array with shape (N,2).

Source code in erosionfront/geomorphic/surface.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def get_points_xz(self) -> NDArray:
    """
    Stack x,z arrays of N points into a single (N,2) array.

    Attributes
    ----------
    Uses x and z array attributes.

    Returns
    -------
    NDArray:
        (x,z) point vector array with shape (N,2).
    """
    return np.vstack([self.x, self.z]).T   #type: ignore

QuarterCircularArcSurface dataclass 

QuarterCircularArcSurface(
    type: str = "",
    label: str = "",
    n_pts: int = 1001,
    height: float = 1,
    steepness: float = 10,
    x_left: float = -1,
    x_right: float = +1,
    x_center: float = 0,
    do_anchor_ends: bool = True,
    x: NDArray | None = None,
    z: NDArray | None = None,
)


              flowchart TD
              erosionfront.geomorphic.surface.QuarterCircularArcSurface[QuarterCircularArcSurface]
              erosionfront.geomorphic.surface.SurfaceMethods[SurfaceMethods]

                              erosionfront.geomorphic.surface.SurfaceMethods --> erosionfront.geomorphic.surface.QuarterCircularArcSurface
                


              click erosionfront.geomorphic.surface.QuarterCircularArcSurface href "" "erosionfront.geomorphic.surface.QuarterCircularArcSurface"
              click erosionfront.geomorphic.surface.SurfaceMethods href "" "erosionfront.geomorphic.surface.SurfaceMethods"

Synthesize a circular arc surface.

Attributes

Modifies x,z atributes. See Methods parent class for more details.

Returned by: Used by:

Methods:

  • __post_init__ –

    Generate x and z arrays for the surface.

  • get_points_xz –

    Stack x,z arrays of N points into a single (N,2) array.

__post_init__ 

__post_init__() -> None

Generate x and z arrays for the surface.

Attributes

Uses model parameter attributes and modifies x,z array attributes.

Source code in erosionfront/geomorphic/surface.py 
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
def __post_init__(self) -> None:
    """
    Generate x and z arrays for the surface.

    Attributes
    ----------
    Uses model parameter attributes and modifies x,z array attributes.
    """
    n_pts_left: int = int(
        (0-self.x_left)/(self.x_right-self.x_left) * self.n_pts
    )
    n_pts_arc: int = int(
        self.height/(self.x_right-self.x_left) * self.n_pts
    )
    n_pts_right: int = int(
        (self.x_right-self.height)/(self.x_right-self.x_left) * self.n_pts
    )
    θ: NDArray = np.linspace(0, np.pi/2, n_pts_arc,)
    self.x = np.hstack([
        np.linspace(self.x_left, 0, n_pts_left,),
        np.sin(θ)* self.height,
        np.linspace(self.height, self.x_right, n_pts_right)
    ])
    self.z = np.hstack([
        np.zeros(n_pts_left,),
        (1-np.cos(θ))*self.height,
        np.ones(n_pts_right)*self.height
    ])
    super().__post_init__()

get_points_xz 

get_points_xz() -> NDArray

Stack x,z arrays of N points into a single (N,2) array.

Attributes

Uses x and z array attributes.

Returns

NDArray: (x,z) point vector array with shape (N,2).

Source code in erosionfront/geomorphic/surface.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def get_points_xz(self) -> NDArray:
    """
    Stack x,z arrays of N points into a single (N,2) array.

    Attributes
    ----------
    Uses x and z array attributes.

    Returns
    -------
    NDArray:
        (x,z) point vector array with shape (N,2).
    """
    return np.vstack([self.x, self.z]).T   #type: ignore

choose_surface 

choose_surface(
    parameters: dict,
) -> (
    StraightLineSurface
    | ErrorFunctionSurface
    | SemiCircularArcSurface
    | QuarterCircularArcSurface
)

Choose initial surface function.

Parameters

dict: Dictionary of keyword arguments to be passed to instantiate a surface class. Choice of surface type is specified in the parameters['type'] element.

Returns

StraightLineSurface | ErrorFunctionSurface | SemiCircularArcSurface | QuarterCircularArcSurface: One of these surface function classes. Instantiation takes **parameters as keyword arguments.

Source code in erosionfront/geomorphic/surface.py 
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
def choose_surface(parameters: dict,) -> (
          StraightLineSurface
        | ErrorFunctionSurface
        | SemiCircularArcSurface
        | QuarterCircularArcSurface
    ):
    """
    Choose initial surface function.

    Parameters
    ----------
    dict: 
        Dictionary of keyword arguments to be passed to instantiate
        a surface class. Choice of surface type is specified in
        the `parameters['type']` element.

    Returns
    -------
    StraightLineSurface | ErrorFunctionSurface | SemiCircularArcSurface \
        | QuarterCircularArcSurface:
        One of these surface function classes.
        Instantiation takes `**parameters` as keyword arguments.
    """
    surfaces: dict = {
        Surfaces.SL : StraightLineSurface,
        Surfaces.ERF : ErrorFunctionSurface,
        Surfaces.SCA : SemiCircularArcSurface,
        Surfaces.QCA : QuarterCircularArcSurface,
    }
    return surfaces[parameters["type"]](**parameters)