Update ns-3 module to compile with HELICS 1.0 alpha

contrib/helics/bakeconf.xml

@@ -0,0 +1,22 @@
+<configuration>
+  <modules>
+    <module name="helics">
+      <source type="git">
+        <attribute name="url" value="https://github.com/GMLC-TDC/HELICS-src.git"/>
+        <attribute name="module_directory" value="helics"/>
+      </source>
+      <build type="cmake" objdir="yes">
+      </build>
+    </module>
+
+    <module name="helics-ns3" type="ns-contrib" min_version="ns-3.27">
+     <source type="git">
+        <attribute name="url" value="https://github.com/GMLC-TDC/helics-ns3.git"/>
+        <attribute name="module_directory" value="helics"/>
+      </source>
+      <build type="none">
+      </build>
+      <depends_on name="helics" optional="False"/>
+    </module>
+  </modules>
+</configuration>

contrib/helics/doc/helics.rst

@@ -0,0 +1,98 @@
+Example Module Documentation
+----------------------------
+
+.. include:: replace.txt
+.. highlight:: cpp
+
+.. heading hierarchy:
+   ------------- Chapter
+   ************* Section (#.#)
+   ============= Subsection (#.#.#)
+   ############# Paragraph (no number)
+
+This is a suggested outline for adding new module documentation to |ns3|.
+See ``src/click/doc/click.rst`` for an example.
+
+The introductory paragraph is for describing what this code is trying to
+model.
+
+For consistency (italicized formatting), please use |ns3| to refer to
+ns-3 in the documentation (and likewise, |ns2| for ns-2).  These macros
+are defined in the file ``replace.txt``.
+
+Model Description
+*****************
+
+The source code for the new module lives in the directory ``src/helics``.
+
+Add here a basic description of what is being modeled.
+
+Design
+======
+
+Briefly describe the software design of the model and how it fits into 
+the existing ns-3 architecture. 
+
+Scope and Limitations
+=====================
+
+What can the model do?  What can it not do?  Please use this section to
+describe the scope and limitations of the model.
+
+References
+==========
+
+Add academic citations here, such as if you published a paper on this
+model, or if readers should read a particular specification or other work.
+
+Usage
+*****
+
+This section is principally concerned with the usage of your model, using
+the public API.  Focus first on most common usage patterns, then go
+into more advanced topics.
+
+Building New Module
+===================
+
+Include this subsection only if there are special build instructions or
+platform limitations.
+
+Helpers
+=======
+
+What helper API will users typically use?  Describe it here.
+
+Attributes
+==========
+
+What classes hold attributes, and what are the key ones worth mentioning?
+
+Output
+======
+
+What kind of data does the model generate?  What are the key trace
+sources?   What kind of logging output can be enabled?
+
+Advanced Usage
+==============
+
+Go into further details (such as using the API outside of the helpers)
+in additional sections, as needed.
+
+Examples
+========
+
+What examples using this new code are available?  Describe them here.
+
+Troubleshooting
+===============
+
+Add any tips for avoiding pitfalls, etc.
+
+Validation
+**********
+
+Describe how the model has been tested/validated.  What tests run in the
+test suite?  How much API and code is covered by the tests?  Again, 
+references to outside published work may help here.

contrib/helics/examples/fed-filter.cc

@@ -0,0 +1,51 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation;
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+/*
+ * The "fed-filter" is a placeholder for a federate that is *not*
+ * ns-3. It is a helics::MessageFederate, so it sends messages between
+ * registered endpoints.
+ */
+
+#include <iostream>
+
+#include "helics/helics.hpp"
+#include "helics/core/core-types.hpp"
+
+int 
+main (int argc, char *argv[])
+{
+  helics::FederateInfo fi ("fed-filter");
+  fi.coreType = helics::coreTypeFromString ("zmq");
+  auto mFed = std::make_shared<helics::MessageFederate> (fi);
+  auto p1 = mFed->registerGlobalEndpoint ("endpoint1");
+  auto p2 = mFed->registerGlobalEndpoint ("endpoint2");
+  mFed->enterExecutionState ();
+  std::cout << "fed-filter entered execution state" << std::endl;
+  auto granted = mFed->requestTime (1.0);
+  std::cout << "fed-filter granted time " << granted << std::endl;
+  helics::data_block data (500, 'a');
+  mFed->sendMessage (p1, "endpoint2", data);
+  std::cout << "fed-filter sent message" << std::endl;
+  while (granted < 8.0) {
+    granted = mFed->requestTime (granted + 1.0);
+    std::cout << "fed-filter granted time " << granted << std::endl;
+    std::cout << "fed-filter hasMessage? " << mFed->hasMessage (p2) << std::endl;
+  }
+  mFed->finalize ();
+  return 0;
+}
+

contrib/helics/examples/fed-sndrcv.cc

@@ -0,0 +1,51 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation;
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+/*
+ * The "SimpleFederate" is a placeholder for a federate that is *not*
+ * ns-3. It is a helics::MessageFederate, so it sends messages between
+ * registered endpoints.
+ */
+
+#include <iostream>
+
+#include "helics/helics.hpp"
+#include "helics/core/core-types.hpp"
+
+int 
+main (int argc, char *argv[])
+{
+  helics::FederateInfo fi ("fed-sndrcv");
+  fi.coreType = helics::coreTypeFromString ("zmq");
+  fi.coreInitString = "--loglevel=4";
+  auto mFed = std::make_shared<helics::MessageFederate> (fi);
+  auto p1 = mFed->registerEndpoint ("endpoint1");
+  auto p2 = mFed->registerEndpoint ("endpoint2");
+  mFed->enterExecutionState ();
+  std::cout << "fed-sndrcv entered execution state" << std::endl;
+  auto granted = mFed->requestTime (1.0);
+  std::cout << "fed-sndrcv granted time " << granted << std::endl;
+  helics::data_block data (500, 'a');
+  mFed->sendMessage (p1, "ns3/endpoint1", data);
+  std::cout << "fed-sndrcv sent message to ns3/endpoint1" << std::endl;
+  while (granted < 8.0) {
+    granted = mFed->requestTime (granted + 1.0);
+    std::cout << "fed-sndrcv hasMessage? " << mFed->hasMessage (p2) << std::endl;
+  }
+  mFed->finalize ();
+  return 0;
+}
+

contrib/helics/examples/ns3-filter.cc

@@ -0,0 +1,132 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation;
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ */
+
+#include "ns3/core-module.h"
+#include "ns3/network-module.h"
+#include "ns3/csma-module.h"
+#include "ns3/internet-module.h"
+#include "ns3/point-to-point-module.h"
+#include "ns3/applications-module.h"
+#include "ns3/ipv4-global-routing-helper.h"
+
+#include "ns3/helics-helper.h"
+
+// Default Network Topology
+//
+//       10.1.1.0
+// n0 -------------- n1   n2   n3   n4
+//    point-to-point  |    |    |    |
+//                    ================
+//                      LAN 10.1.2.0
+
+
+using namespace ns3;
+
+NS_LOG_COMPONENT_DEFINE ("HelicsExample");
+
+/*
+ * The main() loop below represents the ns-3 model. The helics ns-3
+ * integration will filter messages sent by MessageFederate instances by
+ * creating HelicsApplication instances at Nodes. The name given to the
+ * HelicsApplication should match a registered endpoint.
+ */
+
+int 
+main (int argc, char *argv[])
+{
+  bool verbose = true;
+  uint32_t nCsma = 3;
+  std::string endpoint1 = "endpoint1";
+  std::string endpoint2 = "endpoint2";
+
+  HelicsHelper helicsHelper;
+
+  CommandLine cmd;
+  cmd.AddValue ("nCsma", "Number of \"extra\" CSMA nodes/devices", nCsma);
+  cmd.AddValue ("verbose", "Tell echo applications to log if true", verbose);
+  helicsHelper.SetupCommandLine(cmd);
+  cmd.AddValue ("endpoint1", "First helics endpoint", endpoint1);
+  cmd.AddValue ("endpoint2", "Second helics endpoint", endpoint2);
+  cmd.Parse (argc,argv);
+
+  if (verbose)
+    {
+      LogComponentEnable ("HelicsExample", LOG_LEVEL_INFO);
+      LogComponentEnable ("HelicsSimulatorImpl", LOG_LEVEL_INFO);
+    }
+
+  NS_LOG_INFO ("Calling helicsHelper.SetupFederate");
+  helicsHelper.SetupFederate();
+
+  nCsma = nCsma == 0 ? 1 : nCsma;
+
+  NodeContainer p2pNodes;
+  p2pNodes.Create (2);
+
+  NodeContainer csmaNodes;
+  csmaNodes.Add (p2pNodes.Get (1));
+  csmaNodes.Create (nCsma);
+
+  PointToPointHelper pointToPoint;
+  pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
+  pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
+
+  NetDeviceContainer p2pDevices;
+  p2pDevices = pointToPoint.Install (p2pNodes);
+
+  CsmaHelper csma;
+  csma.SetChannelAttribute ("DataRate", StringValue ("100Mbps"));
+  csma.SetChannelAttribute ("Delay", TimeValue (NanoSeconds (6560)));
+
+  NetDeviceContainer csmaDevices;
+  csmaDevices = csma.Install (csmaNodes);
+
+  InternetStackHelper stack;
+  stack.Install (p2pNodes.Get (0));
+  stack.Install (csmaNodes);
+
+  Ipv4AddressHelper address;
+  address.SetBase ("10.1.1.0", "255.255.255.0");
+  Ipv4InterfaceContainer p2pInterfaces;
+  p2pInterfaces = address.Assign (p2pDevices);
+
+  address.SetBase ("10.1.2.0", "255.255.255.0");
+  Ipv4InterfaceContainer csmaInterfaces;
+  csmaInterfaces = address.Assign (csmaDevices);
+
+  ApplicationContainer apps1 = helicsHelper.InstallFilter (
+          csmaNodes.Get (nCsma), endpoint1);
+  apps1.Start (Seconds (1.0));
+  apps1.Stop (Seconds (10.0));
+
+  ApplicationContainer apps2 = helicsHelper.InstallFilter (
+          p2pNodes.Get (0), endpoint2);
+  apps2.Start (Seconds (1.0));
+  apps2.Stop (Seconds (10.0));
+
+  Ipv4GlobalRoutingHelper::PopulateRoutingTables ();
+
+  pointToPoint.EnablePcapAll ("second");
+  csma.EnablePcap ("second", csmaDevices.Get (1), true);
+
+  Simulator::Stop (Seconds (11.0));
+
+  Simulator::Run ();
+
+  Simulator::Destroy ();
+  return 0;
+}
+