add some documentation for VILLAS interface

Documentation/VILLAS.md

+## Interface to VILLASnode
+
+### Building
+
+Build libvillas-ext from [VILLASnode](https://git.rwth-aachen.de/VILLASframework/VILLASnode):
+
+```
+$ git clone git@git.rwth-aachen.de:VILLASframework/VILLASnode.git
+$ cd VILLASnode
+$ make
+# make install
+```
+
+Then, build DPsim as normal.
+
+### Using the interface in simulations
+
+To use the interface in simulations, create `ExternalVoltageSource` or
+`ExternalCurrentSource` objects and register them with a `VillasInterface`.
+Samples are passed between VILLASnode and DPsim in an array of real numbers; you
+need to specify which elements from this array to use when registering a source.
+Similarly, you can register currents through specific components and voltages
+between nodes the be passed back to VILLASnode. See the Doxygen documentation for
+`VillasInterface` and `ExternalInterface` or the examples in `Examples/VillasTest.cpp` for more information.
+
+### Running
+
+To actually run simulations, start VILLASnode first and then start DPsim. If
+VILLASnode is running as root, DPsim needs to be started as root as well to
+connect to it. You may need to adjust `LD_LIBRARY_PATH` to include the directory
+where libvillas-ext was installed:
+
+```
+$ sudo env LD_LIBRARY_PATH=/usr/local/lib ./DPsolver
+```
+
+You can also use the `exec` option of the `shmem` node from VILLASnode; see its
+documentation for more details.

Source/ExternalInterface.h

@@ -6,37 +6,74 @@
 #include "Components/ExternalVoltageSource.h"
 
 namespace DPsim {
-	struct VoltDiff {
-		Int from;
-		Int to;
-		Int realIdx;
-		Int imagIdx;
-	};
-	struct ExtComponent {
-		BaseComponent *comp;
-		Int realIdx;
-		Int imagIdx;
-	};
 
-	/** Abstract base class for interfacing the simulator with other data sources or sinks.
+	/** \brief Abstract base class for interfacing the simulator with other data sources or sinks.
+	 *
 	 * After an ExternalInterface is created, components that should use values
 	 * from this interface can be registered with it using the appropiate
 	 * methods implemented by the subclass. Subclasses must also implement the
-	 * readValues method, which should update the values of the registered
-	 * components.
+	 * readValues and writeValues methods, which should update the values of
+	 * the registered components or send voltages or currents to the external
+	 * sink.
 	 */
 	class ExternalInterface {
 	protected:
+		/// Internal struct for storing an exported voltage.
+		struct VoltDiff {
+			Int from;
+			Int to;
+			Int realIdx;
+			Int imagIdx;
+		};
+		/// Internal struct for storing references to external components.
+		struct ExtComponent {
+			BaseComponent *comp;
+			Int realIdx;
+			Int imagIdx;
+		};
 		std::vector<ExtComponent> mExtComponents;
 		std::vector<VoltDiff> mExportedVoltages;
 		std::vector<ExtComponent> mExportedCurrents;
 		bool mInit = 0;
 	public:
+		/** Register an external voltage source to use values from this interface.
+		 * @param evs The external voltage source to register.
+		 * @param realIdx Interface-specific index identifying the real part.
+		 * @param imagIdx Interface-specific index identifying the imaginary part.
+		 */
 		void registerVoltageSource(ExternalVoltageSource* evs, Int realIdx, Int imagIdx);
+		/** Register an external current source to use values from this interface.
+		 * @param evs The external current source to register.
+		 * @param realIdx Interface-specific index identifying the real part.
+		 * @param imagIdx Interface-specific index identifying the imaginary part.
+		 */
 		void registerCurrentSource(ExternalCurrentSource* ecs, Int realIdx, Int imagIdx);
+		/** Register a voltage between two nodes to be sent through this
+		 * interface after every step.
+		 * @param from Number of the node used as the positive potential.
+		 * Node numbers are like passed to the component constructors (starting
+		 * from 1 with 0 meaning ground).
+		 * @param to Number of the nodes used as the negative potential.
+		 * @param realIdx Interface-specific index identifying the real part.
+		 * @param imagIdx Interface-specific index identifying the imaginary part.
+		 */
 		void registerExportedVoltage(Int from, Int to, Int realIdx, Int imagIdx);
+		/** Register a current through a component to be sent through this
+		 * interface after every step.
+		 * @param comp Component whose current is sent. Note that this component
+		 * must properly implement the getCurrent method.
+		 * @param realIdx Interface-specific index identifying the real part.
+		 * @param imagIdx Interface-specific index identifying the imaginary part.
+		 */
 		void registerExportedCurrent(BaseComponent *comp, Int realIdx, Int imagIdx);
+		/** Read data for a timestep from the interface and passes the values
+		 * to all registered current / voltage sources.
+		 */
 		virtual void readValues() = 0;
+		/** Write all exported values to the interface. Called after every timestep.
+		 * @param model Reference to the system model which should be used to
+		 * calculate needed voltages.
+		 */
 		virtual void writeValues(SystemModel &model) = 0;
 		virtual ~ExternalInterface() {};
 	};

Source/VillasInterface.h

@@ -9,7 +9,11 @@
 #include "Components/ExternalVoltageSource.h"
 
 namespace DPsim {
-	/** Implements ExternalInterface by using the shared memory interface of VILLASnode. */
+	/** \brief Implements ExternalInterface by using the shared memory interface of VILLASnode.
+	 *
+	 * For this class, the indexes are the offsets in the data member of VILLAS's
+	 * struct sample. Make sure that VILLASnode is configured accordingly.
+	 */
 	class VillasInterface : public ExternalInterface {
 	private:
 		const char* mShmemName;
@@ -18,9 +22,20 @@ namespace DPsim {
 		void* mBase;
 
 	public:
+		/** Create a VillasInterface using the given shmem object name.
+		 *
+		 * @param name The name of the POSIX shmem object (like given in the
+		 * configuration of VILLASnode).
+		 */
 		VillasInterface(const char* name);
 		~VillasInterface();
+		/** Read a single struct sample from the shared input queue and pass the contained
+		 * values to all registered current/voltage sources.
+		 */
 		virtual void readValues();
+		/** Collect all exported currents and voltages in a struct sample and
+		 * write it to the shared output queue.
+		 */
 		virtual void writeValues(SystemModel &model);
 	};
 };