# Sphractal
[](https://github.com/Jon-Ting/sphractal/actions/workflows/ci-cd.yml)
## 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`:
```bash
pip install sphractal
```
```bash
conda install -c conda-forge sphractal
```
### Special Requirement for Point Cloud Surface Representation
`Sphractal` requires a file 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](https://github.com/Jon-Ting/fastbc.git) to a directory of your choice:
```bash
git clone https://github.com/jon-ting/fastbc.git
```
* Compile the code into an executable file (which works on any operating system) by doing either one of the following compilations according to the instructions on the [README.md](https://github.com/Jon-Ting/fastBC/blob/main/README.md) page. This will decide whether you will be running the box counting algorithm with GPU acceleration. Feel free to rename the output file from the compilation:
```bash
g++ 3DbinImBCcpu.cpp bcCPU.cpp -o 3DbinImBCcpu
```
```bash
nvcc -O3 3DbinImBCgpu.cpp bcCUDA3D.cu -o 3DbinImBCgpu
```
* (Optional) Setting the path to the compiled file as an environment variable accessible by Python (replace `<PATH_TO_FASTBC>` by the absolute path to the executable file you just built), otherwise you could always pass the path to the compiled file to the relevant functions:
```bash
export FASTBC=<PATH_TO_FASTBC>
```
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
```python
from sphractal import getExampleDataPath, runBoxCnt
inpFile = getExampleDataPath() # Replace with the path to your xyz or lmp file
boxCntResults = runBoxCnt(inpFile)
```
Check out the [basic demonstration](https://github.com/Jon-Ting/sphractal/blob/main/docs/basicDemo.ipynb) and [application demonstration](https://github.com/Jon-Ting/sphractal/blob/main/docs/applicationsDemo.ipynb) notebooks for further explanations and demonstrations!
## Documentation
Detailed [documentations](https://sphractal.readthedocs.io/en/latest/) are hosted by `Read the Docs`.
## Contributing
`Sphractal` appreciates your enthusiasm and welcomes your expertise!
Please check out the [contributing guidelines](https://github.com/Jon-Ting/sphractal/blob/main/CONTRIBUTING.md) and
[code of conduct](https://github.com/Jon-Ting/sphractal/blob/main/CONDUCT.md).
By contributing to this project, you agree to abide by its terms.
## License
The project is distributed under an [MIT License](https://github.com/Jon-Ting/sphractal/blob/main/LICENSE).
## Credits
The package was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) using the
`py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).
The speeding up of the inner functions via just-in-time compilations with [Numba](https://numba.pydata.org/) was inspired by the advice received during the [NCI-NVIDIA Open Hackathon 2023](https://opus.nci.org.au/display/Help/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.
Raw data
{
"_id": null,
"home_page": "https://github.com/Jon-Ting/sphractal",
"name": "sphractal",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "box-counting, box-count, fractal, dimension, sphere, surface",
"author": "Jonathan Yik Chang Ting",
"author_email": "jonting97@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2b/ae/0e997edffefdd89225f58e583f10baffb56e8e8e7e1e596d9c7076efaa56/sphractal-1.1.5.tar.gz",
"platform": null,
"description": "# Sphractal\n\n[](https://github.com/Jon-Ting/sphractal/actions/workflows/ci-cd.yml)\n\n## Description\n\n`Sphractal` is a package that provides functionalities to estimate the fractal dimension of complex 3D surfaces formed from overlapping spheres via box-counting algorithm. \n\n## Background\n* 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.\n\n\n\n* Some examples of these objects (inclusive of both fine- and coarse-grained representation of the individual components) \nare small molecules, proteins, nanoparticles, polymers, and porous materials such as zeolite, metal-organic framework (MOFs).\n* 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.\n* Fractal dimension allows the surface complexity/roughness of objects to be measured quantitatively.\n* The fractal dimension could be estimated by applying the box-counting algorithm on surfaces represented as either:\n * approximated point cloud:\n\n\n\n * that are subsequently voxelised:\n\n\n\n * or mathematically exact surfaces:\n\n\n\n## Features\n\n### Aims\n* Representation of the surface as either voxelised point clouds or mathematically exact surfaces.\n* Efficient algorithm for 3D box-counting calculations.\n* Customisable parameters to control the level of detail and accuracy of the calculation.\n\n## Installation\n\nUse `pip` or `conda` to install `Sphractal`:\n\n```bash\npip install sphractal\n```\n```bash\nconda install -c conda-forge sphractal\n```\n\n### Special Requirement for Point Cloud Surface Representation\n`Sphractal` requires a file compiled from another freely available repository for the functionalities related to voxelised point clouds surface representation to operate properly. \n\nThis could be done by:\n\n* Downloading the source code from the [repository](https://github.com/Jon-Ting/fastbc.git) to a directory of your choice:\n```bash\ngit clone https://github.com/jon-ting/fastbc.git\n```\n\n* Compile the code into an executable file (which works on any operating system) by doing either one of the following compilations according to the instructions on the [README.md](https://github.com/Jon-Ting/fastBC/blob/main/README.md) page. This will decide whether you will be running the box counting algorithm with GPU acceleration. Feel free to rename the output file from the compilation:\n```bash\ng++ 3DbinImBCcpu.cpp bcCPU.cpp -o 3DbinImBCcpu\n```\n```bash\nnvcc -O3 3DbinImBCgpu.cpp bcCUDA3D.cu -o 3DbinImBCgpu\n```\n\n* (Optional) Setting the path to the compiled file as an environment variable accessible by Python (replace `<PATH_TO_FASTBC>` by the absolute path to the executable file you just built), otherwise you could always pass the path to the compiled file to the relevant functions:\n```bash\nexport FASTBC=<PATH_TO_FASTBC>\n```\nNote that for the environment variable to be persistent (to still exist after the terminal is closed), the line should be added to your `~/.bashrc`.\n\n## Usage\n\n```python\nfrom sphractal import getExampleDataPath, runBoxCnt\n\ninpFile = getExampleDataPath() # Replace with the path to your xyz or lmp file\nboxCntResults = runBoxCnt(inpFile)\n```\n\nCheck out the [basic demonstration](https://github.com/Jon-Ting/sphractal/blob/main/docs/basicDemo.ipynb) and [application demonstration](https://github.com/Jon-Ting/sphractal/blob/main/docs/applicationsDemo.ipynb) notebooks for further explanations and demonstrations!\n\n## Documentation\n\nDetailed [documentations](https://sphractal.readthedocs.io/en/latest/) are hosted by `Read the Docs`.\n\n## Contributing\n\n`Sphractal` appreciates your enthusiasm and welcomes your expertise! \n\nPlease check out the [contributing guidelines](https://github.com/Jon-Ting/sphractal/blob/main/CONTRIBUTING.md) and \n[code of conduct](https://github.com/Jon-Ting/sphractal/blob/main/CONDUCT.md). \nBy contributing to this project, you agree to abide by its terms.\n\n## License\n\nThe project is distributed under an [MIT License](https://github.com/Jon-Ting/sphractal/blob/main/LICENSE).\n\n## Credits\n\nThe package was created with [`cookiecutter`](https://cookiecutter.readthedocs.io/en/latest/) using the \n`py-pkgs-cookiecutter` [template](https://github.com/py-pkgs/py-pkgs-cookiecutter).\nThe speeding up of the inner functions via just-in-time compilations with [Numba](https://numba.pydata.org/) was inspired by the advice received during the [NCI-NVIDIA Open Hackathon 2023](https://opus.nci.org.au/display/Help/NCI-NVIDIA+Open+Hackathon+2023).\n\n## Contact\n\nEmail: `Jonathan.Ting@anu.edu.au`/`jonting97@gmail.com`\n\nFeel free to reach out if you have any questions, suggestions, or feedback.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Package to estimate fractal dimension of 3D surfaces formed from overlapping spheres via box-counting algorithm.",
"version": "1.1.5",
"project_urls": {
"Documentation": "https://sphractal.readthedocs.io/en/latest/",
"Homepage": "https://github.com/Jon-Ting/sphractal",
"Repository": "https://github.com/Jon-Ting/sphractal"
},
"split_keywords": [
"box-counting",
" box-count",
" fractal",
" dimension",
" sphere",
" surface"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2484e55e39d4388436085c1388a18a5c1c78b584def7f68e875135f7239e4f26",
"md5": "fb18b30fe3696a9fc45dc785afb6eac0",
"sha256": "a82de4ad523d035609a642e7ecb75d2fd1ec857ada4c953586aeb60df970898b"
},
"downloads": -1,
"filename": "sphractal-1.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb18b30fe3696a9fc45dc785afb6eac0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 924135,
"upload_time": "2024-05-07T02:39:21",
"upload_time_iso_8601": "2024-05-07T02:39:21.797958Z",
"url": "https://files.pythonhosted.org/packages/24/84/e55e39d4388436085c1388a18a5c1c78b584def7f68e875135f7239e4f26/sphractal-1.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2bae0e997edffefdd89225f58e583f10baffb56e8e8e7e1e596d9c7076efaa56",
"md5": "c68bec7391c1476dd3fd73da25f821f2",
"sha256": "79816a4ddd68508b32edce192f1af02c6172a808c7f78f2b58ec5c6a1f9cf082"
},
"downloads": -1,
"filename": "sphractal-1.1.5.tar.gz",
"has_sig": false,
"md5_digest": "c68bec7391c1476dd3fd73da25f821f2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 918713,
"upload_time": "2024-05-07T02:39:24",
"upload_time_iso_8601": "2024-05-07T02:39:24.320292Z",
"url": "https://files.pythonhosted.org/packages/2b/ae/0e997edffefdd89225f58e583f10baffb56e8e8e7e1e596d9c7076efaa56/sphractal-1.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-07 02:39:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Jon-Ting",
"github_project": "sphractal",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphractal"
}
JSON
