Instruction for use of <Ne3dTomo> on tomographic reconstruction of 
 3D electron density of the corona using polarized brightness (pB) observations 
 from STEREO/COR1
 by Tongjiang Wang (email: wangt@cua.edu)
Revision history:
  May 5, 2025 Second releaase: F90 code on spheric grid using OpenMP. Tests show the
computing speed with 6 threads is about 3 times faster than the single thread case.
For single-thread codes on Cartesian and spheric grids, refer to the first release
at https://stereo-ssc.nascom.nasa.gov/data/ins_data/secchi/N3D_COR1B/Source-Code/
The updated codes are also available in https://github.com/wang201806/Ne3dTomo
--------------------------------------------------------------------------------
 # Method
 The detailed method, applications to STEREO/COR1 data, validation, and uncertainty 
 analysis are discussed in the publication "Wang, T., Arge, C.N., & Jones, S., 
 "Improved Tomographic Reconstruction of 3D Global Coronal Density from STEREO/COR1 
 Observations", Solar Physics, (2025) 300:46 at https://doi.org/10.1007/s11207-025-02454-8

 # Required environment and Softwares
  Fortran 90 Compiler: ifx or gfortran in Linux OS
  The codes developed here (for spheric grid and cross validation) utilized m_mrgrnk.f90 
  in orderpack by Michel Olagnon (with CC0 1.0 Universal license; downloaded
  from http://www.fortran-2000.com/rank/)

 # Data preparation
   COR1 pB images are obtained from sets of three COR1 images taken at the polarizer angles
  (0,120,240) in sequence (see detailed descriptions in https://cor1.gsfc.nasa.gov/guide/).
   The IDL routines for data processing including despikes, rebinning, calculating the pB(r)
   background, the satellite position, and converting data from IDL format into the Fortran 
   readable format are included with examples.

 # Usage:
   1. Explanations for sub-directories created after unzipping the downloaded file:
    CR2098-P1/: including 28 128x128 pB images "pb_cor1A_sz128_[1-28].dat" to demonstrate the
           reconstruction of CR2098-P1. "cobs_cor1A.tex" includes the locations of 
           observer (STEREO/COR1-A).  "ybk-xr_cor1A.tex": the background pB and density as a
           function of radial distance.
    idl-prep/  : including idl routies to prepare the input data for F90 code and the routine 
           to show the result generated by Fortran codes

     * Demonstration for data preparation
       in CR2098-P1/: idlsav file "pbmaps_cor1A.sav" includes 28 pB images in ssw map-struct,
         which can be obtained using cor1_pbmap.pro
      i) Despike and rebin the pB images into 128x128 using SSW 
      sat='A'
      crdir='../CR2098-P1/'
      idl> pbname=crdir+'pbmaps_cor1'+sat+'.sav'
      idl> outname=crdir+'pbmaps_cor1'+sat+'_dspk.sav'
      idl> bkname=crdir+'pbmaps_cor1'+sat+'_pbk.sav'
      idl> preview_data,sat,/sav,/filt,name_in=pbname,name_out=outname,/quick
      The idlsav file "pbmaps_cor1A_dspk.sav" is generated in "CR2098-P1/".

      ii) Calculate the radially-dependent pB background pB(r)
      idl> get_cor1_bbk, /sav,sat=sat,name_in=outname, name_out=bkname
      The idlsav file "pbmaps_cor1A_pbk.sav" is generated in "CR2098-P1/".

      iii) Generate the data as input for Fortran code
      idl> idl2f90_data
      "pb_cor1A_sz128_[1-28].dat, cobs_cor1A.tex, and ybk-xr_cor1A.tex" are generated in "CR2098-P1/"
       
     *Compilation of F90 code in bash-shell:
      ./omp_make
 
     *Run the code in bash shell with 6 threads as default setting
     ./omp_run.bsh
      read the parameter file "param_sph_omp.txt" for the setting of parameters.
     Note:
 	1) This version only provides second-order smoothing 
        2) Since the computation of matrix R in spheric grid is very fast, saving the result
        for R is not necessary: set write_Rbuff=0, read_Rbuff=0. However, if you want to apply
        the cross-validation to determine the optimal mu, you need to create a file for storing
         matrix R by setting write_Rbuff=1 (refer to: codes in first release)
     Output: the solution is saved in a file with the default name [nsolu_p361t181r51_reg2_nwt.dat] in CR2098-P1/

    * To show the result
      In idl-prep/
      idl> .r cmp_nsolu_f90-wt
      idl> cmp, 2.5
      Show the density maps at r=2.5 Rsun and radial profile of the mean density  


   # Acknowledgement
    Important! Please cite the following paper to acknowledge the developer when  
    publishing the results, obtained from the original and modified codes. 
    "Wang, T., Arge, C.N., & Jones, S., Improved Tomographic Reconstruction of 3D Global 
     Coronal Density from STEREO/COR1 Observations", Solar Physics, (2025) 300:46 
     DOI: 10.1007/s11207-025-02454-8
     Thank you very much. 


   # License
    All Copyrights (C) 2025 are reserved by Tongjiang Wang (wangt@cua.edu).

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version. Read the file LICENSE in detail. 

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details, 
    https://www.gnu.org/licenses/gpl-3.0.txt.

   
   # Report problems or bugs
     please contact Tongjiang Wang sending emails to wangt@cua.edu 
--------------------------------------------------------------------------------------------
