diff --git a/doc/sphinx/api_manual/API_FFI/Fortran_interface.md b/doc/sphinx/api_manual/API_FFI/Fortran_interface.md deleted file mode 100644 index cfc341b0b..000000000 --- a/doc/sphinx/api_manual/API_FFI/Fortran_interface.md +++ /dev/null @@ -1,7 +0,0 @@ -(part:API_manual:chap:API_FFI:sec:Fortran_interface)= -FORTRAN interface -=========== - -```{todo} -Explain how to use the Fortran interface in your program. Point to or show the example in the example directory. -``` \ No newline at end of file diff --git a/doc/sphinx/api_manual/API_FFI/Fortran_interface/CHIC_integration.md b/doc/sphinx/api_manual/API_FFI/Fortran_interface/CHIC_integration.md new file mode 100644 index 000000000..b227a9b63 --- /dev/null +++ b/doc/sphinx/api_manual/API_FFI/Fortran_interface/CHIC_integration.md @@ -0,0 +1,31 @@ +(part:API_manual:chap:API_FFI:sec:Fortran_interface:subsec:CHIC_integration)= +CHIC Integration +================= + +To illustrate how the World Builder interface can be used, the following section outlines what is done in CHIC: + +1. **Initialize the World Builder**: + + ```fortran + call create_world(cworld, 'path/to/world_file.wb', .false., '', 12345) + ``` + + - the path to the `.wb` file has to be passed as an input to CHIC + +2. **Query Temperature and Composition**: + - pass domain boundaries as input to CHIC (analogous to the `.grid` files used for the gwb-grid app {ref}`part:user_manual:chap:how_to_use_the_apps:sec:gwb-grid_app`) + - parse grid in given boundaries + - overwrite values of temperature and composition at each position: + + ```fortran + ! Query temperature at the given position + call temperature_3d(cworld, x, y, z, depth, temperature) + ! Query composition at the given position + call composition_3d(cworld, x, y, z, depth, composition_number, composition) + ``` + +3. **Release the World Builder**: + + ```fortran + call release_world(cworld) + ``` \ No newline at end of file diff --git a/doc/sphinx/api_manual/API_FFI/Fortran_interface/index.md b/doc/sphinx/api_manual/API_FFI/Fortran_interface/index.md new file mode 100644 index 000000000..4dd2e64e0 --- /dev/null +++ b/doc/sphinx/api_manual/API_FFI/Fortran_interface/index.md @@ -0,0 +1,72 @@ +(part:API_manual:chap:API_FFI:sec:Fortran_interface:subsec:Fortran_integration)= +FORTRAN interface +=========== + +The interface functions are defined in the Fortran wrapper module (`source/world_builder/wrapper_fortran.f90`). Here we provide short explanations for each function (subroutines in Fortran). + +```{important} +To start the World Builder and create a world from a given `.wb` file, the `create_world` subroutine always has to be called first. +``` + +```{code} +subroutine create_world(cworld, file_name, has_output_dir, output_dir, random_number_seed) + +Interface with the World Builder to create a world with a given `.wb` file + +Parameters: + cworld (C_PTR) - Variable that points to the world pointer of the world builder + file_name (C_CHAR) - Name of the `.wb` file to be used + has_output_dir (C_BOOL) - If true, the World Builder gains permission to write files into the given directory (`output_dir`). Currently, these are the World Builder json schema and declarations file. + output_dir (C_CHAR) - Path to directory where the files should be written into. + random_number_seed (C_LONG) - Random seed used in creating the world +``` + +After calling `create_world`, the world builder can be queried to output temperature and composition values at a given position. The subroutines for temperature and composition, each have a 2D and 3D variant. Each subroutine creates an interface with a c function of the world builder of the same name. + +```{code} +temperature_2d(cworld, x, z, depth, temperature) + +temperature_3d(cworld, x, y, z, depth, temperature) + +composition_2d(cworld, x, z, depth, composition_number, composition) + +composition_3d(cworld, x, y, z, depth, composition_number, composition) +``` + +Input arguments: + +1. `cworld` + - variable that points to the world created by `create_world` +2. `x, y, z, depth` + - coordinates where the user wants to query the world builder for a value + - `z` and `depth` need to be consistently given + - `y` is only used in the 3D variants +3. `composition_number` (only for composition) + - give the integer that matches a composition, as given in the used `.wb` file + - explanation on compositions outlined in {ref}`part:user_manual:chap:basic_starter_tutorial:sec:index` + +Output: + +- value (of temperature or composition) at the position specified with x, (y,) z, depth + +```{important} +When done with the World Builder, the `release_world` subroutine has to be called to clean up the memory used by the World Builder. +``` + +```{hint} +A short explanation of how the World Builder is integrated into the Mantle Convection code CHIC can be found on the next page {ref}`part:API_manual:chap:API_FFI:sec:Fortran_interface:subsec:CHIC_integration` +``` + +```{toctree} +:hidden: + +CHIC_integration +``` + + \ No newline at end of file diff --git a/doc/sphinx/api_manual/API_FFI/index.md b/doc/sphinx/api_manual/API_FFI/index.md index 409273b93..e49a4460b 100644 --- a/doc/sphinx/api_manual/API_FFI/index.md +++ b/doc/sphinx/api_manual/API_FFI/index.md @@ -12,6 +12,6 @@ Provide examples how to use the API in different programming languages. C_interface CPP_interface/index -Fortran_interface +Fortran_interface/index Python_interface ```