Metadata-Version: 2.4
Name: adsorpy
Version: 1.2.0
Summary: Random sequential adsorption (RSA) simulation, 2D lattice-based.
Project-URL: github, https://github.com/JoostFWMaas/AdsorPy
Project-URL: Documentation, https://joostfwmaas.github.io/AdsorPy
Project-URL: Changelog, https://github.com/JoostFWMaas/AdsorPy/blob/main/CHANGELOG.md
Author-email: "J.F.W. Maas" <j.f.w.maas@tue.nl>
License-Expression: MIT
License-File: LICENSE.md
Keywords: Monte Carlo,RSA,adsorption,computational chemistry,computational physics,coverage,gap size distribution,jamming,lattice model,molecular adsorption,packing,random sequential adsorption,statistical mechanics,stochastic simulation,surface science
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.10.9
Requires-Dist: numba>=0.65.1
Requires-Dist: numpy>=2.2.6; python_version == '3.10'
Requires-Dist: numpy>=2.4.4; python_version >= '3.11'
Requires-Dist: rtree>=1.4.1
Requires-Dist: shapely>=2.1.2
Provides-Extra: docs
Requires-Dist: furo>=2025.12.19; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=3.10.2; extra == 'docs'
Requires-Dist: sphinx-design>=0.7.0; extra == 'docs'
Requires-Dist: sphinx-pyproject>=0.3.0; extra == 'docs'
Requires-Dist: sphinx>=9.1.0; extra == 'docs'
Provides-Extra: lint
Requires-Dist: mypy>=2.0.0; extra == 'lint'
Requires-Dist: pyright>=1.1.409; extra == 'lint'
Requires-Dist: ruff>=0.15.12; extra == 'lint'
Provides-Extra: test
Requires-Dist: codecov>=2.1.13; extra == 'test'
Requires-Dist: hypothesis>=6.152.4; extra == 'test'
Requires-Dist: pytest-cov>=7.1.0; extra == 'test'
Requires-Dist: pytest>=9.0.3; extra == 'test'
Requires-Dist: scipy==1.15.3; (python_version == '3.10') and extra == 'test'
Requires-Dist: scipy>=1.17.1; (python_version >= '3.11') and extra == 'test'
Description-Content-Type: text/markdown

# AdsorPy

![Output of an AdsorPy run, an image of a covered surface.](https://raw.githubusercontent.com/JoostFWMaas/AdsorPy/ccedff9c0a4cca1e89c4d461dbfeb91c49e38b21/images/AdsorPy_Covered_Surface.png)
![test results badge](https://github.com/JoostFWMaas/AdsorPy/actions/workflows/tests-ci.yml/badge.svg)
[![codecov](https://codecov.io/github/JoostFWMaas/AdsorPy/graph/badge.svg?token=XBYZU63D8Y)](https://codecov.io/github/JoostFWMaas/AdsorPy)

Lattice-based random sequential adsorption (RSA) Python 3.10+ script.

In RSA, molecules arrive one by one at a surface. Adsorption takes place if the molecule does not overlap with molecules
already on the surface.
The list of available orientations for the molecule is traversed in random order until the first orientation that fits
is found, or until the list is exhausted.
All available sites are checked, and various metrics can be extracted afterwards such as the coverage, covered area, and
gap size distribution.

## How to use

Run the `adsorpy.main` in order to run a simple single run using the standard disk-shaped molecule on hexagonal aluminium oxide.
New molecules can be created by running the `adsorpy.molecule_lib` or by calling the `adsorpy.molecule_lib.first_time_loader()` function. Molecules can be generated from `.xyz` files. It is
recommended to run `adsorpy.molecule_lib` directly from command line to define the molecule orientation, then store the new
molecule string for repeated use.

Run the `adsorpy.run_simulation.run_simulation()` function with the molecule footprints generated in the previous step. Output can be printed to stdout, plotted, and saved.

User friendliness will be updated at a later stage, allowing the user to define simulation modes, surfaces, and
molecules more easily.

Documentation (generated with `sphinx`): https://joostfwmaas.github.io/AdsorPy/

## Future additions

In a future update, the code will be expanded with diffusion, desorption, and species conversion (changing from one molecule on the surface to another).

## Design philosophy

Because AdsorPy has been made with scientific rigour in mind, the package is tested in multiple ways:
- Unit tests (`pytest`) of the code ensure correct behaviour for expected input.
- Property tests (`hypothesis`) of the most critical code components ensure correct behaviour for unexpected input as well.
- `mypy` (in `--strict` mode) and `pyright` (`strict`) ensure that the package is correctly-typed, as if it were static. The `py.typed` file, a promise that the code is type-hinted properly, is added because the code passes this test.
- `ruff` is used as a linter with almost all rules enabled (see the pyproject.toml for the list of exclusions and reasons).
- `tox` is used to run all of the aforementioned tests in parallel for multiple Python versions to ensure correct behaviour.
- CI is used for automated testing.

The package also makes use of an optional config file that falls back on standard behaviour, because configs are often used in scientific software (set-and-forget).

# Openness and academic collaboration

The script was made public for the sake of openness and academic collaboration. Please let me know if you have questions about the script, or if you have discovered any issues/bugs. 
At the end of this file, I will place a list of papers that make use of this work. Feel free to contact me if you want your work to be added to the list as well.
