NEWS.md

In multiscape: Multi-Action, Multi-Objective Spatial Planning

multiscape 1.4.2

• Speed up selection_frequency() without changing recurrence counts, and use pre-rendered maps in the large forest-restoration vignette to reduce package build and check times.

multiscape 1.4.1

• Added load_meseta() and load_ecosystem_services() alongside load_sim_multiaction() as the three complete example-data entry points. Updated the README and integrated-planning vignette; historical data() and raster-only access remain unchanged for compatibility.
• Clarified historical dataset identities and separated their reference index from the complete example loaders. Removed an obsolete internal example that referenced unavailable datasets.
• Improved documentation and examples for management actions, ecological effects, economic returns, action constraints, and atomic objectives.
• Added reproducible spatial examples illustrating single-objective optimisation and multi-objective methods (weighted sum, ε-constraint, and AUGMECON).
• Expanded methodological references and clarified the interpretation of objectives and action relationships.
• Consolidated the action sets, cardinality, and logical relations tutorials into a new vignette, Planning with concurrent management actions.
• Improved the organisation and consistency of the package reference documentation.

multiscape 1.4.0

• Added add_objective_max_effect() and add_objective_min_effect() for signed changes relative to the reference, including action interactions. Their arguments are x, actions, features, and alias.
• add_objective_max_benefit() is deprecated with lifecycle and delegates to add_objective_max_effect(), retaining the development branch's signed-net behavior. The published positive-only behavior changed earlier in this branch.

• add_objective_min_loss() is deprecated but retains its original final negative-part criterion. min_effect() is not an equivalent replacement: it minimizes signed change and permits compensation. No removal date is set.

• Added an educational Meseta Ibérica action-planning tutorial, bundled inputs, and a runnable script covering spatial-cost trade-offs and spatial analyses.

• Improved prototype/data-cloning memory use and indexed planning-unit analyses.
• Bounded polygon/raster extraction buffers to avoid eager full-raster allocation failures when building large landscape examples.

Other changes

• Fixed single-objective min_cost action scopes so they agree with the MO cost criterion; planning-unit costs remain global and feasible actions retain their original indices.
• Fixed CBC crashes/short solution vectors caused by trailing empty matrix rows or columns, including fully locked legacy impact models. A redundant bound row preserves dimensions without changing the feasible decisions.
• MO solves use bounded positive scalar-objective rescaling, with values returned in their original units. CBC and Gurobi receive precise numerical defaults; explicit solver parameters take precedence. Epsilon bounds are checked against reevaluated selected decisions and checks/effective settings are recorded in solution diagnostics. Binary integrality noise no longer enters objective evaluation or automatic epsilon endpoints.
• After an optimal AUGMECON solve, refine normalized slacks at the attained primary level within the remaining time limit. The original augmented criterion and global status/gap are preserved and refinement is recorded.

• Native model allocation reserves memory according to the actual core size rather than one million rows/columns for every temporary MO model.

• Deprecated add_objective_min_intervention_impact() with lifecycle. It keeps its original behavior and arguments until removal in a future release. New workflows express action consequences through effects and net benefit. The forest-restoration example now uses deficit effects with a common ceiling per feature and fixed restoration effort, documenting the equivalence and its limits. Cached plans are migrated by exact affine evaluation of their decisions.

• Changed behavior: add_objective_max_benefit() now maximizes signed net change relative to the reference, including negative individual effects and interaction corrections. Earlier versions counted positive effects only; models with negative effects may select different plans. Names and public arguments are unchanged; no separate net-benefit function is introduced.

• add_objective_min_loss() retains its loss-only criterion, with the negative part computed after combining actions within each planning unit and feature. Exact loss auxiliaries support mixed signs, overlapping scopes, zero weights, secondary bounds, and payoff/lexicographic solves in all three MO methods.

• Concurrent individual effects are additive unless joint totals are supplied. Ecological targets and result summaries count the reference once per selected unit in their action scope, using signed joint changes for final outcomes. selected_benefit remains the positive-gain metric; selected_net matches the signed benefit objective when their scopes coincide.

• Modern add_effects() tables and rasters accept registered action sets as total joint outcomes, effects, or relative changes. Original totals and input tables are preserved separately from sparse signed subset corrections. Missing interactions/individual effects are explicitly assumed zero. Exact continuous AND auxiliaries are shared across features, created only for feasible non-zero corrections, and integrated into single-objective and all three MO formulations. Inferred negative outcomes are excluded. Joint solution summaries aggregate signed changes per PU/feature and count the selected reference once. Signed ecological objectives and concurrent targets use the final aggregation described above.

• Added add_constraint_action_requires() (all/any companions), add_constraint_action_excludes() (at most one group member), and add_constraint_action_together() (all or none), scoped separately by PU. Distinct rules accumulate; duplicate identities and names are errors. Unavailable actions are treated as zero, including missing pairs, exclusions, and filtered non-finite costs. Relations use the same compiled feasible set for single-objective, weighted-sum, epsilon-constraint, and AUGMECON methods. They do not lift the default action-count limit or introduce joint effects.
• Defined a strict repeated-call contract without adding public arguments. Actions, effects (including legacy wrappers), profit, solver settings, MO methods, and unaliased objectives can be defined only once per problem. Second definitions raise an error instead of replacing data or settings. Distinct sets, constraints, spatial names, and objective aliases accumulate. Locks accumulate compatible states and reject inversions in either call order. Targets reject duplicate feature/action scopes immediately, including across absolute and relative calls. Budget identity includes cost components and area identity includes its measure. Compare configurations by deriving each alternative from a common problem before its first definition.
• Added add_constraint_action_cardinality() for per-unit minimum, maximum, or exact action counts. Repeated calls support distinct spatial and action scopes; explicit total maxima/equalities replace the implicit one-action limit only in their covered units. Rules are compiled for single-objective and multi-objective methods, including concurrent economic and ecological workflows with final feature aggregation.
• Added add_action_sets() for named lists or long membership tables and get_action_sets() for inspecting definitions. Actions can belong to several sets. Definitions are independent of action feasibility, selection rules, costs, and effects; registering them does not enable simultaneous actions.
• Action-set registration validates members and identifier conflicts, adds new sets across calls, and preserves the original problem. Action catalogs are fixed after their first definition, protecting dependent sets and indices.

multiscape 1.3.0

• add_effects() now accepts exactly one of effect, outcome, or relative_change. Tables without pu expand over feasible action pairs.
• Feature distributions describe a user-defined reference scenario. Effect tables expose reference_amount, action_outcome, and signed effect, while retaining amount_after, benefit, and loss for compatibility.
• Added raster_aggregation and raster_type for spatial effect inputs.
• Legacy effects arguments and columns retain their existing behavior and emit a lifecycle deprecation warning announcing removal in a future release.
• Migrated reference examples, the README, and the Rwanda reserve-design workflow to semantic effect inputs. Added runnable table and raster examples to add_effects() and removed legacy syntax from implicit reserve-model setup.
• Problem summaries distinguish effect input format from counts of positive, negative, and zero effects, replacing the ambiguous "effect mode" label.

multiscape 1.2.1

Spatial relations

• add_spatial_relations() now supports allow_self = TRUE together with directed = TRUE. Diagonal entries (i, i) in directed relations are interpreted as unary planning-unit terms rather than as directed self-dependencies.
• Fragmentation objectives for planning units and actions now handle diagonal terms consistently for both directed and undirected spatial relations.

multiscape 1.2.0

Objective and decision-space analysis

• Added frontier_neighbors(), linkage_distances(), linkage_transition(), linkage_turnover(), and linkage_contrasts() for objective--decision linkage analysis.
• Added get_solution_states() and selection_consistency() for summarizing spatial decisions across solutions.
• Standardized public solution identifiers as positive integers.

Solver configuration

• Added solver-specific validation of unsupported parameters, which are now reported and ignored before solving.
• Disabled automatic solver logs and explicit thread limits by default.
• Fixed CPLEX thread handling, Gurobi log-file naming, CBC solution limits, and preservation of gap_limit precision.

Spatial fragmentation

• Preserved directed spatial relations during model construction.
• Fragmentation objectives now distinguish directed arcs from undirected edges and reject duplicated relations.

Documentation

• Reorganized the package reference and workflow around Problem and SolutionSet, with dedicated objective-space (frontier_()), decision-space (selection_()), and linkage (linkage_*()) function families.
• Updated examples and documentation to use the common simulated multi-action problem across the new analysis functions.

multiscape 1.1.3

Documentation and examples

• Replaced the extended README case study with a concise, spatially structured example of multi-objective, multi-action planning.
• Added load_sim_multiaction() and its associated simulated planning units, features, action costs, and action-specific effects for examples, tests, and introductory documentation.
• Added a detailed vignette on multi-objective forest-restoration planning in a highly productive landscape with an existing conservation network.
• Formulated restoration cost and four ecosystem-service opportunity-cost objectives specifically for the restoration action, while retaining fixed conservation commitments as spatial context.
• Demonstrated an a posteriori AUGMECON workflow with 81 threshold configurations, non-dominance filtering, removal of repeated decision vectors, objective extremes, closest-to-ideal compromise selection, and decision-space comparisons.
• Added a compressed, precomputed SolutionSet to support reproducible vignette and pkgdown builds without requiring Gurobi or rerunning the full optimization.
• Added visual summaries for additional cost versus ecosystem-service opportunity cost, normalized objective performance, joint ecosystem-service regret, representative spatial allocations, and Jaccard similarity among efficient plans.
• Linked objective-space and map diagnostics through consistent solution identifiers and colours for the least-cost plan, the five-objective compromise, and service-specific extremes.

multiscape 1.1.2

• Relaxed model validation so feature targets are no longer mandatory when another substantive constraint or locked-in decision defines a non-empty planning problem.
• Added an informative warning for minimum-cost problems that have no feature targets, positive area requirement, or locked-in decisions, instead of stopping model construction unconditionally.

Result tables and maintenance

• Standardized user-facing result tables so solution_id is shown as the first column.
• Removed run_id from user-facing solution extractors and frontier outputs; it is now kept for get_runs() and internal matching only.
• Removed internal columns such as internal_id from planning-unit outputs.
• Fixed get_targets() so it consistently returns solution_id instead of run_id.
• Updated frontier_extremes() and frontier_distances() to follow the same solution_id-based output convention.
• Added an example for get_runs().
• Fixed Rd warnings from missing cross-references and undocumented deprecated arguments.

multiscape 1.1.1

User-facing API

• Renamed planning-unit functions and arguments to use planning_units consistently instead of pu.

• Deprecated older function aliases kept for backwards compatibility:

• get_pu() in favour of get_planning_units();

• plot_spatial_pu() in favour of plot_spatial_planning_units();
• add_constraint_locked_pu() in favour of the planning-unit naming convention;
• add_objective_min_fragmentation_pu() in favour of add_objective_min_fragmentation_planning_units().

• Deprecated older multi-objective run helpers:

• run_grid() in favour of set_runs_grid();

• run_manual() in favour of set_runs_manual();
• mo_control() in favour of set_runs_control().

Solution and result extractors

• Simplified public result tables to use solution_id as the main identifier for stored solutions.
• Kept run_id primarily for get_runs() and internal diagnostics, reducing ambiguity in user-facing summary outputs.
• Updated get_objectives() to return cleaner user-facing tables while preserving run-level identifiers internally for frontier and dominance calculations.
• Updated getters, plotting functions, and error messages to use solution/solutions terminology consistently.

Multi-objective methods

• Updated weighted-sum defaults so that automatic grids are normalized by default, while manual weight designs use the supplied weights exactly.
• Allowed manual weighted-sum weights to be non-negative and have any positive row total when normalize_weights = FALSE.
• Improved validation of manual weighted-sum designs and multi-objective control objects.
• Removed outdated internal feasible_only handling from objective extraction workflows.

Maintenance

• Updated tests to reflect the new solution_id-based public API.
• Improved internal separation between user-facing extractors and run-level helper functions.
• Fixed inconsistencies in deprecated run terminology across getters, plotting, and frontier utilities.

multiscape 1.1.0

Solution architecture

• Simplified the public result architecture so that solve() consistently returns a SolutionSet, including for single-objective problems.
• Removed the internal Solution class from the public API and documentation. Individual run-level solutions remain available only as internal components of a SolutionSet.
• Added stable solution_id identifiers to distinguish stored solutions from attempted runs identified by run_id.
• Updated run, solution, and summary tables to preserve run_id and solution_id consistently across extraction and analysis functions.
• Improved internal finalization of solution metadata and identifiers after solving.
• Updated SolutionSet printing and documentation to reflect the distinction between run attempts and stored solutions.

Base conservation-planning workflow

• Added automatic support for base conservation-planning problems when no explicit actions or effects are supplied.
• Problems without explicit actions are now interpreted as binary conservation decisions, where each planning unit can be conserved or not conserved.
• Added an implicit conservation action and internally generated feature contributions based on the feature amounts stored in dist_features.
• The implicit conservation model uses amount_after to represent the feature amount obtained when a planning unit is conserved.

Multi-objective run design and controls

• Revised the multi-objective run-design resolver used by weighted-sum, epsilon-constraint, and AUGMECON methods.
• Improved support for automatic and manually specified run designs through run_grid() and run_manual().
• Added and documented common multi-objective execution controls through mo_control().
• Improved handling of infeasible runs, missing solutions, solver errors, and slack upper bounds.
• Standardized the storage of run-design parameters and objective values in the SolutionSet run table.
• Preserved infeasible runs in the run history while assigning solution_id only to runs that produced a stored solution.
• Improved objective evaluation and model preparation across multi-objective methods.
• Fixed weighted-sum objective preparation for implicit conservation benefit objectives.
• Improved validation of objective coefficient vectors and objective-specific error messages.

Result extraction

• Added get_runs() to extract run-level status, runtime, gap, design parameters, solution identifiers, and objective values.
• Added get_objectives() to extract objective values in long or wide format.
• Added get_objective_specs() to extract registered objective aliases, objective types, model types, optimization senses, and creation metadata.
• Updated objective extraction to include both run_id and solution_id.
• Updated existing extraction functions to work consistently with the unified SolutionSet architecture.
• Improved handling of infeasible runs and missing objective values during extraction.

Solution-set management

• Added solution_filter() to return a coherently filtered SolutionSet.
• solution_filter() can filter by run_id, solution_id, solver status, or feasibility.
• Added optional filtering of non-dominated solutions using moocore.
• Added support for selecting the objectives used to evaluate dominance.
• Ensured that filtering updates run tables, design tables, stored solutions, and summary tables consistently.
• Added cloning of SolutionSet objects before modification to prevent reference-based mutation of the original object.
• Added solution_append() to combine compatible SolutionSet objects generated from the same planning problem.
• solution_append() verifies compatibility of planning units, features, actions, effects, targets, constraints, locks, spatial relations, and objective definitions.
• Appended runs and solutions are automatically assigned unique run_id and solution_id values.
• Added support for combining solution sets obtained from different multi-objective methods or run designs applied to the same planning problem.
• Added solution_unique() to retain one representative from groups of equivalent solutions.
• solution_unique() can identify repeated solutions using either complete decision vectors or objective values.
• Added numerical tolerance controls for identifying equivalent points in objective space.
• Preserved runs without stored solutions when removing duplicated solutions.

Frontier analysis

• Added frontier_extremes() to identify the observed minimum and maximum values of each objective.
• Added classification of observed bounds as best or worst according to each objective's optimization sense.
• Added support for returning all tied extreme solutions or only the first representative.
• Added frontier_distances() to calculate normalized distances to observed ideal and nadir points.
• Added automatic transformation of maximization objectives into a common minimization space for frontier calculations.
• Added range normalization so that objectives measured in different units contribute comparably to distance calculations.
• Added Euclidean, Manhattan, and Chebyshev distance metrics.
• Added rankings based on proximity to the observed ideal point and distance from the observed nadir point.
• Added original-scale ideal, nadir, and objective-range metadata to the returned distance tables.
• Clarified that frontier reference points are calculated from the solutions contained in the supplied SolutionSet.

Selection analysis

• Added selection_frequency() to calculate how frequently each planning-unit/action assignment is selected across stored solutions.
• Standardized selection analysis around a canonical planning-unit/action representation.
• Simple conservation-planning problems are represented using the implicit conservation action.
• Added selection_similarity() to quantify structural similarity among solutions.
• Added Jaccard similarity for comparing selected planning-unit/action assignments.
• Added Hamming similarity for comparing complete binary assignment vectors, including shared non-selections.
• Added long-format and matrix-format similarity outputs.
• Added internal helpers to construct consistent long-format and matrix-format selection representations.

Documentation and website

• Reorganized the pkgdown reference index into dedicated sections for:
• result extraction;
• solution-set management;
• frontier analysis;
• selection analysis;
• multi-objective workflow configuration.
• Removed public documentation references to the internal Solution class.
• Updated function documentation to use the unified SolutionSet terminology.
• Updated examples and cross-references for run_id, solution_id, objective extraction, filtering, frontier analysis, and selection analysis.
• Added moocore as an optional dependency for non-dominance filtering.
• Updated GitHub Actions configurations for current Codecov and Node.js runner requirements.
• Updated Codecov uploads to use the PyPI CLI and avoid binary signature-verification failures.
• Updated GitHub Actions versions for Node.js 24 compatibility.

multiscape 1.0.7

• Updated native routine registration to resolve additional CRAN LTO/gcc-ASAN checks.
• Revised examples and package metadata for CRAN compliance.

multiscape 1.0.6

• Fix CRAN submission issues
• Revise examples and DESCRIPTION for CRAN resubmission

multiscape 1.0.5

• Release candidate for CRAN.

multiscape 1.0.4

• First CRAN release of multiscape.
• Provides a modular workflow for exact multi-objective spatial planning based on mixed-integer programming (MIP).
• Introduces the core Problem, Solution, and SolutionSet classes. The public result architecture was later unified around SolutionSet in version 1.1.0.
• Adds support for modular problem construction through create_problem(), add_*(), set_*(), and solve().
• Supports atomic objective registration and multi-objective solution methods, including weighted-sum, epsilon-constraint, and AUGMECON.
• Includes support for spatial relations such as boundary, rook, queen, k-nearest neighbours, and distance-based relations.
• Supports commercial and open-source solvers, including Gurobi, CPLEX, CBC, and SYMPHONY.
• Adds user-facing extraction and visualization tools for planning units, actions, features, targets, spatial outputs, and trade-offs.
• Includes substantial updates to documentation, package structure, and contribution guidelines.

multiscape documentation built on Oct. 12, 2026, 5:08 p.m.