README.md

# Fortran to Python OASIS conversion <!-- omit in toc -->

This repository serves as an example on the conversion of OASIS components from Fortran to Python (using [pyOASIS](https://gitlab.com/cerfacs/oasis3-mct/-/tree/master/pyOASIS)). More precisely, this "toy model" is taken from the `spoc/spoc_communication` example from the [OASIS3-MCT4.0 branch](https://gitlab.com/cerfacs/oasis3-mct/-/tree/OASIS3-MCT_4.0/examples/spoc/spoc_communication). This toy model consists of two components (ocean and atmos) and implements basic coupling exchanges between them.

A description of the most common differences found while performing the conversion can be found in the following issues: #1 #2.

For more info about the performance differences between pyOASIS and OASIS, please take a look at the [performance branch](https://earth.bsc.es/gitlab/rmarti1/oasis-toy-model-python/-/tree/performance) of this repository.

## Table of contents <!-- omit in toc -->
- [Running the example](#running-the-example)
  - [Requirements](#requirements)
  - [Compile](#compile)
  - [Run](#run)
- [Running the tests](#running-the-tests)


### Running the example
#### Requirements
This documentation assumes you are running an UNIX-based OS with Python3 in the PATH, understand the basics of OASIS and are able to compile and run pyOASIS.

#### Compile
In the root folder of this repository there is a [Makefile](./Makefile) which serves as a root makefile for both the Fortran and Python examples. Each of the example codes is located in its respect folder ([`fortran/`](./fortran/) and [`python/`](./python/)) with its specific Makefile.

By executing the following command in the root folder of this repository, you will compile OASIS, pyOASIS and the Fortran implementation of this model.
```bash
make
```

If this is the first time you are compiling pyOASIS, you must issue the following command.
```bash
source oasis3-mct/../compile_oa3-mct/python/init.sh
```
```bash
source oasis3-mct/../compile_oa3-mct/python/init.csh
```
Alternatively, these lines could be added to your `~/.bashrc` or `~/.cshrc` file.

**IMPORTANT NOTICE**: These Makefiles depend on a file named `make.inc`, provided in the OASIS3-MCT repository, and assume its location is `../../../util/make_dir/make.inc`. Feel free to make the necessary changes to these files in order to make it work in your setup.

#### Run
In order to run the example code with your desired programming language you must execute the script `run_example.sh`. Here is an example on how to run the example with ocean running in Fortran and atmos running in Python, each of them with 4 MPI processes.
```bash
bash ./run_example.sh fortran python 4 4
```

Here is the complete specification for the script:
```bash
./run_example.sh <ocean_lang> <atmos_lang> <ocean_nproc> <atmos_nproc>
```

Running this script will create a new folder in the root folder of this repository called `work_<ocean_lang>_<atmos_lang>_<ocean_nproc>_<atmos_nproc>` with all the output and debug information from the run.

### Running the tests
Execute the following command in the root folder of this repository to run all tests (make sure to meet all the [requirements](#requirements) stated above).

```bash
bash run_tests.sh
```

This command will run all combinations (Fortran-Fortran, Python-Fortran, Fortran-Python and Python-Python) of the components and check if all of them result in the same output. Here is an example of a successfull test run:
```
Checking results...
atmos PASSED
ocean PASSED
```