Difference between revisions of "Setting Unix environment variables for GEOS-Chem"

From Geos-chem
Jump to: navigation, search
(Environment variables that specify library paths)
 
(40 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This page contains information about how to set several environment variables in your Unix environment that are needed to [[GEOS-Chem Makefile Structure#Compiling GEOS-Chem|compile GEOS-Chem]].
+
This content has been migrated to the [https://geos-chem.readthedocs.io/en/latest/gcc-guide/01-startup/login-env.html# '''Customize your login environment''' chapter of <tt>geos-chem.readthedocs.io</tt>].
 
+
== Environment variables that specify compiler names ==
+
 
+
GEOS-Chem currently supports the [[Intel Fortran Compiler|Intel Fortran compiler (<tt>ifort</tt>)]], the [[GNU Fortran compiler|GNU Fortran compiler (<tt>gfortran</tt>)]], and the [[PGI Fortran compiler|PGI Fortran compiler (<tt>pgfortran</tt> or <tt>pgf90</tt>)]].  You must set the following variables in your Unix environment to tell GEOS-Chem which compiler type you are using.
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-valign="top" bgcolor="#CCCCCC"
+
!width="125px"|Variable
+
!width="875px"|Description
+
 
+
|-valign="top"
+
|<tt>FC</tt> || Name of the Fortran compiler
+
 
+
|-valign="top"
+
|<tt>CC</tt> || Name of the C compiler.<br><span style="color:darkorange">'''''Not needed for GEOS-Chem, but this may be required to build other software packages (such as the netCDF libraries).'''''</span>
+
 
+
|-valign="top"
+
|<tt>FC</tt> || Name of the C++ compiler.<br><span style="color:darkorange">'''''Not needed for GEOS-Chem, but this may be required to build other software packages (such as the netCDF libraries).'''''</span>
+
 
+
|-valign="top"
+
|<tt>COMPILER</tt> || This should be set to the same value as <tt>FC</tt>.<br><span style="color:darkorange">'''''In [[GEOS-Chem v11-02#v11-02a|v11-02a]] and higher versions, the dependence on the <tt>COMPILER</tt> environment variable will be removed.'''''</span>
+
 
+
|}
+
 
+
On many systems (such as the Harvard Odyssey cluster), <tt>FC</tt>, <tt>CC</tt>, and <tt>CXX</tt> will be set automatically for you when you load a software module into your Unix environment with the <tt>module load</tt> command.  The easiest way to check if these variables have been automatically set for you is to print them to the screen.  Type at the Unix prompt:
+
 
+
echo $FC
+
echo $CC
+
echo $CXX
+
 
+
If  <tt>FC</tt>, <tt>CC</tt>, and <tt>CXX</tt> are not blank, then that means that they have been automatically set for you.  The only remaining thing that you have to do is to add the following line to your system startup file to define the <tt>COMPILER</tt> environment variable.
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-valign="top" bgcolor="#CCCCCC"
+
!width="125px"|If your<br>shell is
+
!width="125px"|add to<br>this file
+
!width="300px"|the following lines of code
+
 
+
|-valign="top"
+
|<tt>/bin/bash</tt>
+
|<tt>.bashrc.</tt>
+
|<code>export COMPILER=$FC</code>
+
 
+
|-valign="top" bgcolor="#CCFFFF"
+
|<tt>/bin/csh</tt> or<br><tt>/bin/tcsh</tt>
+
|<tt>.cshrc</tt>
+
|<code>setenv COMPILER $FC</code>
+
 
+
|}
+
 
+
On the other hand, if <tt>FC</tt>, <tt>CC</tt>, and <tt>CXX</tt> are all undefined, then you will have to manually set them in your startup script, as described in the table below:
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|-valign="top" bgcolor="#CCCCCC"
+
!width="125px"|If your<br>shell is
+
!width="125px"|and your<br>compiler is
+
!width="125px"|add to<br>this file
+
!width="300px"|the following lines of code
+
 
+
|-valign="top"
+
|<tt>/bin/bash</tt>
+
|<tt>ifort</tt>
+
|<tt>.bashrc</tt>
+
|
+
export FC=ifort
+
export CC=icc
+
export CXX=icpc
+
export COMPILER=$FC
+
 
+
|-valign="top" bgcolor="#CCFFFF"
+
|<tt>/bin/bash</tt>
+
|<tt>gfortran</tt>
+
|<tt>.bashrc</tt>
+
|
+
export FC=gfortran
+
export CC=gcc
+
export CXX=g++
+
export COMPILER=$FC
+
 
+
|-valign="top"
+
|<tt>/bin/bash</tt>
+
|<tt>pgfortran</tt>
+
|<tt>.bashrc</tt>
+
|
+
export FC=pgfortran
+
export CC=pgcc
+
export CXX=pgc++
+
export COMPILER=$FC
+
 
+
|-valign="top" bgcolor="#CCFFFF"
+
|<tt>/bin/bash</tt>
+
|<tt>pgf90</tt>
+
|<tt>.bashrc</tt>
+
|
+
export FC=pgf90
+
export CC=pgcc
+
export CXX=pg++
+
export COMPILER=$FC
+
 
+
|-valign="top"
+
|<tt>/bin/csh</tt> or<br><tt>/bin/tcsh</tt>
+
|<tt>ifort</tt>
+
|<tt>.cshrc</tt>
+
|
+
setenv FC ifort
+
setenv CC icc
+
setenv CXX icpc
+
setenv COMPILER $FC
+
 
+
|-valign="top" bgcolor="#CCFFFF"
+
|<tt>/bin/csh</tt> or<br><tt>/bin/tcsh</tt>
+
|<tt>gfortran</tt>
+
|<tt>.cshrc</tt>
+
|
+
setenv FC gfortran
+
setenv CC gcc
+
setenv CXX g++
+
setenv COMPILER $FC
+
 
+
|-valign="top"
+
|<tt>/bin/csh</tt> or<br><tt>/bin/tcsh</tt>
+
|<tt>pgfortran</tt>
+
|<tt>.cshrc</tt>
+
|
+
setenv FC pgfortran
+
setenv CC pgcc
+
setenv CXX pg++
+
setenv COMPILER $FC
+
 
+
|-valign="top" bgcolor="#CCFFFF"
+
|<tt>/bin/csh</tt> or<br><tt>/bin/tcsh</tt>
+
|<tt>pgf90</tt>
+
|<tt>.cshrc</tt>
+
|
+
setenv FC pgf90
+
setenv CC pgcc
+
setenv CXX pg++
+
setenv COMPILER $FC
+
 
+
|}
+
 
+
Then make sure to type:
+
 
+
source ~./bashrc  # if you are using bash
+
source ~/.cshrc    # if you are using csh or tcsh
+
 
+
to apply the changes.
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:37, 10 March 2017 (UTC)
+
 
+
== Environment variables that specify library paths ==
+
 
+
=== For GEOS-Chem ===
+
 
+
GEOS-Chem uses the netCDF library for file I/O. You should first [[Installing_libraries_for_GEOS-Chem#Check_to_see_if_netCDF_is_already_installed_on_your_system|check to see if there is a pre-built netCDF library installation on your system already]].  If not, then you (or your IT staff) can install GEOS-Chem with our [[Installing libraries for GEOS-Chem|GEOS-Chem library installation package]].
+
 
+
After you have verified that a netCDF library installation exists on your system, the next step is to tell GEOS-Chem where to find the relevant library, include, and executable files.  Otherwise you will get errors during the compilation process. The easiest way to do this is to set environment variables in your setup files:
+
 
+
#<tt>.bashrc :</tt> if you use Bourne-Again shell (bash)
+
#<tt>.cshrc  :</tt> if you use C-shell (csh) or T-shell (tcsh)
+
 
+
There are three environment variables that you need to set:
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|- bgcolor="#CCCCCC"
+
!width="125px"|Variable
+
!width="875px"|Description
+
 
+
|-valign="top"
+
|<tt>GC_BIN</tt>
+
|Points to the <tt>bin/</tt> subfolder of the root netCDF path. This is where the <tt>nc-config</tt> and <tt>nf-config</tt> files are located.
+
 
+
|-valign="top"
+
|<tt>GC_INCLUDE</tt>
+
|Points to the <tt>include/</tt> subfolder of the root netCDF path.  This is where netCDF include files (<tt>*.h</tt>, <tt>*.inc</tt>) and compiled module files (<tt>*.mod</tt>) for the netCDF (and HDF5) libraries are located.
+
 
+
|--valign="top"
+
|<tt>GC_LIB</tt>
+
|Points to the <tt>lib/</tt> subfolder of the root netCDF path.  (On some systems this may be named <tt>lib64/</tt> instead.) This is where the netCDF library files (<tt>*.a</tt>) are located.
+
|}
+
 
+
If (and only if) [[Installing_libraries_for_GEOS-Chem#Special_handling_for_netCDF-4.2_and_higher_versions|you loaded the netCDF Fortran library as a separate module]] (e.g. for netCDF-4.2 and higher versions), you will also need to set these variables:
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|- bgcolor="#CCCCCC"
+
!width="125px"|Variable
+
!width="875px"|Description
+
 
+
|-valign="top"
+
|<tt>GC_F_BIN</tt>
+
|Points to the <tt>bin/</tt> subfolder of the root netCDF Fortran path.  This is where the <tt>nf-config</tt> file is located.
+
 
+
|-valign="top"
+
|<tt>GC_F_INCLUDE</tt>
+
|Points to the <tt>include/</tt> subfolder of the root netCDF Fortran path.  This is where netCDF include files (<tt>*.h</tt>) and compiled module files (<tt>*.mod</tt>) are located.
+
 
+
|-valign="top"
+
|<tt>GC_F_LIB</tt>
+
|Points to the <tt>lib/</tt> subfolder of the root netCDF Fortran path.  (On some systems this may be named <tt>lib64/</tt> instead.) This is where the netCDF library files (<tt>*.a</tt>) are located.
+
|}
+
 
+
The best way to define these variables is to add them to your <tt>.bashrc</tt> (or <tt>.cshrc</tt>) system startup file.
+
 
+
We recommend using the <tt>NETCDF_HOME</tt> etc. variables that are defined by the module load command to define the environment variables needed for GEOS-Chem. If you built the netCDF libraries with our netCDF installer package, then you can just define the GEOS-Chem environment variables manually, e.g.:
+
 
+
# Tell GEOS-Chem where to find netCDF library files
+
export GC_BIN=/YOURPATH/ifort/nc4/bin
+
export_GC_INCLUDE=/YOURPATH/ifort/nc4/include
+
export GC_LIB=/YOURPATH/ifort/nc4/lib
+
 
+
If you have any questions about where the library paths for netCDF are located on your system, ask your IT staff.
+
 
+
==== With bash ====
+
 
+
If you use bash, then add the following lines to your <tt>.bashrc</tt> file:
+
 
+
# Tell GEOS-Chem where to find netCDF library files
+
export GC_BIN=$NETCDF_HOME/bin
+
export_GC_INCLUDE=$NETCDF_INCLUDE
+
export GC_LIB=$NETCDF_LIB
+
+
# NOTE: If netCDF-Fortran was loaded as a separate module, then
+
# also define these variables.  (Otherwise comment these out.)
+
export GC_F_BIN=$NETCDF_FORTRAN_HOME/bin
+
export GC_F_INCLUDE=$NETCDF_FORTRAN_INCLUDE
+
export GC_F_LIB=$NETCDF_FORTRAN_LIB
+
 
+
Then to accept the changes, type <tt>source ~/.bashrc</tt> at the Unix prompt.
+
 
+
==== With csh or tcsh ====
+
 
+
If you use C-shell (csh) or T-shell (tcsh), then add the following lines to your <tt>.cshrc</tt> file:
+
 
+
# Tell GEOS-Chem where to find netCDF library files
+
setenv ROOT_LIBRARY_DIR root_library_dir
+
setenv GC_BIN          $(NETCDF_HOME)/bin
+
setenv GC_INCLUDE      $(NETCDF_INCLUDE)
+
setenv GC_LIB          $(NETCDF_LIB)
+
+
# NOTE: If netCDF-Fortran was loaded as a separate module, then
+
# also define these variables.  (Otherwise comment these out.)
+
setenv GC_F_BIN        $(NETCDF_FORTRAN_HOME)/bin
+
setenv GC_F_INCLUDE    $(NETCDF_FORTRAN_INCLUDE)
+
setenv GC_F_LIB        $(NETCDF_FORTRAN_LIB)
+
 
+
where <tt>root_library_dir</tt> is the directory into which you installed the libraries, [[#netCDF-4.2 installation process|as described above]].  Then to accept the changes, type <tt>source ~/.cshrc</tt> at the Unix prompt.
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:21, 10 March 2017 (UTC)
+
 
+
=== For other data processing packages ===
+
 
+
Some related Fortran code packages use slightly different environment variable names than GEOS-Chem does.  Here is a quick list of the differences:
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|- bgcolor="#CCCCCC"
+
!width="150px"|Software package
+
!width="300px"|Instead of these variables
+
!width="300px"|Use these variable names
+
 
+
|-valign="top"
+
|[[The NcdfUtilities package]]
+
|
+
GC_BIN
+
GC_INCLUDE
+
GC_LIB
+
+
GC_F_BIN
+
GC_F_INCLUDE
+
GC_F_LIB
+
|
+
NETCDF_BIN
+
NETCDF_INCLUDE
+
NETCDF_LIB
+
+
NETCDF_FORTRAN_BIN
+
NETCDF_FORTRAN_INCLUDE
+
NETCDF_FORTRAN_LIB
+
 
+
 
+
|-valign="top"
+
|[[GEOS-FP data processing software]]
+
|
+
GC_BIN
+
GC_INCLUDE
+
GC_LIB
+
+
GC_F_BIN
+
GC_F_INCLUDE
+
GC_F_LIB
+
|
+
NETCDF_BIN
+
NETCDF_INCLUDE
+
NETCDF_LIB
+
+
NETCDF_FORTRAN_BIN
+
NETCDF_FORTRAN_INCLUDE
+
NETCDF_FORTRAN_LIB
+
 
+
|}
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 20:27, 10 March 2017 (UTC)
+
 
+
== Errors caused by incorrect environment variable settings ==
+
 
+
If you encounter any of the GEOS-Chem errors listed below, please doublecheck your environment variable settings as described in the preceding sections.
+
 
+
#[[Common_GEOS-Chem_error_messages#f77:_command_not_found|f77: command not found]]
+
 
+
 
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 17:30, 10 March 2017 (UTC)
+

Latest revision as of 18:40, 10 August 2022

This content has been migrated to the Customize your login environment chapter of geos-chem.readthedocs.io.