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

From Geos-chem
Jump to: navigation, search
(GEOS-Chem)
 
(19 intermediate revisions by 2 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="100px"|Variable
+
!width="600px"|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 "Classic", but is needed for GCHP.'''''</span>
+
 
+
|-valign="top"
+
|<tt>CXX</tt> || Name of the C++ compiler.<br><span style="color:darkorange">'''''Not needed for GEOS-Chem "Classic", but is needed for GCHP.'''''</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
+
 
+
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
+
 
+
|-valign="top" bgcolor="#CCFFFF"
+
|<tt>/bin/bash</tt>
+
|<tt>gfortran</tt>
+
|<tt>.bashrc</tt>
+
|
+
export FC=gfortran
+
export CC=gcc
+
export CXX=g++
+
 
+
|-valign="top"
+
|<tt>/bin/bash</tt>
+
|<tt>pgfortran</tt>
+
|<tt>.bashrc</tt>
+
|
+
export FC=pgfortran
+
export CC=pgcc
+
export CXX=pgc++
+
+
|-valign="top" bgcolor="#CCFFFF"
+
|<tt>/bin/bash</tt>
+
|<tt>pgf90</tt>
+
|<tt>.bashrc</tt>
+
|
+
export FC=pgf90
+
export CC=pgcc
+
export CXX=pg++
+
 
+
|-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
+
+
|-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++
+
+
|-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++
+
 
+
|-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++
+
+
|}
+
 
+
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]]) 18:47, 9 January 2019 (UTC)
+
 
+
== Environment variables that specify library paths ==
+
 
+
The following sections describe how to define environment variables that point to the netCDF etc. library paths on your system.
+
 
+
=== GEOS-Chem ===
+
 
+
GEOS-Chem uses the netCDF library for file I/O.  You should first [[Check_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 [[http://wiki.seas.harvard.edu/geos-chem/index.php/Use_Spack_to_install_netCDF_on_your_system|the Spack package manager]].
+
 
+
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> or <tt>.bash_aliases</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#netCDF_4.2_and_later_versions_require_a_separate_netCDF-Fortran_installation|netCDF-Fortran is installed as a separate library on your system]], 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 one of your sysetm startup files.
+
 
+
If you are using a HPC cluster with the [[Installing libraries for GEOS-Chem#Using modules|Lmod module manager]], then environment variables that point to the root library folders (e.g. <tt>NETCDF_HOME</tt>, <tt>NETCDF_FORTRAN_HOME</tt>) will already be loaded into your Unix environment.  We recommend using these variables to define the other environment variables as described in following secttions.
+
 
+
If you installed libraries with Spack, [[Installing_libraries_for_GEOS-Chem#Pointing_GEOS-Chem_environment_variables_to_the_Spack_library_paths|please follow this link]] for information on how point environment variables to Spack library paths.
+
 
+
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 one of your Unix environment startup files (e.g. <tt>.bashrc</tt>, <tt>.bash_aliases</tt>, etc.):
+
 
+
# Tell GEOS-Chem where to find netCDF library files
+
export NETCDF_HOME=path to 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 NETCDF_FORTRAN_HOME=path to netCDF-Fortran library files
+
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 at the Unix prompt: <tt>source ~/.bashrc</tt> (or <tt>source ~/.bash_aliases</tt>, etc.)
+
 
+
==== 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 NETCDF_HOME        path to netCDF library files
+
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 NETCDF_FORTRAN_HOME path to my netCDF-Fortran library files
+
setenv GC_F_BIN            $(NETCDF_FORTRAN_HOME)/bin
+
setenv GC_F_INCLUDE        $(NETCDF_FORTRAN_INCLUDE)
+
setenv GC_F_LIB            $(NETCDF_FORTRAN_LIB)
+
 
+
Then to accept the changes, type <tt>source ~/.cshrc</tt> at the Unix prompt.
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 16:10, 10 January 2019 (UTC)
+
 
+
==== For libraries installed with the Spack package manager ====
+
 
+
If you [[Use_Spack_to_install_netCDF_on_your_system|installed the netCDF libraries with the Spack package manager]], then please see [[Use_Spack_to_install_netCDF_on_your_system#Define_GEOS-Chem_environment_variables_that_point_to_the_Spack_library_paths|this wiki post]] which describes how you can define the envionment variables to point to the proper library paths.
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:10, 17 June 2019 (UTC)
+
 
+
=== Other related Fortran software packages ===
+
 
+
Some related Fortran code packages use slightly different environment variable names than GEOS-Chem does ([[#GEOS-Chem|see above section]]).  Here is a quick list of the differences:
+
 
+
{| border=1 cellspacing=0 cellpadding=5
+
|- bgcolor="#CCCCCC"
+
!width="275px"|Software package
+
!width="275px"|In the same way<br>you defined these variables:
+
!width="275px"|Also define these variables<br>in your <tt>.bashrc</tt> or <tt>.cshrc</tt>
+
 
+
|-valign="top"
+
|[[The NcdfUtilities package]]<br>(standalone distribution)
+
|
+
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)
+
 
+
== Environment variables for OpenMP parallelization ==
+
 
+
 
+
 
+
== 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.
+
 
+
#[[Compile-time_warnings_and_errors#f77:_command_not_found|f77: command not found]]
+
 
+
--[[User:Bmy|Bob Yantosca]] ([[User talk:Bmy|talk]]) 15:12, 17 June 2019 (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.