slimPre
index
/builds/dg/dg/build/slimPre.py

Second-generation Louvain-la-Neuve Ice-ocean model - User interface
 
Contact: jonathan.lambrechts@uclouvain.be
webpage: www.climate.be/slim
 
SLIM solves the governing equations on adaptative unstructured meshes using the discontinuous Galerkin finite element method.
 
slimPre contains the tools writing the input files necessary for the simulations (for simulations, see slim.py file), such as partitioned mesh, bathymetry, coriolis, wind, tides, ...
 
To generate the input files, run the script my_prepro_script.py:
    - On a single core: rundgpy my_prepro_script.py
    - On multiple cores: mpirun -np N rundgpy my_prepro_script.py (replace N by the number of cores)
 
Mesh:
    A Mesh object contains a mesh, loaded from a .msh file, and the mesh projection system
 
Region:
    A Region object contains a Mesh object, and a list of physical tags. The coordinates of all the mesh nodes contained on the physical tags is loaded in variable coordinates
 
Coordinate_system:
    A Coordinate_system object contains a Region object, and the projection system of some data needed by the user. The variable coordinates gives the node coordinates of the Region in the data reference system.
    Vector field data can be rotate using the "rotate" and "rotate3D" functions
 
Time:
    A Time object contains an array of times at which the data will be given. Time can be built using either a vector of instants relative to some initial time, or an initial and a final time and a time step. Some periodic window can also be built.
 
write_file:
    The write_file function writes a netcdf file, using a Region object (giving the nodes for which there is data), a time object (giving the times of the data), and a list of data tuples.
    The first variable of a data tuple is the data name.
    The secod variable of a data tuple is the data array, with as many lines as the number of nodes, and as many columns as the number of time steps
 
netcdf_to_msh:
    The function transforms a netcdf file to a .msh file.
 
tpxo_tide:
    The function returns the data array of sea surface elevation, and the two horizontal transports (rotated in the coordinate system of the mesh, in m^2 s^-1) of the tides, using TPXO 7.2
 
residual_flow:
    The function returns the data array of the two horizontal transports (in m^2 s^-1) at the nodes of some physical tags, such that the velocity is constant at all the nodes and that the total transport (in m^3 s^-1) is equal to the one prescribed by the user.
 
smooth_bathymetry:
    The function smooths the given bathymetry, following a smoothing criterion, and writes it to a file. It can also write a bathymetry constant per element (P0), for a better stability. If the bathymetry is P0, it will be written in a idx file. Otherwise, it will be written in a netcdf file.
 
interpolate_from_structured_grid
    The function interpolates from structured data 
 
interpolate_from_structured_file
    The function interpolates structured data from a GMSH-file
 
get_data_from_netcdf:
    The function returns the data array contained in the netcdf file given as an argument
 
get_distance:
    The function returns an array with the minimum distance from each node of a given Region object to the physical tags given by the user. 
 
fetch_ftp:
    This function downloads some data from the SLIM servers if available. The data is downloaded in the user global_data_directory. Data is only downloaded if it does not exist locally or is older than the server data. global_data_directory is by default ~/.cache/slim_data/
 
set_global_data_directory:
    This functions gives the possibility to edit the global_data_directory
 
make_directory:
    This function makes a directory if it does not exist
 
partition_mesh:
    This function partitions the mesh (if run in multiprocessing) 
 
partition_id:
    This function returns the number of the current partition as a string
 
partition_nb:
    This function returns the number of partitions used as a string
 
exit:
    This function closes the program

 
Modules
       
dgpy
numpy
dgpy.scripts.slim_private

 
Classes
       
builtins.object
Coordinate_system
Mesh
Region
Time
dgpy.scripts.slim_private.pre_evaluator(builtins.object)
distance_msh
distance_shp
geo_tiff

 
class Coordinate_system(builtins.object)
    Create the slimPre Coordinate_system
 
Coordinate_system.coordinates is an array of shape (n,3), n being the number of nodes in the region, with the coordinates of all the region nodes in the data projection system.
Coordinate_system.rotate(u,v) returns the rotated vector array (u,v)
Coordinate_system.rotate3D ...
 
  Methods defined here:
__init__(self, region, data_proj)
keyword arguments:
 
* region
    the slimPre Region object
* data_proj
    data projection system.
rotate(self, u, v)
Return the rotated vector data array (u,v). Returned vector will be oriented in the mesh projection system
 
keyword arguments:
 
* u
    first component of the vector (in the data coordinate system)
* v
    second component of the vector (in the data coordinate system)
rotate3D(self, u, v, w)
Return the rotated vector data array (u,v). Returned vector will be oriented in the cartesian system
 
keyword arguments:
 
* u
    first component of the vector (in the data coordinate system)
* v
    second component of the vector (in the data coordinate system)
* w
    third component of the vector (in the data coordinate system)
rotateSphere(self, F_lon, F_colat, F_r)
Return the vector in the cartesian field of coordinates
 
keyword arguments:
 
* F_lon
    component along the longitude direction
* F_colat
    component along the colatitude direction
* F_r
    component along the radius direction

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Mesh(builtins.object)
    Create the slimPre Mesh
 
  Methods defined here:
__init__(self, mesh_file_name, mesh_proj=None, order=1)
keyword arguments:
 
* mesh_file_name            
    path to the mesh file (.msh format)
* mesh_proj           
    mesh projection system (Default: None). 
    
    This argument must not be given if the mesh is written in 3D (on a sphere), or if all the data are in the same projection system than the mesh.
* order            
    Polynomial order of the discretization

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Region(builtins.object)
    Create the slimPre Region
 
region.coordinates is an array of shape (n,3), n being the number of nodes in the region, with the coordinates of all the region nodes
 
  Methods defined here:
__init__(self, mesh, physical_tags='')
keyword arguments:
 
* mesh
    the slimPre Mesh object
* physical_tags
    the list of all the tags on which put some data (optional)
    
    If physical_tags are not set, all the mesh nodes are gathered

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class Time(builtins.object)
    Create the slimPre Time
 
  Methods defined here:
__init__(self, time_vector=None, initial_time='1970-01-01 00:00:00', final_time=None, time_step=None, periodic=False)
keyword arguments:
 
* time_vector
    vector with all the time steps. Time steps are given in seconds from initial_time. time_vector cannot be given if final_time and/or time_step are set
* initial_time
    initial_time given in the format 'YYYY-MM-DD hh:mm:ss'. If not set, initial_time is '1970-01-01 00:00:00'
* final_time
    final_time given in the format 'YYYY-MM-DD hh:mm:ss'. final_time cannot be given if the time_vector is set. If final_time is set, time_step must be given.
* time_step
    time_step in seconds. time_step cannot be given if the time_vector is set. If time_step is set, final_time must be given.
* periodic
    flag to define a periodic variable (Default: False)
    
    If periodic, the first time should be 0 and the last time should be the period (e.g. time_vector should be from 0 to T), and the first value is repeated.

Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class distance_msh(dgpy.scripts.slim_private.pre_evaluator)
    compute the distance from an interface region.
 
 
Method resolution order:
distance_msh
dgpy.scripts.slim_private.pre_evaluator
builtins.object

Methods defined here:
__init__(self, region, dist)
arguments:
* region : slim region 
    (only implemented for interfaces region)
* dmax : float
     points on line will be inserted every dmax interval

Methods inherited from dgpy.scripts.slim_private.pre_evaluator:
coordinate_system(self)
return the description of the projection in which the coordinates should be provided
evaluate(self, x, y, z)
evaluate at a single point
arguments :
* x,y,z : float
    the point in the projection specified by coordinate_system()
evaluate_geocentric(self, x, y, z)
evaluate at a single point
arguments :
* x,y,z : float
    the point in a cartesian coordinate system with its origin at the center of a sphere of radius 1
evaluate_matrix(self, xyz)
evaluate at several points
arguments :
* xyz : bi-dimensional numpy array
   one point on each line (in the coordinate system specified by coordinate_system())
evaluate_region(self, region)
evaluate at all the points of a given region

Data descriptors inherited from dgpy.scripts.slim_private.pre_evaluator:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class distance_shp(dgpy.scripts.slim_private.pre_evaluator)
    compute the distance from a set of points given in an esri shape file (shp). Distances are evaluated on an ellipsoid.
 
 
Method resolution order:
distance_shp
dgpy.scripts.slim_private.pre_evaluator
builtins.object

Methods defined here:
__init__(self, shp_filename, dmax, tags=[], ellps='+ellps=WGS84')
arguments:
* shp_filename : string
    path to the shp file. The shape file can be composed of points, lines or polygons. The projection used in the shape file should be longitude-latitude (in degrees).
* dmax : float
    if the shp file contains lines (or polygons), points will be inserted on those lines every dmax interval
* tags : [int]
    if there is 'entity' field of integer associated with the shp features, this argument can be used to keep only the features with given values of 'entity'
* ellps : string (default: "+ellps=WGS84")
    libproj string describing the ellipsoid

Methods inherited from dgpy.scripts.slim_private.pre_evaluator:
coordinate_system(self)
return the description of the projection in which the coordinates should be provided
evaluate(self, x, y, z)
evaluate at a single point
arguments :
* x,y,z : float
    the point in the projection specified by coordinate_system()
evaluate_geocentric(self, x, y, z)
evaluate at a single point
arguments :
* x,y,z : float
    the point in a cartesian coordinate system with its origin at the center of a sphere of radius 1
evaluate_matrix(self, xyz)
evaluate at several points
arguments :
* xyz : bi-dimensional numpy array
   one point on each line (in the coordinate system specified by coordinate_system())
evaluate_region(self, region)
evaluate at all the points of a given region

Data descriptors inherited from dgpy.scripts.slim_private.pre_evaluator:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
class geo_tiff(dgpy.scripts.slim_private.pre_evaluator)
    extract data from a geo TIFF file
 
 
Method resolution order:
geo_tiff
dgpy.scripts.slim_private.pre_evaluator
builtins.object

Methods defined here:
__init__(self, tiff_filename)
arguments:
* filename : string
    path to the geo TIFF file

Methods inherited from dgpy.scripts.slim_private.pre_evaluator:
coordinate_system(self)
return the description of the projection in which the coordinates should be provided
evaluate(self, x, y, z)
evaluate at a single point
arguments :
* x,y,z : float
    the point in the projection specified by coordinate_system()
evaluate_geocentric(self, x, y, z)
evaluate at a single point
arguments :
* x,y,z : float
    the point in a cartesian coordinate system with its origin at the center of a sphere of radius 1
evaluate_matrix(self, xyz)
evaluate at several points
arguments :
* xyz : bi-dimensional numpy array
   one point on each line (in the coordinate system specified by coordinate_system())
evaluate_region(self, region)
evaluate at all the points of a given region

Data descriptors inherited from dgpy.scripts.slim_private.pre_evaluator:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)

 
Functions
       
exit(i)
Exit properly the program
extrude(mesh_file_name, bath_file_name, nb_layers=None, z_layers=None, layers_function=None, mesh_file_name_out='', factor_show=0, addLayerDepthAtBot=10000000000.0, periodicity=None)
fetch_ftp(file_name, data_dir=None)
This function downloads some data from the SLIM servers if available. The data is downloaded in the user global_data_directory. Data is only downloaded if it does not exist locally or is older than the server data. 
 
global_data_directory is by default ~/.cache/slim_data/
get_data_from_netcdf(nc_file_name, variable_name)
Return the array containing the values of the variable in the nectdf file (SLIM format)
 
keyword arguments:
 
* nc_file_name
    path to the netcdf file (.nc format)
* variable_name
    name of the variable in the netcdf file
get_distance(region, physical_tags, dmax=1000)
Return the minimum distance from each node on the region to the physical tags. The index of the 1-D array returned is the nodal index, same as Region.coordinates 
 
keyword arguments:
 
* region
    slimPre Region object of the nodes on which compute the distance
* physical_tags
    vector containing the physical tags from which the minimum distance will be computed
* dmax : float (default: 1000)
    points will be inserted on lines every dmax interval
interpolate_from_structured_file(nodes, structured_file, fill_value=-9999, transpose_matrix=False)
Interpolates the values from a structured file of gmsh type:
 
ox oy oz
 
dx dy dz
 
nx ny nz
 
val11 val12 ...
 
val21 val22 ...
 
...
 
This module is only available in 2D !
 
keyword arguments:
 
* nodes
    coordinates of the nodes to interpolate at (from Region or Coordinate_system)
* structured_file
    name of the file containing the structured data (binary files should end with '.bin' extension) 
* fill_value
    default value given to a point outside the structured grid
* transpose_matrix
    boolean assessing if the matrix should be transposed (Default: False) (True if nx is the number of lines and ny is the number of columns)
interpolate_from_structured_grid(x, y, ox, oy, dx, dy, data, fill_value=-9999.0)
Interpolates the values from a structured grid
 
keyword arguments:
 
* x
    list of the x-coordinates of all the points to interpolate at
* y
    list of the y-coordinates of all the points to interpolate at
* ox
    x-origin of the structured data
* oy
    y-origin of the structured data
* dx
    x-step of the structured data
* dy
    y-step of the structured data
* data
    structured grid
* fill_value
    default value given to a point outside the structured grid
make_directory(data_dir)
Create data_dir directory if it does not exist yet
mesh_shp(shp_inputs, lon, lat, mesh_size, mesh_size_min, output, projection='+latlong +ellps=WGS84', boundary_names={})
Generate a mesh file in gmsh .msh file format (http://gmsh.info/). The mesh is generated on a sphere of radius 1. The mesh size
should be specified on this sphere (i.e. distances should be divided by the earth radius)
 
arguments:
 
* shp_inputs : list of string
    vector of path to files in the ESRI shape file format. The shape files can be composed of point, lines or polygons. The projection
    used in the shape files should be longitude-latitude (in degrees).
* lon, lat : float
    position of one point inside the domain, the mesh region is the close surface containing this point.
* mesh_size : (float x, float y, float z) -> float
    callback to get the desired element size, (on a sphere of radius 1) at one point on this sphere
* mesh_size_min : float
    minimum value of the mesh size (approximatively the minimum value returned by mesh_size) on a sphere of radius 1
* output : string
    name of the output file
* projection : string
    description of the projection used in the output file in the libproj "+" format (the mesh itself is generated on the sphere)
* boundary_name : dictionary of (int, string)
    to assign physicals names to the boundary elements of the mesh, a field (of type integer64) called "entity" should be present in the shape files. Then this parameter can be used to map the values of this field to physical names
netcdf_to_msh(mesh_file_name, nc_file_name, variable_name, export_file_name, time=0)
Export a field in the netcdf format to msh format.
 
keyword arguments:
 
* mesh_file_name
    path to the mesh file (.msh format)
* nc_file_name    
    path to the netcdf file (.nc format)
* variable_name 
    name of the variable in the netcdf file
* export_file_name 
    path to the field name (.idx format)
* time  
    time at which the data will be exported in msh format (default: 0)
partition_id()
Return the number of the current partition as a string
partition_mesh(mesh_file_name, partitioned_mesh_file_name)
Partition the mesh 
 
keyword arguments:
 
* mesh_file_name            
        path to the mesh file (.msh format)
* partitioned_mesh_file_name
        name where the partitioned mesh is stored.
partition_nb()
Return the number of partitions used as a string
read_temporal_serie(file_name, time=None, output_netcdf=None)
Return a temporal serie from a text data file.
If time is given, the function returns a vector with the data interpolated
at the instants of time object.
If time is not given, the function returns a tuple (time, data), where
time is a Time object with the instants of the data file
data is a vector with the values of the data file
 
keyword arguments:
 
* file_name
    path to the file.
    Data must be given in the following format:
        1991-06-10 00:00:00, 20.7
        1991-06-11 00:00:00, 40.2
        1991-06-15 00:00:00, 13.8
    Different date must be strictly increasing but the time step
    does not have to be constant
* time
    time is a slimPre Time object.
    if time is given, data will be interpolated to the time instants.
* output_netcdf
    output_netcdf = ('netcdf_file_name', 'variable_name')
    if output_netcdf is given, the data are written in a netcdf file
residual_flow(region, flow, bathymetry, data_file_name=None)
Set a residual flow
 
It will return the velocity (u, v) such that speeds at all the nodes are constant and the velocity is normal to the boundary. The total transport (in m^3 s^-1) is equal to the given flow.
The physical tags of the region object must be boundary physical tags.
 
keyword arguments:
 
* region
    slimPre Region object on which put the data
* flow
    value of the flow crossing the region (must be a boundary region), in m^3 s^-1
* bathymetry
    bathymetry in netcdf format or msh format. It is necessary to compute the transport
* data_file_name
    name of the netcdf data file where the residual flow is exported (optional)
set_global_data_directory(path)
Edit the global_data_directory
smooth_bathymetry(mesh, bathymetry, output_file_name, coefficient=0.5, transform_p0=True)
Smooth the bathymetry in order to locally reduce the noise in the momentum
 
keyword arguments:
 
* mesh 
    slimPre mesh object
* bathymetry
    bathymetry file
    
    Format:
        * tuple containing the raw bathymetry data file (.nc format) and the name of the variable bathymetry 
        * bathymetry mesh file (.msh or .idx) 
* output_file_name
    name of the file name containing the smooth bathymetry. The format is netcdf (if transform_p0 = False) or idx (if transform_p0 = True).
* coefficient
    coefficient for the smoothing algorithm (default: 0.5). This forbids the bathymetry from moving from more than 100*coefficient % on a single element
* transform_p0
    flag to transform the bathymetry to a bathymetry constant per element. This gives a good stability and has negligible impact the results (default: True)
tpxo_tide(region, time, data_file_name=None, export_as_transport=True)
Give TPXO tides data
 
This function will download the files tpxo and generate the data at the requested time steps.
It will return the tpxo tides as variables (ssh, u, v) with u and v as transport (default) or velocity
 
keyword arguments:
 
* region
    slimPre Region object on which put the data
* time
    Time object of the instant at which put the data
* data_file_name
    name of the netcdf data file where tides are exported (optional)
* export_transport
    flag to specify whether exports are water transport [m^2/s] (True) or velocity [m/s] (False) (default: True)
write_file(file_name, region=None, time=None, data=[])
Create a SLIM netcdf file, standard input for SLIM simulations.
 
keyword arguments:
 
* file_name
    name of the netcdf file to write
* region
    slimPre Region object (optional).
* time
    slimPre Time object (optional).
* data
    data is a list of data tuples. Each tuple follows the form 
    
    ("data_name", data_array)
    
    where data_array is an array of n lines and m columns, n being the number of nodes in the region and m being the number of time steps in the time.