SPINS User Guide: Difference between revisions

From Fluids Wiki
Jump to navigation Jump to search
No edit summary
Line 1: Line 1:
Welcome to the SPINS case setup page.
Welcome to the SPINS user guide.


== Getting SPINS and compiling ==
 
== The basics ==
The SPINS model is a Navier-Stokes solver that gets parameters and initial/boundary conditions from calls to user-provided routines. The user-provided routines are encapsulated in class derived from BaseCase (see BaseCase.hpp).
 
Creating your own custom configuration involves supplying the user-provided routines in a derived class based on BaseCase. The case file cases/doc_minimal.cpp shows the structure of a case file. It usually makes sense to start with a similar case file and customise it.
 
== SPINS components ==


SPINS consists of a bunch of C++ source files and a bunch of case files, and it requires four libraries. UMFPack, AMD and Blitz++ are supplied with SPINS, and it uses the system-installed FFTW.
SPINS consists of a bunch of C++ source files and a bunch of case files, and it requires four libraries. UMFPack, AMD and Blitz++ are supplied with SPINS, and it uses the system-installed FFTW.
Line 8: Line 14:
* cpp/src - SPINS source files
* cpp/src - SPINS source files
* cpp/src/cases - A few dozen example case files
* cpp/src/cases - A few dozen example case files
* cpp/AMD - AMD library
* cpp/UMFPack - UMFPack library
* cpp/UFconfig - Helper for compiling AMD/UMFPack


How To: Install SPINS on a new machine
== Getting and compiling SPINS ==


1. Get the code from git
=== Extract the code from the git repository ===
* Create a directory in which to store the code.  
* Create a directory in which to store the code.  
* In that directory type "git clone http://belize.math.uwaterloo.ca/~csubich/spins.git".
* In that directory type "git clone http://belize.math.uwaterloo.ca/~csubich/spins.git".
* This will create a directory called spins.
* This will create a directory called spins.
2. Make the code
=== Build the dependancies ===
* Go to the spins directory.
* Go to the spins directory.
* Type "./make_deps.sh".
* Type "./make_deps.sh".
=== Build SPINS ===
* Go to the systems directory.
* Go to the systems directory.
* Type "./makemake.sh". This will build the code based on the system architecture. Note that there are several files that include instructions for several systems e.g. gpc.sh.  makemake.sh will try to guess which instructions to use if you do not include options in your makemake.sh call from the command line.
* Type "./makemake.sh". This will build the code based on the system architecture. Note that there are several files that include instructions for several systems e.g. gpc.sh.  makemake.sh will try to guess which instructions to use if you do not include options in your makemake.sh call from the command line.
How To: Compile
* Enter the src directory.
* Enter the src directory.
* Type "make cases/your_case.x".
* Type "make cases/your_case.x".
Line 30: Line 32:
* After successful compilation, an executable called your_case.x is created.
* After successful compilation, an executable called your_case.x is created.


How To: Run the code
=== Running SPINS ===
* Please be careful not to run in your home directory on machines like belize or winisk.   
* Please be careful not to run in your home directory on machines like belize or winisk.   
* The code can be executed using mpirun e.g "mpirun -np 4 ./your_case.x".
* The code can be executed using mpirun e.g "mpirun -np 4 ./your_case.x".
* Please note that some cases may require command line options or a configure file called spins.conf.
* Please note that some cases may require command line options or a configure file called spins.conf.


== The basics ==
The SPINS model is a Navier-Stokes solver that gets parameters and initial/boundary conditions from calls to user-provided routines. The user-provided routines are encapsulated in class derived from BaseCase (see BaseCase.hpp).
Creating your own custom configuration involves supplying the user-provided routines in a derived class based on BaseCase. The case file cases/doc_minimal.cpp shows the structure of a case file. It usually makes sense to start with a similar case file and customise it.
== Calling sequence ==
Chris: can you verify this?
To help understand where/when to do certain operations, it's good to know the order that the user routines are called. The order is as follows:
* The constructor
* The type_* routines
* The size_* and and length_* routines
* The tracer number routines (numActive, numPassive, numtracers)
* is_mapped and do_mapping
* init_time
* init_vels
* init_tracer (single tracer) or init_tracers (multiple tracers)
At each time step, the following routines are called
* forcing:
** If no active tracers, only passive_forcing is called
** If active tracers, first vel_forcing, then tracer_forcing
* analysis


== Examples of common operations ==
== Examples of common operations ==
You can find examples of how to do various operations by digging through the case files. Some of the common operations are reproduced here.
You can find examples of how to do various operations by digging through the case files. Some of the common operations are reproduced here.


=== Grid ===
=== Using wave_reader.cpp ===
The case file wave_reader.cpp is a special case used for initialising the model with specified velocity and density fields. A configuration file, spins.conf, is used to hand parameters to SPINS.
==== Example spins.conf ====


==== Generating the grid vectors ====
At the top of your file include the global tensor indices:
<syntaxhighlight lang="cpp">
// Tensor variables for indexing
blitz::firstIndex ii;
blitz::secondIndex jj;
blitz::thirdIndex kk;
</syntaxhighlight>


Define arrays for the grid vectors:
=== Grid ===
<syntaxhighlight lang="cpp">
// Arrays to hold the x, y, and z points
Array<double,1> xx, yy, zz;
</syntaxhighlight>


You can initialise them in the constructor. For Periodic/free-slip the grid spacing is even:  
==== Generating the grid files: regular grid ====
For the unmapped grid, include the following call in your case file's constructor to generate the grid files and readers:
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
// The constructor
automatic_grid(MinX,MinY,MinZ);
casename() : xx(split_range(Nx)), yy(Ny), zz(Nz) {
    // Assumes periodic or free-slip (cosine)
    xx = Lx*(ii+0.5)/Nx; // x-coordinate: periodic
    yy = Ly*(ii+0.5)/Ny; // y-coordinate: periodic
    zz = Lz*(ii+0.5)/Nz; // z-coordinate: free-slip
}
</syntaxhighlight>
</syntaxhighlight>
where MinX, MinY and MinZ are the coordinates of the starting corner of your grid.


For no-slip (Chebyshev) the grid spacing is not even:
==== Mapped grid ====
<syntaxhighlight lang="cpp">
<span style="color:#FF0000"> Can someone write this? </span>
// The constructor
casename() : xx(split_range(Nx)), yy(Ny), zz(Nz) {
    // Assumes no-clip (Chebychev) in all dimensions
    xx = -Lx*cos(ii*M_PI/(Nx-1))/2; // x-coordinate: Chebyshev
    yy = -Ly*cos(ii*M_PI/(Ny-1))/2; // y-coordinate: Chebyshev
    zz = -Lz*cos(ii*M_PI/(Nz-1))/2; // z-coordinate: Chebyshev
}
</syntaxhighlight>
 
==== Outputting the grid ====
 
Create array tmp, then generate each grid and write the array and the grid reader out:
<syntaxhighlight lang="cpp">
// Compute the grids and write them out
DTArray *gridtmp = alloc_array(Nx,Ny,Nz);
 
*gridtmp = xx(ii) + 0*jj + 0*kk;
write_array(*gridtmp,"xgrid");
write_reader(*gridtmp,"xgrid",false);


*gridtmp = 0*ii + yy(jj) + 0*kk;
=== Analytic initialisation ===
write_array(*gridtmp,"ygrid");
<span style="color:#FF0000"> Can someone write this? </span>
write_reader(*gridtmp,"ygrid",false);


*gridtmp = 0*ii + 0*jj + zz(kk);
=== Boundary conditions ===
write_array(*gridtmp,"zgrid");
<span style="color:#FF0000"> Can someone write this? </span>
write_reader(*gridtmp,"zgrid",false);


delete(gridtmp);
=== Forcing / sponge regions ===
</syntaxhighlight>
<span style="color:#FF0000"> Can someone write this? </span>


==== Mapped grid ====
<span style="color:#FF0000"> To Do: write this! </span>


=== Initialisation ===
=== Online Analysis ===
==== Velocities ====
==== Energy Diagnostics ====
<span style="color:#FF0000"> To Do: write this! </span>
==== Tracers ====
<span style="color:#FF0000"> To Do: write this! </span>
 
=== Forcing ===
<span style="color:#FF0000"> To Do: write this! </span>
==== Velocities ====
<span style="color:#FF0000"> To Do: write this! </span>
==== Tracers ====
<span style="color:#FF0000"> To Do: write this! </span>
 
=== Analysis ===
==== Energy Diagnostic ====
If you're using a periodic grid, use this for computing kinetic energy diagnostic
If you're using a periodic grid, use this for computing kinetic energy diagnostic
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
double ke = 0.5*rho_0*pssum(sum(u*u+v*v+w*w))/(Nx*Ny*Nz)*Lx*Ly*Lz; // KE
double dV = (Lx/Nx)*(Ly/Ny)*(Lz/Nz);
if (master()) {
double ke = 0.5*rho_0*pssum(sum( u*u+v*v+w*w ))*dV; // KE
  FILE * en_record = fopen("energy_record.txt","a");
  assert(en_record);
  fprintf(en_record,"%.8f %.14g\n",time,ke);
  fclose(en_record);
}
</syntaxhighlight>
</syntaxhighlight>


Line 159: Line 81:
                   (pow(u(ii,jj,kk),2)+pow(v(ii,jj,kk),2)+pow(w(ii,jj,kk),2))));
                   (pow(u(ii,jj,kk),2)+pow(v(ii,jj,kk),2)+pow(w(ii,jj,kk),2))));
</syntaxhighlight>
</syntaxhighlight>
and you will need to compute the quadrature weights in the constructor
and you will need to compute the quadrature weights in the constructor
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
Line 167: Line 88:
                     type_x(),type_y(),type_z());
                     type_x(),type_y(),type_z());
</syntaxhighlight>
</syntaxhighlight>
If you're on a mapped grid,
<span style="color:#FF0000"> To Do: write this! </span>
==== Saving snapshots ====
<span style="color:#FF0000"> To Do: write this! </span>
==== Computing vorticity ====
<span style="color:#FF0000"> To Do: write this! </span>

Revision as of 14:19, 6 September 2012

Welcome to the SPINS user guide.


The basics

The SPINS model is a Navier-Stokes solver that gets parameters and initial/boundary conditions from calls to user-provided routines. The user-provided routines are encapsulated in class derived from BaseCase (see BaseCase.hpp).

Creating your own custom configuration involves supplying the user-provided routines in a derived class based on BaseCase. The case file cases/doc_minimal.cpp shows the structure of a case file. It usually makes sense to start with a similar case file and customise it.

SPINS components

SPINS consists of a bunch of C++ source files and a bunch of case files, and it requires four libraries. UMFPack, AMD and Blitz++ are supplied with SPINS, and it uses the system-installed FFTW.

Directory structure:

  • cpp/src - SPINS source files
  • cpp/src/cases - A few dozen example case files

Getting and compiling SPINS

Extract the code from the git repository

Build the dependancies

  • Go to the spins directory.
  • Type "./make_deps.sh".

Build SPINS

  • Go to the systems directory.
  • Type "./makemake.sh". This will build the code based on the system architecture. Note that there are several files that include instructions for several systems e.g. gpc.sh. makemake.sh will try to guess which instructions to use if you do not include options in your makemake.sh call from the command line.
  • Enter the src directory.
  • Type "make cases/your_case.x".
  • This requires a file called your_case.cpp in the cases directory. There are several cases included with the code so you may want to start with one of those.
  • After successful compilation, an executable called your_case.x is created.

Running SPINS

  • Please be careful not to run in your home directory on machines like belize or winisk.
  • The code can be executed using mpirun e.g "mpirun -np 4 ./your_case.x".
  • Please note that some cases may require command line options or a configure file called spins.conf.


Examples of common operations

You can find examples of how to do various operations by digging through the case files. Some of the common operations are reproduced here.

Using wave_reader.cpp

The case file wave_reader.cpp is a special case used for initialising the model with specified velocity and density fields. A configuration file, spins.conf, is used to hand parameters to SPINS.

Example spins.conf

Grid

Generating the grid files: regular grid

For the unmapped grid, include the following call in your case file's constructor to generate the grid files and readers: 

automatic_grid(MinX,MinY,MinZ);

where MinX, MinY and MinZ are the coordinates of the starting corner of your grid.

Mapped grid

Can someone write this?

Analytic initialisation

Can someone write this?

Boundary conditions

Can someone write this?

Forcing / sponge regions

Can someone write this?


Online Analysis

Energy Diagnostics

If you're using a periodic grid, use this for computing kinetic energy diagnostic 

double dV = (Lx/Nx)*(Ly/Ny)*(Lz/Nz);
double ke = 0.5*rho_0*pssum(sum( u*u+v*v+w*w ))*dV; // KE

If you're on a Chebyshev grid, you can use this for the KE computation 

double ke = pssum(sum((*get_quad_x())(ii)*(*get_quad_y())(jj)*(*get_quad_z())(kk)*
                  (pow(u(ii,jj,kk),2)+pow(v(ii,jj,kk),2)+pow(w(ii,jj,kk),2))));

and you will need to compute the quadrature weights in the constructor 

// Compute the quadrature weights
compute_quadweights(size_x(),size_y(),size_z(),
                    length_x(),length_y(),length_z(),
                    type_x(),type_y(),type_z());
Retrieved from "http://wiki.math.uwaterloo.ca/fluidswiki/index.php?title=SPINS_User_Guide&oldid=195"