update docs

Magritte-code · Jul 27, 2023 · 2aa4a5f · 2aa4a5f
1 parent 2adc5ed
commit 2aa4a5f
Show file tree

Hide file tree

Showing 7 changed files with 307 additions and 42 deletions.
diff --git a/README.md b/README.md
@@ -8,6 +8,20 @@ _Probabilistic 3D Reconstruction of Spectral Line Observations._
 ![Build status](https://github.com/Magritte-code/p3droslo/actions/workflows/upload-to-anaconda.yaml/badge.svg)
 
 
+## About
+
+p3droslo is a software library for probabilistic 3D reconstruction of astronomical spectral line observations.
+Observations of [spectral lines](https://en.wikipedia.org/wiki/Spectral_line) are indespensible in astronomy, since they encode a lot of information about the physical and chemical conditions of the medium in which they were formed.
+For instance, their narrow extend in frequency space make them very sensitive to Doppler shifts, such that their shape encodes the motion of the medium along the line of sight.
+Given a good model for the line formation process and a good inversion method, these physical and chemical properties can be retrieved.
+Currently, we mainly focus on retrieving the distributions of the abundance of the chemical species producing the line, the velocity field, and its kinetic temperature.
+
+More information about the model for [spectral line formation](https://p3droslo.readthedocs.io/en/latest/background/spectral_line_formation.html) and the [probabilistic reconstruction methods](https://p3droslo.readthedocs.io/en/latest/background/probabilistic_reconstruction.html) can be found in the [background](https://p3droslo.readthedocs.io/en/latest/background/index.html) pages.
+
+p3droslo is built on top of [PyTorch](https://pytorch.org) and benefits a lot from functionality provided by [Astropy](https://www.astropy.org).
+It is currently developed and maintained by [Frederik De Ceuster](https://freddeceuster.github.io) at [KU Leuven](https://www.kuleuven.be/english/kuleuven/index.html).
+
+
 ## Installation
 
 Get the latest release (version 0.0.14) either from [PyPI](https://pypi.org/project/p3droslo/), using `pip`, with:
@@ -42,7 +56,7 @@ We are open to contributions to p3droslo. More information can be found [here](h
 
 ## Collaborating
 
-We are always interested in collaborating on exciting projects! So, if you have a project or just an idea, or data that might benefit from probabilistic 3D reconstruction or any other thing you can find in this repository, please contact [me](https://freddeceuster.github.io).
+We are always interested in collaborating on exciting projects! So, if you have a project or just an idea, or data that might benefit from probabilistic 3D reconstruction or any other thing you can find in this repository, feel free to contact [me](https://freddeceuster.github.io).
 
 
 ## Acknowledgements

diff --git a/docs/src/background/index.rst b/docs/src/background/index.rst
@@ -7,4 +7,5 @@ Some background on the physics of spectral line observations, the probabilistic
    :maxdepth: 2
    :caption: Contents:
 
-   radiative_transfer
+   spectral_line_formation
+   probabilistic_reconstruction
diff --git a/docs/src/background/probabilistic_reconstruction.ipynb b/docs/src/background/probabilistic_reconstruction.ipynb
@@ -0,0 +1,26 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Probabilistic Reconstruction"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/src/background/radiative_transfer.ipynb → .../background/spectral_line_formation.ipynb b/docs/src/background/radiative_transfer.ipynb → .../background/spectral_line_formation.ipynb
diff --git a/docs/src/benchmarks/Benchmark_0.ipynb b/docs/src/benchmarks/Benchmark_0.ipynb
diff --git a/docs/src/index.rst b/docs/src/index.rst
@@ -1,8 +1,7 @@
 p3droslo
 ########
 
-Welcome to the p3droslo documentation! p3droslo is a software library for probabilistic 3D reconstruction of astronomical spectral line observations, developed by `Frederik De Ceuster <https://freddeceuster.github.io>`_.
-
+Welcome to the p3droslo documentation!
 
 .. toctree::
    :maxdepth: 1
@@ -13,6 +12,21 @@ Welcome to the p3droslo documentation! p3droslo is a software library for probab
    API/index
 
 
+About
+*****
+
+p3droslo is a software library for probabilistic 3D reconstruction of astronomical spectral line observations.
+Observations of `spectral lines <https://en.wikipedia.org/wiki/Spectral_line>`_ are indespensible in astronomy, since they encode a lot of information about the physical and chemical conditions of the medium in which they were formed.
+For instance, their narrow extend in frequency space make them very sensitive to Doppler shifts, such that their shape encodes the motion of the medium along the line of sight.
+Given a good model for the line formation process and a good inversion method, these physical and chemical properties can be retrieved.
+Currently, we mainly focus on retrieving the distributions of the abundance of the chemical species producing the line, the velocity field, and its kinetic temperature.
+
+More information about the model for `spectral line formation <https://p3droslo.readthedocs.io/en/latest/background/spectral_line_formation.html>`_ and the `probabilistic reconstruction methods <https://p3droslo.readthedocs.io/en/latest/background/probabilistic_reconstruction.html>`_ can be found in the `background <https://p3droslo.readthedocs.io/en/latest/background/index.html>`_ pages.
+
+p3droslo is built on top of `PyTorch <https://pytorch.org>`_ and benefits a lot from functionality provided by `Astropy <https://www.astropy.org>`_.
+It is currently developed and maintained by `Frederik De Ceuster <https://freddeceuster.github.io>`_ at `KU Leuven <https://www.kuleuven.be/english/kuleuven/index.html>`_.
+
+
 Installation
 ************
 
@@ -52,7 +66,7 @@ We are open to contributions to p3droslo. More information can be found `here <h
 Collaborating
 *************
 
-We are always interested in collaborating on exciting projects! So, if you have a project or just an idea, or data that might benefit from probabilistic 3D reconstruction or any other thing you can find in this repository, please contact `me <https://freddeceuster.github.io>`_.
+We are always interested in collaborating on exciting projects! So, if you have a project or just an idea, or data that might benefit from probabilistic 3D reconstruction or any other method you can find in this repository, feel free to contact `me <https://freddeceuster.github.io>`_.
 
 
 Acknowledgements

diff --git a/src/p3droslo/lines.py b/src/p3droslo/lines.py
@@ -329,14 +329,17 @@ def optical_depth_along_last_axis2(self, chi_ij, density, temperature, v_turbule
 
         # Define the a and b (tabulated) functions
         a = (1.0/sqrt_pi) * inverse_width * chi_ij * density
-        a = torch.einsum("...,    f -> ...f", a, torch.ones_like(frequencies))
+        # a = torch.einsum("...,    f -> ...f", a, torch.ones_like(frequencies))
         b = torch.einsum("..., ...f -> ...f", inverse_width, freqs_restframe - self.frequency)
 
         expb = torch.exp(-b**2) 
         erfb = torch.erf( b   ) 
 
-        a0 = a[..., :-1, :]
-        a1 = a[..., 1: , :]
+        # a0 = a[..., :-1, :]
+        # a1 = a[..., 1: , :]
+
+        a0 = a[..., :-1]
+        a1 = a[..., 1: ]
 
         b0 = b[..., :-1, :]
         b1 = b[..., 1: , :]
@@ -350,27 +353,30 @@ def optical_depth_along_last_axis2(self, chi_ij, density, temperature, v_turbule
         b10 = b1 - b0
 
         # threashhold differentiating the two regimes (large and small Doppler shift)
-        shift_threshold = 1.0e-3
+        shift_threshold = 1.0e-4
 
         # Define the masks for the threashold    
-        # A = torch.ones_like(b10, dtype=bool) #torch.Tensor(torch.abs(b10) >  shift_threshold)
-        # B = torch.zeros_like(b10, dtype=bool) #torch.Tensor(torch.abs(b10) <= shift_threshold)
+        # A = torch.Tensor(torch.abs(b10) >= shift_threshold)
+        B = torch.Tensor(torch.abs(b10) <  shift_threshold)
 
-        dtau = torch.empty_like(b10)
+        # dtau = torch.empty_like(b10)
 
         # dtau[A]  =           (      a1[A] -       a0[A]) * (expb0[A] - expb1[A])
         # dtau[A] += sqrt_pi * (b0[A]*a1[A] - b1[A]*a0[A]) * (erfb0[A] - erfb1[A])
         # dtau[A] *= 0.5 / b10[A]**2
 
-        dtau  =           (   a1 -    a0) * (expb0 - expb1)
-        dtau += sqrt_pi * (b0*a1 - b1*a0) * (erfb0 - erfb1)
-        dtau *= 0.5 / b10**2
+        sp_a1b0 = torch.einsum("..., ...f -> ...f", sqrt_pi * a1, b0)
+        sp_a0b1 = torch.einsum("..., ...f -> ...f", sqrt_pi * a0, b1)
+
+        dtau  = torch.einsum("..., ...f -> ...f", a1 - a0, expb0 - expb1)
+        dtau += (sp_a1b0 - sp_a0b1) * (erfb0 - erfb1)
+        dtau *= (0.5 / b10**2)
 
-        # dtau[B]  = (1.0/ 2.0) * (a0[B] +     a1[B])
-        # dtau[B] -= (1.0/ 3.0) * (a0[B] + 2.0*a1[B]) * b0[B]                        * b10[B]   
+        dtau[B]  = (1.0/ 2.0) * (a0[B] +     a1[B])
+        dtau[B] -= (1.0/ 3.0) * (a0[B] + 2.0*a1[B]) * b0[B]                        * b10[B]   
         # dtau[B] += (1.0/12.0) * (a0[B] + 3.0*a1[B]) *         (2.0*b0[B]**2 - 1.0) * b10[B]**2
         # dtau[B] -= (1.0/30.0) * (a0[B] + 4.0*a1[B]) * b0[B] * (2.0*b0[B]**2 - 3.0) * b10[B]**3
-        # dtau[B] *= expb0[B]
+        dtau[B] *= expb0[B]
 
         # dtau  = (1.0/ 2.0) * (a0 +     a1)
         # dtau -= (1.0/ 3.0) * (a0 + 2.0*a1) * b0                     * b10