HelpFile Overview

LandSFACTS v2.0 HelpFile Overview
The LandSFACTS v2.0 helpfile is divided into the following sections:

· Overview of LandSFACTS

· Getting started... , quick help to start using the software

· User-interfaces , detailed information on each user-interfaces

· Project examples , examples datasets & projects

· Verification & Validation

· Additional information for users and development information.

· Acknowledgements

· Licenses

· Contacts

latest helpfile update: 31/03/11


Overview of LandSFACTS
LandSFACTS is a modelling tool to create scenarios of crops or land uses within the landscape. The model provides a crop/land use per land unit per year, which meets user-specified spatial and temporal constraints on the crops/land uses. The software is spatio-temporal and allow multi-scaling. The modelling is based on stochastic and rule-based processes complemented with simulated annealing.

The model is currently used to create scenarios of cropping systems and land uses from the farm level up to the regional scale in order to assess ecosystem services, such as biodiversity, water quality, soil erosion, carbon sequestration.

Within the whole software the word "crop" can be replaced by "land use", and "field" by "land unit".

Screenshot

Two main restrictions:
· spatial modelling unit: a field, i.e. fields have fixed boundaries through the simulation.
· temporal modelling unit: fixed, e.g. a year.
--> the software allocates only one crop per field per year.


Spatial and temporal arrangements

The LandSFACTS software aims to simulate spatial and temporal arrangements of crops in landscapes, by imposing conditions specific to crop arrangements.

Spatial arrangements:
· spatial extent of crops, the spatial extend of the crops over the landscape may need to be limited. For example, the availability of water would restrict the growing area of maize. The extent can vary between years (e.g. extension of irrigation network).
· spatial constraints on crops, defined as the separation distances between crops. For example, in the context of seed production or GM coexistence, crops must be separated by a minimum distance. The linked field and connectivity constraints are under constructions.
· spatial patterns of crop rotation, the type and degree of crops rotation aggregation or regularity over the landscape is defined by statistical tests. The spatial pattern of rotations will influence the spatial patterns of crops if the crops within the rotation are different.

Temporal arrangements:
· crop rotations, they may be fixed (linear) or flexible (probability of transition from one crop to another);
· temporal constraints on crops, composed by (i) the crop minimum return period; (ii) the crop maximum repetition; (iii) forbidden crop sequences. They are linked to individual fields or groups of fields.
· past crop allocations can be specified for any number of consecutive years before the simulation starts. It can be used to provide initial crops allocation obtained from survey or previous simulation runs.
· temporal patterns of crops, the type and degree of crops temporal variation, coordination between crop rotations, equivalent also to the crops in the first year of simulation, defined by statistical tests.

Spatio-temporal arrangements:
· yearly crop proportions, the crop or group of crop proportions within the whole landscape or group of fields, for any specified years.

Spatial and temporal arrangements of the landscape are inter-related, starting with the link between the spatial arrangements of crop rotations, which are dependent upon the crops in the rotation, and the spatial repartition of the growing area of crops.


Flexibility and Adaptation

Any project can be set up in multiple ways, here are some examples:

· Crop A should be grown only on fields 1, 2 and 3, but not on 4 & 5.
· option 1: using land capability constraint to limit the fields on which crop A may be grown (fields 1 to 3)
· option 2: crop A is removed from the rotations imposed on fields 4 and 5.
Option 1 is more versatile than 2, but the simulation will be slower (constraints slow the simulation speed).

· Woodland expansion
· option 1: fix a target woodland proportion in "yearly crop proportions", and use the "functional crop" iteration options in "simulation set up" (a group fo


Getting started...
This page presents a summary of the use of LandSFACTS software.
Refer to the Description of user-interfaces for complete details. Examples of projects are also available.

1. Start LandSFACTS

2. Create a new project or open an existing one: File / New project or Open project
It is recommended to create a new empty folder to hold all the simulation data. This folder will hold a copy of the input data within the simulation database, along with the results of the simulation and reports on the simulation.

3. Input data: go through the steps chronologically
Compulsory data input:
- landscape as shapefile
- definition of the fields (polygon attribute and land type table)
- definition of the crops to simulate
- definition of the rotations to use
- identify crops available for each field
- identify a rotation for each field
The compulsory data input are for a simple simulation without conditions imposed on the landscape. To impose a constraints further inputs are required (spatial, temporal, crop proportions constraints, simulation set up and iteration parameters).

4. Set up the simulation parameters: Simulation / Set up parameters
Compulsory information:
- indicate the number of simulation years
- the iteration options for the simulation (if constraints are used)

5. Run the simulation: Simulation / Run simulation

6. Interpret the results
The main outputs are:
- the crop allocation to fields for number of year agreeing with the conditions imposed on the landscape.
- if the simulation fails (no crop allocation found), the year and conditions which failed are reported.
- reports on the difficulty of obtaining the crop allocation to fields are available.


User-interfaces

Description of user-interfaces
The user-interfaces are organised in 7 menus:

· File

· Fields

· Crops

· Fields-Crops

· Constraints

· Simulation

· Help (About & link to Helpfile)

· Tips on use


File
This section presents the options available under the File menu:

Options under File:
· New project: create a new project to be saved into a project folder
· Open project: open an already existing project
· Import project: import a project of a previous version.

· Export project to Txt: exports all the tables of the database into individual text files. IMPORTANT: using this tool requires to be familiar with the LandSFACTS database.
· Import project from Txt: imports individual text files into the database (initially created by using "Export project to Txt").
IMPORTANT:using this tool requires to be familiar with the LandSFACTS database.
· Export to C++ Standalone: exports the database into text files ready to be used by the LandSFACTS-c++ standalone program (program not provided here).

· Reports : reports on data hold in the database in a user-friendly format
· Exit: close LandSFACTS


Reports
Requirements:
- project open
- relevant data for each report (i.e. crops must be defined to access the "Crops" report)

aim: The reports show information held within the database in a user-friendly way.

Two reports available (cf. individual screenshots below):
· Crops: list of the crops ID, with their crop types and crop bank
· Field groups: list of fields within each field group (group id and name)
· Rotations : list of the crop rotation ID and their names to support the setting up of the "Initial rotations - Fields")
· Crops in each rotation : list of the transition matrix crops (TMCID) to support the setting up of the "Temporal patterns / Initial crops".
· Rotations assigned to fields:
· Areas and Centroids for polygons: list of areas, centroids & land types for all polygons.
· View saved dbf : any dbf can be viewed, e.g. penalties...

Report: "Crops"

Report: "Field groups"

Report: "Rotations"

Report: "Crops in each rotation"

Report: "Rotation assigned to fields"

Report: "Areas and Centroids for polygons"

top of page


Fields
This section aims to set up the input data uniquely related to the fields:

· Select a shapefile : the digitised landscape

· Fields definition : select polygon attributes & land types

· Groups of fields : define groups of fields, to be used to facilitate data inputs.

· Create neighbours table : create the table to be used in spatial constraints.


Select a shapefile
Requirements:
- project open

aim: The shapefile provide the list and shape of the polygons. If the polygons are not readable by LandSFACTS, no spatial processing will be done by the software itself (calculation of centroids, area and neighbour table), they will have to be done externally by the user.

Browse to the shapefile

To be displayed the polygons of the shapefile need to be "readable" by the LandSFACTS GIS library (GEOS).

The shapefile is loaded.

top of page


Fields definition
Requirements:
- project open
- shapefile selected

aim: Define which polygons of the shapefile are considered as fields (to have crops allocated to them)

Two files must be uploaded:
· polygon attributes table :
list of all polygons ID, area and land type reference (ID). How to create "PolygonAttributes.dbf" table?
· land type table :
definition of all the land type reference. How to create "LandType.dbf"?

When both tables are defined, the land types can be displayed on the map:


Select Polygon Attribute table
Requirements:
- project open
- shapefile selected

Step 1: Import the Polygon attribute table (click on "import Polygon attribute table")

Step 2: Browse to find the table (click on "import Polygon attribute table")

Step 3: Identify the attribute (column) with the Polygon_id and the LandType id (the two only compulsory attributes).

Step 4: "Import"
· The table is uploaded within the database. This step may take several minutes, depending on the number of polygons imported.
· If the "area, centroid X or Y" attributes are not present within the PolygonAttribute table, they are determined using the spatial information in the shapefile.

Complete table

top of page


Select Land Type table
Requirements:
- project open
- shapefile selected
- polygon attribute table

The Land type table identify the land type for each polygon defined in the shapefile.

Step 1: Import Landtypes table (click on import)

Step 2: Identify the columns in the imported files, for the landtype id, name and definition (the last one is optional). When they are filled up, further information is required.

Step 3: Identify the land types corresponding to the fields (where the crops are grown), and optionally the borders (considered as borders by Genesys model).

Step 4: "Import".
The table is uploaded to the database, this take may take several minutes.

Step 5: Click "OK" , the software reports the number of fields identified as polygons.

top of page


Groups of fields
Requirements:
- project open
- shapefile selected
- fields definition

aim: The groups of fields will be used in the following constraints: yearly crop proportions and linked fields.

If a group is currently used within a constraint it cannot be deleted (Delete button is greyed out).

Actions available:
· Add / Modify a group: provide a group name and the crops to put in the group

· Import already defined groups from dbf
· Delete group
· Group view tick box: to view groups on the right pane.


Create neighbours table
Requirements:
- project open
- shapefile selected - readable by the software GIS software
- fields definition

aim: The neighbours table will be used in the following constraints: separation distances, connectivity.

· View full table: show the neighbours table for every created distance (cf. screenshot below)
· Create a new neighbour definition: user specify the distance, and the software determine the neighbours.
· Import a new neighbour definition: require external gis processing of the neighbours (needed when the shapefile polygons are not readable by landSFACTS)
· Delete selected neighbour definition.

top of page


Crops
This section aims to set up the input data uniquely related to the crops:

· Crop definition lists all the crops that will be used within the software.

· Groups of crops are used within the initial crops in fields and in the following constraints: temporal constraints, linked fields.

· Rotation definition lists all the matrices of crops transitions probabilities (surrogates of rotations) that will be used within the software.


Crop Definitions
Requirements:
- project open

aim: The crop definitions list all the crops that will be used within the software.

The crop definition is carried out in three main steps:
1. Select crop type table : defined by Genesys model (e.g. GM, non-GM, winter crops, borders...)
2. Select crop bank table : defines the crops to model (e.g. wheat, oilseed rape, fallow...). This table may be created from an imported CAP code table (from EU codes for CAP declarations)
3. Create final crops : defines the links between the crops (from crop banks table) and the type of crops (from crop type table).

nb: If any crop rotations are set up, it is impossible to remove a crop from final crop table, and also to alter crop bank or crop types.


Crop Type
Requirements:
- project open

Two options are available: Importing a table or creating a default one (with only one crop type).

Import the crop type, cf. How to prepare the Crop Type table?
The imported table is displayed:

nb: If any crop rotations are set up, it is impossible to remove a crop from final crop table, and also to alter crop bank or crop types.

top of page


Crop Bank
Requirements:
- project open

Three options are now available to fill up this table:
· import a crop bank table, cf. How to prepare a CropBank table?
· import a CAP crop table as a template for a new crop bank, cf. How to prepare a CAPcrop table?
· insert and delete crops "by hand", click on "Insert..." and type information in the new cells (new row).

Example of final crop bank table:

nb: If any crop rotations are set up, it is impossible to remove a crop from final crop table, and also to alter crop bank or crop types.

top of page


Final Crop
Requirements:
- project open
- crop type
- crop bank

The final crops definition is set up. The final crops are defined by one crop from the crop bank and one crop type.

Select one row from "crop bank name" + one row from "crop type name" and click on the downwards arrow to commit the link into the database. The link can be remove by using the upward arrow.
· A crop name can be linked to many different crop type (e.g. oilseed rape crop with conventional OSR and transgenic OSR).
· A crop type can be linked to many different crop names (e.g. winter crops with wheat and barley).

Click on save and ok

nb: If any crop rotations are set up, it is impossible to remove a crop from final crop table, and also to alter crop bank or crop types.

top of page


Groups of crops
Requirements:
- project open
- crop defined

aim: The groups of crops will be used within the initial crops in fields and in the following constraints: temporal constraints, linked fields, yearly crop proportions.

By default, each crop has its own crop group (group with 1 crop). Further crop group can be created by using "Add/Modify a group" or "Import already defined groups from dbf".

top of page


Rotation definitions
Requirements:
- project open
- crop definitions

aim: The rotation definitions lists all the matrices of crops transitions probabilities (surrogates of rotations) that will be used within the software.

All the crop rotations to be simulated in LandSFACTS must be set up at this stage.
For further information on how LandSFACTS manages crop rotations, see Crop rotations in LandSFACTS .

· Add new rotation
· View rotation
· Delete rotation: select the rotation in the table, and click on "Delete rotation".
· Examples of rotations

top of page


Add rotation
Requirements:
- project open
- shapefile selected
- fields definition
- crops definition

Step 1: Rotation name & crops
Enter the crops present in the crop rotation, by selecting them one by one in the left table and clicking on the right arrow. The inserted crop appears in the right table.
· In the case of a fixed rotation , it is more practical to enter them chronologically.

Example of a fixed crop rotation (winter wheat - winter barley - oilseed rape)

Step 2: Fill up the transition matrix of the rotation (see Rotations as transition matrices )

The transition matrix is an efficient way of determining the probability of transition from crops in year n (on the left) to crops in year n+1 (on the top). The probabilities (in the cells) must be between 0 and 1, inclusive. A probability of 1 indicates 100% of chance of a transition, whereas a probability of 0 indicates a transition will never occur. Each row must sum to 1.

Two ways of filling up the transition matrix:
· input manually the probabilities of transition within the matrix (click on cell).
· click on "Set fixed Rotation", to have the matrix filled up as a fixed rotation (a probability of 1 for the cells just on the right of the diagonal - top left, bottom right - and bottom left cell with a probability of 1).
· click on "Set equal Rotation", to have every probabilities being identical
· click on "Set constant Rotation", to have a matrix where there is no temporal changes (e.g. wheat is followed by wheat, barley is followed by barley)
· click on "Export rotation matrix", to have the table exported as a text file (e.g. to work in excel on the probabilities)
· click on "Import rotation matrix", to import a previously exported text file table.
NB: the "saving period" and "burn-in period" are parameters used to calculate the crops' long-term proportions at the next tab. It is recommended to keep the default values (see calculations of long-term crop proportions ).

Step 3: The long term proportions of the crops within the rotations are calculated and displayed. In the example below, winter wheat will be grown 30% of the time (same proportions of oilseed rape and winter barley).

If the crop long term proportions are not as desired, click on "back" button, to alter the probabilities in the transition matrix.
Note: The long-term proportions of the crops for each crop rotation will alter the overall crop proportions on the landscape.

Step 4: Finish
The new crop rotation is now listed.

top of page


View rotation
Requirements:
- project open
- crop definition
- one rotation selected in "initial rotation"

· To view a rotation, select the rotation on the table, and click on "View rotation". The rotation may be viewed and altered.
· Save Changes.

top of page


Examples of rotations
Three examples:
- multi-pathway rotations
- unformed rotations
- one constant crop every year

Example of a multi-pathway rotations

Example of unformed rotation
(This example is not agronomically realistic.)

Example of one constant crop every year (in this example fallow)

top of page


Fields-Crops
This section aims to set up the input data related to both the crops and fields:

· Rotations defines which crop rotation is followed on each fields

· Initial crops defines an initial crops for each field (crop in first year of simulation)


Rotations in fields
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition
- rotation definition

aim: A rotation (transition matrix) must be allocated to every field.

Three choices to assign a rotation to each field:
· Up & down arrows: Manual linking by selecting fields (or group of fields) & rotations.
Select one field (PlgID) or one group of fields (GpPlgID) & one rotation & click to downwards arrow. This new link is displayed in the bottom table. The field is removed from the field list (top left), as field can only follow one crop rotation. To remove the link use to upwards arrow.
· "Import from dbf": Import a "Fields-Rotation.dbf" file.
The ".dbf" file must contain the polygon ID and the rotation ID. The file must be in a specific format, for complete specification refer to "How to prepare the Fields-Rotation file?" .
· "Use RotationFields program" : program allocating a rotation to each field, to obtain specific long-term crop proportions over the landscape, and specific spatial patterns of rotations. Crop rotations are randomly allocated to fields, until the user-defined targets are reached. For further details, refer to RotationFields .

Example of completed Rotations-Fields table:

Check the long term crop proportions over the whole area.
· If the crop proportions needs to be altered, the allocation of the rotations to the fields (previous tab) can be altered. In this case you will have to recalculate the long term proportions ("recalculate" button).
If the crop proportions are as required, click "Ok".

top of page


RotationFields program
The RotationFields program links crop rotations to fields to reach targets of long-term crop proportions and specific spatial patterns of rotations. The two options are not compulsory.

The interface is composed of 3 tabulations:
· crop proportions
· spatial patterns
· program parameters

Program approach
The program goes through the following steps chronologically:
1. only the crop rotations with desired crops (i.e. crop proportion targets not equal to 0) are considered.
2. allocate rotation to fields to meet crop proportions
· equal weighing of each rotation (equal probability of choosing any rotation for a field)
· if weighted rotations:
· random weighing of each rotation
· check how many crop proportion targets are met (not considering the fields)
· if more targets are met --> this random weighing replaces the equal weighing
· if less targets are met --> new random weighing until the maximum number of iteration.
· if all targets are met or if maximum number of iteration is reached --> end of iterations.
· for each field, the possible rotations are determined (using possible crops - fields)
· allocate randomly a rotation to each field by using the rotation weights.
· if all targets are met --> the rotation allocation is accepted
· if not reallocate randomly the crops until the maximum number of iteration

3. check spatial patterns
· if without alteration of rotation allocation, patterns are ok --> rotation allocation is completely accepted: end of program
· if the patterns are ok but with altered rotation allocation, the crop proportion are checked for the new rotation allocation (2.)
· if the patterns are not ok, back to 2. for a new rotation allocation.

Program results
If the program finds a rotation allocation, which meets the user-defined crop proportions and spatial patterns, an interface displays: the rotation for each field, and the long-term crop proportions and the spatial patterns values. If this rotation allocation is accepted by the user, it will be written in the database.

A log file is created (log_RotationFields.txt), it reports on the processes within the simulation.

Display of the allocation of the rotations to the fields (rotation with GM in red, with conventional OSR in yellow and set-aside in green). Most of the gm rotations are adjacent to other Gm rotations.

If no answer are found: re-run the program with the same target crop proportions or with altered targets. Check if at least on crop rotation is possible on any fields. For example, if a field may only have fallow (possible crops - fields table), a crop rotation uniquely composed of fallow must be available.

top of page


Crop proportions
The program will target a crop rotation allocation which meets the required crop proportions.

· Proportions: crop proportion in area, the value must be between 0 and 1. "-1" indicates that the program should not check this crops.
· Deviation: standard deviation allowed from the target proportion.
· Weighted rotations: to find a rotation allocation meeting the targeted crop proportion, for every field, the program may have an equal chance of choosing any rotation (not ticked), or a weighted chance of choosing a rotation (ticked). In the case of weighted rotation, each rotation is given a different random weight until the weights allow the crop proportion targets. Weighted rotations should only be used if all the fields have similar areas. Using weighted rotation may provide unbalanced rotation allocation (e.g. if rotation x has a weight of 95%, this rotation will be over-represented).

The crop proportion obtained from the simulation must be within the lower and upper limits included:
lower limits = proportion - proportion * deviation
upper limits = proportion + proportion * deviation
nb. The proportions are rounded at the fourth decimal.

Example
The following example, requires the program to find a crop allocation, with 30% of wheat in the long-term with +- 20%.

top of page


Spatial patterns
The spatial patterns are determined using a statistical test specifically developed, the "E analysis", for further details cf. Spatial and temporal patterns of crops [image] .

· number of randomisation points: number of points determined for building up the randomisation curve. By increasing the number of randomisation points, the randomisation curve will be closer to the reality, thus improving the accuracy of the desired temporal pattern.
· current view of spatial patterns: list of existing spatial patterns

Creation of a constraint:
· click add constraints
· specify name, lower and upper Ep limit.
· group the rotations, by altering their group number in the third column. The patterns test is applied on groups of rotations.

Meaning of Ep values, cf. graph:
· Ep value: proportion of randomisation points with a lower E value. A low Ep value (close to 0) indicates a high spatial aggregation of the crop rotations, i.e. they are spatially close to each other, grouped. A high Ep value (close to 100) indicates a high spatial regularity of the crop rotation, i.e. the rotations are dispersed over the whole landscape, with as much distance between them as possible.
· Lower Ep limit: lower acceptable Ep value
· Upper Ep limit: maximum acceptable Ep value.

top of page


Program parameters
The program parameters determines how the program will behave to reach the targeted crop proportions and spatial patterns.
· maximum number of iterations: number of times the program will try to improve the crop rotation allocation.
· Seed for random number generation: a list of pseudo-random number is generated for the program. This list may start either with a number based on the internal clock of the computer (Time base "Seed") or with a user-defined seed (Specific "Seed"). The later option allows the user to replicate an already existing simulation. During the program, all random decisions will be identical, leading to a true replication of the program previous run (all the inputs must also be the same).

top of page


Initial crops
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition
- rotation definition
- fields-crops / Rotation

aim: An initial crop (from the field's rotation) must be allocated to every field.

The initial crops influence the variability in crop proportions between years.

To assign initial crops to fields:
· Field group filter: to show in the table only the select field groups
· Drop down boxes : select initial crop or group of crops for each field
· "Import" : import from "InitialCrops.dbf".
The dbf contains the polygon ID and the InitTMCID (initial place from the rotation, or group of crops ID ("-" GpCID, the minus sign is required to differentiate the reference to the place in the rotation and the crop group) . For the file specifications, cf. " How to prepare the InitialCrops file? ".
· " InitialCrops program " : program to allocate an initial crop for each field, which complies with user-defined temporal patterns of crops.
· "Random crop allocation":
The program will randomly allocate the initial crop for each field during the simulation through years, considering the proportion of this crop within the rotation of the field.
· "Delete all" : remove all initial crops

top of page


InitialCrops program
The initial crop program randomly chooses an initial crop from the rotation of each field to respect user-defined temporal patterns of crops.

The interface is composed of three tabulations.
· Conditions to test
· Randomisation parameters
· Program parameters

Program approach
The program goes through the following steps chronologically:
1. Creation of the randomisation curve of temporal patterns, by calculating the coefficient of variation of crop areas over the years for x random allocation of initial crops to fields.
2. Randomly allocate an initial crop from the rotation of each field, and calculate the coefficient of variation of the crop areas over the years. If the "optimisation" option is chosen in program parameters, only one field has its initial crop changed at a time.
3. Check if this current allocation is within the targets set by the user.
--> within targets: the initial crops are accepted
--> outside targets: return to step 2.

Results
The temporal patterns of the resulting initial crop allocation is displayed (for the inputs, cf. the helps on the three tabulations). By clicking on "accept", the initial crops are saved within the database.

When running the simulation over 10 years without any constraints (spatial, temporal, crop proportions), the proportions of wheat over the years is as follow:
The average is 0.2516, and the coefficient of variation is 4.2417 (same as %CV). The initial crops of the fields were correctly coordinated to have a constant wheat proportion in the landscape over the years.

A log file is created (log_initialCropsTP.txt), it reports on the processes within the simulation.

top of page


Temporal patterns
Specific temporal patterns can be applied to a single crop or group of crops.

In the example below, the proportion of wheat is required to have a low variation over the years. The proportion of wheat has to be near constant over the simulated years, thus the crop rotation have to be coordinated to spread the wheat constantly over the years.

· CVp: proportions of random points with a CV value lower than the target temporal pattern. A low CVp value (close to 0) indicates a low temporal variation of the crop(s) proportions over the years, i.e. constant crop proportion from year to year. A high CVp value (close to 100) indicates a high temporal variation of the crop(s) proportions over the years, i.e. highly different crop proportions from year to year.
· LowerCVp: lower CVp value accepted.
· HigherCVp: higher CVp value accepted.
· Crop(s) within this condition: a crop or group of crop for which the temporal pattern is sought.

top of page


Randomisation parameters
The randomisation parameters defines how the calculations of the statistical test on crop temporal patterns are carried out:
· number of years: the coefficient of variation of the crops proportion is calculated over a number of years. The minimum authorised number of years is "2", however 10 years is the minimum recommended.
· number of randomisation points: number of points determined for building up the randomisation curve. By increasing the number of randomisation points, the randomisation curve will be closer to the reality, thus improving the accuracy of the desired temporal pattern.

top of page


Program parameters
The program parameters determines how the program will behave to reach the targeted crop temporal patterns.
· maximum number of iterations: number of times the program will try to improve the initial crops allocation.
· optimisation: each time the program tries to improve an initial crop allocation, it either starts with a new random allocation for all the fields (not ticked) or for only one randomly chosen field (ticked).
· Seed for random number generation: a list of pseudo-random number is generated for the program. This list may start either with a number based on the internal clock of the computer (Time base "Seed") or with a user-defined seed (Specific "Seed"). The later option allows the user to replicate an already existing simulation. During the program, all random decisions will be identical, leading to a true replication of the program previous run (all the inputs must also be the same).

top of page


Constraints
This section aims to set up the constraints for the simulation:

· Past allocation : the past crop allocations are taken in account when assessing the temporal constraints during the simulation.

· Land capability : defines which crops can be grown on each fields for each year

· Temporal constraints : defines rules on crop successions for group of fields

· Spatial constraints : defines the separation distances between crops, linked fields and connectivity.

· Yearly Crop Proportions : defines the crop or crop group proportions per group of fields per year.


Past Allocation
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition

aim: Impose past crop allocation to the first years of simulations. Those allocations will not be tested for any constraints.
The use of this constraint in the simulation is controlled in Sub-sets .

This interface only accept the importation of a dbf table. The log_PastAllocation_New.txt of a previous simulation can be directly used (after being converted to dbf) [cf. Text Outputs ].
· SimYear: year the allocation applies from. The lowest year should be 0.
· PlgID: Field ID. All the fields to simulate should be present for every year
· TMCID: place of the crop within the rotation. This is used if directly coming from a previous simulation with the same rotations for every field.
If field-crop was not obtained through LandSFACTS simulations or if field-rotation is changed between previous simulation and the new one --> the value "-99999" should be applied for all fields concerned and years.
· CID: crop id for the given year and field.


Land Capability
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition

aim: lists the crops that can be grown on any field for any year.
The use of this constraint in the simulation is controlled in Sub-sets .

Two steps:
1. Define land capability groups (groups of crops)
2. Assign to field a land capability groups for every year


Define

Define Land capability groups
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition

aim: create groups of crops for each specific land capability.

As a default, a group called "All Crops" is created (it cannot be deleted). Further groups can be imported / added or deleted.

Available actions:
· Add/Modify a group
· Delete group : delete selected group
· Import already defined groups from dbf
· Group view : to view by groups of crops

Example of new group:

Example of new list of land capability groups


Assign to fields

Assign to land capability groups to fields
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition
- land capability definition

aim: assign a group of land capability for every field for every year of simulation

In the interface initially displayed the Land capability option is not activated. Tick "Use land capability" to activate the use of the constraint.

Options available to alter the assignation of the land capability to the fields & years:
· Add year : add the stipulated number of years
· Validate : apply the filter options to the database (add the years first).
· Filter - select a group of fields
· Filter - select a year
· Filter - select a land capability to apply accordingly to the two other filters.
· Constant land capability : all the years will be the same (year = -1)
· Delete year : delete the stipulated number of years
· Copy year :copy the selected year.
· Import from dbf
· Alter the rows viewed in the table by using the filters (do not click "validate")

Example:


Temporal constraints
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition

aim: to impose rules on temporal successions of the crops.
The use of this constraint in the simulation is controlled in Sub-sets .

The temporal constraints prevent unacceptable crop sequences to be chosen, and they are field specific. They are useful to enforces crop succession rules, which might or not be already incorporated within crop rotation. The crop successions depicted by the crop rotations might be altered during the iteration process, while trying to meet the spatial and yearly crop proportions constraints. By reinforcing the crop successions rules with the temporal constraints the integrity of crop succession can be preserved.
The temporal constraints enforce crop succession rules more strongly than crop rotation.

Two types of temporal constraints:
· return period and maximum number of consecutive years
· forbidden crop sequences
· then the constraints must be assigned to fields.

top of page


Return period & successions
aim: This option regulates how often a crop or group of crops may be grown in a field.

To set up:
· constraint name
· return period
· minimum successive repetition of a crop or group of crops
· maximum successive repetition of a crop or group of crops
· crop group for which it applies


Forbidden crop sequences
aim: To forbid specific sequences of crops.

For example: OSR conventional cannot be grown if GM OSR was grown the previous year.

The "any crop =>" option allows to replace "whatever crop is grown in this year".

top of page


Temporal constraints assigned to fields
Requirements:
- project open
- crop definition
- fields definition
- temporal constraints - definition

aim: to determine to which fields, the temporal constraints must be applied.

The temporal constraints are fields specific (use the up and down arrows). If all the constraints must be applied on all the fields, use "Add all constraints to all fields".


Spatial constraints
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition

aim: to impose rules on spatial arrangement of the crops.
The use of this constraint in the simulation is controlled in Sub-sets .

Three types of spatial constraints:
· Separation distances : specific distance between two crops (distance between field's boundaries)
· Connectivity : in progress...
· Linked fields : in progress...


Separation Distances
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition
- neighbours table

aim: to impose specific distance between two crops (distance between field's boundaries)

Tools
· Add constraint : add a new constraint to the table, cf. below.
· Delete constraint : select a constraint & click on "delete constraint".
· Save : commit the constraint into the database
· Close

Add a constraint:
· a new line appears
· add a constraint name
· select the two crops to separate (from final crops table), using the drop down boxes.
· select a separation distance. The listed "distances" are from the neighbours table .

To manage the conflict between two crops due to separation distances not respected, the crop priorities in being changed, can be set up.


Crop priorities
When the crop allocation does not respect the separation distance between two crops, one of the crop must be changed.
· If no crop priority (all set to "-1") : a crop is chosen randomly and altered using the iteration options.
· If a crop has a priority of "0", this crop cannot be changed due to an unrespected separation distance.
· If a crop has a priority (e.g. OSR gm set to "1"), the crop with the lowest priority (lowest = 1, highest = 10,000), is changed first. In this case OSR gm would be changed for another crop.

Example:
In the example below:
- if OSR gm and OSR conventional are spatially too close, OSR gm will be changed for another crop.
- if winter and spring barley are spatially too close, winter barley will be changed for another crop.


Connectivity
new constraint under construction in the model....


Linked fields
new constraint under construction in the model....


Yearly Crop Proportions
Requirements:
- project open
- shapefile selected
- field definition
- crop definition

aim: To impose within any group of field, a proportion for any group of crops for any year.
The use of this constraint in the simulation is controlled in Sub-sets .

Targets of crop proportions can be set up for every year. This option is best used with very flexible crop rotations (many possible crop transitions for every year).

Tools
· Import dbf : import dbf file, cf. How to prepare yearly crop proportions file? .
· Add constraint(s): add another constraint
· All years (for selected rows): applies "-1" as year
· Delete selected constraint(s) : the number of years are deleted from the last years
· Copy selected constraint: copy the crop proportions and deviation from the current year to any other years.

The yearly crop proportion obtained from the simulation must be within the lower and upper limits included.
nb. The proportions are rounded at the fourth decimal.


Simulation
This section aims to set up the simulation parameters, the simulation run and present the results:

· Simulation set up defines the parameters of the simulation

· Sub-sets defines sub-sets of fields and constraints to simulation

· Run Simulation starts the simulation

· Simulation outputs


Simulation set up
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition
- fields-crops / rotations
- fields-crops / initial crops

aim : To control the behavior of the simulation and the outputs.

Tools:
· Simulation parameters : years of simulation, batch mode, random number generation
· Iteration options 1 : controls the behavior of the simulation algorithm (crop replacements and iteration options)
· Iteration options 2 : controls the behavior of the simulation algorithm (options)
· Text outputs : saving results into text files.
· Dbf outputs : saving results as dbf, export data for SIGMEA platform.


Simulation parameters
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition
- fields-crops / rotations
- fields-crops / initial crops

aim : To set up the number of years for the simulation, batch mode and seed for random number generation.

Inputs:
· Years of simulation: total number of years to simulate. For 25 years, the simulation years will be numbered from 0 to 24 included.
· Batch: number of simulation that will be run. All the simulations will starts with exactly the same inputs.
· First batch number: Batch number to start the simulations with. For example to start at the run 53 out of 100 simulations. This option is useful to multi-thread simulations (i.e. to run simultaneously from simulation 0 to 49, and simulation 50 to 100 in two landsfacts windows). Or to continue a batch simulation after an unplanned computer switch off...
· Seed for random number generation: as a default keep "Time based 'Seed'. Every time the simulation will start a new random seed is chosen to randomly control the choices within the model.

A list of pseudo-random number is generated for the program. This list may start either with a number based on the internal clock of the computer (Time base "Seed") or with a user-defined seed (Specific "Seed"). The later option allows the user to replicate an already existing simulation. During the program, all random decisions will be identical, leading to a true replication of the program previous run (all the inputs must also be the same).
Seed for a previous run can be found in the log_Simulation.txt:
The specific seed used for a run is saved within the Simulation parameters table (Simpara array within the simulation), and the SimReport table.


Iteration options 1
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition
- fields-crops / rotations
- fields-crops / initial crops
- at least one constraints to simulate

aim : To set up the iteration options which control how unwanted crop allocations are altered to reach an authorised allocation.

Details of iteration options:
The iteration options below are carried out successively until the crop allocation is accepted or the maximum numbers of iteration for each option are used up.
n.b. The total number of iterations should be higher than 0.

1. Crops changed in all the fields
new random choice of initial crops in the case of the first year of simulation or within the transition matrix any other year of simulation.
Maximum iterations (AllRdmx): number of consecutive times the option is used.
Penalties (AllRdpenal): penalty for the field on which this option is used.

2. Crops changed in only one problematic field

2.1 New random choice WITHIN crop rotation (transition matrix) or of initial crops (for first year of simulation).
Maximum iterations (Rdmx): number of consecutive times the option is used.
Penalties (Rdpenal): penalty for the field on which this option is used.

2.2 New random choice OUTSIDE the crop rotation (transition matrix) or of initial crops (for first year of simulation).
Maximum iterations (Rdmx): number of consecutive times the option is used.
Penalties (Rdpenal): penalty for the field on which this option is used.

2.3 Crop replaced by another crop from the same crop group
The crops may be grouped depending upon their functions within a rotation, e.g. winter wheat and winter barley could be grouped under the winter cereals group. cf. functional groups of crops to set them up. A group must be set up to permit the use of this option.
Maximum iterations (CIDGpmx): number of consecutive times the option is used.
Penalties (CIDGppenal): penalty for the field on which this option is used.

2.4 Crop replaced by universal crop
The universal crop could be fallow or a fake "flag crop" for example. The universal crop cannot be part of a spatial, temporal or yearly crop proportions constraints. An universal crop must be set to permit the use of this option.
The place within the rotation is not kept (since 02/03/10)
Maximum iterations (UnivCIDmx): number of consecutive times the option is used.
Penalties (UnivCIDpenal): penalty for the field on which this option is used.


Functional groups of crops
Notice: At the moment, this interface does not uses the " Group of crops ".

Functional groups of crops are used during the iteration process to alter an unwanted crop allocation.

Rules on functional group of crops
Crops within a group could have similar function with a rotation (e.g. spring cereals, leguminous...), but this is only an example.
A group must be composed of at least two crops and a crop may only be present in one group.

Example of the "Add a functional group" interface


Iteration options 2
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition
- fields-crops / rotations
- fields-crops / initial crops
- at least one constraints to simulate

aim : To set up the iteration options which control how unwanted crop allocations are altered to reach an authorised allocation.

Simulated annealing option: During the iteration process, the program may get stuck within a local minima (e.g. "dead end" from which the crop allocation cannot be improved by altering only one crop at a time). To avoid the local minima, a "worse crop allocation" can be accepted after specific number of unsuccessful improvements (iterations without any amelioration of the crop allocation). An example of the use of simulated annealing .

Optimisation option: The program will aim at meeting the land capability and temporal constraints before to check the other constraints. This option helps speeding up the simulation.

Multi-Reallocation option: During the iteration process, instead of altering the crops in one per field per iteration, multiple fields (user's input) get their crops altered. During the simulation if the multi-Reallocation targets is automatically decreased successively by half whenever required.

Recording penalties option: This option allows to record the penalties every time a crop in a field had to be changed during the simulation. The penalty applied per iteration option can be set up in the tab "Iteration options 1".


Simulated annealing
Example of the use of Simulated annealing

Context:
a simulation must respect:
- yearly crop proportions and
- spatial constraints (with crop priority of GM OSR = 1, all other crops = -1).

After 832 iterations within year 2, the program reach situation 1

Situation 1:
the current crop allocation tested has the required crop proportions, however the spatial constraint is not respected for the following fields:
fields crop
81 gm OSR
0 conv OSR
25 conv OSR
39 conv OSR
Due to the crop priorities, only the field with gm OSR, field 81, can have its crop changed.

Situation 2:
the crop allocation of situation 2 is obtained by altering the crop allocation of situation 1: a new crop, within the crop rotation is randomly chosen for field 81 (not gm OSR).
However, by removing gm OSR from field 81, the gm OSR crop proportion is not respected anymore.
This new situation is not acceptable by the program, and it deletes it, and restarts from situation 1.
Simulated annealing counter is incremented by a value of one.

Conclusion:
The simulation is in a non-breakable loop between situation 1 and situation 2. The only choice from situation 1 is to go to situation 2, but situation 2 is not acceptable, so back to situation 1.

The only way of getting out of the loop is to set up the simulated annealing option. After a number of times specified by the user of non-improvement of the crop allocation, the situation 2 will be accepted. And the crop allocation will be improved from this new crop allocation.

top of page


Text Outputs
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition
- fields-crops / rotations
- fields-crops / initial crops

aim : To identify which output text files will be saved within the project folder under "simulatorOutputs" folder.
The text file summarising all the simulations within a batch (log_BatchCropAllocation.txt) is always saved.

For batch simulation, the "set 2 (minimum)" is recommended.

Description of the files:

· log_FinalCropAllocation: reports the final crop allocation (crop names), one row per field, and one column per year of simulations. This file can easily be "joined" to the shapefile to display the crop allocations in a GIS software.

· log_FinalCropAllocID: same as log_FinalCropAllocation, but with Crop ID (CID) instead of crop names. This file can easily be "joined" to the shapefile to display the crop allocations in a GIS software.

· log_Areas: reports the crop and group of crop areas per group of fields and landscape for each year of simulation.
· log_PastAllocation_New: file ready to be used as an "PastAllocation.txt" input for a following simulation.

· log_OutputTables: reports all the outputs tables
· log_InputTalbes: reports all the inputs tables
· log_Simulation: reports on the simulation process (interest: developers)
· log_PotentialCrops: in development..
· YCParr, UniversalCID, TCSarr.... all the tables of the database (interest: developers)


log_Simulation.txt
Text file recording the simulation process carried out by the simulation algorithm. The log file reports on:

· "1. Simulation inputs": print out of the inputs to the Simulation algorithm (C++ program), e.g. print out of all the arrays, and standalone values.

· "2. Simulation through years": year by year, iteration by iteration:
- the new crop allocation,
- list of fields with unauthorised crop allocation,
- choices for crop reallocations,
- indexes...
If the "Detailed log file" was ticked on the simulation set up / Outputs tab, the iteration processes are saved in greater details (all intermediary crop allocations, detailed lists of unauthorised crop allocations).

· "3. Simulation outputs": print out of all the arrays (same arrays as in inputs)

· "4. Summary of simulation results":
- number of years of successful simulation
- if failed simulation, years and constraints which failed
- number of iterations used
- number of conditions which failed during the iteration process
- overall penalty index

top of page


Dbf Outputs
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition
- fields-crops / rotations
- fields-crops / initial crops

aim : To identify which dbf files will be saved within the project folder.

To save the following results in dbf files:

· Crop allocation to fields through years, currently only available from the pop up box displaying the crop allocation after the simulation.

· Yearly proportions of crops: crop proportions over the whole landscape for every year simulated.
· Penalties to fields incurred during the simulation: cf. simulation outputs for further details.

· overallFieldPenalties.dbf: the penalites incurred by the fields through the allocation algorithm, a "-1" row represents "all the fields". This file is only produced if conditions are being simulated.
created from FieldsPenalties table.
Every time a field has its crop altered to abide with the conditions of the simulation by using the iteration processes, the penalties defined in "IterationParameters" are applied. If the iteration process "1" is used (all fields have their crops changed), the penalties are comptabilised on the PlgID called "-1" (all fields). The penalties are accumulated over the years.

· overallFieldCondTimes.dbf: the penalities incurred by the fields, conditions by conditions, through the allocation algorithm. This file is only produced if conditions are being simulated.
created from FieldsConditionsTimes table.
Every time a field has an unauthorised crop allocation due to a specific condition, a penalty of 1 is given to the field-condition. The penalties are summed over the iterations and years.
nota bene: for these penalties no distinctions are made between the iteration options (random choice, crop group, universal crop).

· Export to SIGMEA Platform (Genesys): creates a new folder "Export2Platform" containing:
- Shapefile of the landscape
- CropBanks table: list of crops, eg. OSR, wheat....
- CropTypes table: list of crop types, eg. winter crops, OGM
- FinalCrops table: list of crops used within LandSFACTS (linking CropBanks and CropTypes)
- SuccessionsCrops: definition of the crop successions
- FieldsSuccessions: links between the fields and the crop successions
If the "add borders" option is enabled, the borders polygons are added to the FieldsSuccessions tables with the selected crop (e.g. Crop border - Border).

· Export to GIS format: creates a new folder "Export2GIS" containing:
- Shapefile of the landscape
- CropAllocation4GIS.dbf: PlgID and a column for each year of successful simulation with the crops full name.
In a GIS software import this table and the shapefile, and then join them through the PlgID to display the crops one year at a time.
· Create detailed log file: a log file on the simulation process is always created, however if this option is not ticked it is less detailed (the intermediate crop allocation and crops failing conditions are not printed for every iterations). It is recommended to keep this option non-ticked except if interested by the exact process within the program.

top of page


Sub-sets
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition
- fields-crops / rotations
- fields-crops / initial crops

aim : To identify which constraints & fields (landscape or group of fields) to simulate.

Conditions to integrate: By default all conditions are set to simulate ("To Simulate? = 1" equivalent to true). To not use one condition within the simulation, set "To Simulate? " to "0".

Fields to simulate: To be able to simulate on a sub-set (smaller than the landscape), no constraints imposed at a higher level should be to simulate. i.e. if only the fields of a farmer will be simulated, no yearly crop proportions constraints at the landscape scale should be set "to simulate".


Run simulation
Requirements:
- project open
- shapefile selected
- fields definition
- crop definition
- fields-crops / rotations
- fields-crops / initial crops
- simulation setup

Select "Optimised database".

The simulation may take from a few minutes to several hours, depending on the number of years of simulation, the number of constraints to simulate and the difficulty of finding an acceptable crop allocation. Please be patient!


Simulation outputs
Requirements:
- project open
- shapefile selected
- polygon attributes
- crop definitions
- rotation definitions
- assign to fields - possible crops
- assign to fields - rotations
- assign to fields - initial crops
- simulation set up
- run simulation

The Simulation outputs are saved within "simulationX" folder:
The outputs are only produced if the user request them in Simulation set up Text Outputs and Dbf Outputs .


Format of input data
This section provide information on how to create some of the input data.

In Format of input data
· How to prepare the shapefile?
· How to create the Polygon Attribute table?
· How to prepare the LandTypes table?
· How to prepare the Crop type table?
· How to prepare the CAP crop table?
· How to prepare the crop bank table?
· How to prepare the PossibleCrops table?
· How to prepare the Fields-Rotation table?
· How to prepare the InitialCrops file?
· How to prepare the YearlyCropProportions file?

How to create DBF in Excel? [ 2003]
In Excel 2007, SAVEDBF add-in is necessary. http://thexlwiz.blogspot.com/

General restrictions on importing dbf files:
· the software does not always manage correctly uncommon characters such as: ö, é, à, ä, è, ü, ', ``, ~. Please avoid using them.

Helpfile in progress.... This section has not yet been updated at all.


How to prepare the shapefile?
The shapefile must:
· comply with ESRI specifications (e.g. able to open in an ESRI application, such as ArcMap® or ArcView®).
· contain simple polygons composed of only one ring (no nested polygons, e.g. islands, no multi-polygons, lines, points...) --> in order for the software to calculate areas and centroids, and determines the neighbour table.
· have ONLY ONE COLUMN (attribute) called "Polygon_ID" (integer 6), containing integer values of the polygon id. The values must be unique (one Polygon_ID per polygon).

The shapefile files
A shapefile is composed of the three following files:
· main file (.shp)
· attributes data file (.dbf )
· index file (.shx)

Optional files (not used by LandSFACTS):
· coordinate system file (.prj )
· spatial index of features file (.sbn)
· metadata file (.shp.xml)

Example of Shapefile

In this example the polygon 10, is highlighted (selected).

top of page


How to prepare the Polygon Attribute table?

How to create the Polygon Attribute table?
Polygon Attribute dbf table
The table is composed of two columns:
· PlgID: Polygon ID (integer 6) refers to the polygons in the shapefile (see Preparation of the shapefile ),
· LandtyID.: land type ID refers to LandType table .
The exact labeling of the columns is not compulsory.

To create this table within excel, refer to How to create DBF in Excel? page.

top of page


How to prepare the LandTypes table?
Land Types dbf table
The table is composed of three columns:
· LandtyID.: ID of each land type. (integer, primary key)
· Name: Name to identify literally the land types (text)
· Def: Definition for the user (text)

To create this table within excel, refer to How to create DBF in Excel? page.

top of page


How to prepare the Crop type table?
The crop type table is defined as required by the Genesys model.
· The columns names must be spelled exactly:
· CTypeID (integer 4)
· TypeDef.(text 30)

Example of CropType.dbf table

To create this table within excel, refer to How to create DBF in Excel? page.

top of page


How to prepare the CAP crop table?
The CAP crop table may be derived from EU classification of crops.

The dbf table must comprise three columns:
· CAPCODE: code from EU
· CName: common name
· Def: any type of definition.
Note: The column names must identical to those listed above.

Example of CAPcrops.dbf table

To create this table within excel, refer to How to create DBF in Excel? page.

top of page


How to prepare the crop bank table?
The column names must be spelled exactly:
· CBankID (primary key): unique ID
· CAPCODE
· Cname (text 20)
· Def (text 50).
· The CAPcode and Def are optional columns.

Example of CropBanks.dbf table
No column should be left empty, if not they might not be imported.

To create this table within excel, refer to How to create DBF in Excel? page.

top of page


How to prepare the PossibleCrops table?
NOT UP TO DATE...

PossibleCrops dbf table

Importing this dbf table is not compulsory. The user interface may allocate possible crops to fields, by using the manual or program option (cf. Assign to fields - Possible crops ).

The dbf table must have the two following columns:
· PlgID: Polygon ID (integer 6) refers to the polygons in the shapefile (see Preparation of the shapefile ),
· CID: Crop ID refers to the possible crops of the field, refer to Reports-Crops to check the meaning of the CID (e.g. crop names).
Note: The column names must be identical to those listed above (no case sensitive). The presence of other columns would not hinder the import function.

Example of PossibleCrops.dbf table

To create this table within excel, refer to How to create DBF in Excel? page.

top of page


How to prepare the Fields-Rotation file?

How to prepare the Fields-Rotation table?
Fields-Rotation dbf table

Importing this dbf table is not compulsory. The user interface may allocate a rotation to each field, by using the manual or program option (cf. Assign to fields - rotations ).

The dbf table must have the two following columns:
· PlgID: Polygon ID (integer 6) refers to the polygons in the shapefile (see Preparation of the shapefile ),
· CRID: Crop rotation ID refers to the rotation used on the field, refer to Reports - rotations to check the meaning of the CRID (e.g. rotation names).
Note: The column names must be identical to those listed above. The presence of other columns would not hinder the import function.

Example of Fields-Rotations.dbf table

When importing, the program checks the existence of the PlgID as fields, and of the CRID.

To create this table within excel, refer to How to create DBF in Excel? page.

top of page


How to prepare the InitialCrops file?
InitialCrops dbf table

Importing this dbf table is not compulsory. The user interface may allocate the initial crop for each field, by using the manual or random program option (cf. Assign to fields - initial crops ).

The dbf table must comprise two columns:
· PlgID: Polygon ID (integer 6) refers to the polygons in the shapefile (see Preparation of the shapefile ),
· InitTMCID: The crop in the first year of simulation, referenced by its place within the rotation. To obtain the correct reference, cf. Reports , "Crops in each rotations". Alternatively, group of crops can be specified by using a minus in front of the group of crop ID ("-" GpCID, i.e. "-14" for refering to GpCID 14)
Note: The column names must be identical to those listed above. The presence of other columns would not hinder the import function.

Example of InitialCrops.dbf table

When importing, the software checks the existence of the PlgID as fields, and the existence of the TMCID within the crop rotation of the field.

To create this table within excel, refer to How to create DBF in Excel? page.

top of page


How to prepare the YearlyCropProportions file?
YearlyCropProportion table

Importing this dbf table is not compulsory. The user interface may allocate a rotation to each field, by using the manual option (cf. Yearly crop proportions ).

The dbf table must have the two following columns:
· SimYear: year within the simulation
· CID: crop ID refers to the crop definitions ( Reports - crops )
· Proporti: target crop proportion of the year. the value must be between 0 an 1 inclusive. A value of "-1" indicates that the proportion of this crop will not be checked.
· Dev: accepted deviation from the target crop proportion value.
Note: The column names must be identical to those listed above. The presence of other columns would not hinder the import function.

Example of YearlyCropProportions.dbf table
...
When importing, the program checks the existence of the SimYear and CID.

To create this table within excel, refer to How to create DBF in Excel? page.

top of page


How to create DBF in Excel?

How to create DBF in Excel? [2003]
To create a dbf table in Microsoft Excel
Two steps process: define name of the table as database and then save as dbf 4. The steps are detailed below.

Define name as database
· Highlight the table to save

· Select Main menu: Insert / Name / Define

· In Define Name window

· Names in workbook: Database
· Refers to: select whole table
· Ok

Save as:
· Highlight table
· Select: File / Save as, format: DBF 4 (dBASE IV, *.dbf).

top of page


General tips

· Dealing with large landscapes

· Miscellaneous tips


Dealing with large landscapes

Definition of large landscape: above 40,000 polygons on which to simulate crops/land uses.
Large number of polygons induces much larger tables within the database, and currently slows down the database transactions in the interfaces.

Recommendations to speed software use:
· avoid displaying the landscape map
· importing large dbf files can be extremely slow and may fail (particularly for fields-rotation, fields-initial crops, and land capability fields). It is easier to import text files using the export/import from Txt in main menu / File.

If the process is still too slow, it might be best to by-pass the LandSFACTS interface and directly work with LandSFACTS standalone version which is console controlled and takes text files as inputs. To export the data from the interface to the standalone version: main menu / File / Export to C++ standalone.
n.b. the standalone version is available upon requested.


Miscellaneous tips
Database:
All the data tables used in LandSFACTS are stored in an SQLite database
Manipulating the LandSFACTS databases outside of LandSFACTS is strongly discouraged.
If external manipulation or viewing of the database is required, the following free, open source software may be used to view or export the tables:
sqlitebrowser (http://sourceforge.net/projects/sqlitebrowser/ )
(SQL knowledge is indispensable).

Ticks on toolbars:
A green tick appears on the toolbar when the step has been completed.
A orange tick appears on the toolbar if all the fields are not linked to a rotation. The simulation will run normally only for the fields with rotation, the other fields are not considered.


Project examples
The following three example datasets are presented:

· Example 1 : To determine the impact of a separation distance between GM and conventional OSR in an existing landscape (known rotation and crop percentage), on the quantity of GM OSR which could be grown.
· Example 2 : To obtain a 5 years crop allocation, which respects yearly crop proportions over the landscape, temporal and spatial constraints. Not yet updated to version 2.0...
· Example 3 : To obtain a 1 year crop allocation, which respects crop proportions over the landscape, temporal and spatial constraints. Not yet updated to version 2.0...
· Two tutorials are provided. Both are composed of a tutorial project folder and a pdf presentation (LandSFACTS_v2-0_Tutorial.pdf), which details the steps for creating and running a project. All the files are present within the Tutorial folder, cf. below.
· Tutorial_Crops: An example of crops simulations
· Tutorial_LandUses: An example of land use scenarios simulations

Each example dataset is available within the following directories:
\LandSFACTS\Example_data_v2_0\Projects\Project_Tutorial


Example 1

Example 1 - Fixed rotations

Aim of the simulation:
To determine the impact of a separation distance between GM and conventional OSR in an existing landscape (known rotation and crop percentage), on the quantity of GM OSR which could be grown.

This example demonstrates the use of LandSFACTS with:
- limited spatial extents of crops
- fixed crop rotations,
- allocate rotations to fields, to respect spatial extent of crop, crop proportion & spatial patterns
- allocate initial crops to field, to respect temporal patterns
- spatial constraints, crop priority
- adapted iteration options

· BigLandSCAPE shapefile: 201 fields, 3 build up area, 5 forests. (using "LandSCAPE\BigLandSCAPE" folder files)

· 9 crops (using "Crop_Definitions\CropTypes_versatile.dbf & CropBank_versatile.dbf")

· 4 fixed crop rotations (binary transition matrix)

· Land Capability to fields. Fields with less than 5,000m2 may only have vegetables and fallow crops. Larger fields may have any crop except vegetables.
Two land capability are defined: i) all non-vegetables ii) vegetable & fallows [both with flag crops]

The LandCapabilityToFields.dbf to import is prepared using the "Reports/Areas and centroids for polygons", and "LandCapability definitions", applied for all years (year = -1)

· Rotation to fields using program: target crop proportions and gm rotation spatially grouped

- number of randomisation points: 10,000; number of iterations: 10,000.

- Results of rotation allocation to fields:

The crop rotation with gm are in red, the conventional in yellow, the vegetables in brown, set-aside in green and non fields in grey. The fields with gm rotation (in red) are clearly spatially grouped.
· initial crops in fields using "InitialCrops program" high temporal aggregation of gm OSR and low temporal variation for wheat, number years: 10, randomisation points: 1000, iterations: 1000, optimisation

- Results:

By running the simulation without any constraints, it is possible to check that the yearly crop proportions are as required: low variation of wheat proportions, and high variation of gmOSR proportions over the years, cf. graph.

· spatial constraints: 200 meters between gm and conventional OSR, in case of conflict, GM OSR should be removed (crop priority = 1).

· Iteration options. The simulation aims at knowing the number of GM OSR, which could not be grown within the current landscape due to the separation distances. The universal option "flag crop" (2.3) is used with up to 200 iterations (e.g. as the landscape has 200 fields, the simulation will be successful). A penalty of 1 will be recorded every time this iteration option will be used within the simulation process.
The crop rotations are fixed (only one choice of crop succession), thus using new random choices would not be helpful, except to alter the initial crops. It is preferred to not alter more than necessary the initial crops, so the option 1. is set to 0, and the option 2.1 to 100 iterations.
There is no need for simulated annealing, as only one constraint is to simulate.

· Run simulation

--> RESULTS:

These results are only one example.

Crop allocation map Legend:
conventional OSR
gm OSR
flag crop
winter wheat
winter barley
vegetables
set-aside
build up

Crop allocation maps:
In the first year of crop allocation (year 0), no gm crops were allocated, cf. below
year 0
In the second year, the field were GM oilseed rape should have been grown were not authorised (flag crops instead of GM oilseed rape),as they are too close to conventional oilseed rape fields.1 field has a GM crop (away from conventional).
year 1
In the third year, only 7 fields had their GMoilseed rape authorised.
year 2
The fourth year (year 3) is identical to the first year (year 0), as the crop rotation have a three year length, except for fields where the flag crop was used.
year 3

Conclusion on crop allocation:
Only one year in three has no conflict between GM and conventional oilseed rape, because the initial crops (year 0), were optimised by randomly altering them, to meet the spatial constraints. This possibility was not available for subsequent year, inducing the flag crop being grown instead of gm to respect the separation distances.
By running the simulation many other times, other crop allocation would be found.

- Overall field penalties: the fields in light orange had their GM oilseed rape replaced once by the universal crop, the dark orange twice.

top of page


Example 2

Example 2 - Flexible rotations
Not yet fully updated to version 2.0...

Aim of the simulation:
To obtain a 5 years crop allocation, which respects yearly crop proportions over the landscape, temporal and spatial constraints.

This example demonstrates the use of LandSFACTS with:
- limited spatial extents of crops
- flexible crop rotation,
- allocate rotations to fields, to respect spatial extent of crops
- random initial crops
- temporal constraints
- spatial constraints, crop priority
- yearly crop proportions
- adapted iteration options

· BigLandSCAPE shapefile: 201 fields, 3 build up area, 5 forests.

· 14 crops (no crop 6)

· Crop groups: cereals & OSR

· 3 crop rotations
vegetables: only vegetables
permanent set-aside: only fallow
all crops: 10 crops with equal probability of transitions between them. This rotation does not impose any temporal restrictions. Rules on forbidden crop successions must be set up in the temporal constraints (return period, forbidden sequences...).

· Land Capability to fields. Fields with less than 5,000m2 may only have vegetables and fallow crops. Larger fields may have any crop except vegetables.
Two land capability are defined: i) all non-vegetables ii) vegetable & fallows [both with flag crops]

The LandCapabilityToFields.dbf to import is prepared using the "Reports/Areas and centroids for polygons", and "LandCapability definitions", applied for all years (year = -1)

· Rotation to fields using program: target long-term crop proportions (only set for permanent fallow).

obtained long-term crop proportions:
final rotations to fields

Display of crop rotations to fields (blue: all crops, brown: vegetables, green: set-aside, grey: build up)

· Initial crops in fields: randomly chosen during the simulation.
· temporal constraints - maximum repetition of wheat, winter & spring barley: 3 years
return period of oilseed rape (gm & conv): 2 years

· temporal constraints - forbidden crop sequences: OSR gm - any crop - OSR conv

· All temporal constraints linked to all fields
· Spatial constraints: 100m between gm and conventional oilseed rape, crop priority: GM oilseed rape to be altered first.

· Yearly crop proportions: only the winter wheat, conventional and gm oilseed rape are being controlled.
The winter wheat proportions for all the years is set a 0.3min, 0.32max, leading to a stable wheat proportions over the years.
The oilseed rape crops will be more variable over the years and a switch from conventional to GM is simulated. GM oilseed rape will start with no crop in the first year, and in the subsequent years its proportion will increase, while conventional OSR decreases.

· All the constraints are to be simulated over 5 years.
· Iteration options: The "all crops" rotation is an extremely flexible rotation, i.e. for any crop in year, in the following year, any of 10 crops can be grown. To find a crop allocation meeting all the constraints, high number of iterations with random choice is a good solution. For this example, in case of non authorised crop allocation, all the crops will be chosen again randomly 100 times (option 1), then if there is still unwanted allocation, 10,000 iterations of new random choice for problematic fields only (option 2.1). No penalties are linked to this options, as a new choice within the flexible rotation is supposed to be normal.
To determine, if any field still have problems after all those random iterations, the universal crop is used with "flag crop" 200 times (option 2.4), with a penalty of 100.

The simulated annealing option will be used after 100 successive and unsuccessful iterations.

Simulation results

A crop allocation meeting all the constraints for all the simulation years was found without using the universal crop option (no penalty to fields). The program used 17,223 iterations with new random choice within the crop rotations to obtain the crop allocations over the 5 years.

By running many times the same simulation (batch mode for example), a different crop allocation for every year could be found. All those crop allocations would meet the spatial and temporal arrangements of crops.

The constraints imposed on the landscape didn't prevent the program to find a crop allocation. For example, by running the same simulation but with a separation distance of 500m instead of 200m, the number of iterations required might be more numerous and it could even be possible that no crop allocation were found.

Display of crop allocation:
year 0
year 1

year 2
year 3
year 4

top of page


Example 3

Example 3: 1 year
Not yet fully updated to version 2.0...

Aim of the simulation:
To obtain a 1 year crop allocation, which respects crop proportions over the landscape, temporal and spatial constraints.

This example demonstrates the use of LandSFACTS with:
- limited spatial extents of crops
- 1 year crop rotation
- allocate rotations to fields, to respect spatial extent of crops, and crop proportions
- spatial constraints, crop priority
- adapted iteration options
The simulation program is more powerful than the RotationFields program and considers the spatial constraints between the crops. Thus to achieve the aim of this example, the allocation of the crops to fields is done using the Simulation program (by having one crop rotation with all the crops) instead of the RotationFields program (by creating a crop rotation for each crop).

· BigLandSCAPE shapefile: 200 fields, 3 build up area, 5 forests.

· 14 crops

· 3 crop rotations.
vegetables: only vegetables
permanent set-aside: only fallow
all crops: 10 crops with equal probability of transitions between them. This rotation does not impose any temporal restrictions (and there is no need for them, as only one year will be simulated).

· Land Capability to fields. Fields with less than 5,000m2 may only have vegetables and fallow crops. Larger fields may have any crop except vegetables.
Two land capability are defined: i) all non-vegetables ii) vegetable & fallows [both with flag crops]

The LandCapabilityToFields.dbf to import is prepared using the "Reports/Areas and centroids for polygons", and "LandCapability definitions", applied for all years (year = -1)

· Rotation to fields using program: target long-term crop proportions (only set for permanent fallow).

Display of crop rotations to fields

· Initial crops: random crop allocations. The Simulation program will be used to determine the crops in the initial and unique year.
· Temporal constraints: none specified, as the simulation will be run only one year.
· Spatial constraints: 150m between GM and conventional OSR. In case of conflict, gm maize will be removed (crop priority = 1).
· Yearly Crop proportions:

· Iteration parameters
The initial years are optimised by using new random choice for all fields (1. with 1,000iterations) and by changing one field at a time (2.1. with 10,000iterations). The flag crop is used as universal crop up to 200 times with a penalty of 100.

· Run the simulation once with a time seed.

==> Results

A crop allocation was found meeting the crop proportions and the separation distances, after 1851 iterations, without any penalties (only new random choice were used, no universal crops).

Display of crop allocation:

top of page


Verification & Validation
Not yet updated to version 2.0...

LandSFACTS aims at providing a crop for each field for every year, that meets user-defined conditions on the crops arrangements.

LandSFACTS does not aim at forecasting or predicting crop allocation. The model only follows the rules set up by the user. Therefore the model does not require validation and cannot be fully validated.

· Validation:
Only one configuration of inputs will provide a forecastable crop allocation, which can be validated:
- only fixed crop rotations (only transition probabilities equal to 1 or 0)
- a known rotation per field
- a known initial crop per field
- no constraints (spatial, temporal, yearly crop proportions)

This validation was carried out using the Dijon dataset provided by Nathalie Colbach, INRA-Dijon.
Dataset tested comprises:
- a landscape with 72 fields
- 21 individual crop rotations of 1 to 6 years length, all fixed rotation (binary transition matrices)
- a known crop rotation per field
- a known initial crop per field

The crop allocation generated by LandSFACTS over 10 years, agrees perfectly with the crop allocation of the real landscape.

This validation confirms that the model integrates correctly:
- the link between fields and rotations
- the link between fields and initial crops
- the link between initial crop and crop rotation
- the link between crop rotation and their crops
- the probabilities within transition matrices
- the number of years to simulate

· Verification
LandSFACTS was verified as much as it was possible. Some of the tests are reported below:

· Crop allocation with for each field a known fixed rotation and initial crop
This type of inputs has been verified and validated with the Dijon Dataset.

· Crop allocation with for each field a known flexible rotation and initial crop
This type of inputs has been verified with:
- BigLandSCAPE shapefile (200 fields)
- 1 crop rotation for all fields:
- for all fields, the initial crop is wheat.
- the simulation is run for 200 years

Results:
- odd year numbers have 100% of wheat.
- even year numbers have 0% of wheat
For the even year numbers:
- winter barley crop proportion (area) : 49.77%
- spring barley crop proportion (area) : 50.23%
The slight difference in crop proportion between the crops is probably due to two factors: limited number of replicates (2,000 units = 100 years * 200 fields) and the proportions are calculated over the total area of each crop instead of number of fields.

· Detecting spatial constraints
Verified using:
- SmallLandSCAPE shapefile
- 1 crop rotation for all the fields:
- for all fields, initial crop is wheat.
- spatial constraints : 150m between GM and conventional OSR
- crop priority: if fields with GM and conv. OSR are conflicting, the GM crop should be changed (priority "1").

· Detecting temporal constraints - return period of crops
Verified using:
- SmallLandSCAPE shapefile
- 3 different OSR (to faciliate their identification)
- 1 crop rotation for all the fields:
- for all fields initial crops is OSR1
- 1 temporal constraint: return period of OSR1, OSR2 & OSR3 set to 2.
- the temporal constraint is applied to all fields
- iteration option: only new random choice within rotation for problematic fields, maximum iteration: 200times, penalty to fields = 1.
- simulation years = 12 (3 times the rotation).

The crop allocation obtained agrees with the expected result: no OSR2 allocated to the fields, instead of OSR2, Wheat is chosen through the iteration process (new choice within transition matrice).

· Detecting temporal constraints - maximum consecutive years of crops
Verified using:
- SmallLandSCAPE shapefile
- 3 different OSR (to faciliate their identification)
- 1 fixed crop rotation for all the fields: OSR1 - OSR2 - OSR3 - Wheat
- for all fields initial crops is OSR1
- 1 temporal constraint: oilseed rape can be grown consecutively up to two years in a row.
- the temporal constraint is applied to all fields
- iteration options: only universal crop called "flag crop", with 200 maximum iterations, penalty to fields = 1.

The crop allocation obtained agrees with the expected result: no OSR3 allocated to the fields. Instead of OSR2, the "flag crop" was grown.

· Detecting temporal constraints - forbidden crop sequences
Verified using:
- SmallLandSCAPE shapefile
- 3 different OSR (to facilitate their identification)
- 1 fixed crop rotation for all the fields: spring Barley - OSR1 - winter Barley
- for all fields initial crops is spring Barley
- 1 temporal constraint: forbidden sequence: spring barley - any - winter barley
- the temporal constraint is applied to all fields
- iteration options: only universal crop called "flag crop", with 200 maximum iterations, penalty to fields = 1.

The crop allocation obtained agrees with the expected result: no winter barley allocated to the fields. Instead of winter barley, the "flag crop" was grown.

· Checking many temporal constraints at the same time
Verified using:
- BigLandSCAPE shapefile (200 fields)
- 6 fixed crop rotations
- a rotation randomly allocated for each field
- for all fields, initial crops is the first crop of the rotation.
- forbidden crop sequences:

- return period of crops and maximum repetition
- all temporal constraints to all fields
- 10 years of simulation

The penalties to fields from the simulation agrees to the expected conflict between the crop rotations and the constraints.

· Reach target yearly crop proportions
Verified using:
- BigLandSCAPE shapefile
- 1 rotation: equal probabilities of transition between 10 crops.
- initial crops for all the fields: randomly chosen during simulation
- yearly crop proportions: proportions of OSR conventional and GM vary through the years.

- simulation for 5 years.

The calculated yearly crop proportions saved as dbf file at the end of the simulation are within the yearly crop proportions targets set.

· Check all types of conditions (temporal, spatial, crop proportions) at the same time
- 3 rotations: perment set-aside, vegetables, allcrops (equal transition between 10 crops).
- yearly crop proportions for wheat, gm and conventional oilseed rape, cf. reach target yearly crop proportions.
- 1 return period (wheat, w & s barley, 1 maximum repetition constraints (OSR gm and conventional & 1 forbidden crop sequence (conventional after gm, with 1 year gap)
- 1 spatial constraint (crop priority: GM OSR = 1, all others = -1)
- 5 years simulation
- all conditions to simulate
- iteration options
After 8026 iterations, the resulting crop allocation meets all the constraints (they have been checked by hand one at a time).

· Coherence between crop allocation outputs
Outputs checked:
- Crop Allocation.dbf
- Export2GIS (CropAllocGIS.dbf)
- Export2Platform (fieldsSuccessions.dbf & SuccessionCrops.dbf)
- Simulation logfile (log_Simulation.txt, Simarr array)

The coherence between those outputs was checked for:
- fixed crop rotation - add borders (ok - using Dijon dataset)
- fixed crop rotation - no borders (ok - using Dijon dataset)
- flexible crop rotation - no borders (ok - using BigLandSCAPE dataset)

top of page


Additional information
Topics covered:

For users:
· Tips on LandSFACTS use
· Glossary
· Spatial and temporal patterns of crops
· Crop rotations in LandSFACTS
· Publications
· Website

Development information:
· Database tables
· Version information
· Software development
· Why LandSFACTS?


Glossary
ACC: type of crop re-allocation (Altered Crop Choice)

Conditions: conditions imposed on the crop allocation, cf. spatial & temporal arrangements

CRID: crop rotation ID, unique number (integer) identifying the crop rotations.

GM: Genetically Modified crops, equivalent to "transgenic crop".

InitTMCID: Initial Transition matrix crop, unique number (integer) identifying the crop place within the rotation in the first year of simulation
cf. TMCID

TMCID: Transition matrix Crop ID, unique number (integer) identifying a place within the rotation. The TMCID are assigned to crops within a rotation chronologically as the user inputs the crops within the rotation, cf. Initial rotations - crops order within rotation .

OSR: oilseed rape crop.

PlgID: polygon ID, unique number (integer) identifying the polygons. More generally it may also refer to the fields (where to grow crops).

Project folder: to hold all the data managed by LandSFACTS: shapefile, database, exported tables, log files of the simulation. It is recommended to create a new folder for each project, to avoid any risk of overwriting previous simulations.

Spatial constraints: cf. spatial & temporal arrangements

Spatial pattern: cf. spatial & temporal arrangements

Temporal constraints: cf. spatial & temporal arrangements

Temporal pattern: cf. spatial & temporal arrangements


Spatial and temporal patterns of crops
The datasets to analyse spatial and temporal patterns of crops are qualitative data linked to discrete spatial units: 1. each crop is a discrete unit (e. g. wheat, oilseed rape, fallow; 2. the crops are grown in fields represented as polygons (vector format). The characteristics of the datasets require specific statistical tests. Statistical analyses of temporal patterns of spatial datasets are nearly non-existent in the literature. Statistical analyses of spatial patterns has been explored in landscape ecology (Fortin et al., 2002; McGarigal, 2002). However analyses in landscape ecology focus mainly on quantitative data linked to a continuous landscape (raster format) (Gustafson, 1998). Such analyses are not relevant to our particular needs. Thus, specifically designed statistical analyses needed to be set up to study the spatial and temporal patterns of crops grown in fields in agricultural landscapes.

1. Definition of temporal patterns of crops
Temporal patterns of crops are highly influenced by crop rotations (the regular, repeated sequence of crops planted in a given field). The structure and crop sequence of the rotation determines the recurrence of crops in the same field. Temporal patterns of crops are also influenced by the synchronisation of crop rotations between multiple fields. Temporal pattern is measured in terms of temporal homogeneity and temporal heterogeneity, cf. Table 1.

Table 1: Example of temporal patterns of crops, for three fields following a three years rotation
Field number | Temporal homogeneity |  |  | Temporal heterogeneity
 | year 1 | year 2 | year 3 | year 1 | year 2 | year 3
1 | wheat | winter barley | oilseed rape | wheat | winter barley | oilseed rape
2 | winter barley | oilseed rape | wheat | wheat | winter barley | oilseed rape
3 | oilseed rape | wheat | winter barley | wheat | winter barley | oilseed rape

2. Definition of spatial patterns of crops
Spatial patterns of crops may be influenced by environmental conditions, such as crops requiring specific soil characteristics, and by agronomic constraints, such as separation distances between seed and food crops. Spatial pattern of crops is defined as a departure from spatial randomness, with spatial aggregation (crops close to identical crops) at one extreme and spatial homogeneity (each crop spread evenly throughout the landscape), also termed regularity in ecology (Perry et al., 2002), at the other. Examples are illustrated in Figure 2.1.

Figure 2.1: Examples of extreme spatial patterns of crops (Castellazzi et al., 2006).

(a) extreme spatial heterogeneity of crops in fields, large aggregation of identical crops; (b) extreme spatial homogeneity of crops in fields, no crops nearest neighbour of itself.

3. Definition of spatio-temporal patterns of crops
Spatio-temporal patterns of crops in a landscape occur when the temporal pattern of crops in fields covaries with the spatial pattern of those fields. For example, to reduce the grower’s work, a spatial cluster of fields away from the rest of the farm may be given the same rotation at the same stage (all fields in the same crop of the same rotation each year), resulting to a spatio-temporal aggregation (heterogeneity) of the crops.

4. Statistical tests
To test the spatial and temporal patterns of crops in landscapes, four tests were devised: two of temporal pattern, one of spatial pattern and one of spatio-temporal pattern, which also can be used for spatial pattern. A summary of the tests are presented in Table 2. For a full description of the methods, see Castellazzi et al. (2006).

Table 2: Summary of spatial and temporal analyses
Pattern studied | Tests | Focus | Analysis
Temporal pattern | Test of temporal heterogeneity within rotations | Phasing of fields following same rotation | Chi-square test per grower, per rotation
 | Test of temporal heterogeneity across rotations | Crops' temporal variability compared to random simulation | Randomisation test of percentage of coefficient of variation of crops through time (per grower, per crop)
Spatial pattern | Test of spatial pattern | Fine pattern | Chi-square test of neighbouring crops
 | alternative test of spatial pattern | General trends | "E"-analysis of groups of crops
Spatio-temporal pattern | Test of spatio-temporal heterogeneity within rotation | General trends | "E"-analysis of groups of identical crop sequences

Each of these statistical tests analyses the crop patterns from a specific viewpoint representing complementary descriptors of the crop patterns. Because, spatial, temporal and spatio-temporal patterns of crops do not exist independently of each other, only concurrent use of the tests can provide an overall understanding of the patterns occurring in the landscape.

5. Patterns observed in real landscape
Using the new statistical descriptors, the spatial and temporal patterns of crops on a dataset from a real landscape were analysed. The study landscape comprised 72 arable fields farmed by 10 individual growers in Burgundy (France). The dataset consists of the crops grown and the crop rotation followed for each field. The main crops were oilseed rape (Brassica napu) and winter wheat (Triticum spp.), plus winter barley (Hordeum spp.), set-aside, and small amount of spring barley (Hordeum spp.) and rye (Secale spp.).

The test of temporal heterogeneity within rotations clearly showed an overall temporal heterogeneity of crops (aggregation), indicating that fields following the same rotation tended to be temporally phased with each other by growers.

The test of temporal heterogeneity across rotations detected no clear rules of temporal patterns; the degree of temporal homogeneity or aggregation was grower- and crop-dependent. The temporal occurrence of crops in a grower’s fields were either regular (same proportion of the crop every year, temporal homogeneity) or aggregated (proportion highly varying through time, temporal heterogeneity), and many grower’s crops showed no strong patterns (Castellazzi et al., 2006).

Temporal regularity of crops could be explained by the desire to have a constant quantity of a crop every year, or by the need to spread out risks (multiple crops every year). Temporal aggregation could be employed to respond to yearly fluctuating market trends (Orson, 2005).

The analyses of the Burgundy study area were carried out at two scales: the study area level and the farm level. Overall no strong spatial patterns were evident. However spatial patterns were significant. For example a grower’s fields showed consistent aggregated spatial patterns through the years (Castellazzi et al). Set- aside was clearly spatially aggregated and tended not being adjacent to wheat, this pattern could be caused by the spatial separation of “good soil” for wheat and soil of lower quality for set-aside (Nagendra et al., 2004).

The test of spatio-temporal patterns of crops showed aggregated patterns of crops for two growers (the fields of one grower are presented in Figure 5.1), indicating that temporally grouped crops could also be spatially grouped.

Figure 5.1: Spatio-temporal patterns of a grower in Burgundy study landscape.

The fields followed the same three-year crop rotation: oilseed rape, winter wheat, and winter barley. The crops displayed in the figure were grown in 1995. The fields in black shading belong to other growers, or are not in this rotation.

· Spatial, temporal and spatio-temporal patterns of crops are present
· The patterns may be either aggregated or homogeneous.
· Crop patterns were found at multiple scales (e.g. farm to landscape)
· They tended to be both crop- and grower-dependent
· The degree of spatial and temporal phasing is an important component of crop patterns, and should be included in the modelling of crop pattern in agricultural landscape (Castellazzi et al., 2006).

References
Castellazzi, M.S., Perry, J.N., Colbach, N., Monod, H., Adamczyk, K., Viaud, V. and Conrad, K.F. (2006). New measures and tests of temporal and spatial pattern of crops in agricultural landscapes. Agriculture, Ecosystems and Environment xxx: xxx-xxx.
Fortin, M.-J., Dale, M.R.T. and ver Hoef, J. (2002). Spatial analysis in ecology. in Encyclopedia of Environmetrics. A. El-Shaarawi and W. W. Piegrorsch, eds. Chichester, John Wiley & Sons, Ltd.
Gustafson, E.J. (1998). Quantifying Landscape Spatial Pattern: What is the State of the Art? Ecosystems(1): 143-156.
McGarigal, K. (2002). Landscape pattern metrics. in Encyclopedia of Environmentrics. A. El-Shaarawi and W. W. Piegrorsch, eds. Sussex, England, John Wiley and Sons. 2: 1135-1142.
Nagendra, H., Munroe, D.K. and Southworth, J. (2004). From pattern to process: landscape fragmentation and the analysis of land use/land cover change. Agriculture Ecosystems & Environment 101(2-3): 111-115.
Orson, J. (2005). Discussion on crop rotation in South-England. J. N. Perry and M. S. Castellazzi.
Perry, J.N., Liebhold, A.M., Rosenberg, M.S., Dungan, J., Miriti, M., Jakomulska, A. and Citron-Pousty, S. (2002). Illustrations and guidelines for selecting statistical methods for quantifying spatial pattern in ecological data. Ecography 25(5): 578-600.

top of page


Crop rotations in LandSFACTS
Crop rotation is one of the oldest and most fundamental agronomical rules, and is followed worldwide. The basis for crop rotation is the successive growing of different crops on a specific field. The alternation of crops with different biophysical properties allows good yields by maintaining the soil quality, and by preventing the spread of diseases and pests (Kirkegaard et al., 2004).

Crop rotation has further advantages as it allows the farmer to rely on several crops in the same year, thus decreasing economic risk due to the failing of a culture or of its market price. Moreover, as each crop is managed differently, the labour workload, such as planting, spraying, and harvesting is more spread out through the year (Cook and Weller, 2004).

The principles of crop rotations constrain their structures. The length of the crop rotation is variable and depends mainly on the longest return period of any of the crops grown. For example, wheat can be grown several years in a row, however potatoes can be grown on a field only every 5 years in the Pays de Caux, France (Joannon, 2004).

Another important factor influencing the crop rotation structure is the succession of crops. Some crops should not immediately succeed some other one, for example winter barley is not grown before wheat (Joannon, 2004). Below an example of possible crop rotation is featured (Figure 1):

Figure 1: Example of flexible crop rotation.

after Joannon (2004).

Another point which must be considered is the crop cycle. Each crop has its own sowing and harvesting period, and logically, one field's crop must be harvested before the sowing of the next crop. These limits lessen the choices of crop rotation. Furthermore, in some years, due to exceptional weather conditions, the crop rotation must be altered to respect crop cycles. For example, a lower than normal light level during the summer, may delay wheat harvest to much later in the year; thus preventing the next winter crop being sown on time. In this event a spring crop would be sown.

Every farmer does not follow crop rotation in the same manner. Possibilities may be classified into four groups : 1. fixed rotation -- the crop rotation is fixed in advance and is followed exactly; 2. semi-fixed rotation -- the main crop rotation is fixed in advance, but depending on a particular condition of the year (weather, economic) crops could be changed for another one which has the same function in the rotation; 3. flexible rotation -- the agronomic principles of the crop rotation are generally followed, but the specific pattern is determined year by year according to economic constraints; 4. the principles of crop rotation may not be followed at all, and crop monoculture may be practised (Cook and Weller, 2004).
For example, in Joannon's (2004) study, farmers were divided into two groups: one group followed a fixed rotation and on 10% of their fields a flexible rotation was followed; the second group followed only flexible rotations, which were not determined in advance.

1. Mathematical classification of crop rotations
Mathematically, crop rotations may be classified into four categories (see. Figure .2). These crop rotations are all accepted by LandSFACTS. However to be integrated into the program, the diagrams must be translated into matrices representing the transitions between crops.

Figure .2: Mathematical classes of crop rotations

2. Rotations as transition matrices

Crop rotations can be considered as sets of rules dictating crop successions, where the crop in year n conditions the crop in year n+1. By assuming that only the previous crop grown influences the next crop, the crop rotations may be represented as a transition matrix, which is a specific case of Markov chains (also called stochastic matrix, Cox and Miller, 1965).
A crop transition matrix (TM) is
· a square matrix TM[i][j], n rows and n columns, with n the number of crops;
· in each cell TM[i][j], the probability of transition from crop [i] to crop [j], the values are between 0 and 1 inclusively;
· the sum of the probabilities of each row adds up to 1.

Three examples of transition matrix are presented below:

Figure 3: Transition matrices of crop rotations

The representation of rotations by transition matrices allow a wide range of landscape to be modelled. For example, in some agronomical areas rotations are highly fixed (like in Burgandy, Colbach et al. 2005), whereas in areas more susceptible to market variation, only the main rotation principles are be followed (like the Fife agricultural area or in south-east England, Orson, 2005).

3. Long term crops proportion
The proportions of the crops over time are defined by the crop rotations, and thus may be calculated from the transition matrices. By multiplying the matrix by itself many times (called the “burn-in period” in LandSFACTS, default value: 200 times), the resulting matrices converge towards a steady state. In the case of a transition matrix containing 0 and 1, such as in fixed rotations, the steady state is evaluated by carrying out further multiplications (called the “saving period” in LandSFACTS, default value: 100 times) and averaging the resulting matrices. The averages of the columns of the steady state corresponds to the long term proportions of each crop in the rotation.

Figure 4: Calculation of long term proportions

References

Cook, R.J. and Weller, D.M. (2004). In Defense of Crop Monoculture. Proceedings of the 4th International Crop Science Congress: New directions for a diverse planet, Brisbane, Australia.
Cox, D.R. and Miller, H.D. (1965). The Theory of Stochastic Processes.
Joannon, A. (2004). Coordination spatial des systemes de culture pour la maitrise de processus ecologic. Ph.D Thesis, INRA Paris-Grignon. 393pp.
Kirkegaard, J., Christen, O., Krupinsky, J. and Layzell, D. (2004). Break crop benefits in temperate wheat production. 4th International Crop Science Congress.

top of page


Publications
Model description

Castellazzi, M.S., Matthews, J., Angevin, F., Sausse, C., Wood, G.A., Burgess, P.J., Brown, I., Conrad, K.F., and Perry, J.N. 2010. Simulation scenarios of spatio-temporal arrangement of crops at the landscape scale. Environmental Modelling and Software. 25, 1881-1889.

Castellazzi, M. S., Matthews, J., Wood, G. A., Burgess, P. J., Conrad, K. F., and Perry, J. N. 2007. LandSFACTS: Software for Spatio-temporal Allocation of Crops to Fields Proceedings of 5th Annual Conference of the European Federation of IT in Agriculture. Glasgow, UK, 1-8-2007.
http://www.efita.net/apps/accesbase/bindocload.asp?d=6176&t=0&identobj=Yaf4lDsD&uid=57305290&sid=57305290&idk=1

Castellazzi, M.S., Perry, J.N., Colbach, N., Monod, H., Adamczyk, K., Viaud, V., and Conrad, K.F. 2007. New measures and tests of temporal and spatial pattern of crops in agricultural landscapes. Agriculture Ecosystems & Environment. 118 (1-4), 339-349.

Castellazzi, M. S. 2007. Spatio-temporal modelling of crop-coexistence in European agricultural landscapes. PhD Thesis, Cranfield University - Cranfield, UK.
https://dspace.lib.cranfield.ac.uk/bitstream/1826/3747/1/Castellazzi_Thesis_2007.pdf

Castellazzi, M.S., Wood, G.A., Burgess, P.J., Morris, J., Conrad, K.F., and Perry, J.N. 2008. A systematic representation of crop rotations. Agricultural Systems. 97, 26-33.
https://dspace.lib.cranfield.ac.uk/handle/1826/3370

Model application

Castellazzi, M. S., Brown, I., Poggio, L., and Gimona, A. 2010. Multi-scale modelling of ecosystem services - an iterative approach. In: Modelling for Environment's Sake. 2010 International Congress on Environmental Modelling and Software. Ottawa, Canada, 2010 http://www.iemss.org/iemss2010/index.php?n=Main.Proceedings

Castellazzi, M. S., Joannon, A., Brown, I., Gimona, A., and Poggio, L. 2010. Developing a nested-scale landscape modelling framework for ecosystem services. 2010 International Conference on Integrative Landscape Modelling - LandMOD2010, Montpellier 3-5 February. http://www.umr-lisah.fr/rtra-projects/landmod2010_abstracts.html

Baggaley, N. J., Lilly, A., Castellazzi, M. S., and Walker, R. 2009. Soil quality = Water quality? Soil erosion modeling at a catchment scale International conference on Soil quality = Environment quality. Teagasc, Ireland. 9-11th September 2009.

Gimona, A., Poggio, L., Castellazzi, M. S., and Brown, I. 2009. Vulnerability of ecological networks to direct and indirect climate impacts. International Association for Landscape Ecology - Ecological networks: Science and Practice. Edinburgh, UK. 1-9-2009.

Joannon A., Vasseur C., Boussard H., Castellazzi M.S., Schermann N., and Baudry J. 2009. A method to assess farmers' room for maneuvring crop location at the landscape level for biodiversity conservation. Farming Systems Design 2009 Conference. Monterey, CA.


Version information
New versioning system since 2.0.0:
Version system: majorVersion . FeaturesChanges . InterfaceChangesOrBigBugFix
The “build” indicates the latest recompilation date of the code, i.e. either for small bug fixes or slight interface changes.
The version of the software & c++ simulator are reported in the "About" on the main toolbar.

What's new in Version 2.0.4?
· Past Allocation constraint
· Enhanced iteration parameters & algorithms
· Enhancement of user-interfaces
· Bugs fixing

What's new in Version 2.0?
· Map display
· definition of group of fields & crops
· Yearly crop proportions constraint for group of crops and group of fields
· Simulations on sub-sets
· Constraints in progress: possible crops, connectivity, linked fields
· Simulation on large landscape available (i.e. 40,000 polygons)
· Enhanced iteration parameters & algorithms
· Enhancement of user-interfaces
· Bugs fixing

What's new in Version 1.6?
· Temporal patterns of crop (InitialCrops program)
· Yearly crop proportions constraint
· Simulation with yearly crop proportions
· Batch mode
· Enhanced iteration parameters
· Further reports on the simulation (penalty indexes)
· Enhancement of user-interfaces
· Bugs fixing

What's new in Version 1.5?
· Spatial patterns of crop rotations (FieldsRotation program)
· Temporal constraints on crops: return period and maximum consecutive repetition of crops and forbidden crop sequences
· Simulation with temporal constraints imposed on the landscape
· Further reports available
· Enhancement of user-interfaces
· Bugs fixing

What's new in Version 1.4?
· Spatial constraint (separation distances between crops)
· Iteration options to optimise the crop allocation, while respecting the conditions imposed on the landscape.
· Simulation with spatial constraint imposed on the landscape
· Program allocation of crop rotations to fields, respecting desired crop proportions.
· Extended outputs: e.g.: export to SIGMEA platform, and to GIS software.
· Extended error checking of user inputs
· LandSFACTS was checked with a landscape with 2000 polygons.
· Bugs fixing

What's new in Version 1.3?
· Import options for "Initial rotations - Fields" and "Temporal patterns - Initial crops".
· Report options: "Rotations" (Rotation ID and rotation name) and "Crops in rotation" (Rotation ID, TMCID e.g. place within rotation, Crops)
· Extended error checking of user inputs
· Bugs fixing


Website
Up-to-date information and downloads are available on the LandSFACTS website, hosted by the Macaulay Land Use Research Institute.

www.macaulay.ac.uk/LandSFACTS/


Database tables
The database can be viewed through SQLite 3 (e.g. sqliteman at http://sqliteman.com/page/4.html).
DISCLAIMER: The database structure and the data themselves should not be altered directly, i.e. the LandSFACTS interfaces should be the only means used to alter the database.
For a schematic representation of the table, cf. Database Diagram

nota bene:The length restrictions noted in the tables below (e.g. integer 6), are only used for the results dbf.


Database diagram


Why LandSFACTS?

History of version 1.4-2.0 name: LandSFACTS

Landscape Scale Functional Allocation of Crops Temporally and Spatially.
New very factual name of version 1.4. Less poetic than for version 1.3 (cf. below), however it shouldn't interfere too much with the efficiency of this new one.

History of version 1.3 name: CeReS

Ceres is the Roman goddess of agriculture. As a goddess, she could probably arrange crops in fields in just about any pattern she wishes.

CeReS, is an acronym made up from French words with similar, relevant English meanings: Culture, Rotation et Simulation.

The name CeReS therefore, acknowledges the contribution of our French colleagues to the software and the statistical analyses which underpin it.

The original inspiration for the name comes from the fact that Ceres was declared a new planet in the solar system shortly after the first functioning version of the software was created.

Unfortunately CeReS had already far too many obligations with wheat and maize models, she declined our offer to be the figurehead of version 1.4. We still would like to thanks her warmly for her time with us during the life of version 1.3.


Software development
LandSFACTS is written in Python version 2.5, and uses SQLite version 3.3.6 for database. The user interfaces are build up using PyQt version 4.4.

The LandSFACTS algorithms are written in C++ using Visual Studio c++ 2008, version Express (Bloodshed Dev-C++, version 4.9.9.1 was used during initial development). The boost 1.38 library is used to generate random numbers.

This help file was created using HelpMaker, version 7.3.51.0.


Acknowledgements
Current development (version 2.0):
Since 2008, the software is being developed within Programme3 ( http://www.programme3.net/rural/rural38biodiversityMultifunction.php ), at the Macaulay Land Use Research Institute (Marie Castellazzi, Iain Brown).
Its development is also supported by Biodivagrim ANR ( http://w3.rennes.inra.fr/sad/pages_sad_armorique/theme_paysage_plus.htm ) at INRA Rennes (Alexandre Joannon). Julien Keruzec, student funded by Biodivagrim, redeveloped the software interface.

Until version 1.6:
The software was initiated within the SIGMEA EU project ( http://www.inra.fr/sigmea ), and was developed from 2004-2007 at Rothamsted Research ( http://www.rothamsted.ac.uk/pie/LandSFACTS/ ) by Marie Castellazzi, Joe Perry, Kelvin Conrad, and Joanne Matthews.
We thank the Dijon-Céréales Cooperative, Dijon, France and their member farmers from the Burgundy study site for agreeing to participate in the survey and their patience in answering our numerous questions.
Rothamsted Research receives grant-in-aid support from the Biotechnology and Biological Sciences Research Council of the United Kingdom.


Licenses
Various components of this software are released under different licenses.

Please read and respect each license and treat each component of this software accordingly.

License for this Help Documentation:

The Help Documentation is licensed under the Creative Commons Attribution-ShareAlike 2.0 License. To view a copy of this licence, visit http://creativecommons.org/licenses/by-sa/2.0/uk/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

Creative Commons
This page is available in the following languages:
????????? Català Dansk Deutsch English English (CA) English (GB) Castellano Castellano (AR) Español (CL) Castellano (MX) Euskara Suomeksi français français (CA) Galego ????? hrvatski Magyar Italiano ??? ??? Melayu Nederlands polski Português svenska slovenski jezik ???? ?? (??)

Attribution-ShareAlike 2.0 UK: England & Wales

You are free:

to copy, distribute, display, and perform the work
to make derivative works
to make commercial use of the work
Under the following conditions:
Attribution. You must give the original author credit.
Share Alike. If you alter, transform, or build upon this work, you may distribute the resulting work only under a licence identical to this one.

For any reuse or distribution, you must make clear to others the licence terms of this work.

Any of these conditions can be waived if you get permission from the copyright holder.

Your fair use and other rights are in no way affected by the above.

This is a human-readable summary of the Legal Code (the full licence) .
Disclaimer
Learn how to distribute your work using this licence

License for the accompanying Sample Data Files:
The Sample Data Files are licenced under the Creative Commons Attribution-NonCommercial-NoDerivs 2.0 License. To view a copy of this licence, visit http://creativecommons.org/licenses/by-nc-nd/2.0/uk/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

Creative Commons
This page is available in the following languages:
????????? Català Dansk Deutsch English English (CA) English (GB) Castellano Castellano (AR) Español (CL) Castellano (MX) Euskara Suomeksi français français (CA) Galego ????? hrvatski Magyar Italiano ??? ??? Melayu Nederlands polski Português svenska slovenski jezik ???? ?? (??)

Attribution-NonCommercial-NoDerivs 2.0
UK: England & Wales

You are free:

to copy, distribute, display, and perform the work
Under the following conditions:
Attribution. You must give the original author credit.
Non-Commercial. You may not use this work for commercial purposes.
No Derivative Works. You may not alter, transform, or build upon this work.

For any reuse or distribution, you must make clear to others the licence terms of this work.
Any of these conditions can be waived if you get permission from the copyright holder.

Your fair use and other rights are in no way affected by the above.

This is a human-readable summary of the Legal Code (the full licence) .
Disclaimer
Learn how to distribute your work using this licence

License for the LandSFACTS software itself:
LandSFACTS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version..

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

GNU GENERAL PUBLIC LICENSE
Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS


Contacts
If you find any bugs, have any comments or questions, please contact:

Marie Castellazzi: m.castellazzi@macaulay.ac.uk