Commit 3ae462d2 authored by Georg Martin Reinke's avatar Georg Martin Reinke
Browse files

add some documentation for VILLAS interface


Former-commit-id: 0a28e4f3
parent aa57cc03
## 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.
......@@ -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() {};
};
......
......@@ -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);
};
};
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment