Merge branch 'main' of

github.com:EHTJulia/ScatteringOptics.jl into main

undefined

.github/workflows/draft-pdf.yml

@@ -0,0 +1,23 @@
+on: [push]
+
+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@v1
+        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

Project.toml

@@ -25,12 +25,12 @@ EHTImages = "0.2"
 EHTUtils = "0.1"
 FFTW = "1"
 HypergeometricFunctions = "0.3"
-Interpolations = "0.14"
-NonlinearSolve = "1"
+Interpolations = "0.14, 0.15"
+NonlinearSolve = "1, 3"
 QuadGK = "2"
 SpecialFunctions = "2"
-VLBISkyModels = "0.2, 0.3"
 StationaryRandomFields = "0.1"
+VLBISkyModels = "0.2, 0.3"
 julia = "1.9"
 
 [extras]

README.md

@@ -1,15 +1,26 @@
 # ScatteringOptics
-
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://EHTJulia.github.io/ScatteringOptics.jl/stable/)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://EHTJulia.github.io/ScatteringOptics.jl/dev/)
 [![Build Status](https://github.com/EHTJulia/ScatteringOptics.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/EHTJulia/ScatteringOptics.jl/actions/workflows/CI.yml?query=branch%3Amain)
-[![Coverage](https://codecov.io/gh/EHTJulia/ScatteringOptics.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/EHTJulia/ScatteringOptics.jl)
+[![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
+
+`ScatteringOptics.jl` is an astronomy software package developed in the Julia programming language for interstellar scintillation observed at radio wavelengths. It implements physical models for the anisotropic scattering of radio waves, which arise from turbulence in the ionized interstellar medium. 
+
+This toolkit is aiming to provide capabilities of simulating and modeling the temporal, spatial, and spectral effects of interstellar scintillation primarily in the strong scattering regime, with taking advantage of Julia's speed and composability. 
+The package is designed to work with sky models and interferometric data types from the advanced Bayesian radio interferometric modeling package [`Comrade.jl`](https://github.com/ptiede/Comrade.jl).
 
-This Julia Package provides a framework to simulate Interstellar-Medium-generated stochastic scattering on EHT VLBI models.
+The package provides essential functionalities for modeling, analyzing, and interpreting the images of the Galactic Center's supermassive black hole, Sagittarius A*, especially with the Event Horizon Telescope, and also the images of extremely high brightness temperature emissions in active galactic nuclei using space very long baseline interferometry.
 
 ## Installation
-The package is installable by
+The package is registered in the Julia standard repository, and installable through the standard ways by
 ```julia
 using Pkg
-Pkg.add("StationaryRandomFields")
+Pkg.add("ScatteringOptics")
 ```
+or
+```julia
+]add ScatteringOptics
+```
+
+## Documentation
+The documentation is available [here](https://ehtjulia.github.io/ScatteringOptics.jl).

docs/make.jl

@@ -17,6 +17,7 @@ makedocs(;
     pages=[
         "Home" => "index.md",
         "Tutorial" => "tutorial.md",
+        "ScateringOptics.jl API" => "autodocs.md"
         "Mathematics" => "math.md"
     ],
 )

docs/src/autodocs.md

@@ -0,0 +1,13 @@
+```@meta
+CurrentModule = ScatteringOptics
+```
+# ScateringOptics.jl API
+
+## Index
+```@index
+```
+
+## Docstrings
+```@autodocs
+Modules = [ScatteringOptics]
+```

docs/src/index.md

@@ -1,9 +1,7 @@
 ```@meta
 CurrentModule = ScatteringOptics
 ```
-
 # ScatteringOptics
-
 [ScatteringOptics](https://github.com/EHTJulia/ScatteringOptics.jl) implements the 'Stochastic Optics' scattering mitigation framework [1] to produce realistic scattering on an input EHT model. The module addressed two distinctive forms of scattering--diffractive blurring and refractive scintillation--independently and then integrates them to output a fully scattered model via the `scatter()` function.
 
 ## Diffractive Kernel
@@ -14,11 +12,4 @@ A `RefractivePhaseScreen` object automatically generates a refractive power law
 
 ## References
 [1] M. D. Johnson. Stochastic optics: A scattering mitigation framework for radio interferometric
-imaging. The Astrophysical Journal, 833(1):74, dec 2016. doi: [10.3847/1538-4357/833/1/74](https://iopscience.iop.org/article/10.3847/1538-4357/aadcff).
-
-```@index
-```
-
-```@autodocs
-Modules = [ScatteringOptics]
-```
+imaging. The Astrophysical Journal, 833(1):74, dec 2016. doi: [10.3847/1538-4357/833/1/74](https://iopscience.iop.org/article/10.3847/1538-4357/aadcff).

docs/src/math.md

@@ -0,0 +1,35 @@
+# Mathematics
+
+`ScatteringOptics.jl` implements a single thin-screen scattering model (described in  [1] and [2]) that simulates both diffractive and refractive scattering. In many instances, the properties of the interstellar scattering can be well described by a single, thin phase-changing screen $\phi_r(r)$, where $r$ is a transverse coordinate on the screen. The statistical characteristics of scattering can be described by those of the phase screen through its spatial structure function $D_\phi(r)$.
+
+Diffractive scattering causes the angular broadening of the source image. 
+The diffractively scattered image ${I_{ea}}(r)$ is mathematically given by the convolution of the source image ${I_{src}}(r)$ with a blurring scattering kernel, ${G}(r)$, 
+
+$${I_{ea}}(r) = {I_{src}}(r) * {G}(r),$$
+
+where $r$ refers to the two-dimensional phase screen coordinate vector. In radio interferometry, each set of measurements, so-called visibilities, obtained with a pair of antennas at different time and frequency segments, samples a Fourier component of the sky image. The source visibilities, $V_{src}(b)$, are related to the diffractively scattered visibilities, $V_{ea}(b)$, by,
+
+$$V_{ea}(b) = V_{src}(b)\,\text{exp}\left[-\frac{1}{2} D_\phi\left(\frac{b}{1+M}\right)\right],$$
+
+in which $b$ is the baseline vector between observing stations. The magnification $M=D/R$ is the ratio of earth-screen distance $D$ to screen-source distance $R$. 
+
+Refractive scattering further introduces compact substructures on the diffractively-scattered, angular-broadened images. 
+The compact substructures arise from phase gradients on the scattering screen $\nabla \phi_r(r)$.
+The refractively scattered image ${I_{a}}(r)$ is given by
+
+$${I_{a}}(r) \approx {I_{ea}}(r) (r + r_F^2 \nabla \phi_r(r)),$$
+
+in which the Fresnel scale, $r_F = \sqrt{\frac{DR}{D+R}\frac{\lambda}{2\pi}}$ is dependent on the observing wavelength $\lambda$ [@Johnson_Narayan_2016]. 
+
+`ScatteringOptics.jl` implements three analytic probabilistic models for the phase screen $\phi_r(r)$, named Dipole, Periodic Boxcar, and Von Mises models in @Psaltis_2018, providing the corresponding semi-analytic descriptions of the phase structure function $D_\phi(r)$. The default model is the Dipole model, known to be consistent with multi-frequency measurements of Sgr A* [1].
+
+
+## References
+
+[1] M. D. Johnson. Stochastic optics: A scattering mitigation framework for radio interferometric
+imaging. The Astrophysical Journal, 833(1):74, dec 2016. DOI: [10.3847/1538-4357/833/1/74](https://iopscience.iop.org/article/10.3847/1538-4357/aadcff).
+
+[2] D. Psaltis, M. Johnson, R. Narayan, L. Medeiros, L. Blackburn, and G. Bower. A model for
+anisotropic interstellar scattering and its application to sgr a*, 2018.
+
+[3] Johnson, M. D., & Narayan, R. (2016). The Optics of Refractive Substructure. 826(2), 170. DOI:[10.3847/0004-637X/826/2/170](https://iopscience.iop.org/article/10.3847/0004-637X/826/2/170)

docs/src/tutorial.md

@@ -3,7 +3,7 @@ CurrentModule = ScatteringOptics
 ```
 
 # Tutorial
-This example code segment uses ScatteringOptics.jl to generate ISM scattering on an input [Comrade.jl](https://github.com/ptiede/Comrade.jl) `SkyModel` object via the `image_scatter()` function
+This example code segment uses ScatteringOptics.jl to simulate interstellar scattering on an input [Comrade.jl](https://github.com/ptiede/Comrade.jl) `SkyModel` object via the `image_scatter()` function.
 
 
 ```julia
@@ -21,7 +21,7 @@ imshow(im, angunit=EHTUtils.μas)
 ```
 ![fig](images/src.png)
 
-Optionally, users can retrieve a purely diffractive scattering ensemble average image with the `convolve` function in `VLBISkyModels.jl`
+Optionally, users can retrieve a purely diffractive scattering ensemble average image with the `convolve` function in `VLBISkyModels.jl`.
 
 ```julia
 # Initialize a scattering model with desired scattering paramaters, otherwise default ISM parameters are used
@@ -42,8 +42,7 @@ imshow(im_ea, angunit=EHTUtils.μas)
 ```
 ![fig](images/ea.png)
 
-Otherwise, the scattering kernel `skm` is not required to obtain a fully scattered image. A `RefractivePhaseScreen` type object may 
-be initialized from the `ScatteringModel` and image dimensions. 
+Otherwise, the scattering kernel `skm` is not required to obtain a fully scattered image. A `RefractivePhaseScreen` type object may be initialized from the `ScatteringModel` and image dimensions. 
 
 ```julia
 # Create a refractive phase screen model from scattering model and image dimensions