problem-class: Problem class
In multiscape: Multi-Action, Multi-Objective Spatial Planning
problem-class R Documentation
Problem class
Description
The Problem class is the central container used by multiscape to
represent a planning problem before, during, and after model construction.
A Problem object stores the full problem specification in a modular
way. This includes the baseline planning data, optional spatial metadata,
action definitions, effects, profit, targets, constraints, objective
registrations, solver settings, and, when available, a built optimization
model or model snapshot.
In other words, Problem is the persistent object that connects the full
multiscape workflow:
create_problem()
-> add_*() / set_*()
-> solve()
Details
Repeated calls
Action catalogues, effects, profit, solver configuration, multi-objective
methods, and unaliased single objectives can each be defined once. A second
definition raises an error. Action sets, named spatial relations, aliased
objectives, and distinct constraints accumulate; duplicate definitions are
rejected. Locks accumulate compatible states, allow identical repeats, and
reject contradictory states. To compare scenarios or configurations, derive
each alternative from a common problem before the relevant definition.
Conceptual role
The Problem class is designed for a data-first and modular workflow.
User-facing functions do not usually modify a solver object directly. Instead,
they enrich the Problem object by storing new specifications in its
internal data field.
Thus, a Problem object should be understood as a structured container
for the mathematical planning problem, not necessarily as a built
optimization model.
Before solve is called, the object may contain only input data
and user specifications. During or after solving, it may additionally contain
a built model pointer, model metadata, and solver-related information.
Core mathematical interpretation
At a high level, the Problem object stores the ingredients required to
define an optimization problem over:
planning units i \in \mathcal{P},
features f \in \mathcal{F},
actions a \in \mathcal{A},
optional spatial relations over planning units,
and user-defined objectives and constraints.
The baseline ecological state is typically stored through a planning
unit–feature table of amounts:
a_{if} \ge 0,
where a_{if} is the baseline amount of feature f in planning unit
i.
Subsequent functions then add action feasibility, effects, profit, targets,
spatial relations, and optimization settings to this baseline representation.
How objects are created
Problem objects are usually created by create_problem.
After creation, downstream functions such as add_actions,
add_effects, add_profit,
add_constraint_targets_absolute, add_constraint_targets_relative,
spatial relation constructors, objective setters, and solver setters extend
the internal data list.
Internal storage
The class contains a single field:
dataA named list storing the full problem
specification, metadata, and, when available, built-model information.
Common entries of data include:
puPlanning-unit table.
featuresFeature table.
actionsAction catalog.
action_setsNamed combinations of actions, stored as a long
table of set–action memberships. These definitions do not impose joint
selection or change the optimization model.
dist_featuresPlanning unit–feature baseline amounts.
dist_actionsFeasible planning unit–action pairs.
dist_effectsAction effects by planning unit, action, and
feature.
dist_profitProfit by planning unit–action pair.
pu_sfPlanning-unit geometry when available.
pu_coordsPlanning-unit coordinates when available.
spatial_relationsRegistered spatial relations.
targetsStored target specifications.
constraintsStored user-defined constraints, including
per-unit action counts in constraints$action_cardinality and logical
relations in constraints$action_relations.
effects_original, joint_effects, effect_terms-
Canonical supplied totals, supplied joint totals, and their signed subset
corrections, when registered sets occur in modern effect input. Missing
interactions are assumed zero as recorded in effects_meta.
objectivesRegistered atomic objectives for single- or
multi-objective workflows.
methodStored multi-objective method configuration, when
applicable.
solve_argsStored solver settings.
model_ptrPointer to a built optimization model, when
available.
model_argsMetadata describing model construction.
model_listOptional exported model snapshot or representation.
metaAuxiliary metadata, including model-dirty flags and other
bookkeeping fields.
Not every Problem object contains all of these entries. The content of
data depends on how far the workflow has progressed.
Lifecycle
A Problem object typically moves through the following stages:
input stage: baseline planning units, features, and feature
distributions are stored,
specification stage: actions, effects, targets, objectives,
constraints, and spatial relations are added,
model stage: an optimization model is built from the stored
specification,
solve stage: the model is solved and results are returned in a
separate Solution or SolutionSet object.
The Problem object itself is not the solution. It is the structured
problem definition from which a solution can be obtained.
Value
No return value. This page documents the Problem class.
Methods
print()Print a structured summary of the stored problem
specification, including data, actions and effects, spatial inputs, targets
and constraints, and model status. If a model has already been built,
additional dimensions and auxiliary-variable information are displayed.
show()Alias of print().
repr()Return a short one-line representation of the object.
getData(name)Return a named entry from self$data.
getPlanningUnitsAmount()Return the number of planning units
stored in x$data$pu.
getMonitoringCosts()Return the planning-unit cost vector,
typically taken from x$data$pu$cost.
getFeatureAmount()Return the number of stored features.
getFeatureNames()Return feature names from
x$data$features$name, or feature ids if names are unavailable.
getActionCosts()Return action-level costs from
x$data$dist_actions$cost when available.
getActionsAmount()Return the number of stored actions.
Printing and diagnostics
The print() method is intended as a quick diagnostic summary. It helps
users understand:
what data have already been loaded,
whether actions, effects, spatial relations, targets, and constraints
have been registered,
whether objectives and methods have been configured,
whether a model has already been built,
and whether the object appears ready to be solved.
In particular, the model section of the printed output summarizes whether the
current problem specification is incomplete, ready, or already materialized as
a built optimization model.
See Also
create_problem,
add_actions,
add_action_sets,
add_constraint_action_cardinality,
add_effects,
add_constraint_targets_absolute,
solve
multiscape documentation built on Oct. 12, 2026, 5:08 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| problem-class | R Documentation |
Problem class
Description
The Problem class is the central container used by multiscape to
represent a planning problem before, during, and after model construction.
A Problem object stores the full problem specification in a modular
way. This includes the baseline planning data, optional spatial metadata,
action definitions, effects, profit, targets, constraints, objective
registrations, solver settings, and, when available, a built optimization
model or model snapshot.
In other words, Problem is the persistent object that connects the full
multiscape workflow:
create_problem() -> add_*() / set_*() -> solve()
Details
Repeated calls
Action catalogues, effects, profit, solver configuration, multi-objective methods, and unaliased single objectives can each be defined once. A second definition raises an error. Action sets, named spatial relations, aliased objectives, and distinct constraints accumulate; duplicate definitions are rejected. Locks accumulate compatible states, allow identical repeats, and reject contradictory states. To compare scenarios or configurations, derive each alternative from a common problem before the relevant definition.
Conceptual role
The Problem class is designed for a data-first and modular workflow.
User-facing functions do not usually modify a solver object directly. Instead,
they enrich the Problem object by storing new specifications in its
internal data field.
Thus, a Problem object should be understood as a structured container
for the mathematical planning problem, not necessarily as a built
optimization model.
Before solve is called, the object may contain only input data
and user specifications. During or after solving, it may additionally contain
a built model pointer, model metadata, and solver-related information.
Core mathematical interpretation
At a high level, the Problem object stores the ingredients required to
define an optimization problem over:
planning units
i \in \mathcal{P},features
f \in \mathcal{F},actions
a \in \mathcal{A},optional spatial relations over planning units,
and user-defined objectives and constraints.
The baseline ecological state is typically stored through a planning unit–feature table of amounts:
a_{if} \ge 0,
where a_{if} is the baseline amount of feature f in planning unit
i.
Subsequent functions then add action feasibility, effects, profit, targets, spatial relations, and optimization settings to this baseline representation.
How objects are created
Problem objects are usually created by create_problem.
After creation, downstream functions such as add_actions,
add_effects, add_profit,
add_constraint_targets_absolute, add_constraint_targets_relative,
spatial relation constructors, objective setters, and solver setters extend
the internal data list.
Internal storage
The class contains a single field:
dataA named
liststoring the full problem specification, metadata, and, when available, built-model information.
Common entries of data include:
puPlanning-unit table.
featuresFeature table.
actionsAction catalog.
action_setsNamed combinations of actions, stored as a long table of set–action memberships. These definitions do not impose joint selection or change the optimization model.
dist_featuresPlanning unit–feature baseline amounts.
dist_actionsFeasible planning unit–action pairs.
dist_effectsAction effects by planning unit, action, and feature.
dist_profitProfit by planning unit–action pair.
pu_sfPlanning-unit geometry when available.
pu_coordsPlanning-unit coordinates when available.
spatial_relationsRegistered spatial relations.
targetsStored target specifications.
constraintsStored user-defined constraints, including per-unit action counts in
constraints$action_cardinalityand logical relations inconstraints$action_relations.effects_original,joint_effects,effect_terms-
Canonical supplied totals, supplied joint totals, and their signed subset corrections, when registered sets occur in modern effect input. Missing interactions are assumed zero as recorded in
effects_meta. objectivesRegistered atomic objectives for single- or multi-objective workflows.
methodStored multi-objective method configuration, when applicable.
solve_argsStored solver settings.
model_ptrPointer to a built optimization model, when available.
model_argsMetadata describing model construction.
model_listOptional exported model snapshot or representation.
metaAuxiliary metadata, including model-dirty flags and other bookkeeping fields.
Not every Problem object contains all of these entries. The content of
data depends on how far the workflow has progressed.
Lifecycle
A Problem object typically moves through the following stages:
input stage: baseline planning units, features, and feature distributions are stored,
specification stage: actions, effects, targets, objectives, constraints, and spatial relations are added,
model stage: an optimization model is built from the stored specification,
solve stage: the model is solved and results are returned in a separate
SolutionorSolutionSetobject.
The Problem object itself is not the solution. It is the structured
problem definition from which a solution can be obtained.
Value
No return value. This page documents the Problem class.
Methods
print()Print a structured summary of the stored problem specification, including data, actions and effects, spatial inputs, targets and constraints, and model status. If a model has already been built, additional dimensions and auxiliary-variable information are displayed.
show()Alias of
print().repr()Return a short one-line representation of the object.
getData(name)Return a named entry from
self$data.getPlanningUnitsAmount()Return the number of planning units stored in
x$data$pu.getMonitoringCosts()Return the planning-unit cost vector, typically taken from
x$data$pu$cost.getFeatureAmount()Return the number of stored features.
getFeatureNames()Return feature names from
x$data$features$name, or feature ids if names are unavailable.getActionCosts()Return action-level costs from
x$data$dist_actions$costwhen available.getActionsAmount()Return the number of stored actions.
Printing and diagnostics
The print() method is intended as a quick diagnostic summary. It helps
users understand:
what data have already been loaded,
whether actions, effects, spatial relations, targets, and constraints have been registered,
whether objectives and methods have been configured,
whether a model has already been built,
and whether the object appears ready to be solved.
In particular, the model section of the printed output summarizes whether the current problem specification is incomplete, ready, or already materialized as a built optimization model.
See Also
create_problem,
add_actions,
add_action_sets,
add_constraint_action_cardinality,
add_effects,
add_constraint_targets_absolute,
solve
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.