diff --git a/.github/workflows/draft-pdf.yml b/.github/workflows/draft-pdf.yml new file mode 100644 index 0000000..2baba30 --- /dev/null +++ b/.github/workflows/draft-pdf.yml @@ -0,0 +1,27 @@ +on: + push: + paths: + - paper/** + - .github/workflows/draft-pdf.yml + +jobs: + paper: + runs-on: ubuntu-latest + name: Paper Draft + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Build draft PDF + uses: openjournals/openjournals-draft-action@master + with: + journal: joss + # This should be the path to the paper within your repo. + paper-path: paper/paper.md + - name: Upload + uses: actions/upload-artifact@v4 + with: + name: paper + # This is the output path where Pandoc will write the compiled + # PDF. Note, this should be the same directory as the input + # paper.md + path: paper/paper.pdf \ No newline at end of file diff --git a/paper/paper.bib b/paper/paper.bib new file mode 100644 index 0000000..d1d5875 --- /dev/null +++ b/paper/paper.bib @@ -0,0 +1,213 @@ +@article{losada_three-point_2024, + author = {Losada, J. M. and Helgeland, A. D. and Terry, J. L. and Garcia, O. E.}, + title = "{A three-point velocity estimation method for two-dimensional coarse-grained imaging data}", + journal = {AIP Advances}, + volume = {14}, + number = {9}, + pages = {095102}, + year = {2024}, + month = {09}, + doi = {10.1063/5.0197251}, +} + +@article{dippolito_convective_2011, + title = {Convective transport by intermittent blob-filaments: {Comparison} of theory and experiment}, + volume = {18}, + number = {6}, + journal = {Physics of Plasmas}, + author = {D'Ippolito, D. A. and Myra, J. R. and Zweben, S. J.}, + year = {2011}, + doi = {10.1063/1.3594609}, +} + +@article{fiedler_coherent_1988, + title = {Coherent structures in turbulent flows}, + journal = {Progress in Aerospace Sciences}, + volume = {25}, + number = {3}, + pages = {231-269}, + year = {1988}, + issn = {0376-0421}, + doi = {10.1016/0376-0421(88)90001-2}, + author = {H.E. Fiedler}, +} + +@inproceedings{nosov_coherent_2009, + author = {V. V. Nosov and V. M. Grigoriev and P. G. Kovadlo and V. P. Lukin and E. V. Nosov and A. V. Torgaev}, + title = {{Coherent structures in turbulent atmosphere}}, + volume = {7296}, + booktitle = {Fifteenth International Symposium on Atmospheric and Ocean Optics/Atmospheric Physics}, + editor = {Gennadii G. Matvienko and Yurii N. Ponomarev}, + organization = {International Society for Optics and Photonics}, + publisher = {SPIE}, + pages = {729609}, + keywords = {turbulence, spectrum, coherent structure, Benard cell, stochastization scenario}, + year = {2009}, + doi = {10.1117/12.823804}, +} + +@article{zweben_invited_2017, + title = {Invited {Review} {Article}: {Gas} puff imaging diagnostics of edge plasma turbulence in magnetic fusion devices}, + volume = {88}, + issn = {10897623}, + doi = {10.1063/1.4981873}, + number = {4}, + journal = {Review of Scientific Instruments}, + author = {Zweben, S. J. and Terry, J. L. and Stotler, D. P. and Maqueda, R. J.}, + year = {2017}, + pmid = {28456269}, + pages = {041101}, +} + +@article{offeddu_analysis_2023, + author = {Offeddu, N. and Wüthrich, C. and Han, W. and Theiler, C. and Golfinopoulos, T. and Terry, J. L. and Marmar, E. and Ravetta, A. and Van Parys, G.}, + title = {Analysis techniques for blob properties from gas puff imaging data}, + journal = {Review of Scientific Instruments}, + volume = {94}, + number = {3}, + pages = {033512}, + year = {2023}, + month = {03}, + issn = {0034-6748}, + doi = {10.1063/5.0133506}, +} + +@article{garcia_stochastic_2016, + author = {Garcia, O. E. and Kube, R. and Theodorsen, A. and Pécseli, H. L.}, + title = {Stochastic modelling of intermittent fluctuations in the scrape-off layer: Correlations, distributions, level crossings, and moment estimation}, + journal = {Physics of Plasmas}, + volume = {23}, + number = {5}, + pages = {052308}, + year = {2016}, + month = {05}, + issn = {1070-664X}, + doi = {10.1063/1.4951016}, +} + +@article{militello_two-dimensional_2018, + author = {Militello, F. and Farley, T. and Mukhi, K. and Walkden, N. and Omotani, J. T.}, + title = {A two-dimensional statistical framework connecting thermodynamic profiles with filaments in the scrape off layer and application to experiments}, + journal = {Physics of Plasmas}, + volume = {25}, + number = {5}, + pages = {056112}, + year = {2018}, + month = {05}, + issn = {1070-664X}, + doi = {10.1063/1.5017919}, +} + +@article{losada_tde_2025, + author = {Losada, J. M. and Garcia, O. E.}, + title = {Time delay velocity estimation from a superposition of localized and uncorrelated pulses}, + journal = {Physics of Plasmas}, + volume = {32}, + number = {4}, + pages = {042505}, + year = {2025}, + month = {04}, + doi = {10.1063/5.0261066}, +} + +@article{militello_relation_2016, + doi = {10.1088/0741-3335/58/12/125004}, + year = {2016}, + month = {oct}, + publisher = {IOP Publishing}, + volume = {58}, + number = {12}, + pages = {125004}, + author = {Militello, F and Omotani, J T}, + title = {On the relation between non-exponential scrape off layer profiles and the dynamics of filaments}, + journal = {Plasma Physics and Controlled Fusion}, +} + +@article{veltri_mhd_1999, + doi = {10.1088/0741-3335/41/3A/071}, + url = {https://dx.doi.org/10.1088/0741-3335/41/3A/071}, + year = {1999}, + month = {mar}, + publisher = {}, + volume = {41}, + number = {3A}, + pages = {A787}, + author = {Pierluigi Veltri}, + title = {MHD turbulence in the solar wind: self-similarity, intermittency and coherent structures}, + journal = {Plasma Physics and Controlled Fusion}, +} + +@article{lowen_power_1990, + author={Lowen, S.B. and Teich, M.C.}, + journal={IEEE Transactions on Information Theory}, + title={Power-law shot noise}, + year={1990}, + volume={36}, + number={6}, + pages={1302-1318}, + doi={10.1109/18.59930} +} + +@article{bak_self_1988, + title = {Self-organized criticality}, + author = {Bak, Per and Tang, Chao and Wiesenfeld, Kurt}, + journal = {Phys. Rev. A}, + volume = {38}, + issue = {1}, + pages = {364--374}, + numpages = {0}, + year = {1988}, + month = {Jul}, + publisher = {American Physical Society}, + doi = {10.1103/PhysRevA.38.364}, + url = {https://link.aps.org/doi/10.1103/PhysRevA.38.364} +} + +@article{kociscak_modeling_2023, + author = {{Kočiščák, S.} and {Kvammen, A.} and {Mann, I.} and {Sørbye, S. H.} and {Theodorsen, A.} and {Zaslavsky, A.}}, + title = {Modeling Solar Orbiter dust detection rates in the inner heliosphere as a {Poisson} process}, + DOI= "10.1051/0004-6361/202245165", + url= "https://doi.org/10.1051/0004-6361/202245165", + journal = {A&A}, + year = 2023, + volume = 670, + pages = "A140", +} + +@article{losada_stochastic_2023, + author = {Losada, J. M. and Theodorsen, A. and Garcia, O. E.}, + title = {Stochastic modeling of blob-like plasma filaments in the scrape-off layer: Theoretical foundation}, + journal = {Physics of Plasmas}, + volume = {30}, + number = {4}, + pages = {042518}, + year = {2023}, + month = {04}, + issn = {1070-664X}, + doi = {10.1063/5.0144885}, +} + +@article{losada_stochastic_2024, + author = {Losada, J. M. and Paikina, O. and Garcia, O. E.}, + title = {Stochastic modeling of blob-like plasma filaments in the scrape-off layer: Correlated amplitudes and velocities}, + journal = {Physics of Plasmas}, + volume = {31}, + number = {4}, + pages = {042514}, + year = {2024}, + month = {04}, + issn = {1070-664X}, + doi = {10.1063/5.0196938}, +} + +@article{hoyer_xarray_2017, + title = {xarray: {N-D} labeled arrays and datasets in {Python}}, + author = {Hoyer, S. and J. Hamman}, + journal = {Journal of Open Research Software}, + volume = {5}, + number = {1}, + year = {2017}, + publisher = {Ubiquity Press}, + doi = {10.5334/jors.148}, + url = {https://doi.org/10.5334/jors.148} +} \ No newline at end of file diff --git a/paper/paper.md b/paper/paper.md new file mode 100644 index 0000000..6d5ffcb --- /dev/null +++ b/paper/paper.md @@ -0,0 +1,140 @@ +--- +title: 'Blobmodel: A Python package for generating superpositions of pulses in one and two dimensions' +tags: + - Python + - pulses + - imaging data + - tokamaks + - turbulence +authors: + - name: Juan M. Losada + orcid: 0000-0003-2054-1384 + equal-contrib: true + affiliation: 1 + - name: Gregor Decristoforo + orcid: 0000-0002-7616-0946 + equal-contrib: true # (This is how you can denote equal contributions between multiple authors) + affiliation: 1 +affiliations: + - name: UiT, The Arctic University of Norway + index: 1 +date: 11 February 2025 +bibliography: paper.bib + +--- + +# Summary + +`blobmodel` is a Python library for generating synthetic data that mimics the behavior +of moving pulses in a turbulent environment. It creates controlled datasets where the +true motion of each pulse is known, allowing researchers to gain further understanding on +the statistical outputs of such systems as well as to test and improve analysis +and tracking algorithms. While originally developed for studying +turbulence in fusion experiments, `blobmodel` can be applied to any field where +turbulence leads to the generation of structures propagating in one or two dimensions. +The software is open source, easy to use, and designed to support reproducible research. + +# Statement of need + +Understanding and analyzing the motion of structures in turbulent systems is crucial +in many areas of research, including plasma physics [@dippolito_convective_2011], +fluid dynamics [@fiedler_coherent_1988], and atmospheric science [@nosov_coherent_2009]. + +More widely, the study of the statistical characteristics resulting from the superposition +of uncorrelated propagating pulses is of importance in fields such as astrophysical plasmas [@veltri_mhd_1999], +detection rates of interplanetary dust [@kociscak_modeling_2023], +$1/f$ noise in self-organized critical systems [@bak_self_1988], +and shot noise in electronics [@lowen_power_1990]. + +In experimental studies, imaging diagnostics are often used to capture the +evolution of these structures [@zweben_invited_2017], but extracting reliable velocity information from such +data remains challenging [@offeddu_analysis_2023]. Many existing analysis methods rely on assumptions about +the underlying dynamics and must be tested against known reference data to ensure +accuracy. + +Several stochastic models have been developed describing a point process resulting from the superposition of +uncorrelated structures with random arrival times [@garcia_stochastic_2016]; or propagating in one [@losada_stochastic_2023] +or two [@militello_two-dimensional_2018] spatial dimensions. In the simplest cases, it is possible +to derive analytical expressions for different statistical quantities such as probability density functions, +autocorrelation functions, power spectral densities and spatial dependence of the mean or other higher-order +moments [@garcia_stochastic_2016; @militello_relation_2016; @losada_stochastic_2023]. More general scenarios +require numerical tools [@losada_stochastic_2024], and synthetic realizations of the model. + +`blobmodel` addresses this need by providing a framework for generating synthetic +datasets resulting from a superposition of uncorrelated pulses [@militello_two-dimensional_2018; @losada_tde_2025]: +$$ + \Phi(x,y,t) = \sum_{k=1}^{K} a_k \varphi\left( \frac{x-v_k(t-t_k)}{\ell_{x, k}}, \frac{(y-y_k)-w_k(t-t_k)}{\ell_{y, k}}\right) , +$$ +where: + +- $a_k$ represents the initial pulse amplitude. +- $v_k$ and $w_k$ are the horizontal and vertical velocity components, respectively. +- $t_k$ is the pulse arrival time at the position $x=0$, $y=y_k$. +- $y_k$ is the pulse vertical position at time $t=t_k$. +- $\ell_{x, k}$ and $\ell_{y, k}$ are the horizontal and vertical pulse sizes, respectively. +- $\varphi$ is an unspecified pulse shape. + +All these parameters, except for the pulse shape $\varphi$ are assumed to be random variables. +Additionally, each pulse may be tilted on an angle given by an additional random variable $\theta_k$ with respect to its centre. + +The framework allows an explicit definition of all relevant process parameters, including: + +- All pulse parameters if defined as degenerate random variables. +- All distribution functions of the pulse parameters otherwise. +- Optionally, a drainage term $\tau_\shortparallel$ that models an exponential decay in the pulse amplitude through an +additional factor $e^{-\frac{t-t_k}{\tau_\shortparallel}}$ in the pulse evolution. +- Spatial and temporal resolution. +- Degree of pulse overlap by setting different ratios of number of pulses to signal length and domain size. +- Total duration of the process. + +This allows researchers to systematically test and benchmark +tracking algorithms and velocity estimation techniques in a controlled setting. +Originally developed for studying turbulence-driven transport in fusion plasma +experiments, blobmodel is applicable to any system where turbulence leads to the +formation of moving structures in one or two-dimensional space. By offering an open-source +and easily accessible tool, blobmodel supports the development and validation of +analysis methods used in experimental and computational research. + +To the authors' knowledge, no other packages exist which provide a comprehensive, +open-source framework for generating synthetic datasets of uncorrelated, propagating +pulses in one or two spatial dimensions, with fully customizable statistical distributions +for pulse parameters and explicit control over spatial and temporal resolution, pulse overlap, +and drainage effects, as implemented in `blobmodel`. + +For more details visit [blobmodel's documentation](https://blobmodel.readthedocs.io/en/latest/). + +The package has been used to generate synthetic data to study and compare the robustness of +velocity estimation techniques on coarse-grained imaging data [@losada_three-point_2024]. + +Additionally, theoretically predicted radial profiles from stochastic modelling +[@garcia_stochastic_2016; @militello_relation_2016] agree with those obtained with `blobmodel`. + +# Implementation details + +The evolution of the pulses is discretized by the `Blob` class in a three dimensional grid +(two space and one time dimensions) according to the above formula. The discretization grid is provided +by the `Geometry` and the superposition of all pulses is performed by the `Model` class, which also contains functions +for the model initialization. The generation of pulses with pulse parameters following user-specified distribution +functions is performed by the `BlobFactory`. + +Since the simulation domain has finite spatial extent, pulses may originate or extend beyond its boundaries. +If a pulse has a non-bound shape, such as a Gaussian, its tails can still contribute to the +superposition inside the domain. However, in long simulations, most pulses will exist outside the +domain for the majority of the time, making it computationally inefficient to account for all of them. +To improve efficiency, a `speed_up` flag has been added to `Model.make_realization`. When enabled, the model +ignores pulses whose contribution within the domain falls below a user-defined `error` threshold. +This allows for significant computational savings while maintaining accuracy in the simulation. + +Periodicity in the vertical direction is an optional feature. It is implemented by replicating each pulse +at vertical positions $y_b\pm L_y$, where $y_b$ is the pulse's original position and $L_y$ is the vertical +size of the simulation domain. This ensures that blobs crossing the upper or lower boundaries are correctly +wrapped around, maintaining continuity in the periodic direction. + +This package is fully compatible with `xarray` [@hoyer_xarray_2017], with all outputs provided as `xarray` datasets +for easy handling and analysis. + +# Acknowledgements + +This work was supported by the UiT Aurora Centre Program, UiT The Arctic University of Norway (2020). + +# References