| Name | swirl-code JSON |
| Version |
1.0.2
JSON |
| download |
| home_page | None |
| Summary | The SWirl Identification by Rotation centers Localization (SWIRL) is an automated vortex identification algorithm written in python and based on the _Estimated Vortex Center_ (EVC) method [Canivete Cuissa & Steiner, 2022]. Given a two-dimensional velocity field defined on a Cartesian grid and the grid cell size in physical units, the SWIRL code returns a list with the identified vortical structures and their main properties. |
| upload_time | 2024-05-12 16:29:56 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
vortex
fluid dynamics
physics
simulation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
```
_/_/_/ _/ _/ _/ _/_/_/ _/
_/ _/ _/ _/ _/ _/ _/
_/_/ _/ _/ _/ _/_/_/ _/
_/ _/ _/ _/ _/ _/ _/ _/
_/_/_/ _/ _/ _/ _/ _/ _/_/_/
(c) IRSOL, 11.04.2022
```
Author: _José Roberto Canivete Cuissa_
Email: _jose.canivete@irsol.usi.ch_
[](https://doi.org/10.5281/zenodo.10016647)
----
# SWIRL code
The SWirl Identification by Rotation centers Localization (SWIRL) is an automated vortex identification algorithm written in python and based on the _Estimated Vortex Center_ (EVC) method [Canivete Cuissa & Steiner, 2022](#references).
Given a two-dimensional velocity field defined on a Cartesian grid and the grid cell size in physical units, the SWIRL code returns a list with the identified vortical structures and their main properties.
----
## Table of contents
- [Abstract](#abstract)
- [Dependencies](#dependencies)
- [How to install](#how-to-install)
- [How to run](#how-to-run)
- [Parameters](#parameters)
- [References](#references)
----
## Abstract
Vortices are one of the fundamental features of turbulent fluid dynamics, yet it is extremely difficult to accurately and automatically identify vortical motions in, for example, simulations and observations of turbulent flows. We propose a new method for an accurate and reliable identification of vortices which requires the knowledge of the velocity field. The advantage of this method is that it accounts for both the local and global properties of the flow, which makes it robust to noise and reliable even in highly turbulent scenarios.
In our method, vortical motions are identified in the given velocity field by clustering estimated centers of rotation computed from grid points where the flow is characterized by some degree of curvature (rotation). The estimated center points are dubbed _estimated vortex center_ (EVC) points. Since a vortex can be intuitively defined as a collection of fluid particles coherently rotating around a common axis, clusters of EVC points will appear in the center of coherently rotating flows.
To accurately estimate EVC points, and therefore allow for a robust identification of vortices, we employ the Rortex mathematical criterion ([Tian et al., 2018](#references); [Liu et al., 2018](#references)) and the properties of the input velocity field. The clustering is then performed with a grid- and vortex-adapted version of the Clustering by fast search and find of density peaks (CFSFDP) algorithm ([Rodriguez & Laio, 2014](#references)).
The algorithm is implemented in the SWIRL code and it has been tested on (noisy) artificial vortex flows and on (magneto-)hydrodynamical and turbulent numerical simulations with excellent results. More details on the EVC method and on the implementation of the code can be found in [Canivete Cuissa & Steiner, 2022](#references).
> If you find the SWIRL code useful in your research, we would really appreciate if you could cite the paper [Canivete Cuissa & Steiner, 2022](#references) in your published work.
----
## Dependencies
The SWIRL code requires Python >= 3.10 and makes use of the following Python libraries:
- numpy
- scipy
- h5py
- matplotlib
----
## How to install
Make sure to have Python >= 3.10 installed in your system and the upgrated version of pip running this command:
```
python3 -m pip install --upgrade pip
```
The easiest way to install the code is to use pip:
```
pip install swirl-code
```
## How to run
A detailed tutorial on how to run the SWIRL code is presented in a Jupyter-Notebook in the _example_ folder. Here, we just give a brief recap.
The core of the swirl module is the `Identification` class, which allows to run the algorithm.
Given a two-dimensional velocity field, `vx` and `vy`, and the size of the grid cells in the two dimensions, `dx` and `dy`, an instance of the `Identification` class can be initialized with
```
>>> vortices = swirl.Identification(v = [vx, vy],
grid_dx = [dx, dy])
```
> Important!
> The spatial units of the velocity field and of the grid cell sizes must be the same, otherwise the identification algorithm won't work correctly. For example, if the velocity field is given in units of $cm/s$, then the grid cells sizes must be given in units of $cm$.
Once the object has been initialized, one can run the algorithm with
```
>>> vortices.run()
```
The identified vortices are stored in the `vortices` object. To access them, one uses the `vortices` object as if it was a list. This means that the first vortex is store in `vortices[0]`, the second in `vortices[1]`, and so on. The number of identified vortices can therefore be obtained with `len(vortices)`.
The properties of the identified vortices are saved in a `Vortex` object, which contains the following attributes
- radius (float) : The effective radius of the vortex
- center (list) : The coordinates of the center of the vortex
- orientation (float) : The orientation of the vortex: +1.0 = Counterclock-wise, -1.0 = Clockwise
- vortex_cells (array) : The list of the coordinates of the cells forming the vortex
- and more ...
Therefore, to access the radius of the first vortex identified, one runs the following command:
```
>>> r = vortices[0].radius
```
The list of the radii, centers, or orientations of all the vortices identified can be obtained directly from the `vortices` object with
```
>>> radii = vortices.radii
>>> centers = vortices.centers
>>> orientations = vortices.orientations
```
To save the properties of the identified vortices, one can run the following method
```
>>> vortices.save('name_of_the_file')
```
which will save all the information relative to the identification process in a structured hdf5 file.
----
## Parameters
The `Identification` class accepts a number of different parameters that one might need to tweak in order to optimize the results. These parameters must be given in a parameter file, which format is shown in the file _default_swirl.param_. If a parameter file is not given as an input in the initialization of the `Identification` class, or if some parameters are omitted, the SWIRL code will use the default values (i.e. the ones shown in the _default_swirl.param_ file). The parameters are defined as follows:
- `stencils` [list] = [1]
A list of integers that correspond the stencils of grid cells used for the computation of numerical derivatives.
- `swirlstr_params` [list] = [0., 0., 0.]
The parameters used in the computation of the swirling strength. The first one is the threshold value $\epsilon_{\lambda}$,
we suggest this value to be always $0.0$. The second and thirs values correspond to the $\kappa_{\zeta}$ and $\delta_{\zeta}$
parameters used to compute the enhanced swirling strength. We suggest these values to be either $0.0$ or around $1.0$.
- `dc_param` [float] = 3.
Parameter used to compute the critical distance used in the
clustering algorithm. Depending on the value of the dc_adaptive
parameter, it can represent the percentual number of data points that,
in average, are considered as neighbours, i.e. inside the critical
distance (True), or to define the critical distance dc = dc_param in units
of grid cells (False).
- `dc_adaptive` [boolean] = True
Option to use the adaptive critical distance evaluation or to use the
fixed one based on the value of dc_param.
- `cluster_fast` [boolean] = True
Option to use the grid adapted version of the clustering algorithm, which
accelerates greatly the computation without sacrificing accuracy. We suggest to keep it True
- `cluster_kernel` [string] = Gaussian
Kernel used to compute densities in the clustering algorithm.
'Gaussian': Gaussian kernel.
'Heaviside': Heaviside function.
- `cluster_decision` [string] = delta-rho
The method used to select the cluster centers in the clustering process.
'delta-rho' : Use the delta and rho criteria to select the cluster centers.
'gamma' : Use the gamma criterion to select the cluster centers.
- `cluster_params` [list] = [1.0, 0.5, 2.0]
List of parameters for the selection of cluster centers in the clustering
process. The list must contain three entries, which correspond to the parameters
$delta_p$, $rho_p$, $gamma_p$.
- `noise_param` [float] = 1.0
Parameter to remove noisy cells from the identification process. It correspond to the parameter
$r_p$. We recommend values $\gtrsim 1.0$.
- `kink_param` [float] = 1.0
Parameter to remove 'non-spiraling' coherent curvatures identified as vortices.
It also corresponds to the parameter $r_p$. We recommend values $\sim 1.0$.
Finally, one can also select the option `verbose=False` in the initialization of the `Identification` object, to not print any output when running the code.
----
## References
1. [Canivete Cuissa, J. R., Steiner, O., 2022, A&A 668, A118](https://ui.adsabs.harvard.edu/abs/2022A%26A...668A.118C/abstract)
2. [Liu, C., Gao, Y., Tian, S., & Dong, X. 2018, Physics of Fluids, 30, 035103](https://ui.adsabs.harvard.edu/abs/2018PhFl...30c5103L/abstract)
3. [Rodriguez, A. & Laio, A. 2014, Science, 344, 1492](https://ui.adsabs.harvard.edu/abs/2014Sci...344.1492R/abstract)
4. [Tian, S., Gao, Y., Dong, X., & Liu, C. 2018, Journal of Fluid Mechanics, 849, 312](https://ui.adsabs.harvard.edu/abs/2018JFM...849..312T/abstract)
----
Raw data
{
"_id": null,
"home_page": null,
"name": "swirl-code",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "vortex, fluid dynamics, physics, simulation",
"author": null,
"author_email": "Jos\u00e9 Roberto Canivete Cuissa <jose.canivete@irsol.usi.ch>",
"download_url": "https://files.pythonhosted.org/packages/9f/ed/4aa596596b9ddfd4a2891e9a4c5b8395438b331f8218d85c2dc42275b8e6/swirl_code-1.0.2.tar.gz",
"platform": null,
"description": "``` \n _/_/_/ _/ _/ _/ _/_/_/ _/\n _/ _/ _/ _/ _/ _/ _/\n _/_/ _/ _/ _/ _/_/_/ _/\n _/ _/ _/ _/ _/ _/ _/ _/\n _/_/_/ _/ _/ _/ _/ _/ _/_/_/\n\n\n (c) IRSOL, 11.04.2022\n```\n\nAuthor: _Jos\u00e9 Roberto Canivete Cuissa_ \nEmail: _jose.canivete@irsol.usi.ch_\n \n\n[](https://doi.org/10.5281/zenodo.10016647)\n\n\n----\n\n# SWIRL code\nThe SWirl Identification by Rotation centers Localization (SWIRL) is an automated vortex identification algorithm written in python and based on the _Estimated Vortex Center_ (EVC) method [Canivete Cuissa & Steiner, 2022](#references). \nGiven a two-dimensional velocity field defined on a Cartesian grid and the grid cell size in physical units, the SWIRL code returns a list with the identified vortical structures and their main properties.\n\n----\n\n## Table of contents\n- [Abstract](#abstract)\n- [Dependencies](#dependencies)\n- [How to install](#how-to-install)\n- [How to run](#how-to-run)\n- [Parameters](#parameters)\n- [References](#references)\n\n----\n\n## Abstract\nVortices are one of the fundamental features of turbulent fluid dynamics, yet it is extremely difficult to accurately and automatically identify vortical motions in, for example, simulations and observations of turbulent flows. We propose a new method for an accurate and reliable identification of vortices which requires the knowledge of the velocity field. The advantage of this method is that it accounts for both the local and global properties of the flow, which makes it robust to noise and reliable even in highly turbulent scenarios. \nIn our method, vortical motions are identified in the given velocity field by clustering estimated centers of rotation computed from grid points where the flow is characterized by some degree of curvature (rotation). The estimated center points are dubbed _estimated vortex center_ (EVC) points. Since a vortex can be intuitively defined as a collection of fluid particles coherently rotating around a common axis, clusters of EVC points will appear in the center of coherently rotating flows. \nTo accurately estimate EVC points, and therefore allow for a robust identification of vortices, we employ the Rortex mathematical criterion ([Tian et al., 2018](#references); [Liu et al., 2018](#references)) and the properties of the input velocity field. The clustering is then performed with a grid- and vortex-adapted version of the Clustering by fast search and find of density peaks (CFSFDP) algorithm ([Rodriguez & Laio, 2014](#references)). \nThe algorithm is implemented in the SWIRL code and it has been tested on (noisy) artificial vortex flows and on (magneto-)hydrodynamical and turbulent numerical simulations with excellent results. More details on the EVC method and on the implementation of the code can be found in [Canivete Cuissa & Steiner, 2022](#references).\n\n> If you find the SWIRL code useful in your research, we would really appreciate if you could cite the paper [Canivete Cuissa & Steiner, 2022](#references) in your published work.\n\n----\n\n## Dependencies\nThe SWIRL code requires Python >= 3.10 and makes use of the following Python libraries:\n- numpy \n- scipy \n- h5py \n- matplotlib \n\n----\n\n## How to install\nMake sure to have Python >= 3.10 installed in your system and the upgrated version of pip running this command:\n```\npython3 -m pip install --upgrade pip\n```\n\nThe easiest way to install the code is to use pip:\n```\npip install swirl-code\n```\n\n## How to run\nA detailed tutorial on how to run the SWIRL code is presented in a Jupyter-Notebook in the _example_ folder. Here, we just give a brief recap.\n\n\nThe core of the swirl module is the `Identification` class, which allows to run the algorithm.\nGiven a two-dimensional velocity field, `vx` and `vy`, and the size of the grid cells in the two dimensions, `dx` and `dy`, an instance of the `Identification` class can be initialized with\n```\n>>> vortices = swirl.Identification(v = [vx, vy],\n grid_dx = [dx, dy])\n```\n\n> Important! \n> The spatial units of the velocity field and of the grid cell sizes must be the same, otherwise the identification algorithm won't work correctly. For example, if the velocity field is given in units of $cm/s$, then the grid cells sizes must be given in units of $cm$. \n\nOnce the object has been initialized, one can run the algorithm with\n```\n>>> vortices.run()\n```\n\nThe identified vortices are stored in the `vortices` object. To access them, one uses the `vortices` object as if it was a list. This means that the first vortex is store in `vortices[0]`, the second in `vortices[1]`, and so on. The number of identified vortices can therefore be obtained with `len(vortices)`. \nThe properties of the identified vortices are saved in a `Vortex` object, which contains the following attributes\n- radius (float) : The effective radius of the vortex\n- center (list) : The coordinates of the center of the vortex\n- orientation (float) : The orientation of the vortex: +1.0 = Counterclock-wise, -1.0 = Clockwise\n- vortex_cells (array) : The list of the coordinates of the cells forming the vortex\n- and more ...\n\nTherefore, to access the radius of the first vortex identified, one runs the following command:\n```\n>>> r = vortices[0].radius\n```\n\nThe list of the radii, centers, or orientations of all the vortices identified can be obtained directly from the `vortices` object with\n```\n>>> radii = vortices.radii\n>>> centers = vortices.centers\n>>> orientations = vortices.orientations\n```\n\nTo save the properties of the identified vortices, one can run the following method\n```\n>>> vortices.save('name_of_the_file')\n```\nwhich will save all the information relative to the identification process in a structured hdf5 file.\n\n----\n\n## Parameters\nThe `Identification` class accepts a number of different parameters that one might need to tweak in order to optimize the results. These parameters must be given in a parameter file, which format is shown in the file _default_swirl.param_. If a parameter file is not given as an input in the initialization of the `Identification` class, or if some parameters are omitted, the SWIRL code will use the default values (i.e. the ones shown in the _default_swirl.param_ file). The parameters are defined as follows:\n- `stencils` [list] = [1] \n A list of integers that correspond the stencils of grid cells used for the computation of numerical derivatives. \n- `swirlstr_params` [list] = [0., 0., 0.] \n The parameters used in the computation of the swirling strength. The first one is the threshold value $\\epsilon_{\\lambda}$, \n we suggest this value to be always $0.0$. The second and thirs values correspond to the $\\kappa_{\\zeta}$ and $\\delta_{\\zeta}$ \n parameters used to compute the enhanced swirling strength. We suggest these values to be either $0.0$ or around $1.0$. \n- `dc_param` [float] = 3. \n Parameter used to compute the critical distance used in the \n clustering algorithm. Depending on the value of the dc_adaptive \n parameter, it can represent the percentual number of data points that,\n in average, are considered as neighbours, i.e. inside the critical \n distance (True), or to define the critical distance dc = dc_param in units\n of grid cells (False).\n- `dc_adaptive` [boolean] = True \n Option to use the adaptive critical distance evaluation or to use the \n fixed one based on the value of dc_param. \n- `cluster_fast` [boolean] = True \n Option to use the grid adapted version of the clustering algorithm, which\n accelerates greatly the computation without sacrificing accuracy. We suggest to keep it True\n- `cluster_kernel` [string] = Gaussian \n Kernel used to compute densities in the clustering algorithm.\n 'Gaussian': Gaussian kernel.\n 'Heaviside': Heaviside function.\n- `cluster_decision` [string] = delta-rho \n The method used to select the cluster centers in the clustering process.\n 'delta-rho' : Use the delta and rho criteria to select the cluster centers.\n 'gamma' : Use the gamma criterion to select the cluster centers.\n- `cluster_params` [list] = [1.0, 0.5, 2.0] \n List of parameters for the selection of cluster centers in the clustering\n process. The list must contain three entries, which correspond to the parameters \n $delta_p$, $rho_p$, $gamma_p$.\n- `noise_param` [float] = 1.0 \n Parameter to remove noisy cells from the identification process. It correspond to the parameter\n $r_p$. We recommend values $\\gtrsim 1.0$.\n- `kink_param` [float] = 1.0 \n Parameter to remove 'non-spiraling' coherent curvatures identified as vortices. \n It also corresponds to the parameter $r_p$. We recommend values $\\sim 1.0$.\n \nFinally, one can also select the option `verbose=False` in the initialization of the `Identification` object, to not print any output when running the code.\n\n----\n\n## References\n1. [Canivete Cuissa, J. R., Steiner, O., 2022, A&A 668, A118](https://ui.adsabs.harvard.edu/abs/2022A%26A...668A.118C/abstract) \n2. [Liu, C., Gao, Y., Tian, S., & Dong, X. 2018, Physics of Fluids, 30, 035103](https://ui.adsabs.harvard.edu/abs/2018PhFl...30c5103L/abstract) \n3. [Rodriguez, A. & Laio, A. 2014, Science, 344, 1492](https://ui.adsabs.harvard.edu/abs/2014Sci...344.1492R/abstract)\n4. [Tian, S., Gao, Y., Dong, X., & Liu, C. 2018, Journal of Fluid Mechanics, 849, 312](https://ui.adsabs.harvard.edu/abs/2018JFM...849..312T/abstract)\n----\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The SWirl Identification by Rotation centers Localization (SWIRL) is an automated vortex identification algorithm written in python and based on the _Estimated Vortex Center_ (EVC) method [Canivete Cuissa & Steiner, 2022]. Given a two-dimensional velocity field defined on a Cartesian grid and the grid cell size in physical units, the SWIRL code returns a list with the identified vortical structures and their main properties.",
"version": "1.0.2",
"project_urls": {
"Documentation": "https://github.com/jcanivete/swirl/blob/main/README.md",
"Issues": "https://github.com/jcanivete/swirl/issues",
"Source": "https://github.com/jcanivete/swirl"
},
"split_keywords": [
"vortex",
" fluid dynamics",
" physics",
" simulation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7efc7f018e5ca427f4618b121a83ec3902ac664f9e380211d7d15942cf0b486b",
"md5": "d2602e598e02247bff962b99b54915bf",
"sha256": "61a9cd8a9617a63e00e0e99524b511a0babd956cd4dbecef4ea50aeda0924b10"
},
"downloads": -1,
"filename": "swirl_code-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d2602e598e02247bff962b99b54915bf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 30681,
"upload_time": "2024-05-12T16:29:54",
"upload_time_iso_8601": "2024-05-12T16:29:54.823935Z",
"url": "https://files.pythonhosted.org/packages/7e/fc/7f018e5ca427f4618b121a83ec3902ac664f9e380211d7d15942cf0b486b/swirl_code-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9fed4aa596596b9ddfd4a2891e9a4c5b8395438b331f8218d85c2dc42275b8e6",
"md5": "ffbcd01fff6a304aa451bb36183e32cd",
"sha256": "51b6cdf3bfe1f8b98f0376776425a082cb98acd81137a20a10f847d757fdaca9"
},
"downloads": -1,
"filename": "swirl_code-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "ffbcd01fff6a304aa451bb36183e32cd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 30155,
"upload_time": "2024-05-12T16:29:56",
"upload_time_iso_8601": "2024-05-12T16:29:56.851160Z",
"url": "https://files.pythonhosted.org/packages/9f/ed/4aa596596b9ddfd4a2891e9a4c5b8395438b331f8218d85c2dc42275b8e6/swirl_code-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-12 16:29:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jcanivete",
"github_project": "swirl",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "swirl-code"
}
