Sphractal

ci-cd

Description

Sphractal is a package that provides functionalities to estimate the fractal dimension of complex 3D surfaces formed from overlapping spheres via box-counting algorithm.

Background

  • Atomic objects in molecular and nanosciences such are often represented as collection of spheres with radii associated with the atomic radius of the individual component.

  • Some examples of these objects (inclusive of both fine- and coarse-grained representation of the individual components) are small molecules, proteins, nanoparticles, polymers, and porous materials such as zeolite, metal-organic framework (MOFs).

  • The overall properties of these objects are often significantly influenced by their surface properties, in particular the surface area available for interaction with other entities, which is related to the surface roughness.

  • Fractal dimension allows the surface complexity/roughness of objects to be measured quantitatively.

  • The fractal dimension could be estimated by applying the box-counting algorithm on surfaces represented as either:

    • approximated point cloud:

  • that are subsequently voxelised:

  • or mathematically exact surfaces:

Features

Aims

  • Representation of the surface as either voxelised point clouds or mathematically exact surfaces.

  • Efficient algorithm for 3D box-counting calculations.

  • Customisable parameters to control the level of detail and accuracy of the calculation.

Installation

Use pip or conda to install Sphractal:

pip install sphractal

conda install -c conda-forge sphractal

Special Requirement for Point Cloud Surface Representation

Sphractal requires an executable compiled from another freely available repository for the functionalities related to voxelised point clouds surface representation to operate properly.

This could be done by:

  • Downloading the source code from the repository to a directory of your choice:

git clone https://github.com/jon-ting/fastbc.git

  • Building an executable by doing either one of the following compilations according to the instructions on the README.md page. This will decide whether you will be running the box counting algorithm with GPU acceleration. Feel free to rename the executables:

g++ 3DbinImBCcpu.cpp bcCPU.cpp -o 3DbinImBCcpu.exe

nvcc -O3 3DbinImBCgpu.cpp bcCUDA3D.cu -o 3DbinImBCgpu.exe

  • (Optional) Setting the path to the executable as an environment variable accessible by Python (replace <PATH_TO_EXE> by the absolute path to the executable file you just built), otherwise you could always pass the path to the executable to the relevant functions:

export FASTBC=<PATH_TO_EXE>

Note that for the environment variable to be persistent (to still exist after the terminal is closed), the line should be added to your ~/.bashrc.

Usage

from sphractal import getExampleDataPath, runBoxCnt

inpFile = getExampleDataPath()  # Replace with the path to your xyz or lmp file
boxCntResults = runBoxCnt(inpFile)

Check out the notebook tutorial for further explanations and demonstrations!

Documentation

Detailed documentations are hosted by Read the Docs.

Contributing

Sphractal appreciates your enthusiasm and welcomes your expertise!

Please check out the contributing guidelines and code of conduct. By contributing to this project, you agree to abide by its terms.

License

The project is distributed under an MIT License.

Credits

The package was created with cookiecutter using the py-pkgs-cookiecutter template. The speeding up of the inner functions via just-in-time compilations with Numba was inspired by the advice received during the NCI-NVIDIA Open Hackathon 2023.

Contact

Email: Jonathan.Ting@anu.edu.au/jonting97@gmail.com

Feel free to reach out if you have any questions, suggestions, or feedback.