--- Welcome to the official ADCIRCWiki site! The site is currently under construction, with limited information. ---

For general information, see the ADCIRC site, ADCIRC FAQ, or the ADCIRC Wikipedia page. For model documentation not yet available on the wiki, see the ADCIRC site. New content is being continuously added to the ADCIRCWiki, and material from the main ADCIRC site will be gradually transitioned over to the wiki.

Getting Started in Linux/Unix: Difference between revisions

From ADCIRCWiki
Jump to navigation Jump to search
 
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
== Getting Started in Linux/Unix ==
== Getting Started in Linux/Unix ==


As with most useful and complex models, just getting started is the main initial barrier.  This section of the wiki describes the most basic scenario of running ADCIRC on a Linux/Unix computer, using a simple test case as an example.   <strong> If the user is running ADCIRC through the SMS application, please see the SMS documentation on running ADCIRC within SMS. This wiki does not cover that usage. </strong>  And although the general process of running ADCIRC on a Windoze computer or cluster is the same as for Linux/Unix, this section does not cover compiling ADCIRC on a Windoze computer. See "Compiling and Running ADCIRC on Windoze" instead.
This section of the wiki describes the most basic scenario of running ADCIRC on a Linux/Unix computer, using a simple test case as an example. <strong> If the user is running ADCIRC through the SMS application, please see the SMS documentation on running ADCIRC within SMS. This wiki does not cover that usage. </strong>  And although the general process of running ADCIRC on a Windows computer or cluster is the same as for Linux/Unix, this section does not cover compiling ADCIRC on a Windows computer. See [[Getting Started in Windows]].


Initially, we will describe getting ADCIRC running on a simple test case in "serial" mode, meaning that only one cpu is used. Running ADCIRC in parallel mode is moderately more complex and will be described separately.   
Initially, we will describe getting ADCIRC running on a simple test case in "serial" mode, meaning that only one cpu is used. Running ADCIRC in parallel mode is moderately more complex and will be described separately.   


This section provides details on the following topics, with the serial, quarter annular harbor test case as a working example. Compiling the code for serial execution, the basic input/output files for ADCIRC, and what to do with the output. Overviews of the main input and output files are also described.  
This section provides details on the following topics, with the serial, quarter annular harbor test case as a working example. Compiling the code for serial execution, the basic input/output files for ADCIRC, and what to do with the output. Overviews of the main input and output files are also described. This section assumes several things.  The user ...
 
This section assumes several things.  The user ...
* knows ADCIRC is a finite element model, with linear triangular elements
* knows ADCIRC is a finite element model, with linear triangular elements
* has access to a computer on which to run ADCIRC, and that the OS is Unix/Linux
* has access to a computer on which to run ADCIRC, and that the OS is Unix/Linux
* knows how to edit files (using an editor such as vi/vim, emacs (really?), or a GUI editor)
* knows how to edit text files
* is familiar with working on computers via the "command line" (i.e., not clicking around with the mouse as in Windoze)
* is familiar with working on computers via the "command line"
* has the source code (which is not freely available)
* has the source code
* has a compiler available (see notes below)
* has a compiler available (see notes below)


=== Compiling ADCIRC ===
=== Compiling ADCIRC ===
The ADCIRC model is written in Fortran (the best language eva') and needs to be compiled into executable code for the specific computer.   Thus, the user needs a Fortran compiler available to translate the text source code into something the computer can execute.
The ADCIRC model is written in Fortran and needs to be compiled into executable code for the specific computer. Thus, the user needs a Fortran compiler available to translate the text source code into something the computer can execute. The mechanics of compiling ADCIRC are independent of the specific compiler. The [https://adcirc.org/files/2018/11/ADCIRCDevGuide.pdf ADCIRC Developers Guide] also has useful documentation on compiling, and readers may wish to look to it for further assistance.  


==== Do you have a Fortran compiler? ====  
==== Do you have a Fortran compiler? ====  
If the answer to this question is "Huh?", then read this: [https://en.wikipedia.org/wiki/Fortran Fortran-Wikipedia] and this: [https://en.wikipedia.org/wiki/Compiler Compilers-Wikipedia].
If the answer to this question is "Huh?", then read this: [https://en.wikipedia.org/wiki/Fortran Fortran-Wikipedia] and this: [https://en.wikipedia.org/wiki/Compiler Compilers-Wikipedia].  
 
==== Which Compiler Do I Use? ====
If you are working on a desktop machine, you probably know if a compiler is available.  If one is not available and you have administrative access to the computer, install the GNU fortran compiler.  Otherwise, have an administrative user install it. The compiler is available here: https://gcc.gnu.org/wiki/GFortranBinaries
 
If you are working on a High-Performance Computing (HPC) cluster maintained as a research and applications resource, then the chances are high (i.e., 100%) that a Fortran compiler exists on the cluster.  In fact, there are probably several, typically including the GNU Fortran computer gfortran, and commercial compilers from Intel (ifort) and Portland Group (pgf).  Which compiler you actually use depends on how your specific user environment is configured.  Large clusters frequently use the "module" approach to add applications to the user's environment, or else just publish a list of compilers and how to add paths to them. 


Regardless, let's assume that you have a compiler identified. The mechanics of compiling ADCIRC are independent of the specific compiler.  
==== Which compiler do I use? ====
If a compiler is not available and you have administrative access to the computer, install the GNU Fortran compiler. Otherwise, have an administrative user install it. The compiler is available [https://gcc.gnu.org/wiki/GFortranBinaries here]. If you are working on a High-Performance Computing (HPC) cluster maintained as a research and applications resource, then the chances are very high that a Fortran compiler exists on the cluster. In fact, there are probably several, typically including the GNU Fortran computer gfortran, and commercial compilers from Intel (ifort) and Portland Group (pgf).  Which compiler you actually use depends on how your specific user environment is configured. Large clusters frequently use the "module" approach to add applications to the user's environment, or else just publish a list of compilers and how to add paths to them.  Consult your system's documentation or an administrator if you cannot determine what compiler is available.  


==== OK, actual compile time ====
==== OK, actual compile time ====
The ADCIRC source code is packaged in directories ("folders" in Windoze parlance). The actual compiling is done in the "work" directory. In a terminal (i.e., on the command-line), go there. In this directory, there is a file called "makefile", which is a system for compiling software into executable code. There is also a file called cmplrflags.mk that contains sections for different compilers. Assuming that you have the gfortran compiler available somewhere on your environment's PATH, edit the cmplrflags.mk file by uncommenting the line that says "compiler=gnu".  This will tell the make process to use compiler information as defined in the "gnu" section for a Linux OS.  At the command prompt, type "make adcirc" to compile the serial ADCIRC model.
The ADCIRC source code is packaged in directories ("folders"). The actual compiling is done in the "work" directory. In a terminal (i.e., on the command-line), go there. In this directory, there is a file called "makefile", which is a system for compiling software into executable code. There is also a file called cmplrflags.mk that contains sections for different compilers. You can either edit this file to specify the compiler or you can specify the compiler at the command line. For instance, assuming that you have the gfortran compiler available somewhere on your environment's PATH, do one of the following:
* Edit the cmplrflags.mk file by uncommenting the line that says <code>compiler=gnu</code>.  This will tell the make process to use compiler information as defined in the "gnu" section for a Linux OS.  At the command prompt, type <code>make adcirc</code>.
OR
* Skip editing the cmplrflags.mk file and just type <code>make adcirc compiler=gnu</code>.
This will compile the serial ADCIRC model. If compilation is successful, there should be an executable file named "adcirc" in the work directory. If you receive errors when compiling and are unsure how to deal with them, a quick search for the error on the internet may help you identify issues, such as compiler flag(s) or software libraries needed for your system. If you are not successful, you may need to reach out to an administrator for your system or to the ADCIRC listserv.


=== Running the Serial Quarter Annular Harbor Test Case ===
=== Running the Serial Quarter Annular Harbor Test Case ===
The test case is the so-called serial quarter annular problem. It is described in some detail here: [https://adcirc.org/home/documentation/example-problems/quarter-annular-harbor-with-tidal-forcing-example/].  
The test case is the so-called serial quarter annular problem. It is described in some detail [https://adcirc.org/home/documentation/example-problems/quarter-annular-harbor-with-tidal-forcing-example/ here]. The ADCIRC grid is only 63 nodes (triangle vertices) and 96 elements. A plot of the grid is shown to the right. The red arc indicates open boundary nodes, and the green lines represent land (i.e., no flow) boundaries.  The forcing for this test is a 0.3048 meter M2 tide on the open boundary, run for 5 days with a 180 sec timestep and a 2 day ramp up of the boundary forcing.  
The ADCIRC grid is only 63 nodes (triangle vertices) and 96 elements. A plot of the grid is shown to the right. The red arc indicates open boundary nodes, and the green lines represent land (i.e., no flow) boundaries.


[[File:Screenshot 2018-08-13 15.02.38.png|200px|thumb|Quarter Annular Harbor Test Case Grid]]
[[File:Screenshot 2018-08-13 15.02.38.png|200px|thumb|Quarter Annular Harbor Test Case Grid]]


Get the test case here: [http://www.unc.edu/ims/adcirc/test_cases/quarter_annular/serial_quarter_annular_v51_52_20.zip]  Unzip/untar the downloaded file.  It will expand into a directory called "serial_quarter_annular_v51_52_20/".  Go there and uncompress the contents.
# Get the test case [https://cdr.lib.unc.edu/downloads/dj52wb456?locale=en here].  
# Extract the downloaded file.  It will expand into a directory called "serial_quarter_annular_v51_52_20/".  Go there and extract the contents.
# There are several files in this directory.  The fort.14 and fort.15 files are <strong>input</strong> files.  The rest are output by ADCIRC and contain various parts of the solution.
# Run the previously compiled ADCIRC serial executable by either copying it to this test case directory and executing it by typing <code>./adcirc</code>, or by using the relative or absolute path to the executable (e.g., <code>/home/MyUserName/ADCIRC/work/adcirc</code>).
This serial case is very fast.  It will produce these '''output''' files:
*adcirc.log - runtime diagnostic log file
*fort.16 - another runtime diagnostic log file
*fort.33 - iterative solver diagnostic file
*fort.61 - station output file
*fort.67 - alternating hotstart file
*fort.68 - alternating hotstart file
*maxele.63 - maximum water level over duration of simulation
*maxvel.63 - maximum depth-averaged water speed over duration of simulation


There are 16 files in this directory.  The fort.14 and fort.15 files are <strong>input</strong> filesThe rest are output by ADCIRC and contain various parts of the solution.
If you get this far, then the case ranNow it's time to [[visualization|visualize]] the results.

Latest revision as of 10:08, 6 July 2020

Getting Started in Linux/Unix

This section of the wiki describes the most basic scenario of running ADCIRC on a Linux/Unix computer, using a simple test case as an example. If the user is running ADCIRC through the SMS application, please see the SMS documentation on running ADCIRC within SMS. This wiki does not cover that usage. And although the general process of running ADCIRC on a Windows computer or cluster is the same as for Linux/Unix, this section does not cover compiling ADCIRC on a Windows computer. See Getting Started in Windows.

Initially, we will describe getting ADCIRC running on a simple test case in "serial" mode, meaning that only one cpu is used. Running ADCIRC in parallel mode is moderately more complex and will be described separately.

This section provides details on the following topics, with the serial, quarter annular harbor test case as a working example. Compiling the code for serial execution, the basic input/output files for ADCIRC, and what to do with the output. Overviews of the main input and output files are also described. This section assumes several things. The user ...

  • knows ADCIRC is a finite element model, with linear triangular elements
  • has access to a computer on which to run ADCIRC, and that the OS is Unix/Linux
  • knows how to edit text files
  • is familiar with working on computers via the "command line"
  • has the source code
  • has a compiler available (see notes below)

Compiling ADCIRC

The ADCIRC model is written in Fortran and needs to be compiled into executable code for the specific computer. Thus, the user needs a Fortran compiler available to translate the text source code into something the computer can execute. The mechanics of compiling ADCIRC are independent of the specific compiler. The ADCIRC Developers Guide also has useful documentation on compiling, and readers may wish to look to it for further assistance.

Do you have a Fortran compiler?

If the answer to this question is "Huh?", then read this: Fortran-Wikipedia and this: Compilers-Wikipedia.

Which compiler do I use?

If a compiler is not available and you have administrative access to the computer, install the GNU Fortran compiler. Otherwise, have an administrative user install it. The compiler is available here. If you are working on a High-Performance Computing (HPC) cluster maintained as a research and applications resource, then the chances are very high that a Fortran compiler exists on the cluster. In fact, there are probably several, typically including the GNU Fortran computer gfortran, and commercial compilers from Intel (ifort) and Portland Group (pgf). Which compiler you actually use depends on how your specific user environment is configured. Large clusters frequently use the "module" approach to add applications to the user's environment, or else just publish a list of compilers and how to add paths to them. Consult your system's documentation or an administrator if you cannot determine what compiler is available.

OK, actual compile time

The ADCIRC source code is packaged in directories ("folders"). The actual compiling is done in the "work" directory. In a terminal (i.e., on the command-line), go there. In this directory, there is a file called "makefile", which is a system for compiling software into executable code. There is also a file called cmplrflags.mk that contains sections for different compilers. You can either edit this file to specify the compiler or you can specify the compiler at the command line. For instance, assuming that you have the gfortran compiler available somewhere on your environment's PATH, do one of the following:

  • Edit the cmplrflags.mk file by uncommenting the line that says compiler=gnu. This will tell the make process to use compiler information as defined in the "gnu" section for a Linux OS. At the command prompt, type make adcirc.

OR

  • Skip editing the cmplrflags.mk file and just type make adcirc compiler=gnu.

This will compile the serial ADCIRC model. If compilation is successful, there should be an executable file named "adcirc" in the work directory. If you receive errors when compiling and are unsure how to deal with them, a quick search for the error on the internet may help you identify issues, such as compiler flag(s) or software libraries needed for your system. If you are not successful, you may need to reach out to an administrator for your system or to the ADCIRC listserv.

Running the Serial Quarter Annular Harbor Test Case

The test case is the so-called serial quarter annular problem. It is described in some detail here. The ADCIRC grid is only 63 nodes (triangle vertices) and 96 elements. A plot of the grid is shown to the right. The red arc indicates open boundary nodes, and the green lines represent land (i.e., no flow) boundaries. The forcing for this test is a 0.3048 meter M2 tide on the open boundary, run for 5 days with a 180 sec timestep and a 2 day ramp up of the boundary forcing.

Quarter Annular Harbor Test Case Grid
  1. Get the test case here.
  2. Extract the downloaded file. It will expand into a directory called "serial_quarter_annular_v51_52_20/". Go there and extract the contents.
  3. There are several files in this directory. The fort.14 and fort.15 files are input files. The rest are output by ADCIRC and contain various parts of the solution.
  4. Run the previously compiled ADCIRC serial executable by either copying it to this test case directory and executing it by typing ./adcirc, or by using the relative or absolute path to the executable (e.g., /home/MyUserName/ADCIRC/work/adcirc).

This serial case is very fast. It will produce these output files:

  • adcirc.log - runtime diagnostic log file
  • fort.16 - another runtime diagnostic log file
  • fort.33 - iterative solver diagnostic file
  • fort.61 - station output file
  • fort.67 - alternating hotstart file
  • fort.68 - alternating hotstart file
  • maxele.63 - maximum water level over duration of simulation
  • maxvel.63 - maximum depth-averaged water speed over duration of simulation

If you get this far, then the case ran. Now it's time to visualize the results.