rtsos 1.1.0rc1__tar.gz

rtsos-1.1.0rc1/.gitignore

@@ -0,0 +1,5 @@
+shellscripts/
+__pycache__
+.DS_Store
+/build
+/dist

rtsos-1.1.0rc1/CMakeLists.txt

@@ -0,0 +1,41 @@
+cmake_minimum_required(VERSION 3.22...3.31)
+
+if(DEFINED SKBUILD_PROJECT_NAME)
+    set(_PROJECT "${SKBUILD_PROJECT_NAME}")
+else()
+    set(_PROJECT "RTSOS")
+endif()
+project(${_PROJECT}
+    LANGUAGES
+        C
+        CXX
+        Fortran
+)
+include(GNUInstallDirs)
+
+# ensure RPATH is defined for relocatable binaries
+set(CMAKE_INSTALL_RPATH "$ORIGIN/../lib")
+set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
+
+# for Conda environment installation with cmake
+if(DEFINED ENV{CONDA_PREFIX})
+    message(STATUS "Building with conda environment: $ENV{CONDA_PREFIX}")
+    list(APPEND CMAKE_PREFIX_PATH "$ENV{CONDA_PREFIX}")
+    set(CMAKE_INSTALL_PREFIX "$ENV{CONDA_PREFIX}" CACHE PATH "Default install prefix for Conda environment" FORCE)
+endif()
+
+# import targets that satisfy the HDF5 dependency
+find_package(HDF5
+    REQUIRED
+    COMPONENTS
+        Fortran
+        HL
+)
+
+# import targets that satisfy the Lapack dependency (includes BLAS)
+find_package(LAPACK
+    REQUIRED
+)
+
+# recurse into source tree
+add_subdirectory(src)

rtsos-1.1.0rc1/Documentation/Describtion_of_input_files/SOS_io.tex

@@ -0,0 +1,271 @@
+%%%%%%%%%%%%%%%%%%%%%%% preamble %%%%%%%%%%%%%%%%%%%%%%%%%%%
+\documentclass[10pt,letterpaper]{article}
+\usepackage{amsmath}
+\usepackage{subfigure}
+
+%%%%%%%%%%%%%%%%%% title page information %%%%%%%%%%%%%%%%%%
+\title{Input and Output Files of the RTSOS Code}
+
+\author{Pengwang Zhai \\ Physics Department, UMBC \\ pwzhai@gmail.com}
+
+%%%%%%%%%%%%%%%%%%%%%%% begin %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\begin{document}
+
+\maketitle
+%%%%%%%%%%%%%%%%%%% abstract and OCIS codes %%%%%%%%%%%%%%%%
+%% [use \begin{abstract*}...\end{abstract*} if exempt from copyright]
+
+\begin{abstract}
+The input and output files of the RTSOS code are described this file
+\end{abstract}
+
+
+\section{Files contained in the package}
+In the main directory, there are a few key directories, including \verb"SOSDIR/SOS_Callable/src/", \verb"SOSDIR/SOS_Callable/compile/", and \verb"SOSDIR/SOS_Callable/test/". The string \verb"SOSDIR" is the directory where the radiative transfer package is in. The src directory including all the source code, the compile directory contains the Makefiles, and the test directory are intent to be used as running programs. The basis of all package is \verb"rtsos_rao_dg.f90", which performs monochromatic radiative transfer simulations. All inelastic scattering builds upon that.
+
+\section{Input files of monochromatic simulation}
+The input files are: \verb"sosi.amu", \verb"sosi.dat",  and the Mie input files for each medium. To run the monochromatic radiative transfer simulation, do the following:
+
+\begin{verbatim}
+cd SOSDIR/compile
+make
+cp rtsos_rao_dg.exe ../test/monochromatic/
+cd ../test/monochromatic/
+rtsos_rao_dg.exe inputfile outputfile
+\end{verbatim}
+
+\noindent where inputfile is a copy of sosi.dat explained in this document and outputfile is the file name for the output file.
+
+\section{Angle file}
+\verb"sosi.amu" specifies the angle related quantities used by the RTSOS code.  An example of the file is:
+
+\begin{verbatim}
+1
+120
+10  4
+0.0
+20.
+40.
+60.
+80.
+100.
+120.
+140.
+160.
+180. 
+0
+60.
+120.
+180
+\end{verbatim}
+
+The first line is the number $N_{st}$ of $\theta_{s}$ angles for the solar incident radiation.  The second line to the ${(2+N_{st}-1)}^{th}$ line specify the incident solar angles $\theta_{s}$ at which the radiation calculation is needed.  Each line contains one solar $\theta_{s}$ angle only, with the unit of degrees.  In the example, thetas=120 deg. After the solar zenith angle, following line has two numbers: they are the number of viewing zenith and azimuth angles, respectively.  In the example, the number of viewing zenith angle is Nzv=10 and the number of azimuthal angle is Nphi=4.  Following the number will be Nzv lines which specify the viewing zenith angles.  After viewing zenith angle, it will be Nphi lines which specify a set of azimuthal angles. In the example, the RTSOS code will calculate a set of viewing zenith angle of 0, 20, ..., 180.  The viewing azimuthal angles are 0, 60, 120 and 180.
+
+\section{Input file sosi.dat}
+\verb"sosi.dat" specifies the system configuration.  Table \ref{tab:sosi} is an example input file.
+\begin{table}
+\caption{Example input file sosi.dat}
+\vspace{0.2 in}
+\centering
+\begin{tabular}{llllllll}
+&-1000 &  0.0  & 0.0   &  0.0   &  0.0    & 0.0   & 0.0   \\
+&1        &  0.1  & 1.0   & 412.0& 215.0 & 0.0   & 0.0   \\
+&-1000 &  0.0  & 0.0   &  0.0   &  0.0    & 0.0   & 0.0   \\
+&-100   &  7.0  & 1.34 &  0.0   &   0.0   & 0.0   & 0.0   \\
+&-1000 &  0.0  & 0.0   &   0.0  &  0.0    & 0.0   & 0.0   \\
+&2        &  0.1  & 1.0   & 412.0& 215.0 & 0.0   & 0.0   \\
+&-1000 &  0.0  & 0.0   &   0.0  & 0.0     & 0.0   & 0.0   \\
+&-200   &  1.0  & 1.0   &   1.5  &  0.0    & 0.0   & 0.0   \\
+&40      &  30   & 60    &          &           &         &         \\
+&2        &  30     & 10      &          &           &         &         \\
+&RayDepol0.pmtx        &        &           & &     &     &               \\
+&gamma\_aa\_0.03bb\_0.33wv0.35.pmtx    &       &    & &         &      &         \\
+\end{tabular}
+\label{tab:sosi}
+\end{table}
+
+There are 12 lines in the example input file.  From the first line to 9th line, each line contains 7 numbers.  The first number is called IPT in the code, which tells what this line is (detector, medium, surface, etc.).  There are four types of objects you can specify through IPT:  Detector, Atmosphere or Ocean scattering layers, Ocean interface, and the Lambertian/(polarized BRDF) bottom.  Table \ref{tab:IPT} shows the meanings of different IPT values:
+
+\begin{table}
+\caption{IPT and its meaning}
+\vspace{0.2 in}
+\centering
+\begin{tabular}{ll}
+IPT=-1000 & Detector \\
+IPT=-100   & Ocean interface\\
+IPT=-101   & Ocean interface as the lower bottom (no ocean medium)\\
+IPT=-102   & Water interface bottom in infrared \\
+IPT=-200   & Lambertian/flat surface mixed reflection bottom   \\
+IPT=-201   & polarized reflection bottom  \\
+IPT=-202   & snow surface  \\
+IPT=-203   & Ross-Li surface model  \\
+IPT=$>$0  & Atmosphere or Ocean scattering medium
+\end{tabular}
+\label{tab:IPT}
+\end{table}
+
+In this input file, a default coordinate system has been assumed.  The first Atmosphere scattering medium is located at the top of the atmosphere.  
+The scattering medium line to the line of IPT=-100 (or -200, or -201, etc.) specify the atmosphere configuration.  
+The line just after the line of IPT=-100 to the line of IPT=-200 configure the oceanic medium.
+IPT=-200 means a mixture of Lambertian and flat reflecting surface.  
+No more atmosphere and ocean medium configuration is allowed beyond the line of IPT=-200 (-101, or -201) because no medium is beyond the bottom.
+
+\begin{table}
+\caption{Inputfile fields}
+\vspace{0.2 in}
+\centering
+\begin{tabular}{llllllll}
+&IPT=-1000 & BN&BN&BN& BN&BN&BN \\
+&IPT $>$ 0 &TAU&LBDOM&wavelength&Temperature&EFLRSC&ALH \\
+&IPT=-101  & windspeed & re(mwater) & im(mwater) & glintflag & RSR0P & FWC \\
+&IPT=-100  & windspeed & re(mwater) & im(mwater) & glintflag,& RSR0P & FWC \\
+&IPT=-102 & windspeed& re(mwater)& im(mwater)&glintflag&temperature&emissivity \\
+&IPT=-200 & albedo &flam&re(mbottom)&im(mbottom)&temperature&emissivity \\
+&IPT=-201 & pBRDFa&pBRDFk&pBRDFb&pBRDFe&re(mbottom)&im(mbottom) \\
+&IPT=-202  & albedo& BN& BN& BN& BN& BN \\
+&IPT=-202  & fiso &fvol & fgeo & BN & BN& BN \\
+\end{tabular}
+\label{tab:InputFile}
+\end{table}
+
+Including the IPT, there are 7 numbers at each line.  Table \ref{tab:InputFile} shows the proctor used for interpreting the inputs. BN means Blank Number, which is currently not used by the program; TAU is the optical depth of that layer; LBDOM is the single scattering albedo of that layer; wavelength is in micron, which is used in inelastic scattering simulations or infrared monochromatic simulations; Temperature is in Kelvin, which is only useful when you calculate infrared radiative transfer. EFLRSC is internally used by the inelastic scattering of ocean waters (by default it is set to 0 in monochromatic simulations); ALH is the atmospheric layer top height. ALH is only useful for calculating pseudospherical shell. To perform pseudospherical shell calculation, use the following in your main program:
+
+%/Users/pwzhai/Research/RT/DSCOVR/SnowBRDF_Data/brdfPaperMaterial/  #snow brdf file path
+\begin{verbatim}
+USE RTUTILITY, ONLY : PSEUDO_SPHERICAL_SHELL
+.
+.
+.
+
+PSEUDO_SPHERICAL_SHELL=.true.
+\end{verbatim}
+
+\noindent And set ALH as the atmospheric layer top heights properly.
+
+WindSpeed is the wind speed (m/s); re(mwater) and im(mwater) are the real and imaginary parts of the water refractive index; GlintFlag = 0 includs sun glints while  GlintFlag = 1 does NOT include sun glint; RSR0P is the remote sensing reflectance just above the ocean surface. RSR0P is a user supplied value to calculate how Remote Sensing Reflectance just above ocean water propagate to the sensor level. 
+
+FWC is the fraction of white cap on surface. By default FWC is set to be zero in the input file, and its actual value will be calculated in RTSOS based on a parameterization in terms of wind speed. If FWC is set to be a number larger than 0 (and smaller than or equal to 1), then  RSR0P should be set to: RSR0P=WCLBDO/PI, where WCLBDO is the equivalent Lambertian reflectance of white cap or other surface debris. Currently the option for user supplied FWC values is only available for IPT=-101 and IPT=-100.
+
+For normal radiative transfer simulation, RSR0P should be zero by default. The interpretation of RSR0P can be summarized in the following four cases: \\
+
+\begin{itemize}
+\item IPT=-101, RSR0P$>$0, FWC=0.0: no ocean radiative transfer will be conducted, RSR0P would be the remote sensing reflectance of the ocean body based on in-situ measurement. \\
+\item  IPT=-101, RSR0P$>$0, FWC$>$0.0:  no ocean radiative transfer will be conducted, RSR0P=WCLBDO/PI, where WCLBDO is the equivalent Lambertian reflectance of white cap or other surface debris, and FWC is the fraction of white cap on surface. \\
+\item  IPT=-100, RSR0P$>$0, FWC$>$0.0:  full atmosphere-ocean radiative transfer will be conducted, RSR0P=WCLBDO/PI, where WCLBDO is the equivalent Lambertian reflectance of white cap or other surface debris, and FWC is the fraction of white cap on surface. \\
+\item  IPT=-100, RSR0P=0, FWC=0.0:  full atmosphere-ocean radiative transfer will be conducted, WCLBDO and FWC are internally calculated in RTSOS based on parameterization in terms of wind speed.
+\end{itemize}
+
+For Lambertian surface, the value of  albedo tells the lambertian surface reflection albedo;  flam is the fraction of the surface which is lambertian reflection; The values of re(mbottom) and im(mbottom) are the real and imaginary refractive index of the surface which are used to determine Fresnel reflection when flam is less than 1. 
+
+Once the RTSOS code reads an IPT of in (-200 -101, -201, -202, -203), it won't accept more atmospheric or ocean layer specification, because there should be nothing below bottom.  The line following the line of IPT=(-200 -101, -201, -202, -203) contains three integers: NCOL, NQUADA, and NQUADO.  NCOL is the number of scattering orders to be performed.  NCOL=10 normally gives fairly good precision. NQUADA and NQUADO are the quadrature numbers needed for the atmosphere and ocean source function integration, respectively.  For the single quadrature code, NQUADO will be ignored.  The next line contains three integers: NUMMIE, MAXLORD, and MAXMORD.  NUMMIE is the number of Mie particle files.  MAXLORD is the maximum L order used to expand the scattering matrices in terms of the Wigner d functions.  MAXMORD is the maximum number of Fourier series order.  There are NUMMIE lines following this line.  Each line specifies the file names of the input files.  The sequence of the file tells the RTSOS code which IPT this file is associated with.
+
+The example input file specifies the following system with each line:
+\begin{itemize}{}
+\item Line 1: A detector is placed at the top of the atmosphere.
+\item Line 2: An atmospheric layer, with an optical thickness of 0.1, and single scattering albedo of 1, IPT=1. Wavelength is 412 nm and temperature is 215 K.
+\item Line 3: A second detector is placed at the bottom of the atmosphere. 
+\item Line 4:  An ocean interface is placed below the atmosphere at the optical depth of 0.1, with the wind speed of 7 m/s, water refractive index is (1.34, 0), sun glint is turned on.
+\item Line 5: A detector is placed at the top of the ocean (just below the ocean interface).
+\item Line 6: An ocean layer is placed below the interface, with optical depth of 0.1, single scattering albedo of 1.0, IPT = 2. Wavelength is 412 nm and temperature is 215 K.
+\item Line 7: A detector is placed at the bottom of the ocean. 
+\item Line 8: A Lambertian bottom is placed at the bottom of the ocean, with reflection albedo of 1.0. The fraction of lambertian reflection $f_{lamb}$=1. The surface refractive index is (1.5, 0), which is only useful if the lambertian fraction is less than 1. In this case the fraction 1-$f_{lamb}$ is characterized by the Frenesl reflection of a flat surface. 
+\item Line 9:  The total number of scattering is 40, with NQUADA=30, NQUADO=60. 
+\item Line 10: There are two Mie input files, the maximum L order is 30, and the order of Fourier series is 10.
+\item Line 11:  IPT=1   ``RayDepol0.pmtx''                will be used
+\item Line 12: IPT=2   gamma\_ aa\_ 0.03bb\_0.33wv0.35.pmtx    will be used
+\end{itemize}
+
+
+The snow surface data is from
+Hudson, S. R., S. G. Warren, R. E. Brandt, T. C. Grenfell, and D. Six (2006), Spectral bidirectional reflectance of Antarctic snow: Measurements and parameterization, J. Geophys. Res., 111, D18106, doi:10.1029/2006JD007290.
+
+If IPT=-202 is specified, the program will read in a string following the pmtx file line which contains the directory of the snow BRDF data.
+
+In the directory that you run \verb!rtsos_rao_dg.exe!, you should have a file called \verb!auxiliary_directory!, which contains the directory of the solar irradiance data file, which is needed when you perform infrared radiative transfer simulations.
+
+The solar irradiance data file is among a collection of data files archived for the PACE simulator, which was documented in the README file of this repo:\
+\verb!https://github.com/aoog-umbc/rtsos-public!
+
+If you have not downloaded it yet, the address of the data file is: \\
+\verb!http://doi.org/10.5281/zenodo.17410093!
+
+The file is named as \verb!RTSOS_data_v1.0_20251022.tar.gz!, which can be placed in a convenient location of your choice, let's call it PACEDATADIR.
+
+You can extract the files by doing the following in a linux terminal:
+
+\begin{verbatim}
+cd PACEDATADIR
+tar -xf RTSOS_data_v1.0_20251022.tar.gz
+\end{verbatim}
+
+You will get two directories. One is \verb!PACEDATADIR/Gas_Absorption_Coefficients/!. The other is PACEDATADIR/Data/, which contains f0.txt, the solar irradiance data file. You can do the following to put PACEDATADIR/Data/ to \verb!auxiliary_directory!: \\
+
+\begin{verbatim}
+cd PACEDATADIR/Data/ 
+pwd > SOSDIR/test/monochromatic/auxiliary_directory
+\end{verbatim}
+
+\noindent where SOSDIR/test/monochromatic/ is the directory of \verb!rtsos_rao_dg.exe!, where you will run the program.
+
+\section{A few nots}
+
+If wind speed is smaller than 0.5 m/s, the code will assume the ocean surface is flat.  Otherwise, the random ocean wave surface will be used.  The wave slope distribution will be Cox \& Munk (1954).
+
+Three truncation scheme are used: delta fit, delta m, and delta m+ are now built-in in the package and the users can select from one of such truncation techniques.
+
+White cap parameterization are implemented.  Physically this means that the code can handle a mixture of lambertian reflector and random rough surfaces.
+
+\section{ Mie input files}
+The RTSOS code needs users provide the Mie particle files before any simulation.  Please refer to our Optics Express (OE) paper for details.  The RTSOS package comes with the Rayleigh examples: \verb"RayDepol0.pmtx"
+
+
+\section{Example}
+The package contains a number of test cases located at
+SOS\_Callable/test/monochromatic/
+and 
+SOS\_Callable/validation/benchmark
+
+ 
+\section{Output file}
+Data in this file are pretty much self-explained.  The top part is the header, which shows the various parameters used in the calculation.  The main body is the Stokes parameters I, Q, U, and V, as functions of viewing angles specified by the zenith angle Theta and azimuthal angle Phi.  TAUDETA shows the optical depth of the detector in atmosphere and TAUDETO shows the optical depth of the detector in ocean.
+
+\section{Important variables in the code}
+The variables listed below are important.  Users should not change them unless they understand what they are doing.
+
+``DELTATAUA''  and ``DELTATAUO'' are the non dimensional step sizes to do optical depth integration in atmosphere and ocean respectively.  The typical value is 0.2 for these two variables.  However, they have to be at most half of the optical depth of a homogeneous layer.  For example, if the optical depth of a homogeneous atmosphere is 0.1, ``DELTATAUA'' has to be 0.05 at most.  If benchmark values are wanted, use `` DELTATAUA=DELTATAUO=0.01.''
+
+ESUN(1:4) is a column vector which specifies the irradiance Stokes vector of the solar incident source.  Set ``ESUN(1)'' to 1 or $\pi$ according to your normalization convention.
+
+``{\bf \verb+WLR_FLAG+}'' is a logical variable.  If ``\verb+WLR_FLAG=.true.+'', water leaving radiance vectors will be calculated for detectors in the atmosphere.
+``\verb+WLR_FLAG=.false.+'' the total radiance vectors will be calculated for specified detectors.
+
+``\verb+TRUC_FLAG+'' is a logical variable. If  ``\verb+TRUC_FLAG=.true.+'', the delta-fit will be used to truncate the phase function and other scattering elements.  The truncation factor f will be read in from the incident file and renormalize the optical depth and single scattering albedo.  Otherwise, set it to .false.  This variable is recommended to set to .true. always.
+
+LINEXP is a logical variable.  If it is set to be ``.true.'',the linear-exponential approximation will be used.  Otherwise, the linear approximation will be used.  The linear-exponential approximation will be always better than the linear approximation.
+
+GEOSR is a logical variable.  ''GEOSR=.true.''  the geometric series approximation  will be used.
+
+SCL is a logical variable.  If ``SCL=.true.'' the code will produce scalar radiance output for detectors. ``SCL=.false.'', vector radiances will be calculated.
+
+\verb+Mishchenko_Sign+: a logical variable.  If ".true.", the code will use Mishchenko's convention for phase matrices expasion.  The reference is:
+
+
+{\it M. I. Mishchenko, L. D. Travis, and A. A. Lacis, Scattering, Absorption, and Emission of Light by Small Particles
+(Cambridge University Press, Cambridge 2002)), Page 103--104}.
+
+
+If ".false.", the code will use Siewert's convention:
+
+{\it C. E. Siewert, ``On the phase matrix basic to the scattering of polarized light,'' Astron. Astrophys. 109, 195200 (1982)}.
+
+Please refer to Eqs. (A-12) in the following paper for details:
+
+{\it Peng-Wang Zhai, et a., ``A vector radiative transfer model for coupled atmosphere and ocean systems based on successive order of scattering method,'' Opt. Express 17, 2057-2079 (2009) 
+http://www.opticsinfobase.org/oe/abstract.cfm?URI=oe-17-4-2057}
+
+new parameter: DELTAM. 
+! DELTAM = 0 USE DELTA M FIT FOR THE PHASE MATRIX truncation
+!          1 USE DELTA M + FIT
+!          2 USE DELTA FIT
+
+\end{document}

rtsos-1.1.0rc1/LICENSE

@@ -0,0 +1,40 @@
+LICENSE
+
+RTSOS – Radiative Transfer model based on Successive Orders of Scattering
+Copyright © 2025 Pengwang Zhai.
+1. License Summary
+RTSOS is made available for research and educational purposes under the terms of the Creative Commons Attribution–NonCommercial 4.0 International License (CC BY-NC 4.0).
+You may freely use, modify, and share this software for non-commercial purposes, provided that you give appropriate credit and include this license notice in any redistribution.
+Commercial use (including use in proprietary or revenue-generating products, consulting services, or contract research for profit) is not permitted without prior written permission.
+For commercial licensing inquiries, please contact:
+📧 Pengwang Zhai – [pwzhai@gmail.com] 
+2. License Terms (CC BY-NC 4.0)
+You are free to:
+Share — copy and redistribute the material in any medium or format
+Adapt — remix, transform, and build upon the material
+under the following terms:
+Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made.
+Example citation:
+Zhai, P. (2025). RTSOS: Radiative Transfer model based on Successive Orders of Scattering (Version 1.0). Zenodo. https://doi.org/xx.xxxx/zenodo.xxxxxx
+NonCommercial — You may not use the material for commercial purposes.
+No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
+The full license text is available at:
+🔗 https://creativecommons.org/licenses/by-nc/4.0/legalcode
+3. Disclaimer of Warranty
+This software is provided “as is”, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement.
+In no event shall the author or copyright holder be liable for any claim, damages, or other liability arising from the use of this software.
+4. Citation and Acknowledgment
+If you use RTSOS in a publication or presentation, please acknowledge:
+Zhai, P. (2025). RTSOS: Radiative Transfer model based on Successive Orders of Scattering (Version 1.0). Available under the CC BY-NC 4.0 License.
+5. Commercial Licensing Clause
+Commercial entities or projects seeking to use RTSOS in any form that contributes to a product, service, or revenue-generating activity must obtain a separate commercial license.
+Please contact the author (Pengwang Zhai) to discuss terms for such use.
+6. Summary (non-legal plain language)
+Use Case	Permitted?	Notes
+Academic research	✅	Cite and acknowledge the author
+Teaching or training	✅	Credit required
+Open-source collaboration (non-commercial)	✅	Allowed under CC BY-NC 4.0
+Government or nonprofit research	✅	Allowed
+Commercial R&D, software, or consulting use	🚫	Requires a commercial license
+
+End of License

rtsos-1.1.0rc1/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: rtsos
+Version: 1.1.0rc1
+Summary: Radiative Transfer model based on Successive Orders of Scattering
+Author-Email: Pengwang Zhai <pwzhai@gmail.com>, Ian Carroll <ian.t.carroll@nasa.gov>
+License-Expression: CC-BY-NC-4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Fortran
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Project-URL: repository, https://github.com/aoog-umbc/rtsos
+Requires-Python: >=3.12
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: xarray>=2022.3
+Requires-Dist: netcdf4>=1.6.1
+Requires-Dist: dask>=2022.10.2
+Description-Content-Type: text/markdown
+
+<!--
+RTSOS — Radiative Transfer model based on Successive Orders of Scattering
+Copyright © 2025 Pengwang Zhai.
+
+Licensed under the Creative Commons Attribution–NonCommercial 4.0
+International License (CC BY-NC 4.0).
+You may use, modify, and share this code for research and
+educational purposes with proper attribution.
+Commercial use requires written permission from the author.
+
+Full license: https://creativecommons.org/licenses/by-nc/4.0/
+Contact: Pengwang Zhai  |  [pwzhai@gmail.com]
+-->
+
+# Radiative Transfer model based on Successive Orders of Scattering (RTSOS)
+
+RTSOS can solve the multiple scattering radiative transfer equation from UV, visible, to infrared. It can handle atmosphere-land or atmosphere-ocean coupled systems. The atmosphere can be a mixture of molecules, aerosols, and cloud droplets. The land bottom can be Lambertian, snow surface, Ross-Li, and a number of other surfaces. The ocean waters are modeled by a mixture of pure ocean water, phytoplankton, and colored dissolved organic matter (CDOM), and other hydrosols. The sensors can be placed at arbitrary levels in the Earth system. The output of the sensor can include the full polarized Stokes parameters (I, Q, U, V). For more information, see References at the end of this document.
+
+PACE simulator is a wrapper built around the monochromatic RTSOS, which has a list of built-in aerosol and ocean inherent optical properties. A publication on the PACE simulator is published on Frontiers in Remote Sensing (Zhai et al., 2022). 
+
+GSFC AC LUT is a wrapper built around the monochromatic RTSOS which
+builds look up tables for atmospheric correction for retrievals of surface reflectance from top-of-atmosphere measurements.

rtsos-1.1.0rc1/README-temp.md

@@ -0,0 +1,22 @@
+<!--
+RTSOS — Radiative Transfer model based on Successive Orders of Scattering
+Copyright © 2025 Pengwang Zhai.
+
+Licensed under the Creative Commons Attribution–NonCommercial 4.0
+International License (CC BY-NC 4.0).
+You may use, modify, and share this code for research and
+educational purposes with proper attribution.
+Commercial use requires written permission from the author.
+
+Full license: https://creativecommons.org/licenses/by-nc/4.0/
+Contact: Pengwang Zhai  |  [pwzhai@gmail.com]
+-->
+
+# Radiative Transfer model based on Successive Orders of Scattering (RTSOS)
+
+RTSOS can solve the multiple scattering radiative transfer equation from UV, visible, to infrared. It can handle atmosphere-land or atmosphere-ocean coupled systems. The atmosphere can be a mixture of molecules, aerosols, and cloud droplets. The land bottom can be Lambertian, snow surface, Ross-Li, and a number of other surfaces. The ocean waters are modeled by a mixture of pure ocean water, phytoplankton, and colored dissolved organic matter (CDOM), and other hydrosols. The sensors can be placed at arbitrary levels in the Earth system. The output of the sensor can include the full polarized Stokes parameters (I, Q, U, V). For more information, see References at the end of this document.
+
+PACE simulator is a wrapper built around the monochromatic RTSOS, which has a list of built-in aerosol and ocean inherent optical properties. A publication on the PACE simulator is published on Frontiers in Remote Sensing (Zhai et al., 2022). 
+
+GSFC AC LUT is a wrapper built around the monochromatic RTSOS which
+builds look up tables for atmospheric correction for retrievals of surface reflectance from top-of-atmosphere measurements.

rtsos-1.1.0rc1/README.md

@@ -0,0 +1,212 @@
+RTSOS — Radiative Transfer model based on Successive Orders of Scattering
+Copyright © 2025 Pengwang Zhai. \
+This software is released under the Creative Commons Attribution–NonCommercial 4.0 International (CC BY-NC 4.0) license.
+You are free to use, modify, and share it for research and educational purposes, provided that you give appropriate credit.
+Commercial use is not permitted without prior written consent from the author.
+📧 For commercial licensing inquiries, contact Pengwang Zhai at [pwzhai@gmail.com].
+🔗 Full license text: Creative Commons BY-NC 4.0 (https://creativecommons.org/licenses/by-nc/4.0/)
+
+RTSOS can solve the multiple scattering radiative transfer equation from UV, visible, to infrared. It can handle atmosphere-land or atmosphere-ocean coupled systems. The atmosphere can be a mixture of molecules, aerosols, and cloud droplets. The land bottom can be Lambertian, snow surface, Ross-Li, and a number of other surfaces. The ocean waters are modeled by a mixture of pure ocean water, phytoplankton, and colored dissolved organic matter (CDOM), and other hydrosols. The sensors can be placed at arbitrary levels in the Earth system. The output of the sensor can include the full polarized Stokes parameters (I, Q, U, V). For more information, see References at the end of this document.
+
+
+PACE simulator is a wrapper built around the monochromatic RTSOS, which has a list of built-in aerosol and ocean inherent optical properties. A publication on the PACE simulator is published on Frontiers in Remote Sensing (Zhai et al., 2022). 
+
+A collection of data files which are needed for simulating the PACE instruments can be downloaded at: \
+http://doi.org/10.5281/zenodo.17410093
+
+The file is named as RTSOS_data_v1.0_20251022.tar.gz, which can be placed in a convenient location of your choice, let's call it PACEDATADIR.
+
+You can extract the files by doing the following in a linux terminal:
+
+cd PACEDATADIR \
+tar -xf RTSOS_data_v1.0_20251022.tar.gz
+
+You will get two directories. One is PACEDATADIR/Gas_Absorption_Coefficients/, which contains the gas absorption cross section lookup table for H2O, O2, CH4, CO2, NO2, ozone. This lookup table was generated by using ARTS: The Atmospheric Radiative Transfer Simulator:
+(https://www.radiativetransfer.org)version 2.3 with HITRAN2020 database (https://hitran.org/media/refs/HITRAN-2020.pdf).
+
+The other is PACEDATADIR/Data/, which contains the absorption coefficients of pure water, plankton particles, the bidirectional reflectance distribution functions of snow surface, scattering matrix of dust particles, the instrument response functions of ocean color instrument, HARP2, and SPEXone, and a number of other data files used in the PACE simulator.
+
+RTSOS and the PACE simulator requires a fortran 90 compiler (https://gcc.gnu.org/fortran/), hdf5 (https://www.hdfgroup.org/solutions/hdf5/) and lapack (https://www.netlib.org/lapack/) libraries.
+
+## Prerequisites 
+- Python >= 3.11
+- HDF5 >= 1.10
+- LAPACK >= 3.9
+- a modern Fortran compiler (e.g. gfortran)
+
+
+Section 1: COMPILE
+
+The steps to use it is: compile the package, configure the input files, and run the code with the executable file. \
+To compile, open a terminal and go to:
+
+$cd RTSOSDIR/compile
+
+where RTSOSDIR is where you clone this repo. Then try to compile the monochromatic code:
+
+$make
+
+If you get an error of missing Fortran compiler, examine "Makefile" and specify the correct Fortran command to F90, for example, ifx, ifort, gfortran, etc.. If successful, you have compiled the monochromatic radiative transfer package, which is the core of the PACE simulator.
+
+Now you can edit the PACE Simulator make file to set the hdf5 library paths:
+
+$emacs makefile_PACE_Simulator_DoubleK
+
+Inside makefile_PACE_Simulator_DoubleK, you want to specify the following directories:
+
+HDF5DIR=/usr/local/Cellar/hdf5@1.10/1.10.7\
+HDF5LIB=-I$(HDF5DIR)/include\
+H5FC=$(HDF5DIR)/bin/h5fc\
+LIBSHDF=$(HDF5LIB) -L$(HDF5DIR)/lib/ -lhdf5 -lhdf5_fortran
+
+If these are correctly set, you can compile the pace simulator:
+
+$make clean\
+$make -f makefile_PACE_Simulator_DoubleK
+
+This will compile the pace simulator.
+
+Section 2: RUN the MODELS
+
+For monochromatic simulation, users are referred to the documentations located at 
+/Documentation/Describtion_of_input_files/SOS_io.pdf
+
+Section 2.1 PACE Simulator
+
+Section 2.1.1 Input files 
+
+To run the PACE simulator, user should become familiar with the input file formats. 
+We provided two python scripts to generate the input files, one for ocean and the other for land surfaces, respectively, which are located at:
+
+test/PACE_Simulator/python_script/python_script/pace_simulator_twolayer_inputfile_land.py\
+test/PACE_Simulator/python_script/python_script/pace_simulator_twolayer_inputfile_ocean.py
+
+Study these two files before you execute them. Most importantly, change aux_dir and gas_absorption_coeff_dir to be:
+ 
+aux_dir='PACEDATADIR/Data/'\
+gas_absorption_coeff_dir='PACEDATADIR/Gas_Absorption_Coefficients/'
+
+Section 2.1.2  Aerosol models
+
+The Aerosol_Model[iaerosol] value is used in the PACE simulator input file to specify the aerosol models. 
+
+In the python script, Aerosol_Model is a array, you can use iaerosol to specify one of the aerosol models.
+
+In the following we use IAEROSOL as Aerosol_Model[iaerosol] equivalently.
+
+IAEROSOL=1-10 is the Shettle&Fenn model:
+
+E. P. Shettle and R. W. Fenn, “Models for the aerosols of the lower atmosphere and the effects of humidity variations on their optical properties,” AFGL-TR 790214, U. S. Air Force Laboratory, Hanscom Air Force Base, Mass. (1979).
+
+and 
+
+IAEROSOL=11-20;\
+IRH=1-8 where RH(IRH)=(/0.30,0.50,0.70,0.75,0.80,0.85,0.90,0.95/).
+
+are the new operational aerosol models currently used in the atmospheric correction at GSFC.
+
+Ziauddin Ahmad, Bryan A. Franz, Charles R. McClain, Ewa J. Kwiatkowska, Jeremy Werdell, Eric P. Shettle, and Brent N. Holben, "New aerosol models for the retrieval of aerosol optical thickness and normalized water-leaving radiances from the SeaWiFS and MODIS sensors over coastal regions and open oceans," Appl. Opt. 49, 5545-5560 (2010)
+
+For ocean simulations, ocean inherent optical properties are documented in Zhai et al., (2017, 2018, 2022).
+
+IAEROSOL=-99 is reserved for the case that a user supplies aerosol/cloud phase matrices. See Sec. 2.2 for more information.
+
+Section 2.1.3 Run the simulator
+
+Now you may try out the pace simulator:
+
+$cp rtsos_PACE_Simulator_DoubleK.exe ../test/PACE_Simulator/\
+$cd ../test/PACE_Simulator/\
+$mkdir alg_test
+$cd alg_test
+#run the simulator as:
+$../rtsos_PACE_Simulator_DoubleK.exe input_rt_pace.txt
+
+where "input_rt_pace.txt" is the input file to the simulator you generated in Section 2.1.1 using the python script.
+
+The current version can conveniently generate synthetic datasets for OCI, HARP, and SPEX
+for flexible datasets for OCI, HARP, and SPEX for flexible atmospheric and ocean conditions. 
+The input parameters are specified in input files.
+
+Section 2.2 Single scattering matrix code
+
+If you used IAEROSOL=-99 in the pace simulator input file, you will need to prepare the aerosol phase matrix. A tool was written by Neranga K. Hannadige (https://scholar.google.com/citations?user=0lAwqNsAAAAJ&hl=en) to generate the input scattering matrix files for the pace simulator. To use it, you can do the following:
+
+cd RTSOSDIR/compile\
+make -f makefile_aerosol_phmx_cal\
+cp Aerosol_Phmx_Cal.exe ../test/PACE_Simulator/alg_test/\
+cd ../test/PACE_Simulator/alg_test/\
+./Aerosol_Phmx_Cal.exe inputfile_for_aerosol_phase_matrix
+
+where "inputfile_for_aerosol_phase_matrix" is the input file for the aerosol phase matrix calculator. You will need to generate inputfile_for_aerosol_phase_matrix by using the script 
+
+PACE_Simulator/python_script/Aerosol_PhaseMatrix_Cal_InputPre.py
+
+In this script, you also want to specify: \
+aux_dir='PACEDATADIR/Data/' \
+and
+aerosol_phasematrix_file_hi and aerosol_phasematrix_file_low to be the aerosol phase matrix files that are generated with the procedure shown above.
+
+The single scattering matrix simulation uses the Mie code developed by M. Mishchenko 
+(Scattering, absorption, and emission of light by small particles, MI Mishchenko, LD Travis, AA Lacis - 2002)
+
+A non spherical dust scattering matrix database is included, which was provided by Prof. Ping Yang at Texas A&M University (Meng, Z., P. Yang, G. Kattawar, L. Bi, K. Liou, and I. Laszlo, 2010: Single-scattering properties of tri-axial ellipsoidal mineral dust aerosols: A database for application to radiative transfer calculations. J. Aerosol Sci., 41, 501–512, https://doi.org/10.1016/j.jaerosci.2010.02.008.)
+
+The single scattering matrix code assumes either bimodal (NMODE=2) or trimodal (NMODE=3) size distribution, see the following structure:
+----------------------------------------------------------------------
+NMODE=2
+----------------------------------------------------------------------
+Available aerosol modes: 
+
+	*fine mode 		(fmfrac)
+		dust like 		(rf1)
+		water soluble 	(rf2)
+		BrC 			(rf3)
+		soot			(1-(rf1+rf2+rf3))
+	
+	*coarse mode 	(1-fmfrac)
+		sea salt		(cmsfrac)
+		dust			(1-cmsfrac)
+
+----------------------------------------------------------------------
+NMODE=3
+----------------------------------------------------------------------
+Available aerosol modes:
+
+	*fine mode		(fmfrac)
+		water soluble 	(rf2)
+		BrC 			(rf3)
+		soot			(1-(rf2+rf3))
+
+	*dust mode		(dustfrac)
+		dust like		(dsfrac)
+		dust			(1-dsfrac)
+
+	*coarse mode 	(1-(fmfrac+dustfrac))
+		coarse mode includes sea salt only
+
+----------------------------------------------------------------------
+
+
+*Note: Different sets of parameters are used for nmode=2 and nmode=3 
+		For nmode=2 dustfrac and dsfrac do not exist
+		For nmode=3 rf1 and cmsfrac do not exist
+
+References:
+
+Zhai, P., Hu, Y., Trepte, C. R., Lucker, P. L. (2009). A vector radiative transfer model for coupled atmosphere and ocean systems based on successive order of scattering method. Optics express, 17(4), 2057-2079.
+
+Zhai, P., Hu, Y., Chowdhary, J., Trepte, C. R., Lucker, P. L., Josset, D. B. (2010). A vector radiative transfer model for coupled atmosphere and ocean systems with a rough interface. Journal of Quantitative Spectroscopy and Radiative Transfer, 111(7), 1025-1040.
+
+Zhai, P., Hu, Y., Josset, D. B., Trepte, C. R., Lucker, P. L., Lin, B. (2013). Advanced angular interpolation in the vector radiative transfer for coupled atmosphere and ocean systems. Journal of Quantitative Spectroscopy and Radiative Transfer, 115, 19-27.
+
+Zhai, P., Hu, Y., Winker, D. M., Franz, B., Boss, E. (2015). Contribution of Raman scattering to polarized radiation field in ocean waters. Optics Express, 23(18), 23582-23596.
+
+Zhai, P., Hu, Y., Winker, D. M., Franz, B., WERDELL, J., BOSS, E. (2017). Inelastic vector radiative transfer solution in ocean waters. Optics Express, 25, A223-A239. 
+
+Zhai, P., Boss, E., Franz, B., Werdell, J., Hu, Y. (2018). Radiative transfer modeling of phytoplankton fluorescence quenching  processes. MDPI Remote Sensing, 10(8), 1039.
+
+Zhai, P., Hu, Y. (2022). An improved pseudo spherical shell algorithm for vector radiative transfer. Journal of Quantitative Spectroscopy and Radiative Transfer, 282, 108132. https://www.sciencedirect.com/science/article/pii/S0022407322000693.
+
+Zhai, P., Gao, M., Franz, B. A., Werdell, P. J., Ibrahim, A., Hu, Y., Chowdhary, J. (2022). A Radiative Transfer Simulator for PACE: Theory and Applications. Frontiers in Remote Sensing, 3. https://www.frontiersin.org/article/10.3389/frsen.2022.840188.
+