Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create plugin documentation #565

Merged
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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.
```
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.

alarshi marked this conversation as resolved.
Show resolved Hide resolved
#### 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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same as above

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it, thank you !

#### 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`.

-----
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.
Original file line number Diff line number Diff line change
@@ -83,7 +83,7 @@ namespace WorldBuilder
double min_distance;
double side_distance;
std::vector<double> 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<double> side_fraction;
std::vector<unsigned int> compositions;
Operations operation;
2 changes: 1 addition & 1 deletion include/world_builder/utilities.h
Original file line number Diff line number Diff line change
@@ -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.
*