sphractal.boxCnt

Module Contents

Functions

findSlope(scales, counts[, npName, outDir, trimLen, ...])

Compute the slope (box counting dimension) from the box-counting data collected.

runBoxCnt(inpFilePath[, radType, radMult, calcBL, ...])

Run box-counting algorithm on the surface of a given atomistic object consisting of a set of spheres represented as either a voxelised point cloud or mathematically precise object.
sphractal.boxCnt.findSlope(scales, counts, npName='', outDir='outputs', trimLen=True, minSample=6, confLvl=95, visReg=True, figType='paper', saveFig=False, showPlot=False, verbose=False)[source]

Compute the slope (box counting dimension) from the box-counting data collected.

Parameters:

  • scales (list of floats) – Box lengths.

  • counts (list of floats) – Number of boxes that cover the exact spherical surface of interest.

  • npName (str, optional) – Identifier of the measured object, which forms part of the output file name, ideally unique.

  • outDir (str, optional) – Path to the directory to store the output files.

  • trimLen (bool, optional) – Whether to remove the box counts obtained using boxes of extreme sizes.

  • minSample (int, optional) – Minimum number of box count data points to be retained for slope estimation from the linear regression fitting.

  • confLvl (Union[int, float]) – Confidence level of confidence interval in percentage.

  • visReg (bool, optional) – Whether to generate figures from the linear regression fitting process.

  • figType ({'paper', 'poster', 'talk'}) – Type of figures to be generated.

  • saveFig (bool, optional) – Whether to save the final figure generated, only works when ‘visReg’ is True.

  • showPlot (bool, optional) – Whether to show the figures generated, only works when ‘visReg’ is True.

  • verbose (bool, optional) – Whether to display the details.

Returns:

  • r2score (float) – Coefficient of determination from determination of the dimension of point clouds surface.

  • boxCntDim (float) – Box-counting dimension of the point clouds representation of the surface.

  • slopeCI (1D ndarray of floats) – Confidence interval of the box-counting dimension of the point clouds surface.

  • minMaxLens (tuple of floats) – Minimum and maximum box lengths used to determine slope.

sphractal.boxCnt.runBoxCnt(inpFilePath, radType='atomic', radMult=1.2, calcBL=False, findSurfAlg='alphaShape', alphaMult=2.0, bulkCN=12, outDir='outputs', trimLen=True, minSample=6, confLvl=95, rmInSurf=True, vis=True, figType='paper', saveFig=False, showPlot=False, verbose=False, voxelSurf=True, numPoints=10000, gridNum=1024, exePath='$FASTBC', genPCD=False, exactSurf=True, minLenMult=0.25, maxLenMult=1, numCPUs=8, numBoxLen=10, bufferDist=5.0, writeBox=True)[source]

Run box-counting algorithm on the surface of a given atomistic object consisting of a set of spheres represented as either a voxelised point cloud or mathematically precise object.

Parameters:

  • inpFilePath (str) – Path to xyz file containing Cartesian coordinates of a set of atoms.

  • radType ({'atomic', 'metallic'}, optional) – Type of radii to use for the atoms.

  • radMult (Union[int, float], optional) – Multiplier to the radii of atoms to identify their neighbouring atoms.

  • calcBL (bool, optional) – Whether to compute the average distance from its neighbours for each atom.

  • findSurfAlg ({'alphaShape', 'convexHull', 'numNeigh'}, optional) – Algorithm to identify the surface atoms.

  • alphaMult (Union[int, float], optional) – Multiplier to the minimum radius to decide ‘alpha’ value for the alpha shape algorithm, only used if ‘findSurfAlg’ is ‘alphaShape’. Recommendation: 2.0 * 100% ATOMIC_RAD == 5/3 * 120% ATOMIC_RAD ~= 100% METALLIC_RAD * 2.5

  • bulkCN (int, optional) – Minimum number of neighbouring atoms for non-surface atoms.

  • outDir (str, optional) – Path to directory to store the output files.

  • trimLen (bool, optional) – Whether to remove the box counts obtained using boxes of extreme sizes.

  • minSample (int, optional) – Minimum number of data points to retain for slope estimation from the linear regression fitting.

  • confLvl (Union[int, float], optional) – Confidence level of confidence intervals (%).

  • rmInSurf (bool, optional) – Whether to remove the inner surface points.

  • vis (bool, optional) – Whether to generate files for visualisation.

  • figType ({'paper', 'poster', 'talk', 'notebook'}) – Research purpose of the figures generated.

  • saveFig (bool, optional) – Whether to save the figures generated from linear regression fitting, only used if ‘vis’ is True.

  • showPlot (bool, optional) – Whether to show the figures generated from linear regression fitting, only used if ‘vis’ is True.

  • verbose (bool, optional) – Whether to display the details.

  • voxelSurf (bool, optional) – Whether to represent the surface as voxelised point clouds.

  • numPoints (int, optional) – Number of surface points to generate around each atom.

  • gridNum (int, optional) – Resolution of the 3D binary image.

  • exePath (str, optional) – Path to the compiled executable of the C++ code for box-counting on 3D binary image written by Ruiz de Miras et al.

  • genPCD (bool, optional) – Whether to generate point cloud data (pcd) file.

  • exactSurf (bool, optional) – Whether to represent the surface in a mathematically exact manner.

  • minLenMult (float, optional) – Multiplier to the minimum radius to determine the minimum box length.

  • maxLenMult (float, optional) – Multiplier to the maximum radius to determine the maximum box length.

  • numCPUs (int, optional) – Number of cores to be used for parallelisation.

  • numBoxLen (int, optional) – Number of box length samples for the collection of the box count data, spaced evenly on logarithmic scale.

  • bufferDist (Union[int,float]) – Buffer distance from the borders of the largest box (Angstrom).

  • writeBox (bool, optional) – Whether to generate output file containing coordinates of examined boxes.

Returns:

  • r2VX (float) – Coefficient of determination from linear regression fitting to the box-counting data obtained from the voxelised point cloud surface representation.

  • bcDimVX (float) – Box-counting dimension of the voxelised point cloud representation of the surface.

  • confIntVX (1D ndarray of floats) – Confidence interval of the slope estimated for the voxelised point cloud surface representation.

  • minMaxLensVX (tuple of floats) – Minimum and maximum box lengths for the final slope determination for the voxelised point cloud surface representation.

  • r2EX (float) – Coefficient of determination from linear regression fitting to the box-counting data obtained from the mathematically exact surface representation.

  • bcDimEX (float) – Box-counting dimension of the mathematically exact representation of the surface.

  • confIntEX (1D ndarray of floats) – Confidence interval of the slope estimated for the mathematically exact surface representation.

  • minMaxLensEX (tuple of floats) – Minimum and maximum box lengths for final slope determination for the mathematically exact surface representation.

Examples

>>> r2VX, bcDimVX, confIntVX, minMaxLensVX, r2EX, bcDimEX, confIntEX, minMaxLensEX = runBoxCnt('example.xyz')