Skip to content

Commit

Permalink
refactor: Update docs to reflect Generators rather than Procedures (#…
Browse files Browse the repository at this point in the history
  • Loading branch information
trisyoungs authored Sep 3, 2024
1 parent d715075 commit e139dba
Show file tree
Hide file tree
Showing 52 changed files with 19 additions and 809 deletions.
2 changes: 1 addition & 1 deletion web/docs/examples/benzene/step2.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ In anticipation of some bad contacts:

{{< action type="tabs">}}Go to the {{< gui-tab type="configuration" text="Liquid" >}} configuration tab{{< /action >}}
{{< action type="groups">}}Click the {{< gui-button icon="palette" text="Show Available Nodes" >}} on the bottom-left of the window{{< /action >}}
{{< action type="mouse">}}Drag the {{< node "SizeFactor" >}} node into the **Procedure** section to add it{{< /action >}}
{{< action type="mouse">}}Drag the {{< node "SizeFactor" >}} node into the **Generator** section to add it{{< /action >}}
{{< action type="edit" text="Set the value for the _Size Factor_ to 10.0" />}}

Finally, before we move on, we will have to reduce our pair potential range from the default of 15 &#8491; since this is larger than the half the maximum width of our simulation box.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,28 +1,24 @@
---
title: 8. Procedures
description: Defining procedures to create, analyse, and edit
title: 8. Generators
description: Creating Configurations with Generators
weight: 8
---

## Overview

Procedures are used within Dissolve to allow user-defined tasks to be created and used for various jobs - e.g. generating the contents for a configuration, performing a specific analysis etc. They are simple sequences of steps or "nodes" that are run when required, with each node having a focussed and specific purpose. Combined, the actions of these simplistic nodes can generate and manipulate complex coordinate ensembles, and analyse complicated structural patterns.
Generators are a flexible way of describing how a configuration should be created. They are sequences of simple steps or "nodes" that are run when required, with each node having a focussed and specific purpose. Combined, the actions of these simplistic nodes can generate basic disordered systems through to complex coordinate ensembles.

There are three stages to any procedure and its constituent nodes, with each stage performed every time the procedure is run:
There are three stages to any generator and its constituent nodes, with each stage performed every time the generator is run:

#### Set Up
Before the procedure is executed, every node present within it is permitted a set-up stage during which any critical values can be retrieved for use, or any data structures (e.g. to hold results) can be initialised.
Before the generator is executed, every node present within it is permitted a set-up stage during which any critical values can be retrieved for use, or any data structures (e.g. to hold results) can be initialised.

#### Execute
The main work of the procedure is performed within the execution stages of the nodes, which are run according to the structure and sequence defined in the procedure.

#### Finalise
Once the procedure has completed its execution stage, every node present within it is permitted a final operation during which data can be retrieved, normalised, processed, saved etc.
, or printing out a final summary of the node's work over the entire procedure.
The main work of the generator is performed within the execution stages of the nodes, which are run according to the structure and sequence defined in the generator.

## Nodes

A procedure is made up of one or more "nodes", each of which performs a specific task on or with some defined objects in a simulation (e.g. species or configuration boxes), generates data from the simulation, or manipulates data generated by other nodes.
A generator is made up of one or more "nodes", each of which performs a specific task on or with some defined objects in a simulation (e.g. species or configuration boxes), generates data from the simulation, or manipulates data generated by other nodes.

## Branches

Expand Down
File renamed without changes.
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ description: Store numerical reference parameters

## Overview

The `Parameters` node stores zero or more named numerical values that may be referenced in [expressions]({{< ref "expressions" >}}) within nodes contained in the same encompassing [procedure]({{< ref "procedures" >}}).
The `Parameters` node stores zero or more named numerical values that may be referenced in [expressions]({{< ref "expressions" >}}) within nodes contained in the same encompassing [generator]({{< ref "generators" >}}).

## Description

Expand Down
2 changes: 1 addition & 1 deletion web/docs/userguide/gui/configurationtab.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,4 +20,4 @@ This option can be used to scale the positions of molecules within the box, incr

#### Generator

A configuration is created from a generator [procedure]({{< ref "procedures" >}}) allowing it to be reconstructed automatically on demand. The defined procedure can be viewed and edited directly here.
A configuration is created from a [generatore]({{< ref "generators" >}}) allowing it to be reconstructed automatically on demand. The defined procedure can be viewed and edited directly here.
2 changes: 1 addition & 1 deletion web/docs/userguide/guide/workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ With all of this ready to go, the first step is equilibrating the system.

## Equilibration

Typically, Dissolve will construct your initial configuration box from a defined generator [procedure]({{< ref "procedures" >}}) and which will most likely involve adding molecules at random positions and rotations. The first step is to equilibrate this high-energy system to a state where the energy is stable and there are no bad overlaps between atoms left in the system. The energy is of course completely defined by the forcefield you've used on your species, so we need to make a further assumption here that it is a reasonable forcefield!
Typically, Dissolve will construct your initial configuration box from a defined [generator]({{< ref "generators" >}}) and which will most likely involve adding molecules at random positions and rotations. The first step is to equilibrate this high-energy system to a state where the energy is stable and there are no bad overlaps between atoms left in the system. The energy is of course completely defined by the forcefield you've used on your species, so we need to make a further assumption here that it is a reasonable forcefield!

For bulk liquid systems it is generally a good idea to apply a size factor to the box during these initial stages - this scales the box volume and the positions of the molecules, and greatly helps in the removal of overlapping molecules. You can find this option on the [configuration tab]({{< ref "configurationtab" >}}), and a reasonable value to use is `10`.

Expand Down
16 changes: 8 additions & 8 deletions web/docs/userguide/inputfile/configurationblock.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,14 @@ The block keyword itself takes a single (required) argument - the name of the co

## Keywords

|Keyword|Arguments|Default|Description|
|:------|:--:|:-----:|-----------|
|`CellDivisionLength`|`double`|`7.0`|Set the side length, in Angstroms, of sub-cell regions into which the configuration's unit cell will be partitioned for the purposes of near-neighbour calculation. The actual side length used to partition the cell will likely differ from the supplied value, in order to ensure full coverage of the whole unit cell volume.|
|`EndConfiguration`|--|--|Indicates the end of the current `Configuration` block.|
|`Generator`|[`Procedure`]({{< ref "procedures" >}})|--|Specifies a complete [`Procedure`]({{< ref "procedures" >}}) able to generate the unit cell and contents of the configuration. The 'generator' procedure is called before the main simulation loop begins, unless an existing snapshot of the configuration has been loaded in from a restart file|
|`InputCoordinates`|[`CoordinatesFileAndFormat`]({{< ref "coordinatesformat" >}})|--|Load atomic coordinates from the specified file and format. The `Generator` procedure is still used to construct the initial contents in terms of species etc., but the coordinates of the atoms are subsequently overwritten by those from the file.|
|`SizeFactor`|`double`|`1.0`|Factor by which to temporarily scale the unit cell and molecule centres of geometry. This option is typically used to remove overlaps between molecules containing ring structures, which would otherwise become interlocked for the duration of the simulation. If greater than 1.0, the intermolecular energy is assessed at the beginning of each main loop iteration. If this energy is negative, the size factor is reduced by a predefined factor.|
|`Temperature`|`double`|`300`|Temperature of the configuration in Kelvin.|
|Keyword| Arguments |Default| Description |
|:------|:-------------------------------------------------------------:|:-----:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|`CellDivisionLength`| `double` |`7.0`| Set the side length, in Angstroms, of sub-cell regions into which the configuration's unit cell will be partitioned for the purposes of near-neighbour calculation. The actual side length used to partition the cell will likely differ from the supplied value, in order to ensure full coverage of the whole unit cell volume. |
|`EndConfiguration`| -- |--| Indicates the end of the current `Configuration` block. |
|`Generator`| [`Generator`]({{< ref "generators" >}}) |--| Specifies a stepwise [`Generator`]({{< ref "generators" >}}) able to generate the unit cell and contents of the configuration. The generator is called before the main simulation loop begins, unless an existing snapshot of the configuration has been loaded in from a restart file |
|`InputCoordinates`| [`CoordinatesFileAndFormat`]({{< ref "coordinatesformat" >}}) |--| Load atomic coordinates from the specified file and format. The `Generator` procedure is still used to construct the initial contents in terms of species etc., but the coordinates of the atoms are subsequently overwritten by those from the file. |
|`SizeFactor`| `double` |`1.0`| Factor by which to temporarily scale the unit cell and molecule centres of geometry. This option is typically used to remove overlaps between molecules containing ring structures, which would otherwise become interlocked for the duration of the simulation. If greater than 1.0, the intermolecular energy is assessed at the beginning of each main loop iteration. If this energy is negative, the size factor is reduced by a predefined factor. |
|`Temperature`| `double` |`300`| Temperature of the configuration in Kelvin. |

## Example

Expand Down
17 changes: 0 additions & 17 deletions web/docs/userguide/modules/analysis/analyse/_index.md

This file was deleted.

39 changes: 0 additions & 39 deletions web/docs/userguide/procedures/nodes/calculateanglenode.md

This file was deleted.

40 changes: 0 additions & 40 deletions web/docs/userguide/procedures/nodes/calculateaxisanglenode.md

This file was deleted.

32 changes: 0 additions & 32 deletions web/docs/userguide/procedures/nodes/calculatedistancenode.md

This file was deleted.

29 changes: 0 additions & 29 deletions web/docs/userguide/procedures/nodes/calculateexpression.md

This file was deleted.

38 changes: 0 additions & 38 deletions web/docs/userguide/procedures/nodes/calculatevectornode.md

This file was deleted.

Loading

0 comments on commit e139dba

Please sign in to comment.