Metadata-Version: 2.1
Name: blobmodel
Version: 1.0.1
Summary: Two dimensional model of propagating blobs
Author-email: gregordecristoforo <gregor.decristoforo@gmail.com>
License: MIT License
        
        Copyright (c) 2021 Gregor Decristoforo
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: xarray
Requires-Dist: tqdm
Requires-Dist: nptyping
Requires-Dist: matplotlib
Requires-Dist: netcdf4
Requires-Dist: pytest-cov
Requires-Dist: black
Requires-Dist: mypy
Requires-Dist: sphinx
Requires-Dist: sphinx-rtd-theme

# blobmodel  <img align="left" src="https://github.com/uit-cosmo/blobmodel/blob/main/readme_files/logo.png" width="120px" >

[![Python version](./readme_files/tmp5kfvrjp5.svg)](https://www.python.org/)
[![Pypi](https://github.com/uit-cosmo/blobmodel/blob/main/readme_files/tmp5kfvrjp5.svg)](https://pypi.org/project/blobmodel/#description)
[![codecov](https://github.com/uit-cosmo/blobmodel/blob/main/readme_files/tmpp0mi4n8p.svg)](https://codecov.io/github/uit-cosmo/blobmodel)
![Tests](https://github.com/uit-cosmo/2d_propagating_blobs/actions/workflows/workflow.yml/badge.svg)
[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Documentation Status](https://readthedocs.org/projects/blobmodel/badge/?version=latest)](https://blobmodel.readthedocs.io/en/latest/?badge=latest)

This package provides realizations of advecting and dissipating blobs in up to two dimensions. 

All blob parameters can be choosen freely, and multiple blob shapes are implemented. Originally, the model is developed for studying the scrape-off layer of fusion experiments, but it can be applicable to many 1d or 2d systems. See the [blobmodel documentation](https://blobmodel.readthedocs.io/en/latest/?badge=latest) for further details.

Examples for one and two dimensions are shown below:

<table>
<tr>
<th> 1D </th>
<th> 2D </th>
</tr>
<tr>
<td>
<img src="https://github.com/uit-cosmo/blobmodel/blob/main/readme_files/1d_blobs.gif" alt="Density evolution" style="max-width: 40%;" />


</td>
<td>

<img src="https://github.com/uit-cosmo/blobmodel/blob/main/readme_files/2d_blobs.gif" alt="Density evolution" style="max-width: 40%;" />


</td>
</tr>
</table>

## Installation
The package is published to PyPI and can be installed with
```sh
pip install blobmodel
```

If you want the development version you must first clone the repo to your local machine,
then install the project in development mode:

```sh
git clone https://github.com/uit-cosmo/blobmodel.git
cd blobmodel
python -m pip install -e .
```

## Usage
Create a grid on which the blobs are discretized using the `Model` class. The `make_realization()` method computes the output as an xarray dataset which can also be written out as a `netcdf` file if the argument `file_name` is specified. A simple example is shown below:

```Python
from blobmodel import Model, show_model

bm = Model(Nx=200, Ny=100, Lx=10, Ly=10, dt=0.1, T=20, blob_shape='gauss',num_blobs=100)

ds = bm.make_realization(file_name="example.nc")
```
The data can be shown as an animation using the `show_model` function:
```Python
show_model(ds)
```
You can specify the blob parameters with a BlobFactory class. The DefaultBlobFactory class has some of the most common distribution functions implemented. An example would look like this:

```Python
from blobmodel import Model, DefaultBlobFactory

# use DefaultBlobFactory to define distribution functions of random variables
bf = DefaultBlobFactory(A_dist="exp", wx_dist="uniform", vx_dist="deg", vy_dist="normal")

# pass on bf when creating the Model
tmp = Model(
    Nx=100,
    Ny=1,
    Lx=10,
    Ly=0,
    dt=1,
    T=1000,
    blob_shape="exp",
    t_drain=2,
    periodic_y=False,
    num_blobs=10000,
    blob_factory=bf,
)
```
Alternatively, you can specify all blob parameters exactly as you want by writing your own class which inherits from BlobFactory. See `examples/custom_blobfactory.py` as an example or take a look at the [blobmodel documentation](https://blobmodel.readthedocs.io/en/latest/?badge=latest).

## Contributing

Feel free to raise issues about anything. Contributions through pull requests are also very welcome. Please take a look at our [Contributor guide](https://blobmodel.readthedocs.io/en/latest/contributor_guide.html) for further details.
