SurfaceTopography package

Subpackages

Submodules

SurfaceTopography.Exceptions module

This module contains most exceptions used in SurfaceTopography.

exception SurfaceTopography.Exceptions.CannotPerformAnalysisError

Bases: Exception

Exception raised when an analysis cannot be performed.

exception SurfaceTopography.Exceptions.NoReliableDataError

Bases: CannotPerformAnalysisError

Exception indicates that an analysis has no reliable data and would need to return an empty result.

exception SurfaceTopography.Exceptions.ReentrantDataError

Bases: CannotPerformAnalysisError

Exception indicates that the underlying data is reentrant and that the analysis function does not work on reentrant data.

exception SurfaceTopography.Exceptions.UndefinedDataError

Bases: CannotPerformAnalysisError

Exception indicates that the underlying data has missing (undefined) data points and that the analysis function cannot handle missing data

exception SurfaceTopography.Exceptions.UnknownFileFormat

Bases: Exception

Raised when an unknown file format identifier was provided to a reader function.

exception SurfaceTopography.Exceptions.ReadFileError

Bases: Exception

exception SurfaceTopography.Exceptions.CannotDetectFileFormat

Bases: ReadFileError

Raised when no reader is able to open the file

exception SurfaceTopography.Exceptions.FileFormatMismatch

Bases: ReadFileError

Raised when the reader cannot interpret the file at all (obvious for txt vs binary, but holds also for a header)

exception SurfaceTopography.Exceptions.UnsupportedFormatFeature

Bases: ReadFileError

Raised when the reader detected that this is the correct format, but a file feature was encountered that is not implemented

exception SurfaceTopography.Exceptions.CorruptFile

Bases: ReadFileError

Raised when the reader identifies the file format as matching, but there is a mistake, for example the number of points doesn’t match

exception SurfaceTopography.Exceptions.MetadataAlreadyFixedByFile(kw, alt_msg=None)

Bases: ReadFileError

Raised when instantiating a topography from a reader, given metadata which cannot be overridden, because it is already fixed by the file contents.

__init__(kw, alt_msg=None)
Parameters:

  • kw (str) – Name of the keyword argument to .topography().

  • alt_msg (str or None) – If not None, use this as error message instead of the default one.

SurfaceTopography.FFTTricks module

SurfaceTopography.FFTTricks.make_fft(topography, engine='mpi', communicator=None)

Instantiate a muFFT object that can compute the Fourier transform of the topography and has the same decomposition layout (or raise an error if this is not the case).

This function checks if the topography object already has a muFFT object attached to it. If it does, it returns that object. If it doesn’t, it creates a new muFFT object and attaches it to the topography object. If the topography object is domain decomposed, it checks if the muFFT object’s domain decomposition matches the topography’s. If it doesn’t, it raises a RuntimeError.

Parameters:

  • topography (SurfaceTopography) – Container storing the topography map.

  • engine (str, optional) – The engine to use for the Fourier transform. (Default: ‘mpi’)

  • communicator (mpi4py communicator or NuMPI stub communicator, optional) – Communicator object. Use communicator from topography object if not present. (Default: None)

Returns:

fft – The muFFT object that can compute the Fourier transform of the topography.

Return type:

muFFT.FFT

Raises:

RuntimeError – If the muFFT object’s domain decomposition does not match the topography’s domain decomposition.

SurfaceTopography.FFTTricks.get_window_2D(window, nx, ny, physical_sizes=None)

Construct a rotationally symmetric window for windowing two-dimensional signals (fields).

Parameters:

  • window (str or np.ndarray) – If window is an np.ndarray, it is just passed through (i.e. immediately returned) from this function. If window is a string, then a corresponding window will be constructed. Currently the only support window is ‘hann’.

  • nx (int) – Number of grid points of the signal in x-direction

  • ny (int) – Number of grid points of the signal in y-direction

  • physical_sizes (tuple of float) – The physical size of the underlying signal. If None, then the number of grid points nx, ny are used as the physical size. This parameter is used to adjust the aspect ratio of the signal. (Default: None)

Returns:

window – Numerical window, multiply the signal with this window

Return type:

np.ndarray

SurfaceTopography.Generation module

Helper functions for the generation of random fractal surfaces

SurfaceTopography.Generation.self_affine_prefactor(nb_grid_pts, physical_sizes, Hurst, rms_height=None, rms_slope=None, short_cutoff=None, long_cutoff=None)

Compute prefactor \(C_0\) for the power-spectrum density of an ideal self-affine topography given by

\[C(q) = C_0 q^{-2-2H}\]

for two-dimensional topography maps and

\[C(q) = C_0 q^{-1-2H}\]

for one-dimensional line scans. Here \(H\) is the Hurst exponent.

Note: In the 2D case:

\[h^2_{rms} = \frac{1}{2 \pi} \int_{0}^{\infty} q C^{iso}(q) dq\]

whereas in the 1D case:

\[h^2_{rms} = \frac{1}{\pi} \int_{0}^{\infty} C^{1D}(q) dq\]

See Equations (1) and (4) in [1].

Parameters:

  • nb_grid_pts (array_like) – Resolution of the topography map or the line scan.

  • physical_sizes (array_like) – Physical physical_sizes of the topography map or the line scan.

  • Hurst (float) – Hurst exponent.

  • rms_height (float) – Root mean-squared height.

  • rms_slope (float) – Root mean-squared slope of the topography map or the line scan.

  • short_cutoff (float) – Short-wavelength cutoff.

  • long_cutoff (float) – Long-wavelength cutoff.

Returns:

prefactor – Prefactor \(\sqrt{C_0}\)

Return type:

float

References

[1]: Jacobs, Junge, Pastewka, Surf. Topgogr.: Metrol. Prop. 5, 013001 (2017)

SurfaceTopography.Generation.fourier_synthesis(nb_grid_pts, physical_sizes, hurst=None, rms_height=None, rms_slope=None, c0=None, psd=None, short_cutoff=None, long_cutoff=None, rolloff=1.0, amplitude_distribution=<function <lambda>>, periodic=True, rfn=None, kfn=None, progress_callback=None, unit=None, info={})

Create a self-affine, randomly rough surface using a Fourier filtering algorithm. The algorithm is described in: Ramisetti et al., J. Phys.: Condens. Matter 23, 215004 (2011); Jacobs, Junge, Pastewka, Surf. Topgogr.: Metrol. Prop. 5, 013001 (2017)

Parameters:

  • nb_grid_pts (array_like) – Resolution of the topography map.

  • physical_sizes (array_like) – Physical physical_sizes of the topography map.

  • hurst (float) – Hurst exponent.

  • rms_height (float) – Root mean-squared height.

  • rms_slope (float) – Root mean-squared slope.

  • c0 (float) – self affine prefactor \(C_0\): \(C(q) = C_0 q^{-2-2H}\)

  • psd (callable) – C(q) Function returning the Power Spectral Density as a function of the absolute value of the wavevector

  • short_cutoff (float) – Short-wavelength cutoff.

  • long_cutoff (float) – Long-wavelength cutoff.

  • rolloff (float) – Value for the power-spectral density (PSD) below the long-wavelength cutoff. This multiplies the value at the cutoff, i.e. unit will give a PSD that is flat below the cutoff, zero will give a PSD that is vanishes below cutoff. (Default: 1.0)

  • amplitude_distribution (function) – Function that generates the distribution of amplitudes. (Default: np.random.normal)

  • periodic (bool) – Return a periodic surface. (Default: True)

  • rfn (str) – Name of file that stores the real-space array. If specified, real-space array will be created as a memory mapped file. This is useful for creating very large topography maps. (Default: None)

  • kfn (str) – Name of file that stores the Fourie-space array. If specified, real-space array will be created as a memory mapped file. This is useful for creating very large topography maps. (Default: None)

  • progress_callback (function(i, n)) – Function that is called to report progress.

  • unit (str, optional) – Length unit.

  • info (dict, optional) – Initial info dictionary.

Returns:

topography – The topography.

Return type:

UniformTopography or UniformLineScan

SurfaceTopography.HeightContainer module

Base class for geometric topogography descriptions

class SurfaceTopography.HeightContainer.AbstractTopography(unit=None, info={}, communicator=<NuMPI.MPIStub.Intracomm object>)

Bases: object

Base class for all classes storing height information.

The member dictionary _functions contains a list of functions that can be executed on this specific class.

The dictionary itself is owned by the interface, UniformTopographyInterface and NonuniformLineScanInterface. This is because the functions are determined by the type of topography that is represented, not by the pipeline hierarchy. For example, converters that convert uniform to nonuniform and vice versa need to have the respective interface of the format they are converting to.

exception Error

Bases: Exception

__init__(unit=None, info={}, communicator=<NuMPI.MPIStub.Intracomm object>)
apply(name, *args, **kwargs)
abstract property is_periodic

Return whether the topography is periodically repeated at the boundaries.

abstract property dim

Returns 1 for line scans and 2 for topography maps.

abstract property physical_sizes

Return the physical sizes of the topography.

property unit

Return the length unit of the topography.

property info: dict

Return the info dictionary. The info dictionary contains auxiliary data found in the topography data file but not directly used by SurfaceTopogoraphy.

property communicator

Return the MPI communicator object.

pipeline()
class SurfaceTopography.HeightContainer.DecoratedTopography(topography, unit=None, info={})

Bases: AbstractTopography

Base class of topographies with parent. Having a parent means that the data is owned by the parent, but the present class performs transformations on that data. This is a simple realization of a processing pipeline. Note that child topographies don’t store their own physical_sizes etc. but pass this information through to the parent.

__init__(topography, unit=None, info={})
Parameters:

topography (SurfaceTopography) – The parent topography.

property info: dict

Return info dictionary

property nb_subdomain_grid_pts
pipeline()
class SurfaceTopography.HeightContainer.TopographyInterface

Bases: object

classmethod register_function(name, function, deprecated=False)
class SurfaceTopography.HeightContainer.UniformTopographyInterface

Bases: TopographyInterface

property is_uniform
property is_reentrant
property is_domain_decomposed
property communicator
abstract property nb_grid_pts
abstract property nb_subdomain_grid_pts
abstract property pixel_size
abstract property area_per_pt
abstract property has_undefined_data
abstract positions()

Returns array containing the lateral positions.

abstract heights()

Returns array containing the topography data.

positions_and_heights(**kwargs)

Returns array containing the lateral positions and the topography data.

class SurfaceTopography.HeightContainer.NonuniformLineScanInterface

Bases: TopographyInterface

property is_uniform
property is_reentrant
abstract property nb_grid_pts
abstract property x_range
abstract positions()

Returns array containing the lateral positions.

abstract heights()

Returns array containing the topography data.

positions_and_heights(**kwargs)

Returns array containing the lateral positions and the topography data.

property is_MPI
property has_undefined_data

SurfaceTopography.Metadata module

pydantic models for the info dictionary which stores metadata

class SurfaceTopography.Metadata.ValueAndUnitModel(*, value: float, unit: str)

Bases: BaseModel

value: float
unit: str
model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'unit': FieldInfo(annotation=str, required=True), 'value': FieldInfo(annotation=float, required=True)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

class SurfaceTopography.Metadata.InstrumentParametersModel(*, name: str = None, resolution: ValueAndUnitModel = None, tip_radius: ValueAndUnitModel = None)

Bases: BaseModel

name: str
resolution: ValueAndUnitModel
tip_radius: ValueAndUnitModel
model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'name': FieldInfo(annotation=str, required=False, default=None), 'resolution': FieldInfo(annotation=ValueAndUnitModel, required=False, default=None), 'tip_radius': FieldInfo(annotation=ValueAndUnitModel, required=False, default=None)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

class SurfaceTopography.Metadata.InstrumentModel(*, name: str = None, parameters: InstrumentParametersModel = None)

Bases: BaseModel

name: str
parameters: InstrumentParametersModel
model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'name': FieldInfo(annotation=str, required=False, default=None), 'parameters': FieldInfo(annotation=InstrumentParametersModel, required=False, default=None)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

class SurfaceTopography.Metadata.InfoModel(*, acquisition_time: datetime = None, instrument: InstrumentModel = None, raw_metadata: dict | list = None, channel_name: str = None, datafile: dict = None)

Bases: BaseModel

acquisition_time: datetime
instrument: InstrumentModel
raw_metadata: dict | list
channel_name: str
datafile: dict
model_computed_fields: ClassVar[Dict[str, ComputedFieldInfo]] = {}

A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[Dict[str, FieldInfo]] = {'acquisition_time': FieldInfo(annotation=datetime, required=False, default=None), 'channel_name': FieldInfo(annotation=str, required=False, default=None), 'datafile': FieldInfo(annotation=dict, required=False, default=None), 'instrument': FieldInfo(annotation=InstrumentModel, required=False, default=None), 'raw_metadata': FieldInfo(annotation=Union[dict, list], required=False, default=None)}

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

SurfaceTopography.NonuniformLineScan module

Support for nonuniform topogography descriptions

class SurfaceTopography.NonuniformLineScan.NonuniformLineScan(x, y, unit=None, info={})

Bases: AbstractTopography, NonuniformLineScanInterface

Nonuniform topography with point list consisting of static numpy arrays.

__init__(x, y, unit=None, info={})

Constructor.

Parameters:

  • x (array_like) – x-positions of the data points that sample the line scan.

  • y (array_like) – y-positions of the data points that sample the line scan.

  • unit (str, optional) – The length unit.

  • info (dict, optional) – The info dictionary containing auxiliary data.

property dim

Returns 1 for line scans and 2 for topography maps.

property physical_sizes

Returns distance between maximum and minimum x-value.

property is_periodic

Return whether the topography is periodically repeated at the boundaries.

property nb_grid_pts
property x_range
positions()

Returns array containing the lateral positions.

heights()

Returns array containing the topography data.

squeeze()
class SurfaceTopography.NonuniformLineScan.DecoratedNonuniformTopography(topography, unit=None, info={})

Bases: DecoratedTopography, NonuniformLineScanInterface

property is_periodic

Return whether the topography is periodically repeated at the boundaries.

property dim

Returns 1 for line scans and 2 for topography maps.

property nb_grid_pts
property unit

Return the length unit of the topography.

property info: dict

Return info dictionary

property physical_sizes

Return the physical sizes of the topography.

property x_range
positions()

Returns array containing the lateral positions.

squeeze()
class SurfaceTopography.NonuniformLineScan.ScaledNonuniformTopography(topography, unit, info={})

Bases: DecoratedNonuniformTopography

Scale heights, positions, or both.

__init__(topography, unit, info={})

This topography wraps a parent topography and rescales x and z coordinates according to certain rules.

Parameters:

  • topography (NonuniformTopographyInterface) – Parent topography

  • unit (str) – Target unit.

  • info (dict, optional) – Updated entries to the info dictionary. (Default: {})

property height_scale_factor
property position_scale_factor
property physical_sizes

Compute rescaled physical sizes.

positions()

Compute the rescaled positions.

heights()

Computes the rescaled profile.

class SurfaceTopography.NonuniformLineScan.StaticallyScaledNonuniformTopography(topography, height_scale_factor, position_scale_factor=1, unit=None, info={})

Bases: ScaledNonuniformTopography

Scale heights, positions, or both.

__init__(topography, height_scale_factor, position_scale_factor=1, unit=None, info={})

This topography wraps a parent topography and rescales x and z coordinates according to certain rules.

Parameters:

  • topography (NonuniformTopographyInterface) – Parent topography

  • height_scale_factor (float) – Factor to scale heights with.

  • position_scale_factor (float, optional) – Factor to scale lateral positions (physical_sizes, etc.) with. (Default: 1)

  • unit (str, optional) – Target unit. This is simply used to update the metadata, not for determining scale factors. (Default: None)

  • info (dict, optional) – Updated entries to the info dictionary. (Default: {})

property height_scale_factor
property position_scale_factor

SurfaceTopography.Pipeline module

SurfaceTopography.Special module

Special topographies

SurfaceTopography.Special.make_topography_from_function(fun, physical_sizes, nb_grid_pts=None, subdomain_locations=None, nb_subdomain_grid_pts=None, centre=(0, 0), **kwargs)
Parameters:

  • fun (callable(X, Y))

  • centre (tuple or "middle") – (cx, cy) h(X,Y) = fun(X-cx, Y-cy) default (0,0)

  • physical_sizes (tuple of floats) – Physical physical_sizes of the topography map

  • periodic (bool) – The topography is periodic. (Default: False)

  • decomposition (str) – Specification of the data decomposition of the heights array. If set to ‘subdomain’, the heights array contains only the part of the full topography local to the present MPI process. If set to ‘domain’, the heights array contains the global array. Default: ‘serial’, which fails for parallel runs.

  • nb_grid_pts (tuple of ints) – Number of grid points for the full topography. This is only required if decomposition is set to ‘subdomain’.

  • subdomain_locations (tuple of ints) – Origin (location) of the subdomain handled by the present MPI process.

  • nb_subdomain_grid_pts (tuple of ints) – Number of grid points within the subdomain handled by the present MPI process. This is only required if decomposition is set to ‘domain’.

  • communicator (mpi4py communicator or NuMPI stub communicator) – The MPI communicator object. default value is COMM_SELF because sometimes NON-MPI readers that do not set the communicator value are used in MPI Programs. See discussion in issue #166

  • info (dict) – The info dictionary containing auxiliary data. This data is never used by PyCo but can be used by third-party codes.

Return type:

SurfaceTopography.Topography instance

SurfaceTopography.Special.make_sphere(radius, nb_grid_pts, physical_sizes, centre=None, standoff='undefined', offset=0, periodic=False, kind='sphere', nb_subdomain_grid_pts=None, subdomain_locations=None, communicator=<NuMPI.MPIStub.Intracomm object>)

Simple sphere geometry.

If kind=”sphere” (Default)

\[\begin{split}h = \left\{ \begin{array}{ll} \sqrt{\text{radius}^2 - r^2} - \text{radius} & \text{ for } r < \text{radius} \\ - \text{standoff} & \text{else} \end{array} \right.\end{split}\]

If kind=”paraboloid” the sphere is approximated by a paraboloid

\[h = \frac{r^2}{2 \cdot \text{radius}}\]

\(r^2 = x^2 + y^2\)

Parameters:

  • radius (float) – self-explanatory

  • nb_grid_pts (float) – self-explanatory

  • physical_sizes (float) – self-explanatory

  • centre (float) – specifies the coordinates (in length units, not pixels). by default, the sphere is centred in the topography

  • kind (str) – Options are “sphere” or “paraboloid”. Default is “sphere”.

  • standoff (float or "undefined") –

    when using interaction forces with ranges of the order the radius, you might want to set the topography outside of the sphere to far away, maybe even pay the price of inf, if your interaction has no cutoff

    For standoff=”undefined”, the entries will be masked in the topography and topography.has_undefined_data will be true

    If kind=”paraboloid” the paraboloid approximation is used

    and the standoff is not applied

  • periodic (bool) – whether the sphere can wrap around. tricky for large spheres

  • communicator (mpi4py communicator NuMPI stub communicator) – MPI communicator object.

class SurfaceTopography.Special.PlasticTopography(topography, hardness, plastic_displ=None)

Bases: DecoratedUniformTopography

SurfaceTopography with an additional plastic deformation field.

name = 'plastic_topography'
__init__(topography, hardness, plastic_displ=None)

Keyword Arguments: topography – topography profile hardness – penetration hardness plastic_displ – initial plastic displacements

property hardness
property plastic_displ
undeformed_profile()

Returns the undeformed profile of the topography.

heights()

Computes the combined profile.

property plastic_area

SurfaceTopography.UniformLineScanAndTopography module

Support for uniform topogography descriptions

class SurfaceTopography.UniformLineScanAndTopography.UniformLineScan(heights, physical_sizes, periodic=False, unit=None, info={}, communicator=<NuMPI.MPIStub.Intracomm object>)

Bases: AbstractTopography, UniformTopographyInterface

Line scan that lives on a uniform one-dimensional grid.

__init__(heights, physical_sizes, periodic=False, unit=None, info={}, communicator=<NuMPI.MPIStub.Intracomm object>)
Parameters:

  • profile (array_like) – Data containing the height information. Needs to be a one-dimensional array.

  • physical_sizes (tuple of floats) – Physical physical_sizes of the topography map

  • periodic (bool, optional) – Flag setting the periodicity of the surface

  • unit (str, optional) – The length unit.

  • info (dict, optional) – The info dictionary containing auxiliary data.

property dim

Returns 1 for line scans and 2 for topography maps.

property physical_sizes

Return the physical sizes of the topography.

property is_periodic

Return whether the topography is periodically repeated at the boundaries.

property nb_grid_pts
property nb_subdomain_grid_pts
property is_domain_decomposed
property pixel_size
property area_per_pt
property has_undefined_data
positions(meshgrid=True)

Return grid positions.

Parameters:

meshgrid (bool, optional) – Ignore, for compatibility with two-dimensional topographies

Returns:

x – X-positions

Return type:

np.ndarray

heights()

Returns array containing the topography data.

save(fname, compress=True)

saves the topography as a NumpyTxtTopography. Warning: This only saves the profile; the physical_sizes is not contained in the file

squeeze()
class SurfaceTopography.UniformLineScanAndTopography.Topography(heights, physical_sizes, periodic=False, nb_grid_pts=None, subdomain_locations=None, nb_subdomain_grid_pts=None, unit=None, info={}, decomposition='serial', communicator=<NuMPI.MPIStub.Intracomm object>)

Bases: AbstractTopography, UniformTopographyInterface

Topography that lives on a uniform two-dimensional grid, i.e. a topography map.

__init__(heights, physical_sizes, periodic=False, nb_grid_pts=None, subdomain_locations=None, nb_subdomain_grid_pts=None, unit=None, info={}, decomposition='serial', communicator=<NuMPI.MPIStub.Intracomm object>)
Parameters:

  • heights (array_like) – Data containing the height information. Needs to be a two-dimensional array.

  • physical_sizes (tuple of floats) – Physical physical_sizes of the topography map

  • periodic (bool, optional) – The topography is periodic. (Default: False)

  • nb_grid_pts (tuple of ints, optional) – Number of grid points for the full topography. This is only required if decomposition is set to ‘subdomain’.

  • subdomain_locations (tuple of ints, optional) – Origin (location) of the subdomain handled by the present MPI process.

  • nb_subdomain_grid_pts (tuple of ints, optional) – Number of grid points within the subdomain handled by the present MPI process. This is only required if decomposition is set to ‘domain’.

  • unit (str, optional) – The length unit.

  • info (dict, optional) – The info dictionary containing auxiliary data.

  • decomposition (str, optional) – Specification of the data decomposition of the heights array. If set to ‘subdomain’, the heights array contains only the part of the full topography local to the present MPI process. If set to ‘domain’, the heights array contains the global array. Default: ‘serial’, which fails for parallel runs.

  • communicator (mpi4py communicator or NuMPI stub communicator, optional) – The MPI communicator object. default value is COMM_SELF because sometimes NON-MPI readers that do not set the communicator value are used in MPI Programs. See discussion in issue #166

  • initialisation (Examples for)

  • ----------------------------

  • code (2. Parallel)

  • >>>Topography(heights

  • physical_sizes

  • [periodic

  • info])

  • code

  • data (providing local)

  • >>>Topography(heights – decomposition=’subdomain’, subdomain_locations, nb_grid_pts, comm, [info])

  • physical_sizes – decomposition=’subdomain’, subdomain_locations, nb_grid_pts, comm, [info])

  • [periodic] – decomposition=’subdomain’, subdomain_locations, nb_grid_pts, comm, [info])

:paramdecomposition=’subdomain’,

subdomain_locations, nb_grid_pts, comm, [info])

Parameters:

  • code (3. Parallel)

  • data (providing full)

  • >>>Topography(heights – decomposition=’domain’, subdomain_locations, nb_subdomain_grid_pts, comm, [info])

  • physical_sizes – decomposition=’domain’, subdomain_locations, nb_subdomain_grid_pts, comm, [info])

  • [periodic] – decomposition=’domain’, subdomain_locations, nb_subdomain_grid_pts, comm, [info])

:paramdecomposition=’domain’,

subdomain_locations, nb_subdomain_grid_pts, comm, [info])

property dim

Returns 1 for line scans and 2 for topography maps.

property is_periodic

Return whether the topography is periodically repeated at the boundaries.

property physical_sizes

Return the physical sizes of the topography.

property nb_grid_pts
property nb_subdomain_grid_pts

needs to be testable to make sure that geometry and halfspace are compatible

property subdomain_locations
property subdomain_slices
property pixel_size
property area_per_pt
property has_undefined_data
positions(meshgrid=True)

Return grid positions.

Parameters:

meshgrid (bool, optional) – If True, return the position on the same grid as the heights. Otherwise, return one-dimensional position arrays. (Default: True)

Returns:

  • x (np.ndarray) – X-positions

  • y (np.ndarray) – Y-positions

heights()

Returns array containing the topography data.

positions_and_heights(**kwargs)

Returns array containing the lateral positions and the topography data.

property communicator

Return the MPI communicator object.

squeeze()
class SurfaceTopography.UniformLineScanAndTopography.DecoratedUniformTopography(topography, unit=None, info={})

Bases: DecoratedTopography, UniformTopographyInterface

property has_undefined_data
property is_domain_decomposed
property is_periodic

Return whether the topography is periodically repeated at the boundaries.

property dim

Returns 1 for line scans and 2 for topography maps.

property pixel_size
property unit

Return the length unit of the topography.

property info

Return info dictionary

property physical_sizes

Return the physical sizes of the topography.

property nb_grid_pts
property nb_subdomain_grid_pts

needs to be testable to make sure that geometry and halfspace are compatible

property subdomain_locations
property subdomain_slices
property area_per_pt
positions(**kwargs)

Returns array containing the lateral positions.

positions_and_heights(**kwargs)

Returns array containing the lateral positions and the topography data.

squeeze()
class SurfaceTopography.UniformLineScanAndTopography.ScaledUniformTopography(topography, unit=None, info={})

Bases: DecoratedUniformTopography

Scale heights, positions or both.

__init__(topography, unit=None, info={})

This topography wraps a parent topography and rescales x, y and z coordinates according to certain rules.

Parameters:

  • topography (UniformTopographyInterface) – Parent topography

  • unit (str) – Target unit.

  • info (dict, optional) – Updated entries to the info dictionary. (Default: {})

property height_scale_factor
property position_scale_factor
property pixel_size

Compute rescaled pixel sizes.

property physical_sizes

Compute rescaled physical sizes.

property area_per_pt

Compute rescaled physical sizes.

positions(**kwargs)

Compute the rescaled positions.

heights()

Computes the rescaled profile.

class SurfaceTopography.UniformLineScanAndTopography.StaticallyScaledUniformTopography(topography, height_scale_factor, position_scale_factor=1, unit=None, info={})

Bases: ScaledUniformTopography

Scale heights, positions or both.

__init__(topography, height_scale_factor, position_scale_factor=1, unit=None, info={})

This topography wraps a parent topography and rescales x, y and z coordinates according to certain rules.

Parameters:

  • topography (UniformTopographyInterface) – Parent topography

  • height_scale_factor (float) – Factor to scale heights with.

  • position_scale_factor (float, optional) – Factor to scale lateral positions (physical_sizes, etc.) with. (Default: 1)

  • unit (str, optional) – Target unit. This is simply used to update the metadata, not for determining scale factors. (Default: None)

  • info (dict, optional) – Updated entries to the info dictionary. (Default: {})

property height_scale_factor
property position_scale_factor
class SurfaceTopography.UniformLineScanAndTopography.TransposedUniformTopography(topography, info={})

Bases: DecoratedUniformTopography

Tranpose topography.

__init__(topography, info={})
Parameters:

  • topography (UniformTopography) – SurfaceTopography to transpose

  • info (dict) – Additional entries for the info dictionary

property nb_grid_pts

Return number of points

property physical_sizes

Return physical physical_sizes

heights()

Computes the rescaled profile.

positions(**kwargs)

Returns array containing the lateral positions.

class SurfaceTopography.UniformLineScanAndTopography.TranslatedTopography(topography, offset=(0, 0), info={})

Bases: DecoratedUniformTopography

used when geometries are translated

name = 'translated_topography'
__init__(topography, offset=(0, 0), info={})

Keyword Arguments: topography – SurfaceTopography to translate offset – Translation offset in number of grid points

property offset
heights()

Computes the translated profile.

class SurfaceTopography.UniformLineScanAndTopography.CompoundTopography(topography_a, topography_b, info={})

Bases: DecoratedUniformTopography

used when geometries are combined

name = 'compound_topography'
__init__(topography_a, topography_b, info={})

Behaves like a topography that is a sum of two Topographies Keyword Arguments: topography_a – first topography of the compound topography_b – second topography of the compound

heights()

Computes the combined profile

SurfaceTopography.Version module

Module contents

defines all surface types used in SurfaceTopography