Getting Started with GraphSynth

Installing

First download either the

executable version or the

source code. If you do not have Visual Studio 2005 installed on your
computer (or C# Express Edition) you will need the exe-version. Unzip the
folder to an easy to remember location, open it, and double-click the setup.exe
file. This should install GraphSynth under your usual list of programs (seems
to work fine for XP and Vista; other operating systems are unknown). It
will likely appear in a folder under the manufacturer of the software which
in this case is our research lab , "UT Automated Design Lab."

Running for the First Time

In either version, running for the first time will produce the following
display (to the right).

You must create a configuration file in order to
proceed - clicking No will simply exit the program. NOTE: the dialog
box will only appear below the welcome screen. I know it's frustrating but
there doesn't seem to be a way to fix it.

Once you click "Yes", the setting window will appear.
Don't be intimidated by the number of options here. The default values will
tend to work fine, and can always be adjusted from the "Settings" entry
on the File drop-down (also through Alt+S).

 

 

But, before you close this window, you should first get
to the Directories tab and set the working directory. The default will likely
work if you are using the source code version, but not for the executable
versions. Click on the "working directory" button and make your way back
to the directory that contains the input,
output and rules sub-directories.

Once you set this, then you can save the settings
to a file (the default location is perfect) and "Apply in this process"
to launch the application. Again, these settings are always available from
the File menu.

Now, you're up and running. But the stark window you're presented with can
be daunting. I recommend opening the rules and seeds discussed in
Examples to help get you started.

In order to run a search process or even a manual Recognize→User
Choose →Apply process from the Design
drop down, you will need to set which graph that is opened is to be your
seed, and which rulesets are to be used.

 

NOTE: clicking the "Run Search Process" button will only work for
the Swirl example problem.

It implements a Greedy-Search through the search tree for the biggest
swirl with 15 nodes. If you are not running the source code then you likely
won't understand this. To date, a complex search (ala Genetic Algorithms,
or A*) can only be accomplished by getting your hands dirty with the code.

Finding your way around the source code

So, you're ready to get your hands dirty, then? Well, welcome aboard.
The section at the top of the navigation page
will explain a little more what mess of files are in front of you. You probably
will want to look at the file called searchProcess.cs under the
Application_UI_and_Search project. This includes a Breadth-First Search,
a Depth First Search and a Best First Search. I have the program set up
so that opening and manipulating files in lower folders (e.g. the MainFormsAndSettings
folder) are discouraged. Most research and development can be done by changing
only the following source code files:

1. searchProcess.cs in the Application_UI_and_Search project.
2. EvaluateSwirls.cs in the Evaluation project (or any appropriate
   evaluation routine for your problem).
3. randomChoose.cs/randomChoose.csWithUndo.cs/

   RecognizeChooseApply.cs

   in the Generation project

4. graphLayout.cs in the Graph Layout project - here you can
   create custom layout algorithms for your graphs.
5. PNPPS.cs in the Guidance project - this is an approach
   to sorting and truncating lists of candidates, but other sorting or
   "tournament selection" approaches can/should be placed here.
6. inheritedGraphClasses.cs in the Representation project
   - classes can inherit from node and
   arc classes and these can be stored
   here.

Prof. Matt Campbell (mc1@mail.utexas.edu)

Friday, August 13, 2010

Occasionally, there are requirements to create additional recognition or application operations for a rule. There is no meta-language to do this, but there is a template for writing any C# functions as extra abilities of the rules.

can write functions l a search plugin for use in GraphSynth2, you first open Visual Studio, choose "New Project" and then choose "Class Library". Your plugin will be compiled to a .DLL file which GraphSynth2 will find in a prescribed directory. One project (.DLL) file may have any number of plugins within it. Take a moment to think of a good name now for your project. Don't let it be, ClassLibrary1. Be verbose!

2. Under the project (in the solution explorer), right-click on References and select "Add Reference". When the pop-up opens. Browse to C:\Program Files\GraphSynth2, and select two class libraries (.DLLs):

a. GraphSynth.FundamentalClassesAndInterfaces

b. GraphSynth.Representation

Optionally, you can choose to reference StarMath as well. This is a custom-made matrix library developed in a parallel project (see http://starmath.codeplex.com/).

3. Now for any plugin you would like to create. Add a new class (or use an existing class), and:

a. add “using GraphSynth;”

b. add “using GraphSynth.Search;”

c. add “using GraphSynth.Representation;”

d. optionally add “using StarMathLib;”

(You can download this as a pdf here.)

1. One of the hardest parts about GraphSynth is learning how to write plugins that will do something interesting with the GraphSynth objects: graphs, rulesets, and rules. To create a search plugin for use in GraphSynth2, you first open Visual Studio, choose "New Project" and then choose "Class Library". Your plugin will be compiled to a .DLL file which GraphSynth2 will find in a prescribed directory. One project (.DLL) file may have any number of plugins within it. Take a moment to think of a good name now for your project. Don't let it be, ClassLibrary1. Be verbose!

2. Under the project (in the solution explorer), right-click on References and select "Add Reference". When the pop-up opens. Browse to C:\Program Files\GraphSynth2, and select two class libraries (.DLLs):

a. GraphSynth.FundamentalClassesAndInterfaces

b. GraphSynth.Representation

Optionally, you can choose to reference StarMath as well. This is a custom-made matrix library developed in a parallel project (see http://starmath.codeplex.com/).

3. Now for any plugin you would like to create. Add a new class (or use an existing class), and:

• a. add “using GraphSynth;”
• b. add “using GraphSynth.Search;”
• c. add “using GraphSynth.Representation;”
• d. optionally add “using StarMathLib;”
• e. to the class declaration, make it inherited from SearchProcess.

For example:

“public class Plugin1 : SearchProcess”

4. It helps to “Go To Definition” (shortcut F12) for SearchProcess and see what type of details you are inheriting. Eventually, when GraphSynth2 scans your folder it will be searching for classes that inherit from SearchProcess.

5. Type override in the new class. You’ll see five things that can be overridden in the base class, SearchProcess. Of course, Equals(object obj), GetHashCode(), and ToString() are universal to any object. But what stands out is “string text { get; }” and “void Run()”. You must override both of these – otherwise the code will not compile. “text” is the string you would like to appear in the drop down menu; and the Run function is where your plugin starts. The “text” string can include whitespaces and special characters, but should probably be kept under 50 characters.

6. There are two additional things to understand. The first is using properties and methods from the base class. Since the Run() function receives nothing and returns nothing, how do we interact with the program? When your plugin is loaded, it is given access to several important objects in GraphSynth. These can be accessed by simply typing them in the Run method, or any non-static method within this plugin class.

• a. optimize OptimizeDirection : You can set a direction used by all performance parameters within a candidate. This is not a necessity, and your specific search process might require some performance parameters to be maximized while others are minimized. “optimize” is an enumerator that can be set to minimize or maximize.
• b. designGraph seedGraph : This retrieves whatever graph is set as the seed in GraphSynth2.
• c. candidate seedCandidate : Simliar to seedGraph, the seedCandidate is simply a new candidate object wrapped around the seedGraph.
• d. ruleSet[] rulesets : The rulesets set in GraphSynth2 are accessed by this array.
• e. ISettings settings : There are various other important settings that one can set in GraphSynth2
  (under Edit->Settings, and in a loaded .gsconfig file) and these can be read here. These include:
  • 1. string settings.workingDirectory
  • 2. string settings.helpDirectory
  • 3. string settings.inputDirectory
  • 4. string settings.outputDirectory
  • 5. string settings.compiledparamRules : the location of the .DLL file that accompanies rules if additional functions are loaded for these rules.
  • 6. string defaultSeedFileName
  • 7. int defaultVerbosity
  • 8. int maxRulesToApply : the maximum number of rules to apply. This is up to you to use. It will not limit your generation of designs unless you choose to use it in a condition.
  • 9. int maxRulesToDisplay : likewise to the above. This is mainly used by the User Choose dialog plugin.
  • 10. int numOfRuleSets : The number of rulesets – the same as rulesets.GetLength(0);
  • 11. bool recompileRules : When true, a new compiledparamRules file will be created with every run of the plugin.
• f. The following are methods that can be used by the plugin.
  void Save(string filename, object o) saves the object (graph, rule, ruleset, or graphWindow, or ruleWindow) to a file named filename. Filename must be rooted (i.e. global).
• g. object[] Open(string filename) returns the contents of the filename (again must be a rooted/global filename).
• 1. if you are opening a .gxml file
  • object[0] will be a designGraph
  • object[1] will be the canvas properties for the graph
  • object[2] will be the filename
• 2. if you are opening a .grxml file
  • object[0] will be a grammarRule
  • object[1] will be the canvas properties for the rule
  • object[2] will be the filename
• 3. if you are opening a .rsxml file
  • object[0] will be a ruleset
• h. void addChildToSortedCandList(List<candidate> candidates, candidate child) : Adds the child to the sorted candidate list based on the value of f0 (performanceParams[0]). The OptimizeDirection is not used as the list is always sorted from lowest to highest.
• i. void addNewCandtoPareto(candidate c, List<candidate> ParetoCands) : Adds the new candidate to the pareto set defined as ParetoCands. The result may be 1) nothing (c is not added), 2) c is added to the list if it is not dominated by any members of ParetoCands, or 3) c is added and elements of ParetoCands are removed because they are dominated by c.
• j. bool dominates(candidate c1, candidate c2) : is a function used by the above. Does c1 dominate c2? By dominates we are referring to how optimizeDirection was set.
• k. bool dominates(candidate c1, candidate c2, optimize[] optDirections) : if optimizeDirection was not set or if it is different for the different performanceParams of the candidates than this version may be used.
• l. int nextRuleSet(int ruleSetIndex, GenerationStatuses status) : A helper function to RecognizeChooseApplyCycle. This function returns what the new ruleSet will be. Here the enumerator nextGenerationSteps and GenerationStatuses is used to great effect. Understand that if a negative number is returned, the cycle will be stopped.
• m. void transferLmappingToChild(designGraph child, designGraph current, designGraph Lmapping) : A necessary function when multiple (more than one) application of a rule is applied to a host. The function reads in the child graph (often a copy of the current), the current graph, and the Lmapping. The Lmapping is changed but the child and current are unaffected.

7. The second issue is enabling and disabling your plugin. While you no longer have to define a constructor, it may be a good idea to, in order to better control how and when your plugin starts. A constructor for your plugin could look like this:

public Plugin1()
{
AutoPlay = false;
RequireSeed = true;
RequiredNumRuleSets = 3;
}

These three properties control the how and when. The default for AutoPlay is, in fact, false; and the default for RequireSeed is, in fact, true. So, in reality one wouldn’t need to define these since they are the defaults. AutoPlay means that the plugin will start automatically (no need to press the play button), and RequireSeed means that the plugin will be disabled until a seed is defined. Finally, the RequiredNumRuleSets as the name implies, sets the number of rulesets that need to be defined before the plugin will be active. It is possible to set this to zero. This is common in cases where the plugin simply manipulates qualities of the seed, or loads in its own files. If it is not defined in a constructor then the default value is either 1 or the number of rulesets defined in the settings (whichever is larger).

8. Finally, running and debugging your plugin. After you write a little code, you will want to see if your plugin is functioning correctly. Since your project is not an executable, it won’t run on its own. You’ll need to go to the properties for the project (right-click on the project and choose the last item “Properties”). Under the fourth tab, Debug, you need to set the “Start external program:” to the GraphSynth executable. It will likely have the path “C:\Program Files\GraphSynth2\GraphSynth.exe” (see attached screenshot).

Now, when you can run GraphSynth2 from Visual Studio. After GraphSynth2 starts you may be disappointed to find that the plugin has not been loaded. This is because you still need to tell GraphSynth2 where to find your plugin. Under Edit->Settings in GraphSynth2, find the Search Plugins under the second tab labeled “Directories”. Choose a directory that contains your plugin. GraphSynth will recursively search the entire directory to find your plugin, so you don’t need to dig down so far. However if you choose something like “C:\Users”, GraphSynth2 will likely hang for some time.

That’s it! Your plugin can be as large as you want with as many additional classes and files that you want. Now you’re all set to write some impressive generative grammar algorithms. Enjoy.

this page is a mirror of the file found in the source code: GraphSynth/GraphSynthSourceFiles/Resources/RunningGSFromSource.htm

Recent changes allow one to run GraphSynth as a console application or with
"Windows Presentation Foundation" Graphics in a rich GUI that allows for
viewing, editing, and testing different graph and rule concepts. The Console
approach is useful for running on experiments where the rules, rulesets, ang
other graphs do not need to be edited. The final results can still be saved to
new graph and candidate files. The premise of the code is that you will run a
particular search plugin on the loaded seed and rulesets.
This method also allows one to run GraphSynth on Linux or Apple computers.

In the current GraphSynth.sln setup, there are four solution folders (note:
solution folders are not fully supported in Express Editions). The "Solution
Items" folder (which will definitely not show up in Express editions), contains
this file, and other assorted data, icon, and text files. Then you will note the
"Console Version" (includes 3 projects), the "WPF GUI Version" (includes 4
projects), and the "Default Plugins" folders (includes 2 projects). This
structure of nine projects is slightly different from what you see in the actual
folders. This is becuase BaseClasses and Representation projects are nearly the
same for the console and gui versions - mostly the differences lie in settings
in the .csproj files. The default plugins only work in the gui-version since
these involve some interactive and visualization elements.

Instructions on Running GraphSynth in the Console

This involves the three projects listed here:

• GraphSynthConsole
• GraphSynthConsole.Representation
• GraphSynthConsole.BaseClasses

all the other projects can be ignored/removed.

This has been greatly simplified from the version posted in early September
(9/2011). All binaries are written to the common bin directory. 

Procedure:

1. Set GraphSynthConsole as the start-up project - this is optional now
   • right-click on the GraphSynthConsole project in the Solution Explorer and select
     "Set as StartUp Project"
   • why is this optional? if you have the GraphSynth gui-version as the default it
     will work anyway since all binaries are written to the same bin directory and
     the exectubles have the same name: GraphSynth.exe.
2. Change the Solution Configuration to "Console Debug"
   • right-click on the solution in the Solution Explorer (very first item, "Solution
     'GraphSynth' (9 projects)."
   • select "Configuration Manager..."
   • In the upper-left drop-down menu entitled, "Active solution configuration:"
     choose "Console Debug"
   • an easier way to do this is simply choose "Console Debug" in the drop-down
     attached to the Standard toolbar.
3. if you just change Solution Configuration - make sure you re-build!
   This is because binaries may not seem out-of-date to Visual Studio, since they
   are all in the same directory.

Running the Application

This simply loads the same settings file (*.gsconfig file) that is used in the
full version. You can also supply an alternative .gsconfig file. Again, the
premise is simply to run plugins on the loaded seed and rulesets. Choose which
   plugin to run...and that's it. Verbosity may be changed at the onset but not
during the process.

 

Instructions on Running GraphSynth as a Windows GUI application

This involves
the four projects listed here:

• GraphSynth
• GraphSynth.CustomControls
• GraphSynth.Representation
• GraphSynth.BaseClasses

but the compilation can also make use of the two default plugins:

• GraphSynth.GraphLayoutBasic
• GraphSynth.UserRandLindChoose

Procedure:

1. Set GraphSynth as the start-up project - this is optional now
   • right-click on the GraphSynth project in the Solution Explorer and select
     "Set as StartUp Project"
   • why is this optional? if you have the GraphSynthConsole-version as the default
     it will work anyway since all binaries are written to the same bin directory and
     the exectubles have the same name: GraphSynth.exe.
2. Change the Solution Configuration to "WPF GUI Debug"
   • right-click on the solution in the Solution Explorer (very first item, "Solution
     'GraphSynth' (9 projects)."
   • select "Configuration Manager..."
   • In the upper-left drop-down menu entitled, "Active solution configuration:"
     choose "WPF GUIDebug"
   • an easier way to do this is simply choose "WPF GUIDebug" in the drop-down
     attached to the Standard toolbar.
3. if you just change Solution Configuration - make sure you re-build!
   This is because binaries may not seem out-of-date to Visual Studio, since they
   are all in the same directory.

Running the Application

This opens the GUI windows and any files specificed in the default
   GraphSynthSettings.gsconfig file. For more information on using the program see
http://www.GraphSynth.com/help.

 

Please send any concerns to 
admin@GraphSynth.com