-->
SPHYSICS FAQ

From SPHYSICS

(Difference between revisions)
Jump to: navigation, search
 
(42 intermediate revisions by one user not shown)
Line 1: Line 1:
Welcome to the SPHYSICS FAQ Page.  If you do not find the answer to the question you were looking for, please try the other [[Forum| Forum]] pages:
+
Welcome to the SPHysics FAQ Page.  If you do not find the answer to the question you were looking for, please try the other [[SPHYSICS_Forum| Forum]] pages:
  
  
#'''[[#Where can I download SPHYSICS?| Where can I download SPHYSICS?]]'''
+
#'''[[#What is SPHysics and what can it do?| What is SPHysics and what can it do?]]'''
#'''[[#Who wrote SPHYSICS?| Who wrote SPHYSICS?]]'''
+
#'''[[#What is the difference between the different versions of SPHysics?| What is the difference between the different versions of SPHysics?]]'''
#'''[[#How do I run SPHYSICS?| How do I run SPHYSICS?]]'''
+
#'''[[#Where can I download SPHysics?| Where can I download SPHysics?]]'''
 +
#'''[[#Who wrote SPHysics?| Who wrote SPHysics?]]'''
 +
#'''[[#What platforms does SPHysics run on?| What platforms does SPHysics run on?]]'''
 +
#'''[[#How do I generate a geometry using SPHysics in fortran codes?| How do I generate a geometry using SPHysics in fortran codes?]]'''
 +
#'''[[#How do I run serial SPHysics on windows?| How do I run serial SPHysics on windows?]]'''
 +
#'''[[#How do I run serial SPHysics on Linux?| How do I run serial SPHysics on Linux?]]'''
 +
#'''[[#How do I run parallelSPHysics?| How do I run parallelSPHysics]]'''
 +
#'''[[#How do I run DualSPHysics?| How do I run DualSPHysics]]'''
 +
#'''[[#How do I visualize the results?| How do I visualize the results?]]'''
 +
#'''[[#For which cases has SPHysics been validated?| For which cases has SPHysics been validated?]]'''
 +
#'''[[#What is the Fortran code structure?| What is the Fortran code structure?]]'''
 +
#'''[[#What if I find a bug in the code?| What if I find a bug in the code?]]'''
 +
#'''[[#Is there documentation for SPHysics?| Is there documentation for SPHysics?]]'''
 +
#'''[[#How can I learn more about SPH and SPHysics?| How can I learn more about SPH and SPHysics?]]'''
 +
#'''[[#How can I contribute to the development of SPHysics?| How can I contribute to the development of SPHysics?]]'''
 +
__NOTOC__
  
=== Where can I download SPHYSICS? ===
+
=== What is SPHysics and what can it do? ===
 +
 
 +
SPHysics is a platform of free open-source codes for Smoothed Particle Hydrodynamics (SPH) written in a variety of languages for different computational resources (fortran, MPI, C++, CUDA) for the simulation of potentially violent free-surface hydrodynamics.  The SPHysics codes can simulate various phenomena including wave breaking, dam breaks, sloshing, sliding objects, floating objects, wave impact on a structure, etc.  More information on the technical capabilities can be found on the [[SPHYSICS_Home_Page| SPHysics home page]].
 +
 
 +
<br/>
 +
=== What is the difference between the different versions of SPHysics? ===
 +
 
 +
We now have a range of codes based on SPHysics:
 +
* '''SPHysics''': a serial code to solve the 2-D & 3-D Navier-Stokes equations written in Fortran
 +
* '''parallelSPHyics''': a parallelised to solve the 2-D & 3-D Naiver-Stokes equations written using MPI and Fortran
 +
* '''DualSPHysics''': a highly optimised code to solver the 2-D & 3-D Navier-Stokes equations written using C++, OpenMP and CUDA
 +
* '''SWE-SPHysics''': a serial code to solver the 1-D and 2-D Shallow Water Equations (SWEs) using Fortran.
 +
 
 +
<br/>
 +
=== Where can I download SPHysics? ===
  
 
Please see the [[Downloads| Downloads Page]].
 
Please see the [[Downloads| Downloads Page]].
  
=== Who wrote SPHYSICS? ===
+
<br/>
 +
=== Who wrote SPHysics? ===
 +
 
 +
SPHysics has been written by a number of contributors from universities from around the world.  For a list of the authors of the different codes please see the '''[[Developers| Developers]]''' page.  The code took several years to develop, apply to test cases and improve.
 +
 
 +
<br/>
 +
=== What platforms does SPHysics run on? ===
 +
 
 +
The SPHysics source codes are downloadable from the main [[Downloads| Downloads page]].  Therefore, the code can run on any operating system or platform where you have the relevant compilers (e.g. fortran, MPICH, OpenMPI, CUDA).  During development every effort has been made to ensure that the SPHysics codes are as portable as possible. 
 +
 
 +
The '''serial codes''' have been tested on the following operating systems and compilers below.
 +
 
 +
''Compilers:''
 +
 
 +
: '''Windows''':
 +
: Intel Visual Fortran (formerly Compaq Visual Fortran)
 +
 
 +
: '''[http://www.silverfrost.com Silverfrost FTN95 (Formerly Salford)]'''
 +
 
 +
: '''[http://gcc.gnu.org/wiki/GFortran GNU gfortran compiler],  (gfortran v4.2+)''' on : '''[http://www.cygwin.com Cygwin]'''
 +
 
 +
: '''Linux''':
 +
: '''[http://gcc.gnu.org/wiki/GFortran GNU gfortran compiler], (gfortran v4.2+)'''
 +
: '''[http://software.intel.com/en-us/intel-compilers/ Intel fortran compiler]'''
 +
 
 +
: '''Mac''':
 +
: '''[http://gcc.gnu.org/wiki/GFortran GNU gfortran],  (gfortran v4.2+)'''
 +
 
 +
The '''parallel Code''' has been tested on the linux/unix-based operating systems using either MPICH v2 or OpenMPI compilers with Intel ifort or GNU gfortran as the underlying compiler.
 +
 
 +
The '''DualSPHysics code''' has been tested on the linux/unix-based and windows operating systems using the CUDA (nvcc) compiler v3.0.
 +
 
 +
<br/>
 +
=== How do I generate a geometry using SPHysics in fortran codes? ===
 +
 
 +
The SPHysics serial and parallel codes come with 7 example cases in 2-D and 5 example cases in 3-D to give users an idea on how to generate their own geometries.  The SPHYSICSgen_2D.f and SPHYSICSgen_3D.f codes can generated different geometries depending on the input (we use input files or keyboard entry). From version 2.0, the default setting for the code is to use one batch file to generate the geometry and run the code.  If you just want to generate the geometry only (e.g. for checking purposes), follow these steps for 2-D (for 3-D just change 2D to 3D throughout):
 +
 
 +
Change to the directory: source\SPHYSICSgen2D\
 +
Use one of the following options depending on your compiler:
 +
: (i)  gfortran on linux/Mac/cygwin:  make -f SPHYSICSgen_gfortran.mak
 +
: (ii)  ifort on linux: make -f SPHYSICSgen_ifort.mak
 +
: (iii) ifort on windows:  NMAKE/f"SPHYSICSgen_win_ifort.mak"
 +
: (iv)  FTN95 on windows: mk32 -f SPHYSICSgen_ftn95.mak
 +
 
 +
Then change to the relevant directory (run_directory/CaseN where N is a number) to run  one of the example test cases (see below).
 +
'''Note the input files (CaseN.txt) require you to specify which compiler you wish to use (around the last line):
 +
: (i)  for the Linux/Mac/cygwin gfortran compiler use the value 1.'''
 +
: (ii)  for the Linux/Mac ifort compiler use the value 2.'''
 +
: (iii) for the Windows ifort compiler use the value 3.'''
 +
: (iii) for the Windows Silverfrost FTN95 compiler use the value 4.'''
 +
 
 +
Note, for Silverfrost FTN95, the CaseN.txt files must NOT have TABS immediately after the numerical values.  Instead, use two consecutive spaces.
 +
 
 +
<br/>
 +
=== How do I run serial SPHysics on windows? ===
 +
 
 +
This depends whether you are using an Intergrated Development Environment (IDE).  Generally, your compiler will produce SPHYSICS.exe which are then run from the command line:
 +
 
 +
: SPHYSICS_2D/3D.exe
 +
 
 +
The code includes special subroutines to generate the appropriate compilation make files which can be adjusted for other compilers and operating environments.  The code has been developed to run on Windows using Intel Visual Fortran.  For example, If you are using the Compaq Visual Fortran Compiler to run Case1, you can use the batch file:
 +
 
 +
: .\Case1_windows_ifort.bat
 +
 
 +
OR for the Silverfrost FTN95 compiler:
 +
 
 +
: .\Case1_windows_ftn95.bat
 +
 
 +
This will compile SPHYSICSgen_2D/3D which will generate the geometry and subsequently compile the executable SPHYSICS_2D/3D under the directory \execs.  The code will then start to run writing the output to a file called "sph.out" aswell as to the screen. '''Note the input files (CaseN.txt) require you to specify which compiler you wish to use (the last line); for the CVF compiler use the value 3; for the Silverfrost FTN95 compiler use the value 4.'''
 +
 
 +
<br/>
 +
=== How do I run serial SPHysics on Linux ===
 +
 
 +
The SPHysics code comes with batch files which are used to compile the source code and then run the codes.  For example, for Case1 which is supplied with the code (under run_directory), at the command prompt, for the gfortran compiler type: 
 +
 
 +
: ./Case1_unix_gfortran.bat   
 +
 
 +
OR if you use the ifortran compiler 
 +
 
 +
: ./Case1_unix_ifort.bat
 +
 
 +
This will compile SPHYSICSgen_2D/3D which will generate the geometry, the makefile SPHYSICS.mak and subsequently compile the executable SPHYSICS_2D/3D under the directory execs/.  The code will then start to run writing the output to a file called "sph.out" aswell as to the screen.  '''Note the input files (CaseN.txt) require you to specify which compiler you wish to use (the last line); for the gfortran compiler use the value 1, and for the Intel Compiler use the value 2.'''
 +
 
 +
<br/>
 +
=== How do I run parallelSPHysics? ===
 +
 
 +
This will depend on your parallel or HPC hardware and more particularly on the Job Submission System for your hardware.  parallelSPHysics comes with submission scripts for the SGE and LSF systems.  See the guide here:  '''[[Media:parallelSPHysics_v2.0_GUIDE.pdf | parallelSPHysics_v2.0_GUIDE.pdf]]'''  October 2010
 +
 
 +
<br/>
 +
=== How do I run DualSPHysics? ===
 +
 
 +
See [http://www.dual.sphysics.org/index.php/forums/ DualSPHysics FAQ]
 +
 
 +
<br/>
 +
=== How do I visualize the results? ===
 +
 
 +
Some basic visualisation tools are included with the source codes.  The results can be visualized either with Matlab or ParaView.  In order to use ParaView, the raw data files require some processing which at present is done using a choice of either some fortran or Matlab code.
 +
 
 +
From version 1.4, you can now use new fortran routines to generate the VTU files for use with ParaView.  If you are running CaseN, copy and run the relevant batch file from \Post-Processing\fortranRoutines\ to \run_directory\CaseN\, e.g. using the cvf compiler on windows, copy  PART2VTU_windows_cvf.bat to the CaseN directory, and then run from the command line using:
 +
 
 +
: .\PART2VTU_windows_ifort.bat
 +
 
 +
On linux, copy the file(s) PART2VTU_unix_gfortran/ifort.bat to the CaseN directory and run from the command line using
 +
 
 +
: ./PART2VTU_unix_gfortran.bat  or  ./PART2VTU_unix_ifort.bat
 +
 
 +
<br/>
 +
=== For which cases has SPHysics been validated? ===
 +
 
 +
The code has been validated for a number of different test cases including dam breaks, waves hitting structures, breaking waves at beaches, Poiseuille flow, Couette flow.  Interested readers are referred to the following publications for more detailed information '''[[SPHYSICS_Publications| Publication list]]'''.
 +
 
 +
<br/>
 +
=== What is the Fortran code structure? ===
 +
 
 +
We are often asked questions on whether the code can do certain things - usually this requires extra code to be added requiring work on your part.  To help you we have added Chapter 5 to the guide.  You can download Chapter 5 here with an image of the '''[[Media:SPHysics_GUIDE_v2.2_Chapter5_FORTRAN_codeStructure.pdf‎ | Code Structure]]''' here.
 +
 
 +
<br/>
 +
=== What if I find a bug in the code? ===
 +
 
 +
A good rule of thumb is that in a commerical code there is a bug every 100 lines of code.  If you find a bug in the SPHysics code, please let the developers know either by emailing us or by using the [[SPHYSICS_Forum| Forum]] pages.
 +
 
 +
<br/>
 +
=== Is there documentation for SPHysics? ===
 +
 
 +
Of course, download the guides here: 
 +
:  (i) serial: '''[[Media:SPHysics_v2.2.000_GUIDE.pdf | SPHysics_v2.2.000_GUIDE.pdf]]'''  October 2010
 +
:  (ii) parallel: '''[[Media:parallelSPHysics_v2.0_GUIDE.pdf | parallelSPHysics_v2.0_GUIDE.pdf]]'''  January 2011
 +
:  (iii) GPU: '''[http://www.dual.sphysics.org/index.php/downloads/ DualSPHysics_v3.0_GUIDE.pdf]'''  December 2013
 +
:  (iv) SWEs: '''[[Media:SWE-SPHysics v1.0.00.pdf | SWE-SPHysics v1.0.00.pdf]]''' March 2013
 +
 
 +
<br/>
 +
=== How can I learn more about SPH and SPHysics? ===
  
SPHYSICS was written by a number of contributors from universities from around the world.....
+
There are now Training Courses held each year in different locations, sometimes 2-day courses and sometimes as part the SPHERIC workshops - see [[Training_Courses| Training Courses]]
  
=== How do I run SPHYSICS on windows? ===
 
  
 +
<br/>
 +
=== How can I contribute to the development of SPHysics? ===
  
=== How do I run SPHYSICS on Linux ===
+
For starters you can buy the main developers a drink of beer at the next conference or workshop.  Failing that, you can post any new subroutines that you want to share with other users to the core SPHysics team.  Periodically the core developers of SPHysics will meet and discuss future developments and directions of SPHysics.  If your new subroutines are considered to be an invaluable addition to the code, they will be considered for inclusion in the next release version.

Latest revision as of 20:47, 16 February 2014

Welcome to the SPHysics FAQ Page. If you do not find the answer to the question you were looking for, please try the other Forum pages:


  1. What is SPHysics and what can it do?
  2. What is the difference between the different versions of SPHysics?
  3. Where can I download SPHysics?
  4. Who wrote SPHysics?
  5. What platforms does SPHysics run on?
  6. How do I generate a geometry using SPHysics in fortran codes?
  7. How do I run serial SPHysics on windows?
  8. How do I run serial SPHysics on Linux?
  9. How do I run parallelSPHysics
  10. How do I run DualSPHysics
  11. How do I visualize the results?
  12. For which cases has SPHysics been validated?
  13. What is the Fortran code structure?
  14. What if I find a bug in the code?
  15. Is there documentation for SPHysics?
  16. How can I learn more about SPH and SPHysics?
  17. How can I contribute to the development of SPHysics?


What is SPHysics and what can it do?

SPHysics is a platform of free open-source codes for Smoothed Particle Hydrodynamics (SPH) written in a variety of languages for different computational resources (fortran, MPI, C++, CUDA) for the simulation of potentially violent free-surface hydrodynamics. The SPHysics codes can simulate various phenomena including wave breaking, dam breaks, sloshing, sliding objects, floating objects, wave impact on a structure, etc. More information on the technical capabilities can be found on the SPHysics home page.


What is the difference between the different versions of SPHysics?

We now have a range of codes based on SPHysics:

  • SPHysics: a serial code to solve the 2-D & 3-D Navier-Stokes equations written in Fortran
  • parallelSPHyics: a parallelised to solve the 2-D & 3-D Naiver-Stokes equations written using MPI and Fortran
  • DualSPHysics: a highly optimised code to solver the 2-D & 3-D Navier-Stokes equations written using C++, OpenMP and CUDA
  • SWE-SPHysics: a serial code to solver the 1-D and 2-D Shallow Water Equations (SWEs) using Fortran.


Where can I download SPHysics?

Please see the Downloads Page.


Who wrote SPHysics?

SPHysics has been written by a number of contributors from universities from around the world. For a list of the authors of the different codes please see the Developers page. The code took several years to develop, apply to test cases and improve.


What platforms does SPHysics run on?

The SPHysics source codes are downloadable from the main Downloads page. Therefore, the code can run on any operating system or platform where you have the relevant compilers (e.g. fortran, MPICH, OpenMPI, CUDA). During development every effort has been made to ensure that the SPHysics codes are as portable as possible.

The serial codes have been tested on the following operating systems and compilers below.

Compilers:

Windows:
Intel Visual Fortran (formerly Compaq Visual Fortran)
Silverfrost FTN95 (Formerly Salford)
GNU gfortran compiler, (gfortran v4.2+) on : Cygwin
Linux:
GNU gfortran compiler, (gfortran v4.2+)
Intel fortran compiler
Mac:
GNU gfortran, (gfortran v4.2+)

The parallel Code has been tested on the linux/unix-based operating systems using either MPICH v2 or OpenMPI compilers with Intel ifort or GNU gfortran as the underlying compiler.

The DualSPHysics code has been tested on the linux/unix-based and windows operating systems using the CUDA (nvcc) compiler v3.0.


How do I generate a geometry using SPHysics in fortran codes?

The SPHysics serial and parallel codes come with 7 example cases in 2-D and 5 example cases in 3-D to give users an idea on how to generate their own geometries. The SPHYSICSgen_2D.f and SPHYSICSgen_3D.f codes can generated different geometries depending on the input (we use input files or keyboard entry). From version 2.0, the default setting for the code is to use one batch file to generate the geometry and run the code. If you just want to generate the geometry only (e.g. for checking purposes), follow these steps for 2-D (for 3-D just change 2D to 3D throughout):

Change to the directory: source\SPHYSICSgen2D\ Use one of the following options depending on your compiler:

(i) gfortran on linux/Mac/cygwin: make -f SPHYSICSgen_gfortran.mak
(ii) ifort on linux: make -f SPHYSICSgen_ifort.mak
(iii) ifort on windows: NMAKE/f"SPHYSICSgen_win_ifort.mak"
(iv) FTN95 on windows: mk32 -f SPHYSICSgen_ftn95.mak

Then change to the relevant directory (run_directory/CaseN where N is a number) to run one of the example test cases (see below). Note the input files (CaseN.txt) require you to specify which compiler you wish to use (around the last line):

(i) for the Linux/Mac/cygwin gfortran compiler use the value 1.
(ii) for the Linux/Mac ifort compiler use the value 2.
(iii) for the Windows ifort compiler use the value 3.
(iii) for the Windows Silverfrost FTN95 compiler use the value 4.

Note, for Silverfrost FTN95, the CaseN.txt files must NOT have TABS immediately after the numerical values. Instead, use two consecutive spaces.


How do I run serial SPHysics on windows?

This depends whether you are using an Intergrated Development Environment (IDE). Generally, your compiler will produce SPHYSICS.exe which are then run from the command line:

SPHYSICS_2D/3D.exe

The code includes special subroutines to generate the appropriate compilation make files which can be adjusted for other compilers and operating environments. The code has been developed to run on Windows using Intel Visual Fortran. For example, If you are using the Compaq Visual Fortran Compiler to run Case1, you can use the batch file:

.\Case1_windows_ifort.bat

OR for the Silverfrost FTN95 compiler:

.\Case1_windows_ftn95.bat

This will compile SPHYSICSgen_2D/3D which will generate the geometry and subsequently compile the executable SPHYSICS_2D/3D under the directory \execs. The code will then start to run writing the output to a file called "sph.out" aswell as to the screen. Note the input files (CaseN.txt) require you to specify which compiler you wish to use (the last line); for the CVF compiler use the value 3; for the Silverfrost FTN95 compiler use the value 4.


How do I run serial SPHysics on Linux

The SPHysics code comes with batch files which are used to compile the source code and then run the codes. For example, for Case1 which is supplied with the code (under run_directory), at the command prompt, for the gfortran compiler type:

./Case1_unix_gfortran.bat

OR if you use the ifortran compiler

./Case1_unix_ifort.bat

This will compile SPHYSICSgen_2D/3D which will generate the geometry, the makefile SPHYSICS.mak and subsequently compile the executable SPHYSICS_2D/3D under the directory execs/. The code will then start to run writing the output to a file called "sph.out" aswell as to the screen. Note the input files (CaseN.txt) require you to specify which compiler you wish to use (the last line); for the gfortran compiler use the value 1, and for the Intel Compiler use the value 2.


How do I run parallelSPHysics?

This will depend on your parallel or HPC hardware and more particularly on the Job Submission System for your hardware. parallelSPHysics comes with submission scripts for the SGE and LSF systems. See the guide here: parallelSPHysics_v2.0_GUIDE.pdf October 2010


How do I run DualSPHysics?

See DualSPHysics FAQ


How do I visualize the results?

Some basic visualisation tools are included with the source codes. The results can be visualized either with Matlab or ParaView. In order to use ParaView, the raw data files require some processing which at present is done using a choice of either some fortran or Matlab code.

From version 1.4, you can now use new fortran routines to generate the VTU files for use with ParaView. If you are running CaseN, copy and run the relevant batch file from \Post-Processing\fortranRoutines\ to \run_directory\CaseN\, e.g. using the cvf compiler on windows, copy PART2VTU_windows_cvf.bat to the CaseN directory, and then run from the command line using:

.\PART2VTU_windows_ifort.bat

On linux, copy the file(s) PART2VTU_unix_gfortran/ifort.bat to the CaseN directory and run from the command line using

./PART2VTU_unix_gfortran.bat or ./PART2VTU_unix_ifort.bat


For which cases has SPHysics been validated?

The code has been validated for a number of different test cases including dam breaks, waves hitting structures, breaking waves at beaches, Poiseuille flow, Couette flow. Interested readers are referred to the following publications for more detailed information Publication list.


What is the Fortran code structure?

We are often asked questions on whether the code can do certain things - usually this requires extra code to be added requiring work on your part. To help you we have added Chapter 5 to the guide. You can download Chapter 5 here with an image of the Code Structure here.


What if I find a bug in the code?

A good rule of thumb is that in a commerical code there is a bug every 100 lines of code. If you find a bug in the SPHysics code, please let the developers know either by emailing us or by using the Forum pages.


Is there documentation for SPHysics?

Of course, download the guides here:

(i) serial: SPHysics_v2.2.000_GUIDE.pdf October 2010
(ii) parallel: parallelSPHysics_v2.0_GUIDE.pdf January 2011
(iii) GPU: DualSPHysics_v3.0_GUIDE.pdf December 2013
(iv) SWEs: SWE-SPHysics v1.0.00.pdf March 2013


How can I learn more about SPH and SPHysics?

There are now Training Courses held each year in different locations, sometimes 2-day courses and sometimes as part the SPHERIC workshops - see Training Courses



How can I contribute to the development of SPHysics?

For starters you can buy the main developers a drink of beer at the next conference or workshop. Failing that, you can post any new subroutines that you want to share with other users to the core SPHysics team. Periodically the core developers of SPHysics will meet and discuss future developments and directions of SPHysics. If your new subroutines are considered to be an invaluable addition to the code, they will be considered for inclusion in the next release version.