Cloning filter documenation (#2680)

* Add new `global` description for interfaces

* Add citation to HELICS paper

* Update link to Trevor's bio

* Add documentation on connector fed and translators

* ---
updated-dependencies:
- dependency-name: requests
  dependency-type: direct:production
...

Signed-off-by: dependabot[bot] <[email protected]>

* Add pulblications to "References" section of docs

* Update conf.py to load add-ons correctly

On Oct 7 2024, these changes will be needed to build the docs correctly.

https://about.readthedocs.com/blog/2024/07/addons-by-default/

https://docs.readthedocs.io/en/stable/addons.html#enabling-read-the-docs-addons

* Add documenation on async time request example

* Small clean-up in docs

* Correct JSON excerpt on endpoints

* Clarify the configuration of a clone filter

* Update Config Options Reference to correct clone filter

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update conf.py with new docs baseURL

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update docs/references/publications.md to remove duplicate citation

Co-authored-by: Ryan Mast <[email protected]>

* Update docs/user-guide/advanced_topics/connector_fed.md

Co-authored-by: Ryan Mast <[email protected]>

* Update docs/user-guide/examples/advanced_examples/advanced_async_time_request.md

Co-authored-by: Ryan Mast <[email protected]>

* Update docs/user-guide/examples/advanced_examples/advanced_async_time_request.md

Co-authored-by: Ryan Mast <[email protected]>

* Update docs/user-guide/examples/advanced_examples/advanced_async_time_request.md

Co-authored-by: Ryan Mast <[email protected]>

* Update docs/references/configuration_options_reference.md

Co-authored-by: Ryan Mast <[email protected]>

* Fix minor bug in conf.py

* Add documentation on helics_connector

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Clean up to-do for helics_connector docs

---------

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: Philip Top <[email protected]>
Co-authored-by: Ryan Mast <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

docs/conf.py

@@ -40,6 +40,16 @@
 
 current_directory = os.path.dirname(os.path.realpath(__file__))
 
+# Updating definitions so that add-ons load correctly. These changes will
+# be required by Oct 7, 2024
+# See https://about.readthedocs.com/blog/2024/07/addons-by-default/
+# Define the canonical URL if you are using a custom domain on Read the Docs
+html_context = {}
+html_baseurl = "docs.helics.org"
+# Tell Jinja2 templates the build is running on Read the Docs
+if os.environ.get("READTHEDOCS", "") == "True":
+    html_context["READTHEDOCS"] = True
+
 
 def download_helics_images():
     print("Downloading doc images from GMLC-TDC/helics_doc_resources")

docs/developer-guide/index.md

@@ -15,5 +15,4 @@
    ../Public_API
    ../ROADMAP
    typeConversions
-   Notes
 ```

docs/index.md

@@ -18,6 +18,7 @@ Brief History: HELICS began as the core software development of the Grid Moderni
 Motivation: Energy systems and their associated information and communication technology systems are becoming increasingly intertwined. As a result, effectively designing, analyzing, and implementing modern energy systems increasingly relies on advanced modeling that simultaneously captures both the cyber and physical domains in combined simulations. It is designed to increase scalability and portability in modeling advanced features of highly integrated power system and cyber-physical energy systems.
 
 General citation for HELICS:
+
 T. Hardy, B. Palmintier, P. Top, D. Krishnamurthy and J. Fuller, "HELICS: A Co-Simulation Framework for Scalable Multi-Domain Modeling and Analysis," in IEEE Access, doi: 10.1109/ACCESS.2024.3363615, available at [https://ieeexplore.ieee.org/document/10424422](https://ieeexplore.ieee.org/document/10424422)
 
 ```{eval-rst}

docs/references/apps/Connector.md

@@ -60,7 +60,7 @@ The match-file can also be JSON formatted.
 - Connections specified with no tags or "default" tag will match with everything as if the tag were not there. If a connection specified by a match in the match-file uses a tag, a connection will only be made if the specified tag is used by a federate, core, or broker.
 - A tag can be specified by a "global_value". The tag used for the connector is the name of the global or tag and the value can be anything other than a "false" value; if the tag is specified with a "false" value it is not used in the matching. Tags used in the match-file can also be specified in the value of the "tags" global or local tag. In this case they are specified with a comma separated list. The complete list of "false" valued strings is as follows:
 
-```txt
+```text
      "0",        "",         "false",
     "False",    "FALSE",    "off",
     "Off",      "OFF",      "disabled",

docs/references/configuration_options_reference.md

@@ -923,22 +923,11 @@ _API:_ `helicsFederateInfoSetFlagOption`
 | [Python](https://python.helics.org/api/capi-py/#helicsFederateInfoSetFlagOption)
 | [Julia](https://julia.helics.org/latest/api/#HELICS.helicsFederateInfoSetFlagOption-Tuple{HELICS.FederateInfo,%20Union{Int64,%20HELICS.Lib.HelicsFederateFlags},%20Bool})
 
+_Property's enumerated name:_ `HELICS_HANDLE_OPTION_CONNECTION_OPTIONAL` [402]
 _Property's enumerated name:_ `HELICS_HANDLE_OPTION_CONNECTION_OPTIONAL` [402]
 
 When an interface requests a target it tries to find a match in the federation. If it cannot find a match at the time the federation is initialized, then the default is to generate a warning. This will not halt the federation but will display a log message. If the `connections_optional` flag is set on a federate all subsequent `addTarget` calls on any interface will not generate any message if the target is not available.
 
-### `reconnectable` [false]
-
-_API:_ `helicsFederateInfoSetFlagOption`
-[C++](https://docs.helics.org/en/latest/doxygen/classhelics_1_1CoreFederateInfo.html#a63efa7762fdc8a9d9869bbed6939448e)
-| [C](api-reference/C_API.md#federateinfo)
-| [Python](https://python.helics.org/api/capi-py/#helicsFederateInfoSetFlagOption)
-| [Julia](https://julia.helics.org/latest/api/#HELICS.helicsFederateInfoSetFlagOption-Tuple{HELICS.FederateInfo,%20Union{Int64,%20HELICS.Lib.HelicsFederateFlags},%20Bool})
-
-_Property's enumerated name:_ `HELICS_HANDLE_OPTION_RECONNECTABLE` [412]
-
-When used to connect to reentrant federates, the reconnectable option can be used to allow automatic reconnection to specific interfaces. This should be used on the interface that is not reentrant.
-
 ---
 
 ### `default_global` [false]
@@ -1255,14 +1244,11 @@ The `info` field is entirely ignored by HELICS and is used as a mechanism to pas
 ## Filter Options
 
 Filters are registered with the core or through the application API.
-There are also Filter object that hide some of the API calls in a slightly nicer interface. Generally a filter will define a target endpoint as either a source filter or destination filter. Source filters can be chained, as in there can be more than one of them. At present there can only be a single non-cloning destination filter attached to an endpoint.
+There are also Filter object that hide some of the API calls in a slightly nicer interface. Generally a filter will be associated with a specific endpoint as either a source filter or destination filter. Source filters can be chained, as in there can be more than one of them. At present there can only be a single non-cloning destination filter attached to an endpoint.
 
-Non-cloning filters can modify the message in some ways, cloning filters just copy the message and may send it to multiple destinations.
+Non-cloning filters can modify the message in some ways, cloning filters just copy the message and may send it to multiple destinations. Cloning is not considered the "operation" of the filter and can be specified in parallel to another filter operation.
 
-On creation, filters have a target endpoint and an optional name.
-Custom filters may have input and output types associated with them.
-This is used for chaining and automatic ordering of filters.
-Filters do not have to be defined on the same core as the endpoint, and in fact can be anywhere in the federation, any messages will be automatically routed appropriately.
+On creation, filters have a target endpoint and an optional name. Custom filters may have input and output types associated with them; this is used for chaining and automatic ordering of filters. Filters do not have to be defined on the same core as the source or destination endpoint on which they act; they can be defined anywhere in the federation and all appropriate messages will be automatically routed through them appropriately.
 
 _API:_
 
@@ -1303,7 +1289,7 @@ _API:_ `helicsFilterAddSourceTarget`
 | [Python](https://python.helics.org/api/capi-py/#helicsFilterAddSourceTarget)
 | [Julia](https://julia.helics.org/latest/api/#HELICS.helicsFilterAddSourceTarget-Tuple{HELICS.Filter,%20String})
 
-Acts on previously registered filter and associated with a specific endpoint of the federate.
+Defines the endpoint sending messages that the filter should act on. All messages coming from the specified endpoint will run through the filter first before being sent on to their specified destination.
 
 ---
 
@@ -1317,7 +1303,7 @@ _API:_ `helicsFilterAddDestinationTarget`
 | [Python](https://python.helics.org/api/capi-py/#helicsFilterAddDestinationTarget)
 | [Julia](https://julia.helics.org/latest/api/#HELICS.helicsFilterAddDestinationTarget-Tuple{HELICS.Filter,%20String})
 
-Acts on previously registered filter and associated with a specific endpoint of the federate.
+Defines the endpoint receiving messages that the filter should act on. All messages going to the specified endpoint will run through the filter first.
 
 ---
 
@@ -1458,14 +1444,17 @@ This filter will randomly drop a message, the drop probability is specified, and
 
 #### `clone`
 
-This filter will copy a message and send it to the original destination plus a new one.
+Unlike other filters, cloning is not considered an "operation" and is enabled by setting the "clone" flag. (Prior to version 3.6, it was required to also define the filter "operation" to "clone".)
+
+The clone filter takes any message sent from endpoints listed in the `source_targets` object and sends a copy to endpoints in the `delivery` object. Note that both of these can be strings for a single endpoint or lists for multiple endpoints. In the example below, all messages originating from the endpoints named "source_endpoint_1_name" and "source_endpoint_2_name" will be copied and sent on to the endpoint named "ep_that_receives_cloned_messages".
 
 ```json
-   "operation": "clone",
-    "properties": {
-        "name": "add delivery",
-        "value": "endpoint name",
-    },
+   "clone": true,
+   "source_targets":[
+     "source_endpoint_1_name",
+     "source_endpoint_2_name"
+   ],
+   "delivery": "ep_that_receives_cloned_messages"
 ```
 
 ## Translator Options

docs/references/index.md

@@ -6,6 +6,7 @@ This section is most useful for those that are acting as integrators, getting a
 .. toctree::
    :maxdepth: 1
 
+   publications
    api-reference/index
    configuration_options_reference
    Tools_using_HELICS