{"id":15,"date":"2022-11-17T15:30:43","date_gmt":"2022-11-17T07:30:43","guid":{"rendered":"http:\/\/www.fvcom.org\/?p=15"},"modified":"2022-11-20T00:18:18","modified_gmt":"2022-11-19T16:18:18","slug":"fvcom-installation-compilation-and-execution","status":"publish","type":"post","link":"https:\/\/fvcom.smast.umassd.edu\/?p=15","title":{"rendered":"FVCOM Installation, Compilation, and Execution"},"content":{"rendered":"\n<figure class=\"wp-block-table\"><table class=\"has-white-color has-text-color has-background\" style=\"background-color:#ff4006\"><tbody><tr><td>1. <strong>Where and how to obtain the source code?<\/strong><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p>The FVCOM source code is available in the FVCOM GitHub repository at<\/p>\n\n\n\n<p><a href=\"https:\/\/github.com\/FVCOM-GitHub.\">https:\/\/github.com\/FVCOM-GitHub.<\/a><\/p>\n\n\n\n<p>The FVCOM GitHub contains several versions of the FVCOM source codes. For example, FVCOM v4.3, FVCOM v4.4.2, and FVCOM v5.0.<\/p>\n\n\n\n<p>There are two ways to download the FVCOM source code from GitHub. The first is to clone the code using a git command from a terminal, and the second is to download the code directly from the GitHub website.<\/p>\n\n\n\n<p><strong>Method 1<\/strong>: Clone the code with a git command from a terminal. For example,<\/p>\n\n\n\n<p><a href=\"https:\/\/github.com\/FVCOM-GitHub\/fvcom442.git\">git clone<\/a> Note: it requires that \u201cgit\u201d is installed on the computer system. Visit <a href=\"http:\/\/the Git webpage (https:\/\/git-scm.com\/download\/linux\">the Git webpage <\/a>for more details about how to install git.<\/p>\n\n\n\n<p><strong>Method 2<\/strong>: Download the code directly from <a href=\"https:\/\/github.com\/FVCOM-GitHub\">the webpage<\/a> .<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>Select the version (such as fvcom43, fvcom442, fvcom50).<\/li>\n\n\n\n<li>Click the green button \u2018Code\u2019 and select \u2018Download ZIP.\u2019<\/li>\n<\/ul>\n\n\n\n<p>We also provide a package of helping users to learn and run FVCOM, including example cases, offline models, libraries interacting with FVCOM, and pre-and post-processing tools. The package is available at <a href=\"http:\/\/a google drive address\">a google drive address<\/a>:<\/p>\n\n\n\n<p><\/p>\n\n\n\n<p><\/p>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-white-color has-text-color has-background\" style=\"background-color:#ff4006\"><tbody><tr><td><strong>2<\/strong>. <strong>What libraries are required to install, and what Fortran compilers can run FVCOM<\/strong><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p><strong>Required\/Optional libraries<\/strong>:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>NetCDF<\/strong>: Read input files and write output files in NetCDF format. Both <a href=\"https:\/\/www.unidata.ucar.edu\/software\/netcdf\/\">NetCDF-C<\/a> and NetCDF-Fortran are required. <\/li>\n<\/ul>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>MPI<\/strong>: Parallel simulation with multiple CPUs. You don\u2019t need it if you run FVCOM using a single CPU. However, we strongly suggest that you run FVCOM using parallel simulation. There are many options to download and install the free MPI software. For example,<ul><li><a href=\"https:\/\/www.mpich.org\/downloads\/\">MPICH <\/a><\/li><\/ul>\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/www.intel.com\/content\/www\/us\/en\/developer\/tools\/oneapi\/overview.html\">OneAPI <\/a><\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Metis<\/strong>: <a href=\"http:\/\/glaros.dtc.umn.edu\/gkhome\/metis\/metis\/overview\">Serial graphic partition <\/a>. The Metis is used for domain partition. It is required for parallel simulation with multiple CPUs. It does not require running FVCOM using a single processor. However, we strongly recommend downloading and installing it.<\/li>\n<\/ul>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Julian<\/strong>: It is used for <a href=\"https:\/\/pds-rings.seti.org\/toolkits\/\">calendar calculation<\/a> . The equilibrium tidal forcing in the FVCOM uses the Julian time.<\/li>\n<\/ul>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Proj4<\/strong>: It is used for <a href=\"https:\/\/proj.org\/\">coordinate conversion<\/a> . FVCOM includes both Cartesian and spherical coordinates. The WRF NetCDF output uses the earth coordinate system defined as longitudes and latitudes. If the Cartesian coordinate is selected for FVCOM, Proj4 is required to turn on to convert longitudes and latitudes to the <em>x-y<\/em> coordinates. Proj4 is also used for the FVCOM output if the earth coordinates system is selected for the model run in the Cartesian coordinates.<\/li>\n<\/ul>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Fortran-proj4<\/strong>: Bindings for proj4 in Fortran. This program is to make Proj.4 work in Fortran. The program can be downloaded at <a href=\"https:\/\/github.com\/mhagdorn\/proj4-fortran\">https:\/\/github.com\/mhagdorn\/proj4-fortran<\/a>.<\/li>\n<\/ul>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>PetSc<\/strong>: The toolkit of scientific computation. This library is required when using the semi-implicit solver in FVCOM. Also, PetSc is required for matrix solvers in Kalman filter assimilation, non-hydrostatic, and SWAVE modules. It is needed to run FVCOM using the two-mode explicit solver. PetSc can be downloaded from the website addressed <a href=\"https:\/\/petsc.org\/\">https:\/\/petsc.org\/<\/a>.<\/li>\n<\/ul>\n\n\n\n<p><strong>ESMF<\/strong>: This library is only required for either two domain nesting or WRF-FVCOM coupling.<\/p>\n\n\n\n<p><\/p>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-white-color has-text-color has-background\" style=\"background-color:#ff4006\"><tbody><tr><td><strong>3.<\/strong> <strong><strong>Which Fortran Compiler works for FVCOM<\/strong>?<\/strong><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p>FVCOM codes are written in Fortran 90 and C-language. We recommend users use the Intel Fortran compiler,<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>ifort and <a href=\"https:\/\/www.intel.com\/content\/www\/us\/en\/developer\/tools\/oneapi\/overview.html\">icc <\/a><\/li>\n<\/ul>\n\n\n\n<p>The users can also use other Fortran compilers. For example,&nbsp;<\/p>\n\n\n\n<p>\u201cgfortran and <a href=\"https:\/\/gcc.gnu.org\/\">gcc<\/a>\u201d ;<br>PGI Fortran (https:\/\/www.pgroup.com\/index.htm).<\/p>\n\n\n\n<p><\/p>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-white-color has-text-color has-background\" style=\"background-color:#ff4006\"><tbody><tr><td><strong><strong>4.<\/strong> <strong>How to compiler FVCOM? Which files do users need to modify?<\/strong><\/strong><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>makedepends<\/strong><\/li>\n<\/ul>\n\n\n\n<p>Generate the module dependencies of the FVCOM code. This step is required only when new codes are added.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Edit <\/strong>\u201c<strong>make.inc<\/strong>\u201d<\/li>\n<\/ul>\n\n\n\n<p>Define the modules and numerical algorithms in \u201cmake in\u201d for the user\u2019s case. The \u2018make.inc\u2019 includes all the settings for compiling FVCOM. This file must be edited correctly to meet what the user tried to do before the FVCOM code is compiled. Three contents in \u201cmake.inc\u201d are required to be set up, including \u201clibrary environments,\u201d \u201ccontrol flags,\u201d and \u201ccompiler settings.\u201d &nbsp;The examples can be found in the example cases posted on Google Drive.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>make clean<\/strong><\/li>\n<\/ul>\n\n\n\n<p>This step is required after completing editing \u2018make.inc\u2019. This execution ensures all code components are compiled after the setting changes.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>make<\/strong><\/li>\n<\/ul>\n\n\n\n<p>Compile the FVCOM codes. The user should see the executable file \u2018fvcom\u2019 if the compilation is successful.<\/p>\n\n\n\n<p>FVCOM can be compiled in a parallel mode using the following command:<\/p>\n\n\n\n<p><strong>make -j <em>N<\/em><\/strong><\/p>\n\n\n\n<p>where <em>N<\/em> is the integer number specifying the maximum number of cores used for compiling the FVCOM source codes. Usually, it does not take a significant time to complete the FVCOM compilation, so a parallel compiler is not necessary.<\/p>\n\n\n\n<p>Based on the tests with Intel\u00ae Xeon\u00ae CPU E5-2640, the total time compiling FVCOM is 120 s with one core. The time can be saved by 40% with two cores and 54% with three cores. No significant improvement is reported when more than three cores are selected. The results could vary with different CPUs and selected flags.<\/p>\n\n\n\n<p><\/p>\n\n\n\n<figure class=\"wp-block-table\"><table class=\"has-white-color has-text-color has-background\" style=\"background-color:#ff4006\"><tbody><tr><td><strong><strong><strong>5.<\/strong> <strong><strong>How to run FVCOM<\/strong>?<\/strong><\/strong><\/strong><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n<p>Step 1: Make a folder \u2018run\u2019 and copy\/link the executable file \u2018fvcom\u2019 to this folder.<\/p>\n\n\n\n<p>Step 2: Prepare all required input files\u2014for example, initial conditions, meteorological forcing, boundary conditions, river charges, etc.<\/p>\n\n\n\n<p>Step 3: Create the namelist file with the name <em>CASENAME<\/em>_run.nml. Users can get a blank namelist file by \u201c.\/fvcom \u2013create_namelist.\u201d<\/p>\n\n\n\n<p>Step 4: Run the model.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>To run FVCOM with a single CPU<\/li>\n<\/ul>\n\n\n\n<p>.\/fvcom \u2013casename=<em>CASENAME<\/em><\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li>To run FVCOM in the parallel way<\/li>\n<\/ul>\n\n\n\n<p>mpiexec -np N .\/fvcom \u2013casename=<em>CASENAME<\/em><\/p>\n\n\n\n<p>or<\/p>\n\n\n\n<p>mpirun -np N&nbsp; .\/fvcom \u2013casename=<em>CASENAME<\/em><\/p>\n\n\n\n<p>where N is the processor number and \u201cCASENAME\u201d is the name of the simulation case and must be consistent with the prefix of the namelist file. For example, if the namelist file is named \u2018gom_run.nml\u2019, then \u201cCASENAME\u201d is \u2018gom\u2019. The CPUs are defined in the namelist file.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>1. Where and how to obtain the source code? The FVCOM source code is available in the FVCOM GitHub repository at https:\/\/github.com\/FVCOM-GitHub. The FVCOM GitHub contains several versions of the FVCOM source codes. For example, FVCOM v4.3, FVCOM v4.4.2, and FVCOM v5.0. There are two ways to download the FVCOM source code from GitHub. The [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-15","post","type-post","status-publish","format-standard","hentry","category-fvcom"],"_links":{"self":[{"href":"https:\/\/fvcom.smast.umassd.edu\/index.php?rest_route=\/wp\/v2\/posts\/15","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/fvcom.smast.umassd.edu\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/fvcom.smast.umassd.edu\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/fvcom.smast.umassd.edu\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/fvcom.smast.umassd.edu\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=15"}],"version-history":[{"count":5,"href":"https:\/\/fvcom.smast.umassd.edu\/index.php?rest_route=\/wp\/v2\/posts\/15\/revisions"}],"predecessor-version":[{"id":79,"href":"https:\/\/fvcom.smast.umassd.edu\/index.php?rest_route=\/wp\/v2\/posts\/15\/revisions\/79"}],"wp:attachment":[{"href":"https:\/\/fvcom.smast.umassd.edu\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=15"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/fvcom.smast.umassd.edu\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=15"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/fvcom.smast.umassd.edu\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=15"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}