From 8fe04dc0026fce536cc86cb30c0e79e4b7091fa8 Mon Sep 17 00:00:00 2001 From: Arushi Saxena Date: Tue, 13 Feb 2024 21:58:59 -0500 Subject: [PATCH 1/4] Add documentation. --- .../creating_new_plugins.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/doc/sphinx/developer_manual/developing_for_the_GWB/creating_new_plugins.md b/doc/sphinx/developer_manual/developing_for_the_GWB/creating_new_plugins.md index 458aab2d7..b08dde930 100644 --- a/doc/sphinx/developer_manual/developing_for_the_GWB/creating_new_plugins.md +++ b/doc/sphinx/developer_manual/developing_for_the_GWB/creating_new_plugins.md @@ -2,6 +2,17 @@ Creating new plugins ==================== -```{todo} -Explain how to create a new plugin. If possible find one which already nearly does what you want and copy and change it, but also explain how to build one from sratch. -``` \ No newline at end of file +It is possible that the user wants to implement a different distribution of properties (temperature or composition) than the ones available in the GWB. This can be achieved by creating a new plugin with the steps outlined subsequently. We will discuss two ways to write a plugin: one is to base it on an existing plugin, and another is to write the plugin from scratch. + +#### Modify an existing plugin + +Identify an existing implementation that nearly does what you want and copy the contents into another file, say `myplugin.cc`, in the same directory. It is also recommended that you make a copy of the corresponding header file into `myplugin.h`. This allows other plugins to use the declarations in `myplugin`. + +As an example, assume that you want to implement faults in your world that have compositional value that varies according to a hat function. In this case, the closest existing functionality is the `smooth` fault composition that varies following a hyperbolic tangent function. You can then modify the implementation of the relevant function, i.e., `get_composition()`, such that it now returns a compositional value based on the hat function. + +#### Write a plugin from scratch + +Create your plugin file that contains the declarations and implementations of all the members of your class, which must be derived from the relevant `Interface` class. For example, if you are creating a new temperature computation for a `continental_plate_model`, then you would include the function declarations of `features/continental_plate_models/fault_models/interface.h`. This implies that you need to have the functions `declare_entries`, `parse_enteries`, and `get_temperature` and their defintions for your plugin. Similar to above, it is recommended that you split the function declarations into a header file, say `myplugin.h`. + +----- +Register the plugin at the bottom of `myplugin.cc` in `WB_REGISTER_*` that instantiates the plugin, documents it, and makes it available to the parameter file handlers. Finally, compile the plugin, using `cmake .` and then `make` in the top directory. From 912b0a850fd839395c2da1ebdb38d21e7ef268f1 Mon Sep 17 00:00:00 2001 From: Arushi Saxena Date: Tue, 13 Feb 2024 21:59:13 -0500 Subject: [PATCH 2/4] fix typos. --- .../world_builder/features/fault_models/composition/smooth.h | 2 +- include/world_builder/utilities.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/include/world_builder/features/fault_models/composition/smooth.h b/include/world_builder/features/fault_models/composition/smooth.h index f61b2c4d4..d741007d8 100644 --- a/include/world_builder/features/fault_models/composition/smooth.h +++ b/include/world_builder/features/fault_models/composition/smooth.h @@ -83,7 +83,7 @@ namespace WorldBuilder double min_distance; double side_distance; std::vector center_fraction; - // currently not using the side composition, but maybe usefu if you want another composition towards the end + // currently not using the side composition, but maybe useful if you want another composition towards the end std::vector side_fraction; std::vector compositions; Operations operation; diff --git a/include/world_builder/utilities.h b/include/world_builder/utilities.h index a20019ae7..ff7ae6082 100644 --- a/include/world_builder/utilities.h +++ b/include/world_builder/utilities.h @@ -261,7 +261,7 @@ namespace WorldBuilder * meshed by a grid. The axis parallel to the surface are formed by * sections, and the axis perpendicuar to the surface are formed segments. * Both sections and elements represent a whole cell in the grid, which is - * an inteter. This structure also provides the fraction in each direction + * an integer. This structure also provides the fraction in each direction * the closest point on the plane is along these two axes (sections and * segments). These variables are called fractions. * From 1cb350b6060e7d1775ab7c7f6cf15cc9eb390d34 Mon Sep 17 00:00:00 2001 From: Arushi Saxena Date: Tue, 13 Feb 2024 23:09:55 -0500 Subject: [PATCH 3/4] Address comments from the PR. --- .../developing_for_the_GWB/creating_new_plugins.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/sphinx/developer_manual/developing_for_the_GWB/creating_new_plugins.md b/doc/sphinx/developer_manual/developing_for_the_GWB/creating_new_plugins.md index b08dde930..cbc039268 100644 --- a/doc/sphinx/developer_manual/developing_for_the_GWB/creating_new_plugins.md +++ b/doc/sphinx/developer_manual/developing_for_the_GWB/creating_new_plugins.md @@ -6,13 +6,13 @@ It is possible that the user wants to implement a different distribution of prop #### Modify an existing plugin -Identify an existing implementation that nearly does what you want and copy the contents into another file, say `myplugin.cc`, in the same directory. It is also recommended that you make a copy of the corresponding header file into `myplugin.h`. This allows other plugins to use the declarations in `myplugin`. +Identify an existing implementation that nearly does what you want and copy the contents into another file, say `myplugin.cc`, in the same directory. It is also recommended that you make a copy of the corresponding header file into `myplugin.h`. This allows other plugins to use the declarations in `myplugin`. Then, rename the class in both the header and the source files to `Myplugin` (the class names are written in the Camel case by GWB convention) and modify the header guard accordingly. -As an example, assume that you want to implement faults in your world that have compositional value that varies according to a hat function. In this case, the closest existing functionality is the `smooth` fault composition that varies following a hyperbolic tangent function. You can then modify the implementation of the relevant function, i.e., `get_composition()`, such that it now returns a compositional value based on the hat function. +As an example, assume that you want to implement faults in your world that have compositional value that varies according to a hat function. In this case, the closest existing functionality is the `smooth` fault composition that varies following a hyperbolic tangent function. You can then rename the class to say Hat and modify the implementation of the relevant function, i.e., `get_composition()`, such that it now returns a compositional value based on the hat function. #### Write a plugin from scratch -Create your plugin file that contains the declarations and implementations of all the members of your class, which must be derived from the relevant `Interface` class. For example, if you are creating a new temperature computation for a `continental_plate_model`, then you would include the function declarations of `features/continental_plate_models/fault_models/interface.h`. This implies that you need to have the functions `declare_entries`, `parse_enteries`, and `get_temperature` and their defintions for your plugin. Similar to above, it is recommended that you split the function declarations into a header file, say `myplugin.h`. +Create your plugin file that contains the declarations and implementations of all the members of your class, which must be derived from the relevant `Interface` class. For example, if you are creating a new temperature computation for a `continental_plate_model`, then you would include the function declarations of `features/continental_plate_models/fault_models/interface.h`. This implies that you need to have the functions `declare_entries`, `parse_enteries`, and `get_temperature` and their definitions for your plugin. Similar to above, it is recommended that you split the function declarations into a header file, say `myplugin.h`. ----- -Register the plugin at the bottom of `myplugin.cc` in `WB_REGISTER_*` that instantiates the plugin, documents it, and makes it available to the parameter file handlers. Finally, compile the plugin, using `cmake .` and then `make` in the top directory. +Register the plugin at the bottom of `myplugin.cc` in `WB_REGISTER_*` that instantiates the plugin, documents it, and makes it available to the parameter file handlers. You can do this by using `WB_REGISTER_*`(name of the class, name of the plugin used in the input file). Finally, compile the plugin, using `cmake .` and then `make` in the build directory. From cd90f6b3cbab8dcc4ccc1c5225ca8bd6c5c659e9 Mon Sep 17 00:00:00 2001 From: Arushi Saxena Date: Wed, 14 Feb 2024 11:44:40 -0500 Subject: [PATCH 4/4] fix heading level. --- .../developing_for_the_GWB/creating_new_plugins.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/sphinx/developer_manual/developing_for_the_GWB/creating_new_plugins.md b/doc/sphinx/developer_manual/developing_for_the_GWB/creating_new_plugins.md index cbc039268..856c7dc13 100644 --- a/doc/sphinx/developer_manual/developing_for_the_GWB/creating_new_plugins.md +++ b/doc/sphinx/developer_manual/developing_for_the_GWB/creating_new_plugins.md @@ -4,13 +4,13 @@ Creating new plugins It is possible that the user wants to implement a different distribution of properties (temperature or composition) than the ones available in the GWB. This can be achieved by creating a new plugin with the steps outlined subsequently. We will discuss two ways to write a plugin: one is to base it on an existing plugin, and another is to write the plugin from scratch. -#### Modify an existing plugin +## Modify an existing plugin Identify an existing implementation that nearly does what you want and copy the contents into another file, say `myplugin.cc`, in the same directory. It is also recommended that you make a copy of the corresponding header file into `myplugin.h`. This allows other plugins to use the declarations in `myplugin`. Then, rename the class in both the header and the source files to `Myplugin` (the class names are written in the Camel case by GWB convention) and modify the header guard accordingly. As an example, assume that you want to implement faults in your world that have compositional value that varies according to a hat function. In this case, the closest existing functionality is the `smooth` fault composition that varies following a hyperbolic tangent function. You can then rename the class to say Hat and modify the implementation of the relevant function, i.e., `get_composition()`, such that it now returns a compositional value based on the hat function. -#### Write a plugin from scratch +## Write a plugin from scratch Create your plugin file that contains the declarations and implementations of all the members of your class, which must be derived from the relevant `Interface` class. For example, if you are creating a new temperature computation for a `continental_plate_model`, then you would include the function declarations of `features/continental_plate_models/fault_models/interface.h`. This implies that you need to have the functions `declare_entries`, `parse_enteries`, and `get_temperature` and their definitions for your plugin. Similar to above, it is recommended that you split the function declarations into a header file, say `myplugin.h`.