********************************************************************** * How to use ISPACK3 (ver. 3.2.2) By Keiichi Ishioka (2024/03/14) ********************************************************************** ----------------------------------------------------------------------- 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 and shared/libispack3.so, 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 and shared/libispack3.so) 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. In addition, using the shared library shared/libispack3.so, ISPACK3 an be used from the Python interface created by Dr. Toshiki Matsushima. For more details, see https://www.gfd-dennou.org/arch/ispack/python/ . ----------------------------------------------------------------------- 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