The architecture of TopoToolbox 3 consists of three layers (Fig. ). The C library libtopotoolbox provides shared functionality to packages that provide a high-level user interface in MATLAB and Python. A language-specific binding layer (pybind11 and MEX) exchanges data between libtopotoolbox and the higher-level packages. Data input/output and visualization are the responsibility of libraries such as rasterio and the Mapping Toolbox in the higher-level language. The common core of libtopotoolbox ensures that essential computational routines are available across multiple languages. Relying on the same underlying library in different languages means that the results are reproducible regardless of the language used and reduces the sensitivity of TopoToolbox's results to changes in its dependencies.

The high-level interfaces to TopoToolbox 3 preserve the object-oriented approach developed for TopoToolbox 2 . Three major classes provide functionality: Grid objects represent DEMs and other gridded data sets. Flow objects represent the flow directions, and Stream represent a stream network as a subset of the DEM connected via the flow directions (Table ). These objects have different names in MATLAB and Python (GRIDobj/GridObject, FLOWobj/FlowObject, and STREAMobj/StreamObject) and the language-agnostic terms Grid, Flow and Stream are used here unless the specific implementation in MATLAB or Python is discussed. Much of the core functionality available in the MATLAB package for each of these three objects has been added to the Python package as well, but complete feature parity between the two interfaces has not yet been achieved. The MATLAB package also includes the additional classes of SWATHobj for extracting swaths of DEMs and DIVIDEobj for analyzing drainage divides , but these have not yet been ported to the Python package. The PPS object for analyzing point processes on stream networks is available experimentally in Python. The GraphFlood algorithm is currently accessible from the run_graphflood function in both Python and MATLAB, but the Python interface to the GraphFlood algorithm has been encapsulated in a GFObject class, which provides additional options that are not yet available in MATLAB.

libtopotoolbox implements a data-oriented approach in which its functions operate only on contiguous arrays of data supplied by the functions' caller. This avoids the complexity of managing object representations and ownership within the C library and enables libtopotoolbox to be used with any language that provides a foreign function interface to C and the ability to access contiguous arrays. Methods in the high-level language extract the necessary arrays from the Grid, Flow and Stream objects before passing them to libtopotoolbox, and they package the output arrays into objects to be returned to users. Some methods like Grid.fillsinks or Flow.flow_accumulation return raster datasets of the same shape and size as the input DEM, so these are returned as Grid objects that can be used in other TopoToolbox functions.

Other methods, especially those of Stream objects, return one-dimensional (1D) MATLAB or Numpy arrays. These are either node attribute lists with an element for every node in the stream network or edge attribute lists with an element for every edge between two nodes of the stream network. Quantities like the distance upstream from an outlet or χ are attached to nodes and thus returned as node attribute lists. Quantities like the distance between two nodes or the fraction of flow apportioned to two downstream neighbors by a multiple flow direction routing algorithm are attached to edges and returned as edge attribute lists. Stream objects maintain an additional mapping between the indices of its 1D node attribute lists and those of its parent Grid object, which can be used to extract information from Grid objects at the nodes of the stream network using the Stream.ezgetnal method.

The Flow and Stream objects represent flow networks with a topologically sorted edge list as in TopoToolbox 2 . This data structure stores the links between nodes in the flow network in an order such that all incoming edges to a node occur before any outgoing edges. The edge list consists of two arrays, each of which contains integers labeling the source and target of each edge in the flow network. Many network analysis algorithms can be implemented succinctly with one or more scans of the topologically sorted edge list, and the uniform representation of flow and stream networks as topologically sorted edge lists means they can share libtopotoolbox implementations for many of their functions. libtopotoolbox contains a set of functions that use flow algebras to compute various quantities of interest such as drainage area, downstream and upstream distance and χ.

libtopotoolbox functions are not typically called by users. Instead, methods on Grid, Flow and Stream objects initialize the necessary input and output arrays and pass them to libtopotoolbox through the binding layer. The binding layer marshals data between the high-level language and libtopotoolbox, converting the high-level language's data representations into the contiguous arrays of data needed by libtopotoolbox. TopoToolbox 3 uses MATLAB's MEX system and pybind11 for the Python bindings. Additional C or C++ source code within the MATLAB and Python packages implements these bindings.

libtopotoolbox currently focuses on in-memory processing of data to make as few assumptions as possible about where a user's data comes from. A DEM loaded into memory in MATLAB using the Mapping Toolbox or in Python using rasterio or created by a landscape evolution model can all be passed to libtopotoolbox functions. The user decides how and when to load their data into memory. This design does make it challenging to operate on DEMs too large to load entirely into memory. Existing solutions for processing large DEMs require control over the input and output of data tiles and communication across the boundaries of tiles e.g.. Implementing these algorithms in libtopotoolbox would require users to access their data through libtopotoolbox instead of the libraries they are already using, which is contrary to the design goal for libtopotoolbox to operate on as wide a variety of data sources as possible. Such solutions could, however, be implemented in TopoToolbox's higher-level packages using libraries like dask or MATLAB's Parallel Computing Toolbox to orchestrate I/O tasks and libtopotoolbox to perform computations on each tile. An alternative that is also being considered is to reimplement the libtopotoolbox interface using hardware acceleration frameworks such as the Parallel Computing Toolbox in MATLAB or Taichi Lang, PyTorch and TensorFlow in Python that provide access to resources like multiprocessors and GPUs. In this case, the high-level interface would remain the same, but users could switch between between the portable libtopotoolbox backend and high-performance backends as needed. Work is ongoing to leverage these libraries to provide an easy-to-use, high-performance interface for analyzing large datasets.

The manual testing performed for TopoToolbox 2 is not able to provide the level of quality assurance required to ensure that code behavior is preserved across languages, that interfaces between high-level languages and libtopotoolbox continue to work correctly after changes in one or both layers, and that the software works properly with external packages. An extensive automated testing system has been implemented for TopoToolbox 3. Each TopoToolbox package contains an automated test suite that runs using a language-specific testing framework. Pull requests submitted to the repository trigger runs of the test suite on GitHub Actions to verify the changes proposed in the pull request. The test suites are run on recent versions of Linux, Windows and macOS, and the Python and MATLAB package repositories run their test suites with the supported versions of Python (3.10 and newer) and MATLAB (R2023b and newer). All changes to TopoToolbox repositories are made through pull requests, and no changes are accepted unless the test suite passes.

A major challenge in testing scientific software is the oracle problem or the need to know the correct answer for a given input . While oracles can be constructed for small test cases and analytical solutions to many algorithms are available, we want to ensure that TopoToolbox gives correct results on real data, not just these hand-crafted data sets, which may not capture edge cases or unexpected features of real data. The TopoToolbox 3 test suites use the following techniques to create realistic test cases.

To demonstrate how the design of TopoToolbox 3 enables users to incorporate it into various geoscientific workflows, we present four examples. The first example demonstrates how functionality existing in the previous version TopoToolbox has been adapted to TopoToolbox 3 by presenting MATLAB and Python implementations of χ maps and evaluating the consistency of results obtained with the two packages. The second example illustrates how a testing strategy known as metamorphic testing was able to catch a subtle bug in libtopotoolbox. The third example presents GraphFlood , a recently developed hydrodynamic model that has been ported to TopoToolbox 3. Finally, the fourth example demonstrates a two-way coupling between TopoToolbox 3 and Landlab that uses TopoToolbox both to implement a process component of a landscape evolution model and to analyze the model's output. Code samples have been included for some of the examples, but they have been condensed for space. Complete Jupyter notebooks and MATLAB Live Scripts implementing these examples can be found on the online TopoToolbox gallery (https://topotoolbox.github.io/gallery, last access: 6 November 2026).

Figure  shows the pair of χ maps of the region generated in MATLAB (Fig. a) and Python (Fig. b).

The TopoToolbox workflow is essentially identical in Python and MATLAB, but the two languages and their TopoToolbox implementations are different and users will have to translate between the two when porting code from one language to another. For example, the two languages use different calling conventions for methods: the MATLAB example uses the functional style (klargestconncomps(s, 2)) with the object given by the first argument while Python uses dot syntax (s.klargestconncomps(2)). MATLAB can also use dot syntax for method calls, but most TopoToolbox documentation prefers the functional style. Python users must explicitly import TopoToolbox and associated libraries for plotting (matplotlib) and array computing (numpy). The names of objects and functions are also different in the two languages. TopoToolbox in MATLAB uses GRIDobj, FLOWobj and STREAMobj to refer to the three main objects that we have called Grid, Flow and Stream objects above. In Python these are called GridObject, FlowObject and StreamObject.

To illustrate the agreement between the two packages, we plot elevation vs. χ computed with each packages for the main trunks of the Rhine and Danube in Fig. . While the two packages provide qualitatively similar results in this case, the Python package underestimates χ relative to the MATLAB one. This discrepancy is due to differences in how the two packages transform rasters into the chosen coordinate system (Step 2 of Fig. ). While the GRIDobj.project function in MATLAB and the GridObject.reproject function in Python are called with the same coordinate reference system and horizontal resolution, the resulting DEMs are not identical. If this reprojection step is bypassed by first transforming the OpenTopography data externally into a projected coordinate system and then loading the projected data into both packages, the computed χ values are identical.

Metamorphic tests identified the problem addressed in pull request #186 when the two FlowObjects created from the same GridObjects in different memory layouts did not appear to be equivalent (Fig. a). While libtopotoolbox takes care to scan over 2D arrays in different directions depending on the memory layout of the underlying array, D8 flow routing also scans a neighborhood of each pixel to determine the direction of steepest descent. In case of ties, the first pixel with the steepest gradient encountered during the scan over the neighborhood is chosen. However, the neighborhood was scanned in a clockwise direction in column-major arrays and in a counterclockwise direction in row-major arrays, and ties were therefore encountered in different orders for row- and column-major arrays (Fig. c and d). This was fixed in pull request #186 by adding an “order” argument to the flow routing functions in libtopotoolbox. This should be 0 for column-major arrays and 1 for row-major arrays. When it is 1, it flips the direction in which the neighborhood is scanned so that the same pixels are chosen in case of ties (Fig. b).

The GraphFlood simulation of the Saison watershed (Fig. a) returns estimates of flood extent (Fig. b) and hydrodynamic parameters under the three precipitation scenarios. The patterns of width and shear stress illustrated by the swaths in Fig. c do not systematically covary, suggesting that the combination of the two provides more information than either alone. The variability in shear stress across the swath illustrates the value of 2D hydrodynamics in capturing signals beyond along-profile variations such as those that can be analyzed with the 1D methods provided by TopoToolbox's Stream objects.

TopoToolbox is now the main outlet for the ongoing development of GraphFlood, combining traditional topographic analysis with physics-based hydrodynamics at the basin scale. The core GraphFlood algorithm is implemented in libtopotoolbox and is exposed in both the Python and MATLAB packages. The Python implementation wraps this implementation in an object-oriented interface (GFObject) to make it easier to configure model runs and manage the input data and results. The GraphFlood methods in either package take Grid objects as input and return them as output so users can load their own data, configure and run the model and then analyze and visualize the results using other TopoToolbox functions. Developing GraphFlood within TopoToolbox allows even a complex numerical model like GraphFlood to be easily distributed to users who can seamlessly integrate it into their workflows.

Figure  shows the simulated elevations and the stream network with knickpoints identified by TopoToolbox at three timesteps of the Landlab simulation: just before the uplift rate is adjusted (Fig. a) and at 100 000 years (Fig. c) and 200 000 years after the uplift rate adjustment (Fig. e). The stream profiles and knickpoints are also visualized in χ plots (Fig. b, d, and f). As the balance of erosion against uplift approaches steady state (Fig. b), the stream profiles collapse towards one another in χ space. They do not collapse perfectly indicating that a steady state between erosion and uplift has not been fully reached by 2 million years, which is affected by the relatively high hillslope diffusion coefficient used here (0.05 m2yr-1). When the uplift rate is increased (Fig. d), knickpoints form, which cluster in χ space as expected, and they migrate upstream at the theoretical celerity of knickpoints in the stream power model .

The TopoToolbox flow router produces nearly identical results to the Landlab FlowAccumulator with a FlowDirectorD8 and DepressionFinderAndRouter. The differences between the two are due to differences in how each flow router resolves topographic sinks and computes flow directions over flat areas. These differences affect the early stages of the simulation before sinks in the random initial conditions are removed by the combined effects of uplift, erosion and diffusion, but small differences introduced early in the simulation grow into large differences at the end of the simulation. To minimize the impact of these effects on the final results, the random initial conditions are modified using TopoToolbox's imposemin function to carve a channel through the initial conditions with a small minimum slope (1×10-5). With minimum imposition on the initial conditions the mean absolute difference between the elevations simulated with the two different flow routers is 0.8 m at the end of the simulation. However, there can be differences in the simulated elevation of individual pixels on the order of 200 m as show in Fig. .

The entire simulation runs in 24.1 s using the TopoToolbox flow router and in 44.7 s using the Landlab FlowAccumulator with a FlowDirectorD8 and the DepressionFinderAndRouter (simulations were run on a Linux workstation with a 2.3 GHz Intel Core i7-11800H processor with 8 cores and 32 GB of RAM). The original example from the Landlab documentation does not use the DepressionFinderAndRouter , but it is included to make better comparisons with pytopotoolbox, which currently always resolves sinks when routing flow. The Landlab simulation is much faster without the DepressionFinderAndRouter (11.5 s). Work is ongoing in TopoToolbox to expose flow routing without sink resolution in pytopotoolbox, which should improve the speed of such simulations because sink resolution is the slowest part of TopoToolbox's flow routing algorithm. However, profiles collected using Python's profile module show (Table ) that converting TopoToolbox's topologically sorted edge list into the list of links required by Landlab (the set_links subroutine) takes around twice as much time to run as the flow routing itself (FlowObject.__init__).

The FAIR Principles for Research Software provide a set of best practices for research software development that guided the design of TopoToolbox 3. These principles state that research software should be findable, accessible, interoperable, reusable. The components of TopoToolbox 3 and accompanying metadata are findable through GitHub as well as the Zenodo archive. Zenodo provides a DOI that serves as a persistent identifier for each released version of the software. The software is accessible in source or precompiled forms from GitHub, and the Python package is registered in the Python Package Index, allowing users to install it with Python's standard packaging tools. Zenodo also allows users to download the source code of each repository as well as metadata. TopoToolbox 3 interoperates with other software by exchanging raster data through standard file formats, and it provides methods for exporting flow and stream networks to vector data files that can be interpreted by other software. TopoToolbox 3 also exchanges information directly between higher-level programming languages and libtopotoolbox by representing all necessary data as flat arrays, so they can be accessed through interfaces provided by Numpy and MATLAB. TopoToolbox 3 can be reused, modified and built upon because it is released as free software under the GNU Public License v3.0. Development is tracked in the Git version control system to establish the provenance of all artifacts incorporated into TopoToolbox 3. Packaging, distribution and dependency management are provided by standard mechanisms in each language, allowing users to install and use the package alongside other software.

Each function in TopoToolbox is documented in the source code with descriptions of its arguments and outputs and brief usage examples. This documentation is available to users on the new TopoToolbox website (https://topotoolbox.github.io, last access: 6 November 2026) and through the MATLAB Help Center. The Python and MATLAB packages also come with a guide to Getting Started with TopoToolbox. User-contributed examples are provided as executable Jupyter notebooks and MATLAB Live Scripts through the TopoToolbox gallery (https://topotoolbox.github.io/gallery, last access: 6 November 2026). Supplementing this official documentation is the long-running TopoToolbox blog (https://topotoolbox.wordpress.com, last access: 6 November 2026), which describes many more use cases and workflows.

TopoToolbox is developed openly on GitHub, and contributions to any of the TopoToolbox packages are accepted from the community. The TopoToolbox GitHub organization (https://github.com/TopoToolbox, last access: 6 November 2026) owns the official GitHub repositories for pytopotoolbox, topotoolbox3, libtopotoolbox and others, but any user can fork a TopoToolbox repository, make changes, and contribute them back through a pull request workflow described in the TopoToolbox Contribution Guidelines . Once a contributor makes a pull request, a TopoToolbox maintainer works with them to ensure that the pull request passes the automated test suite, that it successfully addresses any pertinent bug or issue reports, that it comes with sufficient tests and documentation to enable users and other contributors to make use of the code, and that it meets the stylistic guidelines of the repository, which are documented in each repository's contribution guidelines. There is currently no formal process to become a TopoToolbox maintainer who has permission to merge pull requests, and contributors who have made contributions to TopoToolbox repositories and who express a willingness to help new contributors through this process can be given this permission by existing maintainers.

The automated testing and publishing of software and metadata through continuous integration ensures that the FAIR Principles continue to hold as TopoToolbox is modified and extended. The remaining technical challenges facing the sustainability of TopoToolbox lie largely in improving and maintaining interoperability with other software. Passing flow network information to Landlab, for example, requires an expensive indexing operation every time the flow network is updated because TopoToolbox does not maintain within its data structures all of the information required by Landlab' StreamPowerEroder. Standardized representations of flow networks within the Earth surface processes community could make such integrations smoother and less dependent on the internal implementation details of each library.

The testing strategy outlined above serves three major roles in TopoToolbox 3. It characterizes the informally specified behavior of TopoToolbox 2 and ensures that TopoToolbox 3 does not unintentionally change that behavior. It confirms that new implementations of algorithms in libtopotoolbox and the interface between libtopotoolbox and other packages behave as expected and continue to behave that way as changes are made. Finally, it ensures the consistency of behavior across packages, so that an analysis done in Python will produce the same result as the same analysis done in MATLAB.

Testing helps to manage the complexity of the expanding TopoToolbox ecosystem. As TopoToolbox has grown to include new contributors adding code in multiple programming languages, it is increasingly challenging for any single developer to hold the entire system in their head. The tests instead serve as a shared repository of knowledge about the system, and automated testing and continuous integration ensures that the properties described by the tests continue to hold. Contributors can make changes knowing that they will not break other components without warning, and the tests they contribute specify how their components behave as further changes are made. We do not practice strict test-driven development where failing tests are added before implementing any new code. Instead, we let the tests coevolve with the code, enabling more flexible experimentation, especially when it is unclear how code should be tested or what properties need to be preserved. This does require careful code review when changing the tests to ensure that the safeguards provided by the tests continue to operate.

As TopoToolbox 3 has grown beyond MATLAB, we have encountered the problem of maintaining consistency across different computational platforms, the combinations of hardware, operating systems, programming languages, libraries and user code that make up a software application . Ideally, the results of an analysis conducted with TopoToolbox 3 would be the same regardless of whether a user conducted the analysis in MATLAB on a Windows PC or in Python on a Mac as the scientific validity of an analysis is undermined if its results depend on the platform used to run it. The χ maps example (Fig. ) show that, unfortunately, there can be significant differences between the results of analyses implemented on different platforms.

Both the Python and MATLAB versions of TopoToolbox depend on external libraries for some of their functionality. These dependencies can pose a risk to the future stability of both TopoToolbox and to the reproducibility of scientific results generated with TopoToolbox because the libraries may change their behavior. While this risk is clearly visible in the Python package, where its dependencies are open source packages developed by the community, it does also affect the MATLAB package. One of the major updates required to the MATLAB package during the transition to TopoToolbox 3 involved how georeferencing information is maintained in the GRIDobj, FLOWobj and STREAMobj, which was necessitated by changes in MATLAB's Mapping Toolbox.

In thinking about these risks, we can roughly categorize TopoToolbox's external dependencies into two categories: interface dependencies and computational dependencies. Interface dependencies load information into and export information from TopoToolbox. Libraries like rasterio and the Mapping Toolbox read and write data from storage, and visualization libraries like matplotlib are used to communicate the results of analyses. In principle, changes to interface dependencies should not change the results of an analysis, but only the process by which that analysis is obtained. If matplotlib ceased to exist, the plotting functionality of pytopotoolbox would no longer work, but alternative plotting libraries could still be used with the same GridObjects, FlowObjects and StreamObjects as before, or the data could be exported for visualization in another system. Computational dependencies perform components of the topographic analyses. Libraries like Python's numpy and scipy and MATLAB's Image Processing Toolbox are used primarily as computational dependencies. The reprojection functionality of rasterio and the Mapping Toolbox illustrates that libraries that primarily serve as interface dependencies can also be computational dependencies when they manipulate data while loading it. Changes to computational dependencies may change the results of an analysis, and upgrading these dependencies must be handled with care through extensive testing.

TopoToolbox 3 relies on the shared implementation of functions in libtopotoolbox and cross-platform testing, especially snapshot characterization tests and metamorphic testing as demonstrated in the array memory layout example, to minimize the dependency of its results on the underlying platforms. These two strategies guaranteed that the discrepancy in the MATLAB and Python outputs for the χ maps did not originate in the flow routing, flow accumulation or χ transform code, all of which is done in libtopotoolbox and tested across platforms. The only remaining computation in that example is the transformation of the OpenTopography data to a projected coordinate system. Bypassing reprojection by transforming the data in MATLAB and using that saved dataset directly in Python confirms that the discrepancy arises entirely in the functions GRIDobj.project and GridObject.reproject. These are implemented using raster transformation functions from the MATLAB Mapping Toolbox and rasterio, respectively. While we nominally apply the same settings in each case – bilinear resampling to a fixed 90 m resolution – it is clear that either the underlying implementations or the TopoToolbox interfaces to those implementations make additional assumptions that result in different answers.

The discrepancies observed in the Landlab example (Fig. ) are of a similar nature: both Landlab's FlowAccumulator with FlowDirectorD8 and the TT3FlowRouter implement D8 flow routing, but they make different choices in how they route flow through depressions and over flat regions. These algorithmic differences can add up to large maximum absolute differences in the simulated elevations (over 200 m) even if the mean absolute difference is quite small. However, these results were only obtained by modifying the initial conditions explicitly to minimize the impact of the different sink resolution algorithms, and the discrepancies are much larger when using completely random initial conditions.

TopoToolbox's automated test suites are tools for software development, not scientific investigation. They are verification tests, which check that the software faithfully implements its specifications, not validation tests, which check that the model implemented by the software faithfully represents the real world . The automated tests do not replace the essential scientific work of validating the algorithms implemented by TopoToolbox. Because the DEM is only an approximation of the real landscape , there will always be a limit to how well tests such as those we have illustrated here can validate the assumptions of the algorithms implemented in the software. We instead advocate careful comparison of the outputs of TopoToolbox to independent data sets and to the outputs of other software and models. Because TopoToolbox 3 can be integrated more tightly with other software, it is now much easier to make these comparisons as illustrated in the Landlab example above. Validating the theoretical behavior of knickpoint migration and comparing the output of the Landlab FlowAccumulator with that of the TopoToolbox TT3FlowRouter were both essential for correctly implementing the TT3FlowRouter. At the same time, the test cases contributed to TopoToolbox do not need to demonstrate scientific validity. An algorithm intended for large-scale DEM analysis might require large datasets and complicated analyses to validate it properly, tests which are hard to develop and costly to run. Property-based tests with small, randomly generated DEMs can verify that the implementation in TopoToolbox works as expected with a lower computational expense and a smaller software development and maintenance burden.

One of the strengths of TopoToolbox is providing a foundation upon which users can build their own tools for more specialized analyses. The architecture of TopoToolbox 3 opens new paths to extend the software. TopoToolbox 3 can still be used by exchanging raster or vector data files between it and other tools. Users who need only a small portion of the functionality of TopoToolbox, who would prefer to do the majority of their analysis in another tool such as a GIS, or who do not need tight, interactive coupling between TopoToolbox and their other tools may find this approach the easiest to get started with. In this case, the new Python interface can be valuable for this kind of analysis even if users are not relying on more sophisticated integration between TopoToolbox and other Python-based software.

The GraphFlood and Landlab applications described above demonstrate two other ways that TopoToolbox 3 can be extended. GraphFlood is implemented in libtopotoolbox, and interfaces in both the Python and MATLAB packages expose this functionality to users of either programming language. Implementing an extension in libtopotoolbox allows it to be used from both MATLAB and Python, but it does require implementing the tool in C, subject to constraints on external dependencies, dynamic memory management and data formats imposed by the design of libtopotoolbox.

Alternatively, extensions can be built in high-level languages using the core TopoToolbox functions alongside external dependencies. The Landlab integration, for example, is implemented purely in Python. It uses TopoToolbox functions to perform the necessary analyses and provides interface functions that convert data between the formats expected by Landlab and TopoToolbox as well as a class implementing the Landlab component interface. Packages have also been developed in this style in MATLAB, including ttminvoellmy, an interface to the MinVoellmy avalanche model , and BankfullMapper, a toolkit for semi-automatic bankfull geometry extraction and discharge estimation . Software developed in this way can use the standard dependency resolution mechanisms of their programming languages to depend on TopoToolbox. Users can maintain such extensions independently of the TopoToolbox organization if they desire. However, the TopoToolbox organization and its online documentation and discussion forums can publicize such extensions and illustrate how they can be used.