<title>Writing new rules</title>

<h3>Writing new rules</h3>

As a first step, try changing the parameters of some of the rules. This can give very different behavior. Read <a href="http://mrob.com/pub/comp/xmorphia/">Robert Munafo's pages</a> about Gray-Scott, for example, and try out some of the parameters he discusses on this pattern: <a href="open:Patterns/GrayScott1984/self-replicating_spots.vti">GrayScott1984/self-replicating_spots.vti</a>.

<h4>Formulas and kernel rules</h4>

Ready also allows you to reprogram rules completely. For formula and kernel rules, hit 'edit' next to the formula/kernel and then see what effect your change has. Some changes will cause an error when you try to run or step forward, and will show you a message box saying what went wrong.

Keywords for formula rules on images:

<table border="1" cellpadding="5">

<tr><td>laplacian_a</td><td>A <a href="https://en.wikipedia.org/wiki/Laplace_operator">Laplacian kernel</a> applied to chemical 'a' (or 'b', etc.).</td></tr>

<tr><td>bilaplacian_a</td><td>A <a href="https://en.wikipedia.org/wiki/Biharmonic_equation">bi-Laplacian kernel</a> applied to chemical 'a' (or 'b', etc.). Equivalent to applying the Laplacian kernel twice.</td></tr>

<tr><td>trilaplacian_a</td><td>A tri-Laplacian kernel applied to chemical 'a' (or 'b', etc.). Equivalent to applying the Laplacian kernel three times.</td></tr>

<tr><td>gaussian_a</td><td>A <a href="https://en.wikipedia.org/wiki/Gaussian_filter">Gaussian kernel</a> of sigma=1 applied to chemical 'a' (or 'b', etc.).</td></tr>

<tr><td>sobelN_a, sobelE_a, sobelNE_a, etc.</td><td>A <a href="https://en.wikipedia.org/wiki/Sobel_operator">Sobel filter</a> applied to chemical 'a' (or 'b', etc.) pointing in the compass directions.</td></tr>

<tr><td>x_gradient_a</td><td>The <a href="https://en.wikipedia.org/wiki/Image_gradient">gradient</a> of chemical 'a' (or 'b', etc.) in the x-direction.</td></tr>

<tr><td>y_gradient_a</td><td>The gradient of chemical 'a' (or 'b', etc.) in the y-direction.</td></tr>

<tr><td>z_gradient_a</td><td>The gradient of chemical 'a' (or 'b', etc.) in the z-direction.</td></tr>

<tr><td>x_deriv2_a, etc.</td><td>The second derivative of chemical 'a' (or 'b', etc.) in the x-direction (or y, or z).</td></tr>

<tr><td>x_deriv3_a, etc.</td><td>The third derivative of chemical 'a' (or 'b', etc.) in the x-direction (or y, or z).</td></tr>

<tr><td>gradient_mag_squared_a</td><td>The squared magnitude of the gradient of chemical 'a' (or 'b', etc.). For a 2D pattern this is equal to x_gradient_a^2 + y_gradient_a^2.</td></tr>

<tr><td>x_pos</td><td>The location of the cell in the x-direction, in the range 0 to 1.</td></tr>

<tr><td>y_pos</td><td>The location of the cell in the y-direction, in the range 0 to 1.</td></tr>

<tr><td>z_pos</td><td>The location of the cell in the z-direction, in the range 0 to 1.</td></tr>

<tr><td>a_n, a_ne, a_n2, a_une, etc.</td><td>The neighboring cells. Indexed as u=up/d=down Z cells, n=north/s=south Y cells, e=east/w=west X cells: a_[u/d][Z][n/s][Y][e/w][X]. The digit is omitted if it is one. The digit and the direction are omitted if the digit is zero. Currently we allow indices up to 10 - if you want to go further then write a kernel instead.</td></tr>

The <i>grid spacing</i> (sometimes denoted by <i>h</i>) of the Laplacian and Gaussian stencils is controlled by parameter <tt>dx</tt>. If there is no parameter called <tt>dx</tt> then the default value of 1 is used.

To understand how the formula is used, try View > <a href="view.html#View_ViewFullKernel">View Full Kernel</a> to see the OpenCL kernel code that is assembled. You'll see for example how the <tt>timestep</tt> parameter is used at the end during the forward Euler step. Any formula rule can be permanently converted to a kernel rule by using Action > <a href="action.html#Action_ConvertToFullKernel">Convert to Full Kernel</a>.

For speed we process the image in blocks of 4x1x1, stored as float4. All of the above keywords are float4 values. While doing it this way makes Ready run faster, it can complicate the way we have to write rules - see the examples and please get in touch for more help.

Images in Ready can be 1D, 2D or 3D. The keywords in the formulas generate stencils of the appropriate dimensionality.

Ready also supports running formulas on meshes. However not all of the above keywords are well-defined on arbitrary meshes. The table below shows those keywords that are supported:

Keywords for formula rules on meshes:

<table border="1" cellpadding="5">

<tr><td>laplacian_a</td><td>A <a href="https://en.wikipedia.org/wiki/Laplace_operator">Laplacian kernel</a> applied to chemical 'a' (or 'b', etc.).</td></tr>

<h4>Initial pattern generator</h4>

For more details on how the patterns are specified, including how the initial pattern generator works, open the pattern files in a text editor (right-click on them) (<a href="edit:Patterns/GrayScott1984/self-replicating_spots.vti">example</a>). The format is documented <a href="formats.html">here</a>.

<h4>Share your findings</h4>

If you come up with interesting patterns then please share them with the world! The best patterns submitted to us will be included in the next release of Ready - see our <a href="credits.html#competition">pattern competition</a>.