Added documentation for high-level interace.

docs/manual/high_level_interface.md

@@ -0,0 +1,96 @@
+# MPTRAC High-Level Interface Documentation
+
+## Overview
+
+The MPTRAC Lagrangian transport model provides a high-level interface for simulating atmospheric transport processes. This interface, implemented through the `mptrac_*` functions in `mptrac.c` and `mptrac.h`, facilitates memory management, initialization, data input/output, and simulation execution.
+
+This document describes the core functions of the interface and demonstrates their usage with an example workflow.
+
+## Function Categories
+
+### 1. Memory Management
+
+- **`void mptrac_alloc(...)`**: Allocates memory for control, cache, climatology, meteorology, and atmospheric data structures on the CPU and GPU.
+
+- **`void mptrac_free(...)`**: Frees memory allocated for these structures.
+
+### 2. Initialization and Updates
+
+- **`void mptrac_init(...)`**: Initializes the MPTRAC model with control, cache, climatology, and atmospheric data. It adjusts the time range of the simulation and initializes the random number generator.
+
+- **`void mptrac_update_device(...)`**: Updates device memory with the latest data from CPU memory.
+
+- **`void mptrac_update_host(...)`**: Updates host memory from GPU memory.
+
+### 3. Data Input
+
+- **`void mptrac_read_ctl(...)`**: Reads control parameters from a file or the command line.
+
+- **`void mptrac_read_clim(...)`**: Reads various climatology data from data files.
+
+- **`int mptrac_read_met(...)`**: Reads meteorological data from a file.
+
+- **`int mptrac_read_atm(...)`**: Reads air parcel data from a file.
+
+### 4. Data Output
+
+- **`void mptrac_write_output(...)`**: Writes simulation results in various output types.
+
+- **`void mptrac_write_met(...)`**: Writes meteorological data to a file.
+
+- **`void mptrac_write_atm(...)`**: Writes air parcel data to a file.
+
+### 5. Simulation Execution
+
+- **`void mptrac_run_timestep(...)`**: Executes a single timestep of the Lagrangian transport model. Simulates various processes such as advection, diffusion, convection, chemistry, etc.
+
+### 6. Meteorological Data Handling
+
+- **`void mptrac_get_met(...)`**: Retrieves meteorological data for a specific time.
+
+## Example Workflow
+
+Below is an example of how to use the high-level MPTRAC interface in a typical simulation.
+
+### 1. Allocate Memory
+
+```
+mptrac_alloc(&ctl, &cache, &clim, &met0, &met1, &atm);
+```
+
+### 2. Initialize the Model
+
+```
+mptrac_read_ctl(filename, argc, argv, ctl);
+mptrac_read_clim(ctl, clim);
+mptrac_read_atm(filename, ctl, atm);
+mptrac_init(ctl, cache, clim, atm, ntask);
+```
+
+### 3. Run the Simulation
+
+Within the time loop of the model, repeatedly call:
+
+```
+mptrac_get_met(ctl, clim, t, &met0, &met1);
+mptrac_run_timestep(ctl, cache, clim, &met0, &met1, atm, t);
+mptrac_write_output(dirname, ctl, met0, met1, atm, t);
+```
+
+### 4. Free Memory
+
+```
+mptrac_free(ctl, cache, clim, met0, met1, atm);
+```
+
+## Notes
+
+- Error handling is essential when reading input data or allocating memory.
+
+- The example workflow shown here properly handles GPU offloading and data transfers between CPU and GPU memory. In other application, ensure proper synchronization between host and device memory when using GPUs.
+
+## References
+
+- [`mptrac.h`](https://github.com/slcs-jsc/mptrac/blob/master/src/mptrac.h): Header file with function declarations.
+
+- [`trac.c`](https://github.com/slcs-jsc/mptrac/blob/master/src/trac.c): Example implementation of the MPTRAC interface.

docs/mkdocs.yml

@@ -25,6 +25,7 @@ nav:
         - Model physics: model-physics.md
         - Tropopause data: tropopause-data.md
     - Developer manual:
+        - High-level interface: high_level_interface.md
         - Code development: code-development.md
         - Parallelization: parallelization.md
         - Profiling: profiling.md