Recent changes to Macro

Macro modified by Alberto Tonda

Alberto Tonda — Mon, 29 Jun 2015 15:06:30 -0000

--- v4
+++ v5
@@ -1,4 +1,6 @@
 # Macros
+
+Macros describe the possible values that a specific node can assume, inside the constrained tagged graph of µGP's individuals. Macros can feature fixed, immutable parts, and several parameters, that can be changed by the evolutionary algorithm.

 ## Attributes

Macro modified by Alberto Tonda

Alberto Tonda — Mon, 08 Jun 2015 10:05:04 -0000

--- v3
+++ v4
@@ -132,6 +132,7 @@
     [1]  
     [2]  
 </item>
+~~~~

 ## Examples

Macro modified by Giovanni Squillero

Giovanni Squillero — Mon, 13 Oct 2014 08:26:36 -0000

--- v2
+++ v3
@@ -2,13 +2,13 @@

 ## Attributes

-*id* The name of the macro  
+**id** The name of the macro  

-*weight* Relative chance for the macro to appear in the subsection. Whenever µGP must add a random macro, it decides which macro using a roulette wheel with each slice proportional in size to the *weight*. Defaults to 1.0.  
+**weight** Relative chance for the macro to appear in the subsection. Whenever µGP must add a random macro, it decides which macro using a roulette wheel with each slice proportional in size to the *weight*. Defaults to 1.0.  

 ## Expression

-The text of the macro. It is composed of a fixed text with some *parameters* (i.e., placeholders) that µGP will fill with appropriate values. Placeholders must refer to existing parameters through the *ref* attribute. For instance:
+The text of the macro. It is composed of a fixed text with some *parameters* (i.e., placeholders) that µGP will fill with appropriate values. Placeholders must refer to existing parameters through the *ref* attribute. For instance:

 ~~~~ xml
 <expression>
@@ -20,9 +20,9 @@
 </expression>
 ~~~~ 

-During the evolution, µGP will create values for parameters *foo* and *bar*. When the individual is dumped to a file, such placeholders would be replaced by the actual values.
+During the evolution, µGP will create values for parameters *foo* and *bar*. When the individual is dumped to a file, such placeholders would be replaced by the actual values.

-Please note that the first and last placeholders both refer to parameters *foo*. Thus, they will be filled with the same value. For instance, lets imagine that µGP picks the value **GROUCHO** for *foo*, and **HARPO** for *bar*. The resulting output would be:
+Please note that the first and last placeholders both refer to parameters *foo*. Thus, they will be filled with the same value. For instance, lets imagine that µGP picks the value **GROUCHO** for *foo*, and **HARPO** for *bar*. The resulting output would be:

 ~~~~ 
 Any number of lines free text
@@ -34,7 +34,7 @@

 ## Parameters

-µGP allows to specify the type of parameters in the *parameters* section.
+µGP allows to specify the type of parameters in the *parameters* section.

 ~~~~ xml
 <parameters>  
@@ -48,13 +48,13 @@

 ### Numeric Parameters

-*Integer* An integer number. The attributes defines the range: `minimum="''range start''"` and `maximum="''range end''"`. No defaults are provided. All attributes are compulsory. Example:  
+**Integer** An integer number. The attributes defines the range: `minimum="''range start''"` and `maximum="''range end''"`. No defaults are provided. All attributes are compulsory. Example:  

 ~~~~ xml
 <item name="dwarf" type="integer" minimum="1" maximum="7"/>
 ~~~~ 

-*Float* A floating point number. The attributes defines the range: `minimum="''range start''"` and `maximum="''range end''"`. No defaults are provided. All attributes are compulsory. Example:  
+**Float** A floating point number. The attributes defines the range: `minimum="''range start''"` and `maximum="''range end''"`. No defaults are provided. All attributes are compulsory. Example:  

 ~~~~ xml
 <item name="angle" type="float" minimum="0" maximum="3.141592653"/>
@@ -62,13 +62,13 @@

 ### String Parameters

-*Bit Arrays* An array of bits. The attribute `length="''len''"` specifies the number of bits in the array. The `pattern="''mask''"` attribute allows to specify a bit mask. For instance, `pattern="0--1"` will specify a bit array of 4 bits, with the first stuck to zero and the last stuck to one. The only available values of the parameter would be: `0001`, `0011`, `0101`, and `0111`. Indeed, this is terribly useful when the value is used to program a peripheral. Finally, it is possible to define which the numeric base is used to dump the array into the file: `base="''bin|oct|hex''"`. Example:  
+**Bit Arrays** An array of bits. The attribute `length="''len''"` specifies the number of bits in the array. The `pattern="''mask''"` attribute allows to specify a bit mask. For instance, `pattern="0--1"` will specify a bit array of 4 bits, with the first stuck to zero and the last stuck to one. The only available values of the parameter would be: `0001`, `0011`, `0101`, and `0111`. Indeed, this is terribly useful when the value is used to program a peripheral. Finally, it is possible to define which the numeric base is used to dump the array into the file: `base="''bin|oct|hex''"`. Example:  

 ~~~~ xml
 <item name="base_ascii" type="bitArray" length="8" pattern="0-------" base="hex"/>
 ~~~~ 

-*Constants* A constant string in a defined set. The elements `<value>''string''</value>` defines the possible values. Example:  
+**Constants** A constant string in a defined set. The elements `<value>''string''</value>` defines the possible values. Example:  

 ~~~~
 <item name="brother" type="constant">  
@@ -80,19 +80,19 @@
 </item>
 ~~~~ 

-*UniqueTag* A string guaranteed to be unique in the current run. It may be useful to create loops (jumps) or variables. No attributes. Example:  
+**UniqueTag** A string guaranteed to be unique in the current run. It may be useful to create loops (jumps) or variables. No attributes. Example:  

 ~~~~ xml
 <item name="dest" type="uniqueTag"/>
 ~~~~

-*Environment* The value of a variable in the operating environment[1](http://en.wikipedia.org/wiki/Environment_variable). It may be useful to link the behavior to the operating system condition, or to tweak the evolution from the external. The attribute `variable="''var''"` specifies the name of the variable. Example:  
+**Environment** The value of a variable in the operating environment[1](http://en.wikipedia.org/wiki/Environment_variable). It may be useful to link the behavior to the operating system condition, or to tweak the evolution from the external. The attribute `variable="''var''"` specifies the name of the variable. Example:  

 ~~~~ xml
 <item name="os_info" type="environment" variable="TERM"/>
 ~~~~

-*SelfRef* The name of the very same macro instance. No attributes.  
+**SelfRef** The name of the very same macro instance. No attributes.  

 ~~~~ xml
 <item name="ego" type="selfRef"/>
@@ -103,19 +103,19 @@
 Parameters can specify a reference to a different macro inside the same
 subsection. This is usually used to implement branches and jumps.

-*innerGenericLabel* A reference to a generic macro. The attribute `prologue="''true|false''"` specifies if the prologue may be a potential target, while the attribute `epilogue="''true|false''"` specifies if the epilogue may be a potential target. This can be useful because the prologue may be used to define the header of functions, with a peculiar *label format*, and try to jump to it would generate a syntax error. Finally, the attribute `itself="''true|false''"` specifies if the macro itself may be a potential target. Example:  
+**innerGenericLabel** A reference to a generic macro. The attribute `prologue="''true|false''"` specifies if the prologue may be a potential target, while the attribute `epilogue="''true|false''"` specifies if the epilogue may be a potential target. This can be useful because the prologue may be used to define the header of functions, with a peculiar *label format*, and try to jump to it would generate a syntax error. Finally, the attribute `itself="''true|false''"` specifies if the macro itself may be a potential target. Example:  

 ~~~~ xml
 <item name="free_jump" type="innerGenericLabel" prologue="false" epilogue="true" itself="false"/>
 ~~~~ 

-*innerBackwardLabel* A reference to a preceding macro. The attribute `prologue="''true|false''"` specifies if the prologue may be a potential target, while the attribute `itself="''true|false''"` specifies if the macro itself may be a potential target. Example:  
+**innerBackwardLabel** A reference to a preceding macro. The attribute `prologue="''true|false''"` specifies if the prologue may be a potential target, while the attribute `itself="''true|false''"` specifies if the macro itself may be a potential target. Example:  

 ~~~~ xml
 <item name="back_jump" type="innerBackwardLabel" prologue="false" itself="true"/>
 ~~~~

-*innerForwardLabel* A reference to a following macro. The attribute `epilogue="''true|false''"` specifies if the epilogue may be a potential target, while the attribute `itself="''true|false''"` specifies if the macro itself may be a potential target. Useful to createa code with no loops. Example:  
+**innerForwardLabel** A reference to a following macro. The attribute `epilogue="''true|false''"` specifies if the epilogue may be a potential target, while the attribute `itself="''true|false''"` specifies if the macro itself may be a potential target. Useful to createa code with no loops. Example:  

 ~~~~ xml
 <item name="safe_jump" type="innerForwardLabel" epilogue="true" itself="false"/>
@@ -125,7 +125,7 @@

 Parameters can specify a reference to a different subsection. Inter-section references always refers to the prologue of the subsection.

-*outerLabel* A reference to a different subsection. The elements `<ref>` defines the list of possible targets. Each one has the attribute `section="''section name''"` that specifies the name of the target section, and the attribute `subsection="''subsection name''"` that specifies the name of the target subsection inside the specified section. Remember that more instances of the same subsection may exists in the a section. Example:  
+**outerLabel** A reference to a different subsection. The elements `<ref>` defines the list of possible targets. Each one has the attribute `section="''section name''"` that specifies the name of the target section, and the attribute `subsection="''subsection name''"` that specifies the name of the target subsection inside the specified section. Remember that more instances of the same subsection may exists in the a section. Example:  

 ~~~~ xml
 <item name="call" type="outerLabel">

Macro modified by Giovanni Squillero

Giovanni Squillero — Mon, 13 Oct 2014 08:25:31 -0000

--- v1
+++ v2
@@ -2,9 +2,9 @@

 ## Attributes

-id : The name of the macro  
+*id* The name of the macro  

-weight : Relative chance for the macro to appear in the subsection. Whenever µGP must add a random macro, it decides which macro using a roulette wheel with each slice proportional in size to the *weight*. Defaults to 1.0.  
+*weight* Relative chance for the macro to appear in the subsection. Whenever µGP must add a random macro, it decides which macro using a roulette wheel with each slice proportional in size to the *weight*. Defaults to 1.0.  

 ## Expression

@@ -48,13 +48,13 @@

 ### Numeric Parameters

-Integer : An integer number. The attributes defines the range: `minimum="''range start''"` and `maximum="''range end''"`. No defaults are provided. All attributes are compulsory. Example:  
+*Integer* An integer number. The attributes defines the range: `minimum="''range start''"` and `maximum="''range end''"`. No defaults are provided. All attributes are compulsory. Example:  

 ~~~~ xml
 <item name="dwarf" type="integer" minimum="1" maximum="7"/>
 ~~~~ 

-Float : A floating point number. The attributes defines the range: `minimum="''range start''"` and `maximum="''range end''"`. No defaults are provided. All attributes are compulsory. Example:  
+*Float* A floating point number. The attributes defines the range: `minimum="''range start''"` and `maximum="''range end''"`. No defaults are provided. All attributes are compulsory. Example:  

 ~~~~ xml
 <item name="angle" type="float" minimum="0" maximum="3.141592653"/>
@@ -62,13 +62,13 @@

 ### String Parameters

-Bit Arrays : An array of bits. The attribute `length="''len''"` specifies the number of bits in the array. The `pattern="''mask''"` attribute allows to specify a bit mask. For instance, `pattern="0--1"` will specify a bit array of 4 bits, with the first stuck to zero and the last stuck to one. The only available values of the parameter would be: `0001`, `0011`, `0101`, and `0111`. Indeed, this is terribly useful when the value is used to program a peripheral. Finally, it is possible to define which the numeric base is used to dump the array into the file: `base="''bin|oct|hex''"`. Example:  
+*Bit Arrays* An array of bits. The attribute `length="''len''"` specifies the number of bits in the array. The `pattern="''mask''"` attribute allows to specify a bit mask. For instance, `pattern="0--1"` will specify a bit array of 4 bits, with the first stuck to zero and the last stuck to one. The only available values of the parameter would be: `0001`, `0011`, `0101`, and `0111`. Indeed, this is terribly useful when the value is used to program a peripheral. Finally, it is possible to define which the numeric base is used to dump the array into the file: `base="''bin|oct|hex''"`. Example:  

 ~~~~ xml
 <item name="base_ascii" type="bitArray" length="8" pattern="0-------" base="hex"/>
 ~~~~ 

-Constants : A constant string in a defined set. The elements `<value>''string''</value>` defines the possible values. Example:  
+*Constants* A constant string in a defined set. The elements `<value>''string''</value>` defines the possible values. Example:  

 ~~~~
 <item name="brother" type="constant">  
@@ -80,19 +80,19 @@
 </item>
 ~~~~ 

-UniqueTag : A string guaranteed to be unique in the current run. It may be useful to create loops (jumps) or variables. No attributes. Example:  
+*UniqueTag* A string guaranteed to be unique in the current run. It may be useful to create loops (jumps) or variables. No attributes. Example:  

 ~~~~ xml
 <item name="dest" type="uniqueTag"/>
 ~~~~

-Environment : The value of a variable in the operating environment[1](http://en.wikipedia.org/wiki/Environment_variable). It may be useful to link the behavior to the operating system condition, or to tweak the evolution from the external. The attribute `variable="''var''"` specifies the name of the variable. Example:  
+*Environment* The value of a variable in the operating environment[1](http://en.wikipedia.org/wiki/Environment_variable). It may be useful to link the behavior to the operating system condition, or to tweak the evolution from the external. The attribute `variable="''var''"` specifies the name of the variable. Example:  

 ~~~~ xml
 <item name="os_info" type="environment" variable="TERM"/>
 ~~~~

-SelfRef : The name of the very same macro instance. No attributes.  
+*SelfRef* The name of the very same macro instance. No attributes.  

 ~~~~ xml
 <item name="ego" type="selfRef"/>
@@ -103,19 +103,19 @@
 Parameters can specify a reference to a different macro inside the same
 subsection. This is usually used to implement branches and jumps.

-innerGenericLabel : A reference to a generic macro. The attribute `prologue="''true|false''"` specifies if the prologue may be a potential target, while the attribute `epilogue="''true|false''"` specifies if the epilogue may be a potential target. This can be useful because the prologue may be used to define the header of functions, with a peculiar *label format*, and try to jump to it would generate a syntax error. Finally, the attribute `itself="''true|false''"` specifies if the macro itself may be a potential target. Example:  
+*innerGenericLabel* A reference to a generic macro. The attribute `prologue="''true|false''"` specifies if the prologue may be a potential target, while the attribute `epilogue="''true|false''"` specifies if the epilogue may be a potential target. This can be useful because the prologue may be used to define the header of functions, with a peculiar *label format*, and try to jump to it would generate a syntax error. Finally, the attribute `itself="''true|false''"` specifies if the macro itself may be a potential target. Example:  

 ~~~~ xml
 <item name="free_jump" type="innerGenericLabel" prologue="false" epilogue="true" itself="false"/>
 ~~~~ 

-innerBackwardLabel : A reference to a preceding macro. The attribute `prologue="''true|false''"` specifies if the prologue may be a potential target, while the attribute `itself="''true|false''"` specifies if the macro itself may be a potential target. Example:  
+*innerBackwardLabel* A reference to a preceding macro. The attribute `prologue="''true|false''"` specifies if the prologue may be a potential target, while the attribute `itself="''true|false''"` specifies if the macro itself may be a potential target. Example:  

 ~~~~ xml
 <item name="back_jump" type="innerBackwardLabel" prologue="false" itself="true"/>
 ~~~~

-innerForwardLabel : A reference to a following macro. The attribute `epilogue="''true|false''"` specifies if the epilogue may be a potential target, while the attribute `itself="''true|false''"` specifies if the macro itself may be a potential target. Useful to createa code with no loops. Example:  
+*innerForwardLabel* A reference to a following macro. The attribute `epilogue="''true|false''"` specifies if the epilogue may be a potential target, while the attribute `itself="''true|false''"` specifies if the macro itself may be a potential target. Useful to createa code with no loops. Example:  

 ~~~~ xml
 <item name="safe_jump" type="innerForwardLabel" epilogue="true" itself="false"/>
@@ -125,7 +125,7 @@

 Parameters can specify a reference to a different subsection. Inter-section references always refers to the prologue of the subsection.

-outerLabel : A reference to a different subsection. The elements `<ref>` defines the list of possible targets. Each one has the attribute `section="''section name''"` that specifies the name of the target section, and the attribute `subsection="''subsection name''"` that specifies the name of the target subsection inside the specified section. Remember that more instances of the same subsection may exists in the a section. Example:  
+*outerLabel* A reference to a different subsection. The elements `<ref>` defines the list of possible targets. Each one has the attribute `section="''section name''"` that specifies the name of the target section, and the attribute `subsection="''subsection name''"` that specifies the name of the target subsection inside the specified section. Remember that more instances of the same subsection may exists in the a section. Example:  

 ~~~~ xml
 <item name="call" type="outerLabel">  
@@ -164,10 +164,3 @@
 Hey, this is a floating point number between 0 and 1: 0.999999
 ...
 ~~~~
-
-Check [How to write population's constraints](How to write population's constraints "wikilink") for a
-complete example of top-down construction of population's constraints.
-
-[1] 
-
-[2]

Macro modified by Giovanni Squillero

Giovanni Squillero — Mon, 13 Oct 2014 08:19:09 -0000

Macros

Attributes

id : The name of the macro

weight : Relative chance for the macro to appear in the subsection. Whenever µGP must add a random macro, it decides which macro using a roulette wheel with each slice proportional in size to the weight. Defaults to 1.0.

Expression

The text of the macro. It is composed of a fixed text with some parameters (i.e., placeholders) that µGP will fill with appropriate values. Placeholders must refer to existing parameters through the ref attribute. For instance:

<expression>
    Any number of lines free text
    Any number of lines free text
    These are two placeholders `<param ref="foo"/>` and `<param ref="bar"/>`!
    More free text (if needed)
    The last parameter: `<param ref="foo"/>` (please note that it uses the same "ref" as the first one)
</expression>

During the evolution, µGP will create values for parameters foo and bar. When the individual is dumped to a file, such placeholders would be replaced by the actual values.

Please note that the first and last placeholders both refer to parameters foo. Thus, they will be filled with the same value. For instance, lets imagine that µGP picks the value GROUCHO for foo, and HARPO for bar. The resulting output would be:

Any number of lines free text
Any number of lines free text
These are two placeholders GROUCHO and HARPO!
More free text (if needed)
The last parameter: GROUCHO (please note that it uses the same "ref" as the first one)

Parameters

µGP allows to specify the type of parameters in the parameters section.

<parameters>  
    <item name="''ref1''" type="''type''" ''parameter definition attributes'' />  
    <item name="''ref2''" type="''type''" ''parameter definition attributes'' />  
    ...  
</parameters>

All parameters are characterized by a name and a type. Other attributes depend on the type. The name of the parameters must match the ref inside the expression.

Numeric Parameters

Integer : An integer number. The attributes defines the range: minimum="''range start''" and maximum="''range end''". No defaults are provided. All attributes are compulsory. Example:

<item name="dwarf" type="integer" minimum="1" maximum="7" />

Float : A floating point number. The attributes defines the range: minimum="''range start''" and maximum="''range end''". No defaults are provided. All attributes are compulsory. Example:

<item name="angle" type="float" minimum="0" maximum="3.141592653" />

String Parameters

Bit Arrays : An array of bits. The attribute length="''len''" specifies the number of bits in the array. The pattern="''mask''" attribute allows to specify a bit mask. For instance, pattern="0--1" will specify a bit array of 4 bits, with the first stuck to zero and the last stuck to one. The only available values of the parameter would be: 0001, 0011, 0101, and 0111. Indeed, this is terribly useful when the value is used to program a peripheral. Finally, it is possible to define which the numeric base is used to dump the array into the file: base="''bin|oct|hex''". Example:

<item name="base_ascii" type="bitArray" length="8" pattern="0-------" base="hex" />

Constants : A constant string in a defined set. The elements <value>''string''</value> defines the possible values. Example:

<item name="brother" type="constant">  
    <value>`CHICO`</value>
    <value>`HARPO`</value>  
    <value>`GROUCHO`</value>  
    <value>`GUMMO`</value>  
    <value>`ZEPPO`</value>  
</item>

UniqueTag : A string guaranteed to be unique in the current run. It may be useful to create loops (jumps) or variables. No attributes. Example:

<item name="dest" type="uniqueTag" />

Environment : The value of a variable in the operating environment1. It may be useful to link the behavior to the operating system condition, or to tweak the evolution from the external. The attribute variable="''var''" specifies the name of the variable. Example:

<item name="os_info" type="environment" variable="TERM" />

SelfRef : The name of the very same macro instance. No attributes.

<item name="ego" type="selfRef" />

Intra-section References

Parameters can specify a reference to a different macro inside the same
subsection. This is usually used to implement branches and jumps.

innerGenericLabel : A reference to a generic macro. The attribute prologue="''true|false''" specifies if the prologue may be a potential target, while the attribute epilogue="''true|false''" specifies if the epilogue may be a potential target. This can be useful because the prologue may be used to define the header of functions, with a peculiar label format, and try to jump to it would generate a syntax error. Finally, the attribute itself="''true|false''" specifies if the macro itself may be a potential target. Example:

<item name="free_jump" type="innerGenericLabel" prologue="false" epilogue="true" itself="false" />

innerBackwardLabel : A reference to a preceding macro. The attribute prologue="''true|false''" specifies if the prologue may be a potential target, while the attribute itself="''true|false''" specifies if the macro itself may be a potential target. Example:

<item name="back_jump" type="innerBackwardLabel" prologue="false" itself="true" />

innerForwardLabel : A reference to a following macro. The attribute epilogue="''true|false''" specifies if the epilogue may be a potential target, while the attribute itself="''true|false''" specifies if the macro itself may be a potential target. Useful to createa code with no loops. Example:

<item name="safe_jump" type="innerForwardLabel" epilogue="true" itself="false" />

Inter-section References

Parameters can specify a reference to a different subsection. Inter-section references always refers to the prologue of the subsection.

outerLabel : A reference to a different subsection. The elements <ref> defines the list of possible targets. Each one has the attribute section="''section name''" that specifies the name of the target section, and the attribute subsection="''subsection name''" that specifies the name of the target subsection inside the specified section. Remember that more instances of the same subsection may exists in the a section. Example:

<item name="call" type="outerLabel">  
    [1]  
    [2]  
</item>

## Examples

If you'd like your individuals to contain a portion of text like:

`Hey, this is a floating point number between 0 and 1: 0.563986`

The appropriate syntax will be something like this:

<macro id="hey" weight="1">
<expression>Hey, this is a floating point number between 0 and 1:<param ref="p"/></expression>
<parameters>
<item name="p" type="float" minimum="0" maximum="1"/>
<parameters/>
</macro>

The <macro> tag has two parameters, id (unique name of the macro in the constraints file) and weight (the relative frequency of appearance of instances of the macro in the individuals).

The <expression> tag defines the macro expression. The fixed parts are reported as they are, while the parameters (tag <param> must be specified in the <parameters> tag.

In this case, there is only one parameter, called "p". The parameter is of type float (floating point number),and it can assume a minimum value of 0, and a maximum value of 1. Note that the special value infinity is also possible, to have unconstrained floating point numbers.

Instances of the macro above might be:

Hey, this is a floating point number between 0 and 1: 0.563986
Hey, this is a floating point number between 0 and 1: 0.012345
Hey, this is a floating point number between 0 and 1: 0.999999
...

Check How to write population's constraints for a
complete example of top-down construction of population's constraints.

[1]

[2]