From 3b849f149ab15cc7db29fe3f4e1f0faea1468b85 Mon Sep 17 00:00:00 2001 From: Lars Hoffmann Date: Tue, 28 Jan 2025 19:55:52 +0100 Subject: [PATCH] Update mkdocs documentation. --- docs/manual/fortran_wrapper.md | 4 ++-- docs/manual/high_level_interface.md | 30 +++++++++++++++-------------- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/docs/manual/fortran_wrapper.md b/docs/manual/fortran_wrapper.md index 7e0949492..963b17aba 100644 --- a/docs/manual/fortran_wrapper.md +++ b/docs/manual/fortran_wrapper.md @@ -1,6 +1,6 @@ -# Fortran Wrapper +# Fortran wrapper -This project shows the integration of C functions in Fortran. The project started as [natESM sprint LAGOOn](https://www.nat-esm.de/services/support-through-sprints/documentation). +MPTRAC has been equiped with a wrapper to access the C functions from Fortran. The project started as coding sprint in [natESM project LAGOOn](https://www.nat-esm.de/services/support-through-sprints/documentation). To integrate multi language programming with Fortran and C in a single program the ISO_C_BINDINGS module is since Fortran 2003 the standard tool that facilitates interoperability between the two languages. In Fortran the Compiler is informed with the BIND(C) attribute that a symbol shall be interoperable with C. diff --git a/docs/manual/high_level_interface.md b/docs/manual/high_level_interface.md index 4d077dd5f..50a2963e0 100644 --- a/docs/manual/high_level_interface.md +++ b/docs/manual/high_level_interface.md @@ -1,12 +1,14 @@ -# MPTRAC High-Level Interface Documentation +# High-Level interface ## 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. +The MPTRAC Lagrangian transport model provides a high-level interface for simulating atmospheric transport processes. + +This high-level interface, implemented through the `mptrac_*` functions in [`mptrac.c`](https://github.com/slcs-jsc/mptrac/blob/master/src/mptrac.c) and [`mptrac.h`](https://github.com/slcs-jsc/mptrac/blob/master/src/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 +## Function categories ### 1. Memory Management @@ -14,7 +16,7 @@ This document describes the core functions of the interface and demonstrates the - **`void mptrac_free(...)`**: Frees memory allocated for these structures. -### 2. Initialization and Updates +### 2. Initialization and memory 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. @@ -22,7 +24,7 @@ This document describes the core functions of the interface and demonstrates the - **`void mptrac_update_host(...)`**: Updates host memory from GPU memory. -### 3. Data Input +### 3. Data input - **`void mptrac_read_ctl(...)`**: Reads control parameters from a file or the command line. @@ -32,7 +34,7 @@ This document describes the core functions of the interface and demonstrates the - **`int mptrac_read_atm(...)`**: Reads air parcel data from a file. -### 4. Data Output +### 4. Data output - **`void mptrac_write_output(...)`**: Writes simulation results in various output types. @@ -40,25 +42,25 @@ This document describes the core functions of the interface and demonstrates the - **`void mptrac_write_atm(...)`**: Writes air parcel data to a file. -### 5. Simulation Execution +### 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 +### 6. Meteorological data handling - **`void mptrac_get_met(...)`**: Retrieves meteorological data for a specific time. -## Example Workflow +## Example workflow -Below is an example of how to use the high-level MPTRAC interface in a typical simulation. +Below is an example of how to use the high-level MPTRAC interface in a typical simulation. Please see [`trac.c`](https://github.com/slcs-jsc/mptrac/blob/master/src/trac.c) for the full code. -### 1. Allocate Memory +### 1. Allocate memory ``` mptrac_alloc(&ctl, &cache, &clim, &met0, &met1, &atm); ``` -### 2. Initialize the Model +### 2. Initialize the model ``` mptrac_read_ctl(filename, argc, argv, ctl); @@ -67,7 +69,7 @@ mptrac_read_atm(filename, ctl, atm); mptrac_init(ctl, cache, clim, atm, ntask); ``` -### 3. Run the Simulation +### 3. Run the simulation Within the time loop of the model, repeatedly call: @@ -77,7 +79,7 @@ mptrac_run_timestep(ctl, cache, clim, &met0, &met1, atm, t); mptrac_write_output(dirname, ctl, met0, met1, atm, t); ``` -### 4. Free Memory +### 4. Free memory ``` mptrac_free(ctl, cache, clim, met0, met1, atm);