geoparticle 1.0.4
geoparticle 1.0.4
License: Apache-2.0
Requires Python: >=3.9
Keywords: Geometry, Particle, Smoothed Particle Hydrodynamics, SPH

# geoparticle
*A Python package for geometry construction in particle-based simulation.*

I mainly use this package for geometry construction in LAMMPS, with some examples provided in the repository; of course, it can also be used for other software.

<!-- README.md badge -->
[![Docs Status](https://readthedocs.org/projects/geoparticle-tutorial/badge/?version=latest)](https://geoparticle-tutorial.readthedocs.io/en/latest/)
[![pypi](https://img.shields.io/pypi/v/geoparticle.svg)](https://pypi.org/project/geoparticle/)

## Installation

### Installing from pypi

```bash
pip install geoparticle
```

### Installing from the source code

Download and enter the source code directory, then

```
pip install .
```

## Documentation

The documentation is hosted on [Read the Docs](https://geoparticle-tutorial.readthedocs.io/en/latest/).

## Background

Particles of specified geometries are typically created by the `lattice` command in LAMMPS, which can lead to rough surfaces when the particle spacing is not small enough. However, too small spacing can result in too many particles and thus increase the computational cost.

![](https://raw.githubusercontent.com/Jasmine969/geoparticle/master/static/lattice-lmp.png)

The case is the same when one creates atoms based on an external STL file (an example STL file exported by COMSOL is shown below):

![](https://raw.githubusercontent.com/Jasmine969/geoparticle/master/static/comsol.png)

## Features

To resolve this problem, I developed this package for easy construction of geometries where smooth surfaces are required. Miscellaneous geometries are provided, including 1D geometries (lines and curves):

![](https://raw.githubusercontent.com/Jasmine969/geoparticle/master/static/1Dgeo.png)

2D geometries (rectangles and circles):

![](https://raw.githubusercontent.com/Jasmine969/geoparticle/master/static/2Dgeo.png)

3D geometries (blocks, cylinders, tori, and spheres):

![](https://raw.githubusercontent.com/Jasmine969/geoparticle/master/static/3Dgeo.png)

all of which can be surface, thick shells, or filled bodies.

Diverse operations are also provided, including translation, mirror, rotation, stack, clipping, union, intersection, and subtraction.

![](https://raw.githubusercontent.com/Jasmine969/geoparticle/master/static/ops.png)

Some utility functions are also provided.

## Quick start

`examples/gallery.py` provided detailed scripts to yield the geometries above.

Two more examples are given to shown how to couple geoparticle with LAMMPS. The first example is the 2D gas-liquid dam break, while the second is a 3D intestine connected with an inlet and an outlet.

![](https://raw.githubusercontent.com/Jasmine969/geoparticle/master/static/dam.png)

![](https://raw.githubusercontent.com/Jasmine969/geoparticle/master/static/intestine.png)

See the [documentation](https://geoparticle-tutorial.readthedocs.io/en/latest/) for details.

## Limitations

The particle spacings may be not exactly as specified in order to create a smooth surface.

Resultant geometries of boolean operations can have more particles than expected in some cases, because

- For intersection and subtraction, only particles with distances smaller than `rmax` will be identified the same. Users should align particles of different geometries to get the expected results.
- For union, particles of all the given geometries will be collected to yield the union. Users should ensure no particles are overlapped.