**********************************************************************
*     How to use ISPACK3 (ver. 3.2.0) By Keiichi Ishioka (2022/03/30)
**********************************************************************
-----------------------------------------------------------------------
Introduction
-----------------------------------------------------------------------

 This library (ISPACK) is a package of basic tools (Spectral transform, 
etc.) as subroutines, which are required mainly for computations of 
simple fluid equations. Because each subroutine is designed to be used
independently, this library is not an integrated environment in which
you can run numerical models without sufficient knowledge. How to
combine and use these subroutines is up to users.

-----------------------------------------------------------------------
Copyright and License
-----------------------------------------------------------------------

 The copyright of this library belongs to Keiichi Ishioka.
This library is a free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public License 
(LGPL-2.1 or later) as described in the COPYRIGHT file.
The author hopes that you will mention that you use this library 
if you publish results of numerical experiments using this library.
This is, however, not an advertising clause but only a hope.

-----------------------------------------------------------------------
Relation with older versions (2.1.3 and before)
-----------------------------------------------------------------------

ISPACK version 3 (and after) is completely independent of 
ISPACK version 2.1.3 (and before). There is neither cross-reference
nor namespace collision.

-----------------------------------------------------------------------
Contents
-----------------------------------------------------------------------
The contents of this package are as follows.

  README: This file
  README.ja: Readme file written in Japanese
  CHANGELOG: Changelog (in Japanese)
  COPYRIGHT: Copyright statement
  LGPL: GNU Lesser General Public License (LGPL)
  Makefile: Main part of the Makefile
  Mkinclude: Include file for the Makefile (The default settings are suitable
     for most of Linux distributions)
  Mkinclude.sub: Include file for Makefiles for each of 
     the following subdirectories

  fxpack: Fast Fourier Transform (FFT) routines
  lxpack: Associated Legendere functions transform routines
  sxpack: Spherical harmonics transform routines
  sypack: Parallelized version of sxpack using MPI
  mxpack: Miscellaneous routines for time-measuring, etc.

  sample: Sample programs using the subroutines above 


 Each **pack directory has the following two subdirectories.
Please refer to them if needed.
  
  src: directory that contains sources of the subroutines
  doc: directory that contains the document of the subroutines
       (LaTex format)

-----------------------------------------------------------------------
How to install ISPACK library
-----------------------------------------------------------------------

  1) Change macro definitions in Mkinclude suitablly for your environment.
     
    Though the meaning of each macro may be obvious, explanations are
    given only for the macros that may have to be changed.

    - DIRS: Place package names that are desired to be included in the
            library. In the default setting, all packages except for 
            sjpack-cuda are listed. If you do not need all the packages
            to be included, place the desired package names only.

    - LIBNAME: The name of the static library to be installed. You do 
          not have to change the default value "libispack3" if there is 
          no possibility to conflict with other libraries.

    - DESTDIR: The intall directory for the library.

    - FC,FFLAGS: The name of Fortran90 compiler and the flags (for 
         optimization, for example) for the compiler. Note that ISPACK
         uses quadruple precision floating point number inside, so that
         th Fortran90 compiler must support it. Accordingly, PGI Fortran
         cannnot be used currently.         

    - MPIFC,MPIFFLAGS: The name of Fortran90 compiler for MPI programs
         and the flags (for optimization, for example) for the compiler.

    - CC,CFLAGS: The name of C compiler and the flags for the compiler.

    - SSE: A switch to be set in making fftj and sjpack.
         It should be set depending on your computational environment 
         as follows:
         
      * If your system is a 64bit Linux on a x86 CPU which has AVX
        (after Sandy Bridge), then set as;
	    SSE = avx

      * If your system is a 64bit Linux on a x86 CPU which has FMA
        (after Haswell), then set as;
	    SSE = fma

      * If your system is a 64bit Linux on a x86 CPU which has AVX512
        (after Xeon Phi KL), then set as;
	    SSE = avx512

      * If your system is a 64bit Linux on FUJITSU A64FX, then set as;
	    SSE = fx

      * If your system is a 64bit Linux for NEC SX-Aurora, then set as;
	    SSE = sx

      * If your system is not mentioned above, then set as;
	    SSE = fort

  2) In this directory, where this README file is located, execute
     as follows.

	% make

     Then, the library, libispack3.a, is created in the directory specified 
     as DESTDIR.
        
  3) After making the library, if you want to remove unnecessary object 
     files, execute as follows.

	% make clean

     Furthermore, if you execute as follows,

	% make veryclean

    the library and temporary files are also removed and this directory
    is restored to the original state before the execution of make. 
    If you make a mistake in selecting SSE, please redo the installation
    from the beginning.

-----------------------------------------------------------------------
How to use the library
-----------------------------------------------------------------------

 Since the library created by the above procedure (libispack3.a) is a normal 
Fortran90 library, you can link your program with it when being compiled.
Please refer to the subdirectories under the "sample" directory to see 
example codes to show how to use.

-----------------------------------------------------------------------
Sample programs
-----------------------------------------------------------------------
  Simple sample programs based on this library for numerical experiment
of fluid mechanics are located in subdirectories under the "sample" 
directory. There are the following subdirectories so far.

 - sxpack-test: Test programs for sxpack.
 - sypack-test: Test programs for sypack.

 Please refer to the MEMO file in each subdirectory for how to use.

-----------------------------------------------------------------------
Parallelization
-----------------------------------------------------------------------

 When you use packages parallelized with MPI (sypack), please refer to
manuals of compilers and commands for MPI on the system. The sample
programs (sypack-test) can be used as a reference for how to call the
parallelized subroutines practically.

 When you use packages parallelized with OpenMP (lxpack and sxpack),
please refer to manuals for how to set compiler options and
runtime environment variables on the system.

-----------------------------------------------------------------------
Paper
-----------------------------------------------------------------------

  Details of optimization technique is described in the following paper:
Ishioka, K. (2018): A New Recurrence Formula for Efficient Computation
of Spherical Harmonic Transform, Journal of the Meteorological Society
of Japan, 96(2), 241-249.

https://www.jstage.jst.go.jp/article/jmsj/96/2/96_2018-019/_pdf

-----------------------------------------------------------------------
Miscellaneous
-----------------------------------------------------------------------

 Bug reports and comments are welcomed to the following E-mail address.

     ishioka@gfd-dennou.org

