How to implement a new generator

Creating a Generator

Setting up the QMake File

For building the generator, I recommend qmake (also you can use any other build system to create a dynamic library (see the "Programm Library Howto" available at tldp.org).

Use the file DummyGenerator.pro as a template, the only entries you should need to change are the HEADERS and SOURCES, which specify the header and source files which your project will need.

If your building your generator outside the scenario generator source, you also have to set the environment variable GENERATOR_HEADERS.

Creating a new generator

All generators must implement the interface Generator. The basic control flow is as follows:

The ScenarioGeneratorApplication retrieves a set of parameters from the generator via the method getParameters(). According to these parameters the gui is built. If the value of a parameter is changed via the user interface, the method setParameter(Parameter*p) is called, and according to the id the parameter changed can be determined.

The following methods have to be implemented:

Method	Comment
Generator* create_generator();	See DummyGenerator for implementation
void destruct_generator(Generator* generator);	See DummyGenerator for implementation
vector<ParameterCollection*> getParameters()	Create the parameter model for the scenario generator. Each collection contained the vector will be displayed in a seperate tab, thus providing some kind of high-level structure. Note that the objects returned here will get deleted by the ScenarioGeneratorApplication. For that reason, they have to be allocated with new in this method! See also DummyGenerator for implementation.
void setParameter(Parameter* p)	This method is called if the user has set the parameter to a new value. Note that Parameter p is set to that new value. Use the id of this parameter to determine which value has been changed.
bool validateParameters()	Return true, if all parameters are set accordingly, so that output or a preview may be generated. Return false otherwise! Here you may want to write messages to the console. The corresponding stream is acessible via ScenarioGeneratorApplication::getInstance()->getTextMessageStream()
generatePreview()	Create the vtk objects for the preview. See DummyGenerator for implementation, see also below "Creating Objects"
virtual Object* getSampleObject()	Return an instance of the kind of object which the generator will use. That object will not be drawn, but just used internally for setup.
generateOutput(const std::string& directory)	Write the output to the given directory.

Here is an example of handling parameters. For more details, see the DummyGenerator.

Imagine we want to create a generator with one boolean and one integer parameter.

class DummyGenerator : public Generator {

public:

		virtual	void setParameter(Parameter* p);		
		virtual vector<ParameterCollection*> getParameters();

		...
		

private:

		int _numObjects;
		bool _dummyBoolValue;
		

};

vector<ParameterCollection*> DummyGenerator::getParameters() {

 
		vector<ParameterCollection*> parameters; 
		ParameterCollection* tab = new ParameterCollection("DummyCollection", "DummyCollection",
			"DummyCollection", Parameter::BUTTON);		
		parameters.push_back(tab);

		tab->addParameter(
			new ParameterWithIntValue("numObjects",
				"Number of Objects", "The number of objects which is created and displayed",
				Parameter::LINE_EDIT,  false, _numObjects));

		tab->addParameter(new ParameterWithBool("dummyBoolValue", "dummyBoolValue",
			"This is just a dummy Boolean Value" , Parameter::CHECKBOX, false, false));

		return parameters;
		

}

void DummyGenerator::setParameter(Parameter* p) {

		std::cout << "SetParameter for param" << p->getNameId() << endl;
		std::string id = p->getNameId();

		if (id == "numObjects") {
			std::cout << "Setting numObjects!" << std::endl;
			_numObjects = static_cast<ParameterWithIntValue*>(p)->getValue();
		}
		else if (id == "objectSpacing") {
			std::cout << "Setting objectSpacing!" << std::endl;
			_objectSpacing = static_cast<ParameterWithDoubleValue*>(p)->getValue();
		}

		std::cout << "Parameter value is set!" << endl;
		

}

For visualization, Objects are supposed to be created in the generatePreview() method (which is then called from ScenarioGenerator that also performs actual visualization).

Parameters

All parameters have the following properties which are set via their constructors:

property	Description
ID	- The ID has to be unique in order to identify this parameter, and will never be changed by the scenario generator. It is recommended to prefix a parameter in a parameter collection by the id of its parent collection (so to get a fully qualified identifier). It is advised to use the same name as the name of the variable that stores the value of the parameter in the generator class.
Name	The name specifies the string which is displayed to the user as a label.
Description	The description will be displayed as a tool tip
requiresGUIRebuild	If set to true, the GUI will be rebuilt every time the value of this parameter is changed (e.g. the generator returns a different number of parameter objects then)
WidgetType	Controls how the parameter is displayed, e.g. as a text box or as a number spinner. Valid values are defined in the enumeration Parameter::WidgetType

Values of parameters can be retrieved via getValue() / getStringValue().

The following parameter classes are available:

ParameterClass	Type	WidgetType(s) allowed	Remark
ParameterWithIntValue	INTEGER	LINE_EDIT, SPINBOX	-
ParameterWithDoubleValue	DOUBLE	LINE_EDIT	-
ParameterWithBool	BOOL	CHECKBOX	-
ParameterWithChoice	vector of type string	LIST, COMBOBOX	-
ParameterWithStringValue	STRING	LINE_EDIT	-
ParameterCollection	Acts as a container for a set of parameters.	BUTTON	The parameters contained in the collection are displayed in a new panel when the button is clicked.

Creating a MarDyn generator:

In order to create this kind of generator, it is necessary to inherit MDGenerator class, which inherits the Generator class. MDGenerator class serves as an interface with abstract methods readPhaseSpaceHeader() and readPhaseSpace().

Generating the preview is to be done by forwarding the molecules from the particleContainer to the ScenarioGenerator class, whereas generating the output can be done using the CheckpointWriter from MarDyn.

MarDyn generators would typically have two types of parameters, parameters dealing with the Components and other parameters. For component parameters, one should use the ComponentParameters class, which is a collection of parameters defining a component and facilitates the change that occurs in them. For other parameters, please use defined parameter classes (see below).

Creating Objects

To visualize spherical objects, it is necessary to inherit the abstract Object class. This class provides an interface for drawing a sphere and representing an arbitrary scalar or vector value, where scalar values are represented as colors of the spheres (from blue to red), and vector values as arrows. It is also possible to combine both.

The class Object provides the following abstract methods which are to be implemented:

virtual vector<string> getDrawableValues()= 0; This method returns a vector of names of values whose drawing the class supports. These values will be displayed in the Combo Box in the main toolbar of the Scenario Generator.

virtual vtkSmartPointer<vtkActor> draw(string valueName) = 0; this method calls the corresponding function to draw the value with the given name. The name passed in as the argument has been obtained from the Combo Box and represents the users choice of the value to be drawn. Therefore, it is advised to implement an if – then – else going through all the value strings specified in getDrawableValues() and calling the corresponding method.\

Other important methods of class Object:

vtkSmartPointer<vtkActor> drawValue(Position& position, double value, double minValue, double maxValue, bool color); the function draws spheres on given positions, where the color depends on the value, where the value is in the [minValue, maxValue] range, and the boolean parameter color specifies if the value will be color encoded or not

vtkSmartPointer<vtkActor> drawVector(Position& position, Vector& v); draws a vector v as an arrow starting in the given position, with the length depending on the magnitude

Example of inheriting a class Object to create a class DummyObject:

The class DummyObject will enable drawing a Sphere with or without colors.

std::vector<std::string> DummyObject::getDrawableValues() {

		std::vector<std::string> v;
		v.push_back("Sphere"); // draws a sphere withouth a color
		v.push_back("Sphere ID"); // draws a sphere whose color represents the ID
		return v;
	

}

vtkSmartPointer<vtkActor> DummyObject::draw(string valueName){

		if (valueName == "Sphere"){
			return drawValue(_position, _id, 0, _numObjects, false); // false - no colors
		} else if (valueName == "Sphere ID"){
			return drawValue(_position, _id, 0, _numObjects, true); // true - draw colors
	

} }