# MOSAIX
## SVN information
svn propset svn:keywords "Date Revision HeadURL Author Id" *.bash *.xml *.py src/MOSAIX/* Utils/*
$Author$
$Date$
$Revision$
$Id$
$HeadURL$
All documentation available at https://forge.ipsl.jussieu.fr/igcmg/wiki/IPSLCM6/MOSAIX
Extraction : `svn co http://forge.ipsl.jussieu.fr/igcmg/svn/TOOLS/MOSAIX MOSAIX`
or `svn co svn+ssh://omamce@forge.ipsl.jussieu.fr/ipsl/forge/projets/igcmg/svn/TOOLS/MOSAIX MOSAIX`
## [XIOS](http://forge.ipsl.jussieu.fr/ioserver/)
MOSAIC is known to work with XIOS2, revision 2379
XIOS : http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/trunk
Extraction : svn co http://forge.ipsl.jussieu.fr/ioserver/svn/XIOS/trunk XIOS
## Licensing
MOSAIX is under CeCILL\_V2 licence. See `Licence_CeCILL_V2-en.txt`file
for an english version of the licence and `Licence_CeCILL_V2-fr.txt`
for a french version.
Permission is hereby granted, free of charge, to any person or
organization obtaining a copy of the software and accompanying
documentation covered by this license (the "Software") to use,
reproduce, display, distribute, execute, and transmit the Software,
and to prepare derivative works of the Software, and to permit
third-parties to whom the Software is furnished to do so, all subject
to the following warning :
### Warning
Warning, to install, configure, run, use any of MOSAIX software or to
read the associated documentation you'll need at least one (1) brain
in a reasonably working order. Lack of this implement will void any
warranties (either express or implied). Authors assumes no
responsability for errors, omissions, data loss, or any other
consequences caused directly or indirectly by the usage of his
software by incorrectly or partially configured
## MOSAIX
MOSAIX is a small set of fortran routines, bash scripts, python
scripts and xml files allowing to generate coupling weights for the
IPSL Earth System Model. It is under development, and presently not
used by the production runs. It aims to replace the old MOSAIC
software. It uses XIOS as a library to compute weights. In the present
state, it can handle ORCA, LMDZ lon/lat and DYNAMICO grids.
MOSAIX can generate second order conservative interpolation
weights. They are used in place of bilinear interpolation by
[OASIS-MCT](https://portal.enes.org/oasis)
As MOSAIX uses XIOS, it works in parallel, using MPI distributed memory.
## Compatibility with MOSAIC
- Weights are not compatible with the weights generated by
MOSAIC. The precision of the interpolation (conservation) is
improved. The ocean mask interpolated on the atmosphere grid will
be slightly different, and not compatible.
- **Run-off** : runoff weights are computed with a different
algorithm, the result can be quite different.
- **Calving** : In IPSLCM6, the calving was integrated for each
latitude of the grid on the LMDZ grid. Weights were use to
aggregate several latitudes to compute an integral over a
latitudinal band. This is not possible with DYNAMICO, and was
abandon for rectilinear LMD grid. The atmosphere model must the
integral over a region (presently latitudinal bands). The final
result should be the same as with MOSAIC.
## Computer
MOSAIX been developped and extensively used on Irene Skylake computer,
using the Intel compilation tools. MOSAIX is supposed to work on any
computer where XIOS works.
It has been tested on Mac OS X, using `gcc` as a compiler. It is
fragile, as regularly XIOS updates break the compatibility.
## TODO
- Creates a non-masked grid for atmosphere, to compute integrals of run-off.
- Creates 2nd order interpolation weights that conserve
posivity. They won't be conservative.
- Test on other computers : Irene AMD, Jean-Zay, etc ...
## Known problems
- ?
## Future work
- Geographical distribution of the calving for the northern hemisphere.
## Code availability
- Web : [https://forge.ipsl.jussieu.fr/igcmg/browser/TOOLS/MOSAIX](https://forge.ipsl.jussieu.fr/igcmg/browser/TOOLS/MOSAIX)
- SVN : svn co http://forge.ipsl.jussieu.fr/igcmg/svn/TOOLS/MOSAIX MOSAIX
- SVN : svn co svn+ssh://@forge.ipsl.jussieu.fr/ipsl/forge/projets/igcmg/svn/TOOLS/MOSAIX MOSAIX
## Portability
MOSAIX has been tested on Curie and Irene ([TGCC](https://www-tgcc.ccc.cea.fr)).
## Requirements
- Fortran compiler, C++ compiler, MPI.
- A working [XIOS](http://forge.ipsl.jussieu.fr/ioserver)
library. Revision 1615 is known to work.
- fcm version 1.2
- NetCDF fortran librairies. See
[XIOS](http://forge.ipsl.jussieu.fr/ioserver) for a suitable version.
- Python, version>=3.6 with
[netCDF4](http://unidata.github.io/netcdf4-python/) and
[numpy](http://www.numpy.org) modules. Python version>=2.7 mights work, but has not been tested recently.
- Bash version>=4.
- [NCO](http://nco.sourceforge.net). Version 4.6.0 is known to work.
## Input files
MOSAIX needs files describing the grid of the models. See
`CreateWeightsMask.bash` and the bottom of this page.
## Output files
All netCDF files have a detailed header.
- Weight files `rmp_*`. Should have a rather explicit name. The name
is configurable at the beginning of `CreateWeightsMask.bash`.
- Diagnostic file used for debug `dia_*.nc` for each rmp file,
except for runoff and calving. Debug information are directly in
weight files in this last cases.
- Grid description file for OASIS-MCT `grids.nc`, `areas.nc` and
`masks.nc`.
- A file containing the fraction of ocean in each atmosphere grid
box. For instance `ICO40_grid_maskFrom_eORCA1.2.nc`.
- A `README` file. Includes a checksum for each generated files.
## Scripts and codes
* **CreateWeightsMask.bash**. Creates the weights to interpolate
between atmospheric and ocean grid. Weight files are suitable for
OASIS-MCT. Creates the fraction of ocean in atmospheric grid
cells. Uses parallel processing with MPI. Has a configuration
section at the beginning.
- **CreateOasisGrids.bash**. Creates files `grids.nc`, `areas.nc`
and `masks.nc` with information from both models, suitable for
OASIS-MCT. Mono CPU. Launched by `CreateWeights.bash`.
- **update_xml.py**. Python script used to perform on the fly
editing of xml files. Used by `CreateWeights.bash`. More
information with `python update_xml.py -h`.
- **iodef\_atm\_to_oce.xml** and **iodef\_oce\_to_atm.xml**. xml
files read by `interpol.f90`. These files are edited by
`update_xml.py`.
- **MOSAIX/src/MOSAIX/interpol.f90**. Fortran source using the XIOS
library.
- **make_mosaix**. Small script for compiling **interpol.f90**. You
need to compile XIOS first. Uses compiler, compiler options and
librairies defined by XIOS.
```bash
make_xios \[options\]
options :
\[--xios path\] : path to XIOS. Default is ../XIOS
\[--full\] : to regenerate dependencies and recompile from scratch
Example : ./make_mosaix --xios ../XIOS
```
- **RunoffWeights.py**. Python code to generates weights for
run-off. Launched by `CreateWeights.bash`. More information with
python `RunOffWeights.py -h`.
- Defines a coastal band on land in the atmosphere model. For LMDZ
rectilinear grids, the width of this band is parametrized, in grid
points. For ico grids, the band contains only point with a
fraction of ocean in \]0,1\[.
- Defines a coastal band on ocean in the ocean model. The width of
this band is parametrized.
- An atmosphere point of the coastal band is linked to an ocean
point in the coastal band if the distance between the two is less
than searchRadius.
- **CalvingWeights.py**. Python code to generates weights for
calving. Launched by `CreateWeights.bash`. More information with
python `CalvingWeights.py -h`.
- The atmosphere model integrate the calving over on specific
regions. Presently the regions are three latitudinal bands with
limits 90°S/40°S/50°N/90°N.
- The weights distribute the calving in the ocean in the
corresponding latitudinal bands. By default, the distribution is
uniform.
- For the southernmost band, it is possible to use a geographical
distribution read in a file. These files are currently available
for eORCA1 and eORCA025.
## Grids
- _\[tuv\]orc_. ORCA grid at _\[TUV\]_ points. Masked on land, with
area equal to grid box surface.
- _tlmd_. LMD rectilinear grid at scalar (physics) point. Masked on
land, with area equal to grid box surface.
- _tico_. LMD icosahedron grid at scalar (physics) point. Masked on
land, with area equal to grid box surface.
- _olmd_. LMD rectilinear grid at scalar (physics) point. Not
masked, with areas equal to 1.
- _oico_. LMD icosahedron grid at scalar (physics) point. Not
masked, with areas equal to 1.
- _corc_. ORCA grid at _T_ point. Masked on land, duplicated (from
periodicity) point masked, with area equal to grid box surface.
- _oorc_. ORCA grid at _T_ point. Masked on land, duplicated (from
periodicity) point masked, with area equal 1.
## Generating input grid files
**Generating icosahedral grid in double precision using XIOS:**
Here are the main changes:
- File `context_lmdz.xml` :
```xml
.....
.....
.....
.....
```
- File `field_def_lmdz.xml` :
```xml
...
```
- File `file_def_histmth_lmdz.xml` :
```xml
fract_oce + fract_sic
((fract_oce + fract_sic) > 0) ? 1 : 0
..........
```