diff --git a/docs/conf.py b/docs/conf.py index 29680fc38c..f80cb1f241 100755 --- a/docs/conf.py +++ b/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") diff --git a/docs/developer-guide/index.md b/docs/developer-guide/index.md index 2daf3f6e61..d8534c7f22 100644 --- a/docs/developer-guide/index.md +++ b/docs/developer-guide/index.md @@ -15,5 +15,4 @@ ../Public_API ../ROADMAP typeConversions - Notes ``` diff --git a/docs/index.md b/docs/index.md index 2d147ca12e..7efa4e5ddd 100644 --- a/docs/index.md +++ b/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} diff --git a/docs/references/apps/Connector.md b/docs/references/apps/Connector.md index 9cf36cb741..363d362cc3 100644 --- a/docs/references/apps/Connector.md +++ b/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", diff --git a/docs/references/configuration_options_reference.md b/docs/references/configuration_options_reference.md index c170932e88..b8e3627e0b 100644 --- a/docs/references/configuration_options_reference.md +++ b/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 diff --git a/docs/references/index.md b/docs/references/index.md index 90e17d8d6d..28e5d0cf2d 100644 --- a/docs/references/index.md +++ b/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 diff --git a/docs/references/publications.md b/docs/references/publications.md new file mode 100644 index 0000000000..de7bf1615e --- /dev/null +++ b/docs/references/publications.md @@ -0,0 +1,76 @@ +# HELICS Publications + +## Citing 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) + +## Co-Simulation Architecture and Theory with HELICS + +B. Palmintier, D. Krishnamurthy, P. Top, S. Smith, J. Daily and J. Fuller, "Design of the HELICS high-performance transmission-distribution-communication-market co-simulation framework", Proc. Workshop Model. Simul. Cyber-Physical Energy Syst. (MSCPES), pp. 1-6, Apr. 2017, available at: [https://ieeexplore.ieee.org/document/8064542/](https://ieeexplore.ieee.org/document/8064542/). + +Juan Gilberto Rueda Vasquez. COMPARISON BETWEEN TWO CO-SIMULATION FRAMEWORKS, MOSAIK AND HELICS. Rel. Lorenzo Bottaccioli, Edoardo Patti, Claudia De Vizia. Politecnico di Torino, Corso di laurea magistrale in Ict For Smart Societies (Ict Per La Società Del Futuro), 2022, available at [https://webthesis.biblio.polito.it/25624/](https://webthesis.biblio.polito.it/25624/) + +P. Palensky, P. Mancarella, T. Hardy and M. Cvetkovic, "Cosimulating Integrated Energy Systems With Heterogeneous Digital Twins: Matching a Connected World," in IEEE Power and Energy Magazine, vol. 22, no. 1, pp. 52-60, Jan.-Feb. 2024, doi: 10.1109/MPE.2023.3324886, available at [https://ieeexplore.ieee.org/document/10398554](https://ieeexplore.ieee.org/document/10398554). + +Barbierato, L., Rando Mazzarino, P., Montarolo, M. et al. A comparison study of co-simulation frameworks for multi-energy systems: the scalability problem. Energy Inform 5 (Suppl 4), 53 (2022). doi: 10.1186/s42162-022-00231-6, available at [https://energyinformatics.springeropen.com/articles/10.1186/s42162-022-00231-6](https://energyinformatics.springeropen.com/articles/10.1186/s42162-022-00231-6). + +A. Latif, B. Palmintier, F. Nejabatkhah and P. Jacques, "Multi-federate co-convergence with HELICS," 2024 IEEE Power & Energy Society Innovative Smart Grid Technologies Conference (ISGT), Washington, DC, USA, 2024, pp. 1-5, doi: 10.1109/ISGT59692.2024.10454238, available at [https://ieeexplore.ieee.org/document/10454238](https://ieeexplore.ieee.org/document/10454238) + +## HELICS Application papers + +The following are a list of some of the published work using HELICS. If you have published work using HELICS you would like to see on this list, email support@helics.org with the citation and we'll review it. + +J. R. Theisen, A. Bose, M. Mukherjee, D. Burgess, K. Wilhelm and M. Diedesch, "Community-Based Transactive Coordination Mechanism for Enabling Grid-Edge Systems," 2024 IEEE Texas Power and Energy Conference (TPEC), College Station, TX, USA, 2024, pp. 1-6, doi: 10.1109/TPEC60005.2024.10472237, available at [https://ieeexplore.ieee.org/document/10472237](https://ieeexplore.ieee.org/document/10472237). + +A. K. Bharati, V. Ajjarapu, W. Du and Y. Liu, "Role of Distributed Inverter-Based-Resources in Bulk Grid Primary Frequency Response Through HELICS Based SMTD Co-Simulation," in IEEE Systems Journal, vol. 17, no. 1, pp. 1071-1082, March 2023, doi: 10.1109/JSYST.2022.3218117 available at [https://ieeexplore.ieee.org/document/9966492](https://ieeexplore.ieee.org/document/9966492). + +Y. Liu, R. Huang, W. Du, A. Singhal and Z. Huang, "Highly-Scalable Transmission and Distribution Dynamic Co-Simulation With 10,000+ Grid-Following and Grid-Forming Inverters," in IEEE Transactions on Power Delivery, vol. 39, no. 1, pp. 578-590, Feb. 2024, doi: 10.1109/TPWRD.2023.3302303, available at [https://ieeexplore.ieee.org/abstract/document/10210125](https://ieeexplore.ieee.org/abstract/document/10210125). + +Panossian, N.V.; Laarabi, H.; Moffat, K.; Chang, H.; Palmintier, B.; Meintz, A.; Lipman, T.E.; Waraich, R.A. Architecture for Co-Simulation of Transportation and Distribution Systems with Electric Vehicle Charging at Scale in the San Francisco Bay Area. Energies 2023, 16, 2189. doi: 10.3390/en16052189, available at [https://www.mdpi.com/1996-1073/16/5/2189](https://www.mdpi.com/1996-1073/16/5/2189). + +T. Phillips, L. D. Marinovici, C. Rieger and A. Orrell, "Scalable Resilience Analysis Through Power Systems Co-Simulation," in IEEE Access, vol. 11, pp. 18205-18214, 2023, doi: 10.1109/ACCESS.2023.3246486, available at [https://ieeexplore.ieee.org/document/10050105](https://ieeexplore.ieee.org/document/10050105). + +William Lardier, "ASGARDS-H: Enabling Advanced Smart Grid cyber-physical Attacks, Risk and Data Studies with HELICS". Masters thesis at Concordia University, 2020, available at [https://spectrum.library.concordia.ca/id/eprint/987690/](https://spectrum.library.concordia.ca/id/eprint/987690/). + +Y. Liu, R. Huang, W. Du, A. Singhal and Z. Huang, "High-Performance Transmission and Distribution Co-simulation with 10,000+ Inverter-Based Resources," 2022 IEEE Industry Applications Society Annual Meeting (IAS), Detroit, MI, USA, 2022, pp. 1-5, doi: 10.1109/IAS54023.2022.9940149, available at [https://ieeexplore.ieee.org/document/9940149](https://ieeexplore.ieee.org/document/9940149). + +Narayanan, Anantha, and Hardy, Trevor. "Synthetic Data Generation for Machine Learning Model Training for Energy Theft Scenarios Ssing Cosimulation". United Kingdom: N. p., 2022. Web. doi:10.1049/gtd2.12619, available at [https://ietresearch.onlinelibrary.wiley.com/doi/10.1049/gtd2.12619](https://ietresearch.onlinelibrary.wiley.com/doi/10.1049/gtd2.12619). + +Jing Wang, Prateek Munankarmi, Jeff Maguire, Chengnan Shi, Wangda Zuo, David Roberts, Xin Jin. "Carbon emission responsive building control: A case study with an all-electric residential community in a cold climate". Applied Energy, Volume 314,2022, 118910, +doi: 10.1016/j.apenergy.2022.118910, available at (https://www.sciencedirect.com/science/article/pii/S0306261922003336)[https://www.sciencedirect.com/science/article/pii/S0306261922003336]. + +A. Singhal, T. L. Vu and W. Du, "Consensus Control for Coordinating Grid-Forming and Grid-Following Inverters in Microgrids," in IEEE Transactions on Smart Grid, vol. 13, no. 5, pp. 4123-4133, Sept. 2022, doi: 10.1109/TSG.2022.3158254, available at [https://ieeexplore.ieee.org/document/9732444](https://ieeexplore.ieee.org/document/9732444). + +N. Gray, R. Sadnan, A. Bose and A. Dubey, "Effects of Communication Network Topology on Distributed Optimal Power Flow for Radial Distribution Networks," 2021 North American Power Symposium (NAPS), College Station, TX, USA, 2021, pp. 1-6, doi: 10.1109/NAPS52732.2021.9654692, available at [https://ieeexplore.ieee.org/document/9654692](https://ieeexplore.ieee.org/document/9654692). + +A. O. Abbas and B. H. Chowdhury, "A Stochastic Optimization Framework for Realizing Combined Value Streams From Customer-Side Resources," in IEEE Transactions on Smart Grid, vol. 13, no. 2, pp. 1139-1150, March 2022, doi: 10.1109/TSG.2021.3135155, available at [https://ieeexplore.ieee.org/document/9650528](https://ieeexplore.ieee.org/document/9650528). + +J. Wang, J. Simpson, R. Yang, B. Palmintier, S. Tiwari and Y. Zhang, "Performance Evaluation of an Advanced Distributed Energy Resource Management Algorithm," 2021 IEEE International Conference on Communications, Control, and Computing Technologies for Smart Grids (SmartGridComm), Aachen, Germany, 2021, pp. 378-384, doi: 10.1109/SmartGridComm51999.2021.9632298, available at [https://ieeexplore.ieee.org/document/9632298](https://ieeexplore.ieee.org/document/9632298). + +H. M. Mustafa et al., "Cyber-Power Co-Simulation for End-to-End Synchrophasor Network Analysis and Applications," 2021 IEEE International Conference on Communications, Control, and Computing Technologies for Smart Grids (SmartGridComm), Aachen, Germany, 2021, pp. 164-169, doi: 10.1109/SmartGridComm51999.2021.9632286, available at [https://ieeexplore.ieee.org/document/9632286](https://ieeexplore.ieee.org/document/9632286). + +Tuffner, Francis K., Undrill, John, Scoffield, Don, Eto, Joseph H., Kosterev, Dmitry, and Quint, Ryan D. 2021. "Distribution-Level Impacts of Plug-in Electric Vehicle Charging on the Transmission System during Fault Conditions". United States. doi: 10.2172/1832905, avialble at [https://www.osti.gov/servlets/purl/1832905](https://www.osti.gov/servlets/purl/1832905). + +M. Mukherjee, T. Hardy, J. Fuller and A. Bose, "Transactive Implementation of Decentralized Electricity Market for Grid-Edge Systems," 2021 IEEE Power & Energy Society General Meeting (PESGM), Washington, DC, USA, 2021, pp. 1-5, doi: 10.1109/PESGM46819.2021.9638098, available at [https://ieeexplore.ieee.org/document/9638098](https://ieeexplore.ieee.org/document/9638098). + +Monish Mukherjee, Trevor Hardy, Jason C. Fuller, Anjan Bose. "Implementing Multi-Settlement Decentralized Electricity Market Design for Transactive Communities with Imperfect Communication. Applied Energy, Volume 306, Part A, 2022, 117979, doi: 10.1016/j.apenergy.2021.117979. [https://www.sciencedirect.com/science/article/pii/S0306261921012824](https://www.sciencedirect.com/science/article/pii/S0306261921012824). + +Michael Blonsky, Jeff Maguire, Killian McKenna, Dylan Cutler, Sivasathya Pradha Balamurugan, Xin Jin. "OCHRE: The Object-oriented, Controllable, High-resolution Residential Energy Model for Dynamic Integration Studies". Applied Energy, Volume 290, 2021,116732, doi: 10.1016/j.apenergy.2021.116732, available at [https://www.sciencedirect.com/science/article/pii/S0306261921002464](https://www.sciencedirect.com/science/article/pii/S030626192100246). + +Prateek Munankarmi, Jeff Maguire, Sivasathya Pradha Balamurugan, Michael Blonsky, David Roberts, Xin Jin. "Community-scale interaction of energy efficiency and demand flexibility in residential buildings". Applied Energy, Volume 298, 2021, 117149, doi: 10.1016/j.apenergy.2021.117149, available at [https://www.sciencedirect.com/science/article/pii/S0306261921005754](https://www.sciencedirect.com/science/article/pii/S0306261921005754). + +N. Duan, N. Yee, B. Salazar, J. -Y. Joo, E. Stewart and E. Cortez, "Cybersecurity Analysis of Distribution Grid Operation with Distributed Energy Resources via Co-Simulation," 2020 IEEE Power & Energy Society General Meeting (PESGM), Montreal, QC, Canada, 2020, pp. 1-5, doi: 10.1109/PESGM41954.2020.9281757, available at [https://ieeexplore.ieee.org/document/9281757](https://ieeexplore.ieee.org/document/9281757). + +W. Wang, X. Fang and A. Florita, "Impact of DER Communication Delay in AGC: Cyber-Physical Dynamic Co-simulation," 2021 IEEE 48th Photovoltaic Specialists Conference (PVSC), Fort Lauderdale, FL, USA, 2021, pp. 2616-2620, doi: 10.1109/PVSC43889.2021.9518779, available at [https://ieeexplore.ieee.org/document/9518779](https://ieeexplore.ieee.org/document/9518779). + +N. Panossian, T. Elgindy, B. Palmintier and D. Wallison, "Synthetic, Realistic Transmission and Distribution Co-Simulation for Voltage Control Benchmarking," 2021 IEEE Texas Power and Energy Conference (TPEC), College Station, TX, USA, 2021, pp. 1-5, doi: 10.1109/TPEC51183.2021.9384935, available at [https://ieeexplore.ieee.org/document/9384935](https://ieeexplore.ieee.org/document/9384935) + +A. K. Bharati and V. Ajjarapu, "A Scalable Multi-Timescale T&D Co-Simulation Framework using HELICS," 2021 IEEE Texas Power and Energy Conference (TPEC), College Station, TX, USA, 2021, pp. 1-6, doi: 10.1109/TPEC51183.2021.9384985, available at [https://ieeexplore.ieee.org/document/9384985](https://ieeexplore.ieee.org/document/9384985). + +N. Duan, C. Huang, C. -C. Sun and L. Min, "Smart Meters Enabling Voltage Monitoring and Control: The Last-Mile Voltage Stability Issue," in IEEE Transactions on Industrial Informatics, vol. 18, no. 1, pp. 677-687, Jan. 2022, doi: 10.1109/TII.2021.3062628, available at [https://ieeexplore.ieee.org/document/9366429](https://ieeexplore.ieee.org/document/9366429). + +Dylan Cutler, Ted Kwasnik, Sivasathya Balamurugan, Tarek Elgindy, Siddharth Swaminathan, Jeff Maguire, Dane Christensen. "Co-Simulation of Transactive Energy Markets: A Framework for Market Testing and Evaluation". International Journal of Electrical Power & Energy Systems,Volume 128, 2021, 106664, doi: 10.1016/j.ijepes.2020.106664, available at [https://www.sciencedirect.com/science/article/pii/S014206152034209](https://www.sciencedirect.com/science/article/pii/S0142061520342095). + +J. Zhang et al., "Development of HELICS-based High-Performance Cyber-Physical Co-simulation Framework for Distributed Energy Resources Applications," 2020 IEEE International Conference on Communications, Control, and Computing Technologies for Smart Grids (SmartGridComm), Tempe, AZ, USA, 2020, pp. 1-5, doi: 10.1109/SmartGridComm47815.2020.9302977, available at [https://ieeexplore.ieee.org/abstract/document/9302977](https://ieeexplore.ieee.org/abstract/document/9302977). + +Bhattarai B.P., L.D. Marinovici, M. Touhiduzzaman, F.K. Tuffner, K.P. Schneider, J. Xie, and P. Thekkumparambath Mana, et al. "Studying impacts of communication system performance on dynamic stability of networked microgrid". IET Smart Grid 3, no. 5:667 - 676, 2020, doi:10.1049/iet-stg.2019.0303, available at [https://ietresearch.onlinelibrary.wiley.com/doi/10.1049/iet-stg.2019.0303](https://ietresearch.onlinelibrary.wiley.com/doi/10.1049/iet-stg.2019.0303). diff --git a/docs/user-guide/advanced_topics/advanced_topics_index.md b/docs/user-guide/advanced_topics/advanced_topics_index.md index fc746a7061..6abe9032e4 100644 --- a/docs/user-guide/advanced_topics/advanced_topics_index.md +++ b/docs/user-guide/advanced_topics/advanced_topics_index.md @@ -11,6 +11,7 @@ callbacks CallbackFederate commandInterface + connector_fed CoreTypes dynamic_federations encrypted_communication @@ -27,13 +28,7 @@ simultaneous_cosimulations targeted_endpoints timeouts - commandInterface - iteration - aliases - callbacks - CallbackFederate - networking - encrypted_communication + timingOptimization ``` Whereas the [Fundamental Topics](../fundamental_topics/fundamental_topics_index.md) provided a broad overview of co-simulation and a good step-by-step introduction to setting up a HELICS co-simulation, the @@ -54,6 +49,7 @@ The Advanced Topics will cover: - [**Callbacks**](./callbacks.md) - Over time a number of callbacks have been added for various operations and stages of the life cycle of a federate. This document describes the different callbacks available. - [**Callback Federates**](./CallbackFederate.md) - HELICS 3.3 introduced a beta test for callback federates which allow a federate to operate purely inline with a core based solely on callbacks. This can allow a much higher number of federates on a given system than was previously possible. - [**Command Interface**](./commandInterface.md) - HELICS v3 introduced the command interface as a method of asynchronously communicating between federates. +- [**helics_connector**](./commandInterface.md) - App that creates connections between federates as a separate process from the declaration of said interfaces. - [**Cores**](./CoreTypes.md) - Discussion of the different types of message-passing buses and their implementation as HELICS cores. - [**Dynamic Federations**](./dynamic_federations.md) - Sometimes it is useful to have a federate that is not ready at the beginning of co-simulation. This is a dynamic federation. There are various levels of this (not all are available yet) and this document discusses some aspects of dynamic co-simulation. - [**Encrypted Communication**](./encrypted_communication.md) - How to encrypt communication between HELICS brokers/federates. @@ -70,12 +66,6 @@ The Advanced Topics will cover: - [**Simultaneous co-simulations**](./simultaneous_cosimulations.md) - Options for running multiple independent co-simulations on a single system. - [**Targeted Endpoints**](./targeted_endpoints.md) - details on the new targeted endpoints in HELICS 3. - [**Timeouts**](./timeouts.md) - HELICS includes a number of timeouts to prevent failed operations from continuing indefinitely, the various timeout options are discussed in this document. -- [**Command Interface**](./commandInterface.md) - HELICS v3 introduced the command interface as a method of asynchronously communicating between federates. -- [**Aliases**](./aliases.md) - HELICS 3.3 introduced the notion of aliases. Aliases allow a mapping of an interface key to a different string. -- [**Callbacks**](./callbacks.md) - Over time a number of callbacks have been added for various operations and stages of the life cycle of a federate. This document describes the different callbacks available. -- [**Callback Federates**](./CallbackFederate.md) - HELICS 3.3 introduced a beta test for callback federates which allow a federate to operate purely inline with a core based solely on callbacks. This can allow a much higher number of federates on a given system than was previously possible. -- [**Networking**](./CallbackFederate.md) - HELICS provides several ways of working in more restrictive networking environments. -- [**Encrypted Communication**](./encrypted_communication.md) - How to encrypt communication between HELICS brokers/federates. - [**Timing Optimization**](./timingOptimization.md) - Guidance and recommendation on how to configure and set-up timing to optimize federation performance. - [**Translators**](./translators.md) - Translators provide a means of HELICS message interfaces to communicate with HELICS value interfaces and vice versa. - [**Webserver API**](./webserver.md) - How to interact with a running co-simulation using a REST-based web API. diff --git a/docs/user-guide/advanced_topics/connector_fed.md b/docs/user-guide/advanced_topics/connector_fed.md index f0afd51b0b..1e6495552d 100644 --- a/docs/user-guide/advanced_topics/connector_fed.md +++ b/docs/user-guide/advanced_topics/connector_fed.md @@ -6,24 +6,23 @@ To support this HELICS comes with a connector application called "helics_connect ## "helics_connector" Federate -The role of the "helics_connector" federate is to evaluate a mapping of the connections between federate interfaces and create the connections between these interfaces. Under the hood, it's using public APIs that allow the sources ("targets") for inputs and endpoints to be defined and destinations ("targets") to be added to publications. (Which is to say, if the stock "helics_connector" federate doesn't work the way you would like, you could actually make your own.) The documentation of the "helics_connector" app can be found on its [dedicated documentation page](../../references/apps/Connector.md) but I'll summarize the highlights here: +The role of the "helics_connector" federate is to evaluate a mapping of the connections between federate interfaces and create the connections between these interfaces. Under the hood, it's using public APIs that allow the sources ("targets") for inputs and endpoints to be defined and destinations ("targets") to be added to publications. (Which is to say, if the stock "helics_connector" federate doesn't work the way you would like, you could actually make your own.) The documentation of the "helics_connector" app can be found on its [dedicated documentation page](TODO) but I'll summarize the highlights here: - Matches are defined in a plain text or JSON structured text file. - Matches can be defined as one-to-one connections or use regular expressions to match many interfaces in one succinct line. - Tags can be used to add an extra dimension to the matching process, only allowing federates with certain tags to be have their interfaces be candidates for the matching process. - If federates support it, the connector can query a federate about the interfaces it could make and then, based on the results of the matching operation, command said federate to create the necessary interfaces. -- Potential interfaces can be defined in a json configuration file given to a federate. This can include interface templates to automatically generate a number of interfaces ## Callback Complications -The "query-and-command" form of operation is the most complex, largely because it requires the implementation of callback functions. Unless you're using the C API directly, implementing the callback functions takes a little bit of extra effort to get the C-based libraries under the hood working. Since most of the User Guide examples are in Python and most of our users are using Python, we've [documented callbacks in PyHELICS](TODO). Take a look at that page for further details to get a slightly better understanding why C-based callbacks are more complicated in Python. The better approach as of Version 3.5.1 is to use the `potential interfaces` section, then the callbacks for queries and interface generation are handled automatically by the helics federate. +The "query-and-command" form of operation is the most complex, largely because it requires the implementation of callback functions. Unless you're using the C API directly, implementing the callback functions takes a little bit of extra effort to get the C-based libraries under the hood working. Since most of the User Guide examples are in Python and most of our users are using Python, we've [documented callbacks in PyHELICS](TODO). Take a look at that page for further details to get a slightly better understanding why C-based callbacks are more complicated in Python. ## "helics_connector" Interface creation -The order in which "helics*connector" specified the needed interfaces in the federate is not deterministic. This is especially important when using the APIs that get the interface by index (\_e.g* `helicsFederateGetInputByIndex)`, `helicsFederateGetPublicationByIndex`, `helicsFederateGetEndpointByIndex`, `helicsFederateGetEndpointByIndex`). There is no guarantee that the order the interfaces are added to the federate will be the same from computer to computer. To continue using this API the name should be queried then potentially reordered or use the `ByName` version of the calls. +The order in which "helics*connector" creates the interfaces in the federate is not deterministic. This is especially important when using the APIs that get the interface by index (\_e.g* `helicsFederateGetInputByIndex)`, `helicsFederateGetPublicationByIndex`, `helicsFederateGetEndpointByIndex`, `helicsFederateGetEndpointByIndex`). There is no guarantee that the order the interfaces are added to the federate will be the same from computer to computer. To continue using this API ## Examples Three examples have been created to demonstrate the use of the "helics_connector" federate: one uses a direct match-file, one uses a regex match-file and the the last uses a direct match-file while using the query-and-command method of interface creation. Links to the examples are provided below; all produce identical results. -An example utilizing both kinds of iteration will be developed shortly. Iteration example is available in [here](../examples/advanced_examples/advanced_iteration.md) +An example utilizing both kinds of iteration is available [here](../examples/advanced_examples/advanced_iteration.md). diff --git a/docs/user-guide/examples/advanced_examples/advanced_async_time_request.md b/docs/user-guide/examples/advanced_examples/advanced_async_time_request.md new file mode 100644 index 0000000000..7f8c34b773 --- /dev/null +++ b/docs/user-guide/examples/advanced_examples/advanced_async_time_request.md @@ -0,0 +1,40 @@ +# Asynchronous (non-blocking) Time Request + +Generally, when federates make a time request they do so by calling `helicsFederateRequestTime()`. This is a blocking call; the HELICS library will wait until it has reached the time it determines should be granted to the federate and then will do so, returning the granted time. In many cases, this blocking call is acceptable as a time request generally means a federate has nothing to do until it receives new inputs from the rest of the federation as it has completed updating its internal model based on the last received inputs from the federation. + +There are cases, though, where a federate may want to make a time request and then continue working on another computational task instead of waiting in an idle state for the time request to be granted. HELICS provides an alternative time request API to accomplish this: `helicsFederateRequestTimeAsync()`. + +## Using the Asynchronous Time Request + +Making the asynchronous time request is simple: to make the non-blocking time request use the `helicsFederateRequestTimeAsync()` API. This API does not return a value and does not block the federate operation. The code following this API will begin immediately executing while the rest of the federation advances through simulated time. When this federate is done with its extra work, it uses the `helicsFederateRequestTimeComplete()` API call. This is a blocking call (just like `hliecsFederateRequestTime()` was), though it is possible the state of the federation is such that HELICS is ready to immediately grant a time. + +There is also a similar set of APIs when working with the iterative time requests: `helicsFederateRequestTimeIterativeAsync()` and `helicsFederateRequestTimeIterativeComplete()`. + +## Example Explanation + +The advanced default example has been very slightly modified to demonstrate the use of `helicsFederateRequestTimeAsync()` and `helicsFederateRequestTimeComplete()`. In this case, Battery.py has been edited to always make the async time request and then immediately call a frivolous function that, once a simulated day, delays the time request by one wall-clock second and sends a message to the logs. (Obviously, in a real-world application the work done in this function would not be frivolous.) Running this example and looking at the logs shows this message, indicating the function is being run after the async time request but before completing the time request. + +The results of this example are identical to those of the Advanced Default example as there is no impact on the simulated results, just the wall-clock time it takes to run the simulation. + +## Running the example + +The example can be found in the [HELICS Examples repopsitory.](https://github.com/GMLC-TDC/HELICS-Examples/tree/main/user_guide_examples/advanced/advanced_async_time_request) + +To run the example: + +```shell +$ helics run --path=advanced_async_runner.json +``` + +And the results should look like this: +![](https://github.com/GMLC-TDC/helics_doc_resources/raw/main/user_guide/advanced_default_estimated_SOCs.png) + +![](https://github.com/GMLC-TDC/helics_doc_resources/raw/main/user_guide/advanced_default_charging_power.png) + +## [Questions and Help](../../support.md) + +Do you have questions about HELICS or need help? + +1. Come to [office hours](https://helics.org/HELICSOfficeHours.ics)! +2. Post on the [gitter](https://gitter.im/GMLC-TDC/HELICS)! +3. Place your question on the [github forum](https://github.com/GMLC-TDC/HELICS/discussions)! diff --git a/docs/user-guide/examples/advanced_examples/advanced_examples_index.md b/docs/user-guide/examples/advanced_examples/advanced_examples_index.md index e2f1c84945..b5df03df02 100644 --- a/docs/user-guide/examples/advanced_examples/advanced_examples_index.md +++ b/docs/user-guide/examples/advanced_examples/advanced_examples_index.md @@ -15,6 +15,8 @@ advanced_orchestration advanced_iteration advanced_FMU + advanced_async_time_request + advanced_helics_connector ``` diff --git a/docs/user-guide/examples/advanced_examples/advanced_helics_connector.md b/docs/user-guide/examples/advanced_examples/advanced_helics_connector.md new file mode 100644 index 0000000000..3342ecf711 --- /dev/null +++ b/docs/user-guide/examples/advanced_examples/advanced_helics_connector.md @@ -0,0 +1,271 @@ +# helics_connector + +This example demonstrates the use of the "helics_connector" app to create interface connection between federates outside of the configuration JSON or API calls. + +- [helics_connector](#helics_connector) + - [Where is the code?](#where-is-the-code) + - [What is this co-simulation doing?](#what-is-this-co-simulation-doing) + - [Differences compared to the Advanced Default example](#differences-compared-to-the-advanced-default-example) + - [HELICS Differences](#helics-differences) + - [HELICS components](#helics-components) + - [Configuration by match-file](#configuration-by-match-file) + - [Match-file specification](#match-file-specification) + - [Configuration by interface creation](#condfiguration-by-interface-creation) + - [Query callback](#query-callback) + - [Configuration command response](#configuration-command-response) + - [Interface creation timing](#interface-creation-timing) + - [Execution and Results](#execution-and-results) + - [Questions and Help](#questions-and-help) + +## Where is the code? + +This example code on [the use of helics_connector can be found here](https://github.com/GMLC-TDC/HELICS-Examples/tree/main/user_guide_examples/advanced/advanced_connector). If you have issues navigating the examples, visit the HELICS [Gitter page](https://gitter.im/GMLC-TDC/HELICS) or the [user forum on GitHub](https://github.com/GMLC-TDC/HELICS/discussions). + +[![](https://github.com/GMLC-TDC/helics_doc_resources/raw/main/user_guide/advanced_connector_github.png)](https://github.com/GMLC-TDC/HELICS-Examples/tree/main/user_guide_examples/advanced/advanced_connector) + +## What is this co-simulation doing? + +This example shows how to use helics_connector to create connections between HELICS federate interfaces without specifying said connections via the JSON configuration or similar APIs. Specifically, only publications (with no targets defined), outputs (with no source defined), and endpoints need to be defined in the JSON. helics_connector then uses a match-file to establish the connections between publication outputs and inputs. + +### Differences compared to the Advanced Default example + +This example has the same federates interacting in the same ways as in the [Advanced Default example](./advanced_default.md). The only difference is the use of helics_connector to create the data exchanges between the federates. + +#### HELICS Differences + +By configuring the federates without any targeting in the input or output, helics_connector uses existing public APIs to establish the data exchanges between federates. No core library changes were made to add this functionality and it is entirely possible for other HELICS users to write their own versions of helics_connector to satisfy their particular needs. + +### HELICS components + +#### Configuration by match-file + +The only difference between the federation as defined in the "advanced default" example and this example is how the configuration is defined. The advanced_default example uses subscriptions instead of inputs in the configuration JSON while this example uses inputs. For example, a portion of the Battery federate configuration for the advanced_default example and this example are shown below; the advanced_default configuration uses subscriptions and specifies a "key" as a data source where this example uses inputs and has no "key" value. + +```json +"subscriptions":[ + { + "key":"Charger/EV1_voltage", + "type":"double", + "unit":"V", + "global": true + } +] +``` + +```json +"inputs": [ + { + "global": true, + "name": "Battery/EV100_input_voltage", + "type": "double", + "unit": "V" + } +] +``` + +#### Match-file specification + +The match-file can be specified either using a plain textfile or JSON. The simplest format specifies the individual connections between federates, one connection per line: + +``` +Charger/EV1_output_voltage Battery/EV1_input_voltage from_to +Charger/EV2_output_voltage Battery/EV2_input_voltage from_to +Charger/EV3_output_voltage Battery/EV3_input_voltage from_to +Charger/EV4_output_voltage Battery/EV4_input_voltage from_to +Charger/EV5_output_voltage Battery/EV5_input_voltage from_to +Charger/EV1_input_current Battery/EV1_output_current to_from +Charger/EV2_input_current Battery/EV2_output_current to_from +Charger/EV3_input_current Battery/EV3_output_current to_from +Charger/EV4_input_current Battery/EV4_output_current to_from +Charger/EV5_input_current Battery/EV5_output_current to_from +``` + +In JSON, the format looks like: + +```json +{ + "connections": [ + ["Charger/EV1_output_voltage", "Battery/EV1_input_voltage", "from_to"], + ["Charger/EV2_output_voltage", "Battery/EV2_input_voltage", "from_to"], + ["Charger/EV3_output_voltage", "Battery/EV3_input_voltage", "from_to"], + ["Charger/EV4_output_voltage", "Battery/EV4_input_voltage", "from_to"], + ["Charger/EV5_output_voltage", "Battery/EV5_input_voltage", "from_to"], + ["Charger/EV1_input_current", "Battery/EV1_output_current", "to_from"], + ["Charger/EV2_input_current", "Battery/EV2_output_current", "to_from"], + ["Charger/EV3_input_current", "Battery/EV3_output_current", "to_from"], + ["Charger/EV4_input_current", "Battery/EV4_output_current", "to_from"], + ["Charger/EV5_input_current", "Battery/EV5_output_current", "to_from"] + ] +} +``` + +The "from-to" or "to-from" is used to indicate which side of the connection is un-named and thus is the producer of the data ("from") and which side is named and is the target for the data ("to"). helics_connector goes through and finds all **unconnected** interfaces on the federates themselves, finds the corresponding interface indicated as a "from" connection in the match-file, and then connects them with any existing entry in the match-file on the "to" side (even if they already have a target). + +Alternatively, the match-file can be specified using regular expressions. This can be a convenient way to specify a large number of interface connections if they follow a naming convention. The regular expression format takes advantage of the ability to name terms in the expression, allowing terms in one part of the expression to be used later on in the expression. In the case, the above match-file looks like this: + +``` +# this is a comment +REGEX:Charger/EV(?\d*)_output_voltage, REGEX:Battery/EV(?)_input_voltage, from_to +REGEX:Charger/EV(?\d*)_input_current, REGEX:Battery/EV(?)_output_current, from_to +``` + +In this case, "ev_num" is the name given to the numerals that appear after the characters "EV" and are used in both first and second terms of the match-file. Each regular expression must be prefixed with the "REGEX:" string. + +Its possible to mix direct connections and regular expressions in the same matchfile but not because the helics_connector only works on unconnected interfaces, there is an implied precedence in the match-file that works top down. That is, connections at the top of the file over-ride those specified at the bottom of the file. Once an interface marked as a "from" is connected, it is not eligible for connections defined later in the file. + +#### Configuration by interface creation + +A second, more complex example is also included where helics_connector facilitates a custom communication protocol between federates where the interfaces themselves are created on demand. In this case, the federates using this protocol must be written to respond to a specific query where they indicate the interfaces they could create and then respond to a specific command from helics_connector by creating the interfaces indicated by helics_federate. In both cases helics_connector uses a match-file specification to define which interfaces to create. + +The configuration JSON of the federate is quite different as no interfaces are defined and only timing information is included: + +```json +{ + "name": "Battery", + "core_type": "zmq", + "log_level": "warning", + "period": 60.0, + "uninterruptible": false, + "terminate_on_error": true, + "wait_for_current_time_update": true +} +``` + +##### Query callback + +The federate code needs to include the necessary functionality to define a callback to handle custom queries. The example shown here is in Python and the HELICS Python library is C-based so setting up the callback correctly is more challenging than most of the Python code in these examples. + +To pass information into the callback (which is never explicitly called and thus it is not possible to pass specific parameters), a "UserData" class is defined that allows the inclusion of arbitrary data (in this case, the number of EVs). This has been defined as a value that is passed in when the object is instantiated ("num_EVs"). This value is used to define a class attribute, thus preserving it in the object itself. + +```python +class UserData(object): + def __init__(self, num_EVs): + self.num_EVs = num_EVs + userdata = h.ffi.new_handle(self) + self._userdata = userdata +``` + +The function that is called when the query is made. In our example, we called it "query_callback" and it has a decorator of the callback function in C that must match the signture of said function. + +```python +@h.ffi.callback("void query(const char *query, int querySize, HelicsQueryBuffer buffer, void *user_data)") +def query_callback(query_ptr, size:int, query_buffer_ptr, user_data): +``` + +The query being sent to this federate is defined in the "query_buffer_ptr" variable but must be decoded into a string by declaring it a HELICS buffer object and then decoding it into a string: + +```python +query_buffer = h.HelicsQueryBuffer(query_buffer_ptr) +query_str = h.ffi.string(query_ptr,size).decode() +``` + +After doing all this work, we can see that the query sent is "potential_interfaces"; this is the query sent by helics_connector to find out what potential interfaces each federate can create. To answer this query we need to pull in the number of EVs passed in through the UserData object + +```python +num_EVS = h.ffi.from_handle(user_data).num_EVs +``` + +The query response is a JSON dictionary composed of three lists: the federates publications, inputs, and endpoints. In this case, the name of the interfaces can be created easily but must match the names used in the helics_connector match-file. The dictionary is used to fill the HELICS buffer object that was sent in, effectively responding to the query. + +```python +for EVnum in range(1, num_EVs + 1): + pubs.append(f"Battery/EV{EVnum}_output_current") + inputs.append(f"Battery/EV{EVnum}_input_voltage") +response_dict = { + "publications": pubs, + "inputs": inputs, + "endpoints": [] + } +query_response = json.dumps(response_dict) +h.helicsQueryBufferFill(query_buffer, query_response) +``` + +With "UserData" and "query_callback" defined, they now just need to be included in the main body of the federate code. An instance of the UserData object is created ("user_data") using the number of EVs and a handle (pointer) to the object is defined. Lastly, the query callback is defined via a HELICS API, referencing both "query_callback" and "user_data". + +```python +user_data = UserData(num_EVs) +user_data_handle = h.ffi.new_handle(user_data) +h.helicsFederateSetQueryCallback(fed, query_callback, user_data_handle) +``` + +##### Configuration command response + +After responding to the query, the federate also needs to respond to the command sent by helics_connection to define the interfaces it needs to create. helics_connector sends a JSON as a command with the "command" field of that object being "register_interfaces". The rest of the object has three fields: the publications, inputs, and endpoints the object needs to create. + +```json +{ + "command": "register_interfaces", + "inputs": [ + "Battery/EV5_input_voltage", + "Battery/EV4_input_voltage", + "Battery/EV3_input_voltage", + "Battery/EV2_input_voltage", + "Battery/EV1_input_voltage" + ], + "publications": [ + "Battery/EV5_output_current", + "Battery/EV4_output_current", + "Battery/EV3_output_current", + "Battery/EV2_output_current", + "Battery/EV1_output_current" + ] +} +``` + +The example code checks to make sure the interfaces are provided as lists and then creates the interfaces as a part of the custom "register_interfaces_from_command" function. In this case, we assume all inputs are doubles; a more general command could include data types. + +```python +if isinstance(cmd["publications"], list): + for pub in cmd["publications"]: + h.helicsFederateRegisterGlobalPublication(fed, pub, h.HELICS_DATA_TYPE_DOUBLE) +if isinstance(cmd["inputs"], list): + for inp in cmd["inputs"]: + h.helicsFederateRegisterGlobalInput(fed, inp, h.HELICS_DATA_TYPE_DOUBLE) +``` + +##### Interface creation timing + +The above defined query response and command protocol all takes place during the initialization phase of the federate operation. To accomplish multiple asynchronous events in initializing mode, the ["iterative" version of entering initialization mode](https://python.helics.org/api/capi-py/#helicsFederateEnterInitializingMode) needs to be used. Due to the way HELICS grants time in initializing mode, the query is guaranteed to be available after enter initializing mode. This is handled via the callback and not explicit call needs to be made. To guarantee the command message is available for acting on, the same iterative initializing mode call is made again. After this, the command is deciphered, the interfaces created, and, finally, the federate enters executing mode. + +```python +h.helicsFederateEnterInitializingModeIterative(fed) +# Query is guaranteed to be available after this call but may be +# available earlier. Callback responds whenever the query comes in. +h.helicsFederateEnterInitializingModeIterative(fed) +command = h.helicsFederateGetCommand(fed) + if len(command) == 0: + raise TypeError("Empty command.") + try: + logger.debug(f"command string: {command}") + cmd = json.loads(command) + except: + raise TypeError("Not able to convert command string to JSON.") +register_interfaces_from_command(fed, cmd) # custom function +h.helicsFederateEnterExecutingMode(fed) +``` + +## Execution and Results + +Run the co-simulation, use one of the following: + +```shell +$ helics run --path=./advanced_matchfile_direct_runner.json +$ helics run --path=./advanced_matchfile_regex_runner.json +$ helics run --path=./advanced_connector_interface_creation_runner.json +``` + +Since this is only a change to the configuration method of the federation, the results are identical to those in the [Advanced Default example.](./advanced_default.md) + +![](https://github.com/GMLC-TDC/helics_doc_resources/raw/main/user_guide/advanced_default_charging_power.png) + +![](https://github.com/GMLC-TDC/helics_doc_resources/raw/main/user_guide/advanced_default_estimated_SOCs.png) + +![](https://github.com/GMLC-TDC/helics_doc_resources/raw/main/user_guide/advanced_default_battery_SOCs.png) + +## [Questions and Help](../../support.md) + +Do you have questions about HELICS or need help? + +1. Come to [office hours](https://helics.org/HELICSOfficeHours.ics)! +2. Post on the [gitter](https://gitter.im/GMLC-TDC/HELICS)! +3. Place your question on the [github forum](https://github.com/GMLC-TDC/HELICS/discussions)! diff --git a/docs/user-guide/examples/fundamental_examples/fundamental_endpoints.md b/docs/user-guide/examples/fundamental_examples/fundamental_endpoints.md index 29ec00f720..4b192c679c 100644 --- a/docs/user-guide/examples/fundamental_examples/fundamental_endpoints.md +++ b/docs/user-guide/examples/fundamental_examples/fundamental_endpoints.md @@ -4,14 +4,17 @@ The Federate Message + Communication Configuration Example extends the Base Exam This tutorial is organized as follows: -- [Example files](#example-files) -- [Federate Communication with Endpoints](#federate-communication-with-endpoints) - - [When to use pub/subs vs endpoints](#when-to-use-pubsubs-vs-endpoints) - - [Translation from pub/sub to endpoints](#translation-from-pubsub-to-endpoints) - - [Config Files](#config-files) - - [Simulators](#simulators) - - [Co-simulation Execution](#co-simulation-execution) -- [Questions and Help](#questions-and-help) +- [Endpoint Federates](#endpoint-federates) + - [Example files](#example-files) + - [Federate Communication with Endpoints](#federate-communication-with-endpoints) + - [When to use pub/subs vs endpoints](#when-to-use-pubsubs-vs-endpoints) + - [Translation from pub/sub to endpoints](#translation-from-pubsub-to-endpoints) + - [Config Files](#config-files) + - [Simulators](#simulators) + - [Battery](#battery) + - [Charger](#charger) + - [Co-simulation execution](#co-simulation-execution) + - [Questions and Help](#questions-and-help) ## Example files @@ -124,7 +127,7 @@ As with the Base Example, configuration can be done with JSON files. The first c ```json "endpoints":[ { - "key":"Battery/EV1_current", + "name":"Battery/EV1_current", "destination":"Charger/EV1_voltage", "global": true }, @@ -136,7 +139,7 @@ As with the Base Example, configuration can be done with JSON files. The first c ```json "endpoints":[ { - "key":"Charger/EV1_voltage", + "name":"Charger/EV1_voltage", "destination":"Battery/EV1_current", "global": true },