MSCART

Introduction

The MSCART software is a simulator of scalar and vector radiative transfer in 3D cloudy atmosphere (Wang et al 2017 and 2019). The historical development could be traced back to my PhD project of MCRT software (Wang et al 2011 and 2012). It has experienced nearly 10 years development. It has became a versatile and sound tool for passive and active remote sensing. Recently, we release the code freely for scientists and students and distribute through our web site if you agree to the MSCART license terms (see License Section). Please visit the MSCART User Guide for further information on the MSCART usage.

To get an effective link for downloading, please fill the Registration Form with all below items

real name, position and affiliation
email address of academic institution
field of interest

and send it to the developer of Dr. Wang. The link would be sent to you in two work days.

The MSCART software was a part of ARTSUITE project. The project was aimed to develop a suite of atmospheric radiative transfer tools for remote sensing and climate research. In addition of MSCART, ARTSUITE also includes single scattering optical properties simulator CalScaOPT, atmospheric optical properties field generator CalAtmOPF. But they are not not the part of the freely distributed software package. They are only allowed to be used on condition of a collaborative basis. If you are interested, please contact the Dr. Wang.

Dependencies

The MSCART source code has the following dependencies:

UNIX or Linux-like environment
CMake 2.8 for building MSCART (CMake 3.10+ required for MPI parallelization).
Fortran compilers: Intel Fortran 15.0.2+, GNU Fortran 5.5.0+
NetCDF 4.0 for reading and writing data files
Python for python test scripts
DISLIN for plotting phase functions/matrices (optional)
GIT for version control (optional)
Ford for creating HTML documentation (optional)

Here we suggest you an old version of NetCDF 4.0 library. Because it doesn't depend on other extra libraries, such as hdf5.0, zlib and etc. It thus can greatly ease the NetCDF installation.

Installation

The software are archived to three tar-gizpped files. To unpack them,

tar -xzvf mscart-src-*.tar.gz
tar -xzvf mscart-case-*.tar.gz
tar -xzvf mscart-example-*.tar.gz

then user will find source codes, test cases and examples as follows

├── CMakeLists.txt               : CMake building file
├── cmake                        : CMake running scripts
├── lib                          : utility library
├── mscart                       : mscart source codes
├── case                         : test cases
├── examples                     : simulation examples
├── media                        : ford documentation pictures
├── pages                        : ford documentation markdown
├── mainpage_mscart.md           : ford mainpage markdown
├── doc                          : ford documentation in html
├── license.txt                  : license agreement

CMake was used as build system. The executables can be built by using GNU and Intel Fortran compiler.

Intel Fortran Compiler

For Intel Fortran compiler, you can go to above work directory (and have all the dependencies installed), and modify the NETCDF library path directories in cmake/Intel.cmake. Then run the following commands

mkdir build/intel-release/
cd build/intel-release-nocaf/
cmake -D CMAKE_BUILD_TYPE:STRING=Release \
      -D CMAKE_Fortran_COMPILER:FILEPATH=ifort \
      ../../
make
make install

Alternatively, you can run cmake/intel-release-cmake.sh in the build/intel-release/ directory.

If the Intel Fortran compiler supports the COARRAY parallelization, you can modify the compiler flag of -coarray-num-images in cmake/Intel.cmake to set the number of processors and then run the following

mkdir build/intel-release-caf/
cd build/intel-release-caf/
cmake -D CMAKE_BUILD_TYPE:STRING=Release \
      -D CMAKE_Fortran_COMPILER:FILEPATH=ifort \
      -D WITH_COARRAY:BOOL=ON ../../
make
make install

Alternatively, run intel-release-caf-cmake.sh in the build/intel-release/ directory.

If the Intel Fortran compiler supports the MPI parallelization, you can run following

mkdir build/intel-release-mpi/
cd build/intel-release-mpi/
cmake -D CMAKE_BUILD_TYPE:STRING=Release \
      -D CMAKE_Fortran_COMPILER:FILEPATH=ifort \
      -D WITH_MPI:BOOL=ON ../../
make
make install

Alternatively, run intel-release-mpi-cmake.sh in the build/intel-release/ directory.

Once the installation was finished, you would find the programs in the directory of bin/intel-release***/. The executables with the MPI support must be run with the MPI executable launcher mpiexec.

GNU Fortran Compiler

For GNU Fortran compiler, you can build executable without the parallelization by running gnu-release-cmake.sh, with the COARRAY parallelization by running gnu-release-caf-cmake.sh (requiring the OpenCoarrays installed and setting the OpenCoarrays include and library directory variable CAF_MPI_INCLUDE_DIR and CAF_MPI_LIBRARY_DIR in 'cmake/GNU.cmake'), or with the MPI parallelization by running gnu-release-mpi-cmake.sh The executables with the COARRAY support must be run with COARRAY Fortran executable launcher cafrun for OpenCoarrays. The executables with the MPI support must be run with the MPI executable launcher mpiexec.

NOTE about Double Precision

The double precision should be used in lidar signal simulation, since low accuracy usually occurs in trigonometric function calculation in the backscattering geometry, such as sine and cosine function. Users can modify the real variable of krs in lib/Kind_Pack.f90 to double precision to achieve this purpose,

Case Testing

To ensure functionality of all the parts in the programs, we strongly recommend you to run testing executables. For the serial and COARRAY parallelization codes, the users can directly run the following command in the directory of build/intel-release/ (build/intel-release-caf/):

ctest -j N

where N is the number of parallel jobs. For the MPI parallelization code, the users need firstly setting the environmental variable MPIEXEC and then run the ctest in the directory of build/intel-release-mpi:

export MPIEXEC='mpiexec -n 4'
ctest -j N

Documentation

The users can find documentation in the doc directory, which was built with FORD using following commands:

ford -o doc mainpage.md

License

This software license agreement (SLA) is a legal agreement between you and the author of the MSCART software. The MSCART is developed by Dr. Zhen Wang of Department of Atmospheric Sounding in Nanjing University of Information Science & Technology, China.

Only scientists affiliated at academic scientific facilities and students are eligible for a free usage of MSCART. As a proof of the status an email address from an eligible facility must be provided. Any commercial use of the program or its parts is prohibited. Users are not allowed to redistribute the program or its parts. The MSCART simulator should be properly acknowledged in any publication based on the results obtained with the MSCART code, i.e. users should cite our publications of Wang et al., (2017, 2019) in the main references. Users shoud let us know of any publications that use simulation results by sending an email to Zhen Wang (intersharp@126.com). If you not wish to be bounded by the terms of the SLA, please delete the software product from your computer. If you keep MSCART on your computer, you are considered to agree to the SLA terms.

Disclaimer

Please be advised, Dr. Zhen Wang furnishes his software without any warranty that the program is free of errors and is not responsible for any direct, indirect or consequential damages that may be incurred by the software. Users are encouraged to send bug reports to the developer email.

Developer Info

Zhen Wang (王震)

Optics Ph.D., work at Nanjing University of Information Science & Technology, China