Why do I get the “Java heap space” error, and how to fix it ?
Why flsgen_structure did not find a structure satisfying my targets ?
Why flsgen_generate failed to generate a landscape ?
Can I specify the spatial extent and resolution of produced landscapes ?
How can I change the spatial configuration of produced landscapes ?
Can I specify the minimum distance between patches of the same class ?
How does the computing time of rflsgen varies according to input and parameters ?
How does flsgen_structure selects the structures to return if there are several possibilities ?
What is Constraint Programming ?
By default, rJava allocate 512MB to the Java virtual machine (JVM). When generating large landscapes, this can be insufficient. The solution is, before loading rflsgen (and any other package using rJava), to increase the memory allocated to the JVM using options(java.parameters = "-Xmx4g"). Note that this allocates 4GB to the JVM. If you want to allocate another amount of memory just replace 4g with the desired value.
There are two possibilities:
If rflsgen indicates that “User targets cannot be satisfied”, it means that the solver has finished exploring the search tree and that there is no solution satisfying your targets. As the underlying Constraint Programming solver (Choco) relies on exact algorithms, this message is the guarantee that your targets cannot be satisfied. To date, this is not possible to explain why the targets are contradictory in a human-readable way. So what you can do is try to see if there are obvious contradictions in your targets (e.g. two classes that both need to occupy 60% of the landscape), or try with other targets.
If rflsgen indicates that “User targets could not be satisfied under the specified time limit”, it means that the time limit was reached before the solver could find a solution, or prove that there is no solution. By default the time limit in flsgen_structure() is 60 seconds, you can increase this limit with the time_limit argument, or disable it with the value 0. You can also change the search_strategy, which indicate to Choco-solver how to construct its search tree. Although this search strategy does not influence whether the targets will be satisfied or not, some strategies can be more efficient depending on the problem configuration. Available search strategies in Choco are: ""DEFAULT", "RANDOM", "DOM_OVER_W_DEG", "DOM_OVER_W_DEG_REF", "ACTIVITY_BASED", "CONFLICT_HISTORY", "MIN_DOM_LB", "MIN_DOM_UB" (please refer to Choco documentation if you want more details).
Although flsgen_structure() relies on exact search algorithms to identify suitable landscape structures, the spatial generation algorithm used in flsgen_generate() is stochastic and can fail. The reason for using a stochastic algorithm is that finding a spatial embedding of a landscape structure is equivalent to the polyomino packing problem, which is known to be NP-Complete (i.e. computational complexity increases exponentially with problem size). It would not be possible to generate reasonably large landscapes (e.g. larger than 100x100) in a feasible time. Using a stochastic algorithm offers fast runtime, but at the price that it can fail without knowing if a solution exists. In practice, the success of flsgen_generate() is highly constrained by the proportion of the non-focal landscape class (NON_FOCAL_PLAND), and to a lesser extent by the min_distance parameter. In conclusion, you have two possibilities: (1) if NON_FOCAL_PLAND is less than 15%, you should probably generate a landscape structure with a high NON_FOCAL_PLAND, (2) else, you can increase the number of trials with the max_try and max_try_patch parameters or decrease the min_distance parameter.
This can be specified with the x, y, epsg, resolution_x and resolution_y parameters in the flsgen_generate() function.
There are three parameters influencing the spatial configuration of produced landscapes in flsgen_generate:
min_distance parameter, defines the minimum distance between any two patches of the same class.terrain parameter, is a continuous raster guiding the generation algorithm.terrain_dependency parameter, defines to which extent the generation algorithm is influenced by the terrain.Terrain rasters can either be generated “on-the-fly” by flsgen, which relies on the diamond-square (or midpoint displacement) algorithm or given as input. This last option makes it possible to use continuous neutral landscapes generated with other software packages such as NLMR, or even digital elevation models from real landscapes.
Yes, with the min_distance parameter of flsgen_generate(). You can also play with the min_max_distance, which makes the minimum distance between the patch variable and comprised between min_distance and min_max_distance.
As there are a lot of factors that can influence the computing time of rflsgen, there is no simple answer to this question.
Regarding flsgen_structure(), the number of classes and the landscape dimensions influences the size of the underlying constraint satisfaction problem. But a large problem can be solved very quickly if the solver can take advantage of the targets to filter the search tree. In general, fragmentation indices such as MESH, NPRO, or DIVI, are more difficult to satisfy if the targets only allow one value. However, in most cases flsgen_structure() only needs a few seconds (or less) to find a solution.
flsgen_generate() has a more predictable computing time, which is mainly driven by the landscape dimension and the total proportion of focal classes. In practice, it is fast even for large landscapes (several millions of cells), and the RAM should be a problem before the computing time.
Most often, there can be hundreds, thousands, or even millions of possible structures satisfying user targets. flsgen_structure() relies on Choco-solver to identify suitable landscape structures. The default behaviour of Choco-solver is to return the first solution found. If we ask the solver to find another solution, it will return the second found, etc. The nb_solutions parameter in flsgen_structure() tells Choco-solver how many solutions it must find before stopping the search. There is also a search_strategy parameter in flsgen_structure() which indicate to Choco-solver how to construct its search tree. Although this search strategy does not influence whether the targets will be satisfied or not, it can help diversify the generated structure by exploring the search tree in different ways. Available search strategies in Choco are: ""DEFAULT", "RANDOM", "DOM_OVER_W_DEG", "DOM_OVER_W_DEG_REF", "ACTIVITY_BASED", "CONFLICT_HISTORY", "MIN_DOM_LB", "MIN_DOM_UB" (please refer to Choco documentation if you want more details).
Choco-solver is an open-source Java Constraint Programming solver. It is a reliable solver implemented with state-of-the-art algorithms which have been used in academic and industrial projects for years.
Constraint programming (CP) is a declarative paradigm for modelling and solving constraint satisfaction and constrained optimization problems. In this context declarative means that the modelling of a problem is decoupled from its solving process, which allows the primary focus to be on what must be solved rather than describing how to solve it. CP is a subfield of artificial intelligence that relies on automated reasoning, constraint propagation and search heuristics. As an exact approach, CP can provide constraint satisfaction and optimality guarantees, as well as enumerate every solution of a problem. In CP, the modeller represents a problem by declaring variables whose possible values belong to a specified finite domain, by stating constraints (mainly logical relations between variables), and eventually by defining an objective function to minimize or maximize. A solution to the problem is an instantiation of every variable such that every constraint is satisfied. As opposed to mixed-integer linear programming, constraints can be non-linear and variables of several types (e.g. integer, real, set, graph). A CP solver then handles the solving process relying on an automated reasoning method alternating a constraint propagation algorithm (deduction process on values within domains that does not lead to any solution) and a backtracking search algorithm. In a nutshell, more than satisfiability, each constraint embeds a filtering algorithm able to detect inconsistent values in variables domains. At each step of the backtracking search algorithm, the solver calls the constraint propagation algorithm that repeatedly applies these algorithms until a fixed point is reached. When it is proven that a part of the search tree contains no solution, the solver rolls back to a previous state and explores another part of the search tree: this is backtracking. Note that most CP solvers are also able to handle Pareto multi-objective optimization.
If you are interested in learning more about Constraint Programming, you can read the Handbook of Constraint Programming: Rossi, E. F., van Beek, P., & Walsh, T. (2006). Handbook of Constraint Programming.