Wind-US and the tools are designed to be compiled in a build (or development) directory and then the final executables installed into an application directory. This allows one to install multiple versions of Wind-US into a single application directory that uses shared run-time scripts. The user can select which version to use at run-time. The following sections describe the steps necessary to install the build distributions in this manner.
Makefiles are distributed with the Wind-US build distribution for a variety of platform, operating system, and CPU combinations, including:
If you need to build the code for a platform not listed above, you will need to first create the appropriate makefiles, using the existing ones as a starting point. See the section Porting Wind-US to a New UNIX Platform for further information.
Assuming the appropriate makefiles exist, the recommended procedure to build and install Wind-US from source is as follows. Please re-read each step completely before executing any commands that are described.
Create an appropriate top-level directory.
mkdir -p $HOME/WINDUS cd $HOME/WINDUS
This will ultimately contain the build/development source (wind-dev) and application executable (wind) subdirectories.
If an existing top-level Wind-US installation directory is to be used, the existing wind-dev subdirectory should be renamed so that it is not overwritten. Any makefiles you may have modified within this directory may be of use in constructing makefiles for the new installation.
When installing multiple versions into a shared installation directory, one should start with the oldest version and work towards the newest. This way the most current run scripts will be made available. Installing an older version into an existing directory might install older run scripts that do not support more recent code options.
Put the gzip'ed tar file containing the Wind-US build distribution into this directory. You should now have a file of the form:
dist.windus.x.xxx.tgz
Unpack the Wind-US build distribution by doing:
gunzip -c filename | tar xvf -
where filename is the file name, including the .tgz extension. This creates a directory named wind-dev containing the Wind-US source code. There will also be two scripts to assist with the installation: Install.appl and Install.tools.
If you also plan to install the tools, you should follow those instructions in parallel with these. In particular, it is important to unpack the tools build bundle before proceeding with any changes to the makefiles. Otherwise those changes could be overwritten when you do eventually unpack the tools.
Use the installation script to create the application directory and copy some necessary scripts. Responses to the interactive prompts are shown in italic font.
./Install.appl Under what parent directory should Wind-US be installed? (Default is current directory): Hit enter to accept the default directory. Run scripts will be installed in $HOME/WINDUS/wind/bin Is this OK? (y/n [y]) Answer: y Copying files to $HOME/WINDUS/wind Modifying cfd.login and cfd.profile Wind-US scripts have been copied to the installation directory. To finish the installation ... csh/tcsh users: add the following line to your .login file source $HOME/WINDUS/wind/bin/cfd.login sh/bash/ksh users: add the following line to your .profile file . $HOME/WINDUS/wind/bin/cfd.profile
Update the login scripts
Follow the instructions described by the script output to update your login scripts. At the same time, define the environment variable WIND_DEV as the location of the directory containing the top-level Makefile. This should be the full path to the wind-dev directory.
Typically, csh and tcsh users must edit their $HOME/.login file and add the following two lines:
setenv WIND_DEV "path_name/wind-dev" source path_name/wind/bin/cfd.login
where again path_name is the full path name of the directory used in step 1. Similarly, bash, ksh, and sh users must edit their $HOME/.profile file and add the following two lines:
WIND_DEV="path_name/wind-dev"; export WIND_DEV . path_name/wind/bin/cfd.profile
This causes the contents of the cfd.login (or cfd.profile) file to be executed automatically at login time to set up the environment variables CFDROOT, SYSTEM, and SYSTEM_CPU, that are required for installing and running Wind-US, and to modify your PATH to include the location of the Wind-US executable.
At this point, log out and log back in to execute your .login or .profile file (depending on your login shell). Alternatively, in your home directory execute (for csh and tcsh users)
source .login
or (for sh and ksh users)
. .profile
Check to see if the environment variables have been set to appropriate values, by doing
printenv WIND_DEV printenv CFDROOT printenv SYSTEM printenv SYSTEM_CPU
WIND_DEV was defined in step 5. CFDROOT should have a value of path_name/wind where path_name is the full path name of the directory used in step 1. This represents the root location that contains the Wind-US executable(s) and scripts. SYSTEM and SYSTEM_CPU should describe the operating system and cpu type. If all are correctly set, skip the next step.
If CFDROOT is not set properly, you will need to manually edit the Wind-US login script. Denoting path_name as the full path name (starting with a "/") of the directory used in step 1, users of the csh or tcsh shell should edit the file path_name/wind-dev/bin/cfd.login to modify the definition of CFDROOT as follows:
if (! "$?CFDROOT") then #=BEGROOT= setenv CFDROOT "path_name/wind" #=ENDROOT= endif
Similarly, bash, ksh, or sh users would edit the file path_name/wind-dev/bin/cfd.profile to modify the definition of CFDROOT to:
if [ ! "$CFDROOT" ] ; then #=BEGROOT= CFDROOT="path_name/wind" #=ENDROOT= export CFDROOT fi
Return to step 6 to have this change take effect.
Now that the environment variables are set properly, move into the WIND_DEV directory.
cd $WIND_DEV
Configure the makefiles.
The default values in the configuration files should be sufficient to produce an executable on most well-configured systems (assuming that compilers are installed). The primary exception to this is Linux, which does not have a "default" Fortran 90/95 compiler. Another potential problem is the location of the MPI libraries, which needs to be specified if you wish to use MPI for parallel runs. To be safe, review the contents of the following files or parts of files, where SYSTEM and SYSTEM_CPU correspond to the SYSTEM and SYSTEM_CPU environment variables, paying special attention to the items noted below.
When modifying files it is always a good idea to save a copy of the original (i.e., as *.bak), and for new files to create an empty *.bak file. This makes it easy to identify which files you have changed, and you can use a visual difference program to compare those changes against the original.
Makefile.configure
If you are compiling on a multi-processor system with MPI message passing available, change the definition of USE_MPI from NO to YES. This will link in the MPI libraries, allowing the use of MPI message passing for parallel processing. Note, though, that because Wind-US uses dynamically-linked libraries, an executable created with USE_MPI equal to YES will not run on multi-processor systems without MPI.
If you will never be running parallel jobs using PVM message passing, change the definition of USE_PVM from YES to NO.
The value of PRECISION may be changed to make all Fortran variables single or double precision. The default is a mix, with single precision for the mean flow solution and boundary conditions, and double precision for chemistry data, right-hand-side data, grid coordinates, and grid metrics.
source/Makefile.user
source/makefiles/Makefile.include.SYSTEM.SYSTEM_CPU.xxx, where xxx corresponds to opt, dbx, or pure. Most users compile the optimized (opt) version.
This file contains the compiler optimizations for the specific system being used.
Check the definition of CPP, which is the full path name for the C pre-processor cpp, to make sure it is correct for your system. On many systems, you can locate cpp using the whereis command.
whereis -b cpp
For Linux systems, you will most likely have to change the definitions related to the Fortran and C compilers being used (i.e., the variables ABI, FC, F90, LD, etc.) These lines should be commented/uncommented as needed for your system, but additional changes may also be necessary or desired.
If you are compiling on a multi-processor system with MPI message passing, check the definition of MPILIBS, and modify it if necessary to use a different version or a non-standard location.
If your system doesn't support the Fortran long integer data type, add "-DNOFLONG" (without the quotes) to the definition of WINDDEFS. Errors in the compilation of mem_management_module.f90 about an ambiguous definition for the generic interfaces alloc and dealloc, involving the specific interfaces for allockindlong_1 and allockindint_1, etc., are an indication that "-DNOFLONG" is needed.
Compile the Wind-US source.
From the WIND_DEV directory, run make to create all the required libraries and executables for running Wind-US. The output from the compilation process is very lengthy. To capture the output from make in the file make.log for later examination if something goes wrong, in addition to displaying it at the terminal, csh and tcsh users should do
make opt |& tee make.log
and sh and ksh users should do
make opt 2>&1 | tee make.log
If the compilation is successfull, the Wind-US executable should be present in the directory $WIND_DEV/SYSTEM/SYSTEM_CPU/bin.
To install the compiled Wind-US and PVM executables into the application directory, use the following commands:
make install make install_scripts make copy_pvm
The first two commands copy the Wind-US executable to $CFDROOT/SYSTEM/CPU/bin and the scripts to $CFDROOT/bin. The third copies the PVM executables and libraries to $CFDROOT/pvm/SYSTEM/CPU, some PVM include files to $CFDROOT/pvm/include, and PVM scripts to $CFDROOT/pvm/lib. The parameters SYSTEM and CPU correspond to the SYSTEM and SYSTEM_CPU environment variables, respectively.
Note that the Wind-US executables are named by major revision number (i.e., Wind-US4.exe). However, in some cases, such as before and after a bug fix, it is useful to retain minor revisions. To do so, before issuing the install commands listed above, you should rename the existing executable in the application directory ($CFDROOT/SYSTEM/SYSTEM_CPU/bin) to include the minor revision number (i.e., Wind-US4.111.exe). The windver script can be used to print the version number for a particular executable.
It would be best to log out and log back in before running Wind-US. This executes the shell start-up scripts, modifying the PATH environment variable to include the newly-created location for the Wind-US executable.
The tools build distribution is designed to be a completely independent package, so that the tools can be built without requiring any additional files from Wind-US. Thus, one could have separate directory trees for the Wind-US build distribution and tools build distributions. This would lead to a great deal of duplication, however. Therefore, the build distributions are designed to overlay one another. The following instructions assume that all the tools are being built in the same directory tree. Please re-read each step completely before executing any commands that are described.
Create an appropriate top-level directory.
mkdir -p $HOME/WINDUS cd $HOME/WINDUS
This will ultimately contain the build/development source (wind-dev), more specifically (wind-dev/tools-dev), and application executable (wind) subdirectories.
An existing top-level Wind-US directory is often used for this purpose, since it reduces the amount of extra disk space and configuration necessary. In this case, you will want to use the directory above wind-dev. See step 11 in the procedure for building Wind-US.
Install lua version 4.01 if it is not already available on your system. Note that due to changes in the API, newer versions of lua will not work with the Wind-US tools. These instructions assume that lua will be installed under the top-level directory of step 1. However, it could be installed in its own stand-alone location.
Download the source code from http://www.lua.org/ftp/lua-4.0.1.tar.gz and save as:
lua.4.0.1.tar.gz
Unpack the source files.
gunzip -c lua.4.0.1.tar.gz | tar xvf -
This will extract the lua.4.0.1 directory. To compile lua,
cd lua.4.0.1 make
This should create the following files:
$HOME/WINDUS/lua-4.0.1/bin/lua $HOME/WINDUS/lua-4.0.1/bin/luac $HOME/WINDUS/lua-4.0.1/lib/liblua.a $HOME/WINDUS/lua-4.0.1/lib/liblualib.a
Install the CGNS library if it is not already available on your system. Once again, these instructions assume that it will be installed under the top-level directory of step 1. However, it could be installed in its own stand-alone location.
Download cgnslib (2.5.5) from https://cgns.github.io/download.html and save as:
cgnslib.2.5.5.tar.gz
Newer versions of cgnslib may also work. Unpack the source files.
gunzip -c cgnslib.2.5.5.tar.gz | tar xvf -
This will extract the cgns_2.5 directory. Compile the CGNS library with commands similar to the following. You may need to adjust the settings, depending on your system.
cd $HOME/WINDUS/cgnslib_2.5 ./configure --prefix=$HOME/WINDUS/cgnslib_2.5 --with-system=LINUX64 --enable-64bit make SYSTEM=LINUX64 mkdir include mkdir lib make install
This should create the following files:
$HOME/WINDUS/cgnslib_2.5/include/cgnslib.h $HOME/WINDUS/cgnslib_2.5/include/cgnslib_f.h $HOME/WINDUS/cgnslib_2.5/include/cgnswin_f.h $HOME/WINDUS/cgnslib_2.5/lib/libcgns.a
Put the gzip'ed tar file containing the tools build distribution into the top-level directory used in step 1. You should now have a file of the form:
dist.alltools.tgz
Unpack the tools build distribution by doing:
gunzip -c dist.alltools.tgz | tar xvf -
This creates a directory named wind-dev containing the source code. The source code for individual tools will be located in subdirectories of wind-dev/tools-dev. There will also be two scripts to assist with the installation: Install.appl and Install.tools.
If you also plan to install Wind-US, you should follow those instructions in parallel with these. In particular, it is important to unpack all of the build bundles before proceeding with any changes to the makefiles. Otherwise those changes could be overwritten when unpacking another bundle.
Follow steps 4-8 in the procedure for building Wind-US and verify that the WIND_DEV, CFDROOT, SYSTEM, and SYSTEM environment variables are correctly defined.
Use the installation script to create the application directory and copy some necessary scripts. Responses to the interactive prompts are shown in italic font.
./Install.tools Under what parent directory should the tools be installed? (Default is current directory): Hit enter to accept the default directory. Run scripts will be installed in $HOME/WINDUS/tools/bin Is this OK? (y/n [y]) Answer: y Copying files to $HOME/WINDUS/tools Modifying tools.login and tools.profile Wind-US scripts have been copied to the installation directory. To finish the installation ... csh/tcsh users: add the following line to your .login file source $HOME/WINDUS/tools/bin/tools.login sh/bash/ksh users: add the following line to your .profile file . $HOME/WINDUS/tools/bin/tools.profile
Update the login scripts.
Follow the instructions described by the script output to update your login scripts. Typically, csh and tcsh users must edit their $HOME/.login file and add the following line:
source path_name/tools/bin/tools.login
where again path_name is the full path name of the directory used in step 1. Similarly, bash, ksh, and sh users must edit their $HOME/.profile file and add the following line:
. path_name/tools/bin/tools.profile
This causes the contents of the tools.login (or tools.profile) file to be executed automatically at login time to set up the TOOLSROOT environment variable that is required for installing and running the tools, and to modify your PATH to include the location of the tools executables.
At this point, log out and log back in to execute your .login or .profile file (depending on your login shell). Alternatively, in your home directory execute (for csh and tcsh users)
source .login
or (for sh and ksh users)
. .profile
Verify that the TOOLSROOT environment variable is properly set, by doing:
printenv TOOLSROOT
It should have a value of path_name/tools where path_name is the full path name of the directory used in step 1. If it is, skip the next step.
If TOOLSROOT is not set properly, you may need to manually edit the tools login script. Denoting path_name as the full path name (starting with a "/") of the directory used in step 1, users of the csh or tcsh shell should edit the file path_name/tools/bin/tools.login to modify the definition of TOOLSROOT as follows:
#=BEGROOT= setenv TOOLSROOT "path_name/tools" #=ENDROOT=
Similarly, bash, ksh, or sh users would edit the file path_name/tools/bin/tools.profile to modify the definition of TOOLSROOT to:
#=BEGROOT= TOOLSROOT="path_name/tools" #=ENDROOT= export TOOLSROOT
Return to step 9 to have this change take effect.
Now that the environment variables are set properly, move into the WIND_DEV directory.
cd $WIND_DEV
Configure the makefiles.
Most systems other than Linux should be able to use the default values in the configuration files without problem. On Linux systems, it is likely that the definitions related to the Fortran and C compilers will have to be changed. To be safe, check the following files to be sure they contain information that is appropriate for your system. (See the notes for step 10 in the procedure for building Wind-US).
Makefile.configure
See the instructions above for building Wind-US).
source/makefiles/Makefile.include.SYSTEM.SYSTEM_CPU.opt
See the instructions above for building Wind-US).
Comment out (or not) the explicit static and shared library settings as appropriate:
#TOOLS_STATLIB= -static #TOOLS_SHARLIB= -shared
Note that the default behavior of the Intel compiler is to use shared libraries. In some versions of the compiler, specifying the -shared option leads to linker errors. Thus, for Intel compilers, it is recommended to leave both settings commented out.
Provide the proper locations of Tcl, Lua, and CGNS. These may differ depending on your system setup, but are typically set to:
TOOLS_TCLLIBS= -L/usr/lib64 -ltcl8.5 TOOLS_LUALIBS= -L/$(HOME)/WINDUS/lua-4.0.1/lib -llua -llualib TOOLS_CGNSLIBS= -L/$(HOME)/WINDUS/cgnslib_2.5/lib -lcgns TCL_INCLUDE= $(INCCMD)/usr/include LUA_INCLUDE= $(INCCMD)/$(HOME)/WINDUS/lua-4.0.1/include CGNS_INCLUDE= $(INCCMD)/$(HOME)/WINDUS/cgnslib_2.5/include
Provide the proper locations of the compiler libraries defined by TOOLS_OSLIBS, TOOLS_CPPLIBS, and MADCAP_OSLIBS.
source/makefiles/pvm_conf/SYSTEM.SYSTEM_CPU.def.opt
Do not bother configuring or creating this file unless you encounter an error during the compilation process. This file is used to override the default settings given in a similarly named pvm/conf/SYSTEM.def file.
tools-dev/Makefile
This file defines the make dependencies and rarely needs to be changed.
tools-dev/libmdgl/SYSTEM.mkf
This file is used to compile the graphics library needed by GMAN, CFPOST, and MADCAP.
Compile the tools source.
In the WIND_DEV directory, run make to create all the required libraries and executables for all the tools for which you have installed source. To capture the output from make in the file make_tools.log for later examination if something goes wrong, in addition to displaying it at the terminal, csh and tcsh users should do
make all_tools |& tee make_tools.log
and sh and ksh users should do
make all_tools 2>&1 | tee make_tools.log
You can also compile tools individually, by doing
make tool_name
where tool_name is the name of the tool. Note that the names to be used for GMAN, CFPOST, and MADCAP are gmanpre, cfpost_prod, and madcapprod, respectively.
The $WIND_DEV/SYSTEM/SYSTEM_CPU/bin directory will contain the executables for the various tools if the compilation is successful.
Copy the executable and library files from the build directory to the application directory where they will be used. This is done via the command:
make install_tools
This copies the tools executables to $TOOLSROOT/SYSTEM/CPU/bin, where SYSTEM and CPU correspond to the SYSTEM and SYSTEM_CPU environment variables, as described in step 11 in the procedure for building Wind-US.
It would be best to log out and log back in again before running any of the tools. This executes the shell start-up scripts, modifying the PATH environment variable to include the newly-created location for the tools executables.
In general, it is recommended to compile executables on each machine type that you will use. However, in some situations two machines may be similar enough that the same executable can be used with only a minor degradation in performance. In that case, symbolic links may be used to specify that a different (but compatible) executable should be used instead.
Suppose you have compiled executables for a LINUX64-GLIBC2.5 system with a XEON processor, but would also like to provide binaries for OPTERON processors. You can share the available executable by creating a symbolic link. The Wind-US, PVM, and tools executables are stored in a directory hierarchy designated by the SYSTEM and SYSTEM\_CPU environment variables. Symbolic links must be created in the appropriate locations within the wind, wind/pvm, and tools subdirectories. For the case described, the easiest mechanism for sharing the executables is to create a symbolic link between the XEON and OPTERON directories.
ln -s XEON OPTERON
The resulting directory structure will be:
wind_install/ wind/ LINUX64-GLIBC2.5/ XEON/ OPTERON -> XEON/ ... bin/ ... pvm/ lib/ LINUX64-GLIBC2.5/ XEON OPTERON -> XEON/ ... tools/ LINUX64-GLIBC2.5/ XEON/ OPTERON -> XEON/ ... bin/ ...
where the notation "OPTERON -> XEON/" is used to indicate that OPTERON is a symbolic link pointing to XEON/.
If multiple users in an organization will be running Wind-US, it is convenient to install the Wind-US and tools executables below a parent directory that can be accessed by all the users via a network file system (NFS). This way, the location and method of accessing the executables will be the same on all user machines, and they can be centrally updated without any significant effort from individual users. It is suggested that one individual from an organization download the needed application distributions and serve as a single point of contact for Wind-US.
When the scripts and executables are to be accessed via NFS, if the path name used by the user to access the NFS-mounted file system is different from the actual directory name on the "host" system, a slight variation of the above installation procedure is necessary. That's because the user's environment variables CFDROOT and TOOLSROOT must define the NFS-mounted location of the wind and tools subdirectories. Similarly, the lines users add to their .login or .profile files should specify path names used to access the NFS-mounted file system.
NFS file systems are typically accessed using automount. As an example, assume that Wind-US and the tools have been installed on a host workstation named wind_machine, and that the parent installation directory is /usr/local/wind_nfs. On wind_machine, that directory is exported read-only to the "home" system, normally an individual's workstation, of each Wind-US user. The user can then access that directory via automount by adding "/net/wind_machine" to the beginning of the path name. E.g.,
cd /net/wind_machine/usr/local/wind_nfs
The cfd.login, etc., files on wind_machine should be copied to new files named cfd.nfs.login, etc. [This is done so that users logging directly onto wind_machine can still access Wind-US as described in the previous sections.] The definitions of CFDROOT and TOOLSROOT in cfd.nfs.login, etc., should be modified to point to the automount'ed location of the wind and tools subdirectories. I.e., in cfd.nfs.login CFDROOT is defined as
setenv CFDROOT /net/wind_machine/usr/local/wind_nfs/wind
and in tools.nfs.login TOOLSROOT is defined as
setenv TOOLSROOT /net/wind_machine/usr/local/wind_nfs/tools
Finally, using the above example, csh and tcsh users accessing Wind-US via automount would modify their .login file to add the lines
source /net/wind_machine/usr/local/wind_nfs/wind/bin/cfd.nfs.login source /net/wind_machine/usr/local/wind_nfs/tools/bin/tools.nfs.login
and sh and ksh users would modify their .profile file to add the lines
. /net/wind_machine/usr/local/wind_nfs/wind/bin/cfd.nfs.profile . /net/wind_machine/usr/local/wind_nfs/tools/bin/tools.nfs.profile
Users accessing via NFS would not need to set the WIND\_DEV environment variable, since they would not be compiling the source code.
It should be noted that Wind-US does not need to be installed on each individual machine in order to run in parallel mode using a network of distributed systems. The executables for all the different types of systems and CPUs being used are installed only on the master system. The Wind-US run scripts automatically take care of copying the appropriate Wind-US and PVM executables and files to the systems being used, starting and stopping the message passing software, and cleaning up at the end of the run. See the Parallel Processing section of the Wind-US User's Guide for details.
When using MPI for parallel communication, the MPI libraries should be installed on each worker machine.
Last updated 30 Sep 2016