The Institution Framework is a modular system designed to simulate policy-making institutions that interact with environmental / ecological / economic models. The architecture follows a clear separation of concerns with distinct components:
-
Institution Framework Core
InstitutionManager: Coordinates multiple institutions and handles communication with target modelsInstitution: Represents a policy-making entity with decision-making capabilitiesPolicy: Defines specific policy instruments with parameters and constraints
-
Integration Layer
TargetModelOutput: Data structure for transferring model state to institutionsInstitutionOutput: Data structure for transferring policy decisions to modelsModelOutputProvider: Interface that target models should implement
-
Example Implementation
SimpleLandUseModel2: Example model implementing theModelOutputProviderinterfaceTestRunner2: Demonstration of how to connect the framework with a model
┌──────────────────────┐ ┌───────────────────────┐
│ Target Model │ │ Institution Framework│
│ (implements │◄────►│ │
│ ModelOutputProvider)│ │ │
└──────────────────────┘ └───────────────────────┘
▲ ▲
│ │
│ │
│ │
▼ ▼
┌─────────────────────┐ ┌───────────────────────┐
│ Data Transfer │ │ Policy Decision │
│ Objects │ │ Logic │
│ (TargetModelOutput,│ │ (Fuzzy Logic, │
│ InstitutionOutput) │ │ Optimization) │
└─────────────────────┘ └───────────────────────┘
The serves as the main entry point for the framework. It:
- Loads institution configurations from JSON
- Coordinates multiple institutions
- Handles communication between institutions and the target model
- Provides methods to initialize policies and process model outputs
The class represents a policy-making entity that:
- Evaluates gaps between current state and policy goals
- Uses fuzzy logic to determine policy changes
- Applies constraints like inertia and budget limitations
- Produces policy outputs that affect the target model
The interface defines the contract that target models must implement:
prepModelOutput(): Provides time series data of model variablesprepEstimatedQuantities(): Provides estimated quantities for policiesprepBudget(): Provides available budget for each institutiongetOutput(): Combines the above into aTargetModelOutputobject
- : Carries model state to institutions
- : Carries policy decisions to the target model
Your model must implement the interface:
public class YourModel implements ModelOutputProvider {
@Override
public HashMap<String, ArrayList<Double>> prepModelOutput() {
// Return time series data for each variable
// Example: {"crop_production": [100, 105, 110], "biodiversity": [80, 75, 70]}
}
@Override
public HashMap<String, HashMap<String, Double>> prepEstimatedQuantities() {
// Return estimated quantities for each policy by institution
// Example: {"AgriInst": {"crop_subs": 1.0, "meat_subs": 1.0}}
}
@Override
public HashMap<String, Double> prepBudget() {
// Return available budget for each institution
// Example: {"AgriInst": 10000.0, "EnvInst": 5000.0}
}
@Override
public TargetModelOutput step(InstitutionOutput institutionOutput) {
// Update model state based on policy values
// Return model output for institutions
}
}Define your institutions and policies in a JSON file. For example:
{
"institutions": [
{
"institutionName": "AgriInst",
"policies": [
{
"policyName": "crop_subs",
"block": "crop_subsidy_block",
"inputNameToGoal": {
"crop_production": 800.0
},
"unitCost": 10.0,
"weights": 1.0,
"policyLow": 0.0,
"policyUp": 100.0,
"inertiaLow": -5.0,
"inertiaUp": 5.0,
"stepSize": 1.0
}
]
}
]
}Define fuzzy logic rules for policy decisions. For example:
FUNCTION_BLOCK crop_subsidy_block
VAR_INPUT
crop_production_gap: REAL;
END_VAR
VAR_OUTPUT
intervention: REAL;
END_VAR
FUZZIFY crop_production_gap
TERM negative := (-1000, 1) (-100, 1) (0, 0);
TERM zero := (-50, 0) (0, 1) (50, 0);
TERM positive := (0, 0) (100, 1) (1000, 1);
END_FUZZIFY
DEFUZZIFY intervention
TERM decrease := (-10, 1) (-5, 1) (0, 0);
TERM maintain := (-2, 0) (0, 1) (2, 0);
TERM increase := (0, 0) (5, 1) (10, 1);
METHOD: COG;
DEFAULT := 0;
END_DEFUZZIFY
RULEBLOCK No1
RULE 1: IF crop_production_gap IS negative THEN intervention IS increase;
RULE 2: IF crop_production_gap IS zero THEN intervention IS maintain;
RULE 3: IF crop_production_gap IS positive THEN intervention IS decrease;
END_RULEBLOCK
END_FUNCTION_BLOCK
public class YourSimulation {
public static void main(String[] args) {
try {
// Initialize institution manager
InstitutionManager institutionManager = new InstitutionManager();
institutionManager.loadInstitutions(
"path/to/institutions.json", // JSON file path for institutions and policies
"path/to/fuzzy_rules.fcl", // FCL file path for fuzzy logic rules
10, // Time lag for PID calculations
true // Start policy evaluation at step 0
);
// Initialize your model
YourModel model = new YourModel();
// Get initial policy values
InstitutionOutput institutionOutput = institutionManager.getInitPolicies();
// Run simulation
for (int i = 0; i < 1000; i++) {
// Step model with current policies
TargetModelOutput modelOutput = model.step(institutionOutput);
// Get updated policies from institutions
institutionOutput = institutionManager.step(modelOutput);
}
// Process and save results
} catch (IOException e) {
e.printStackTrace();
}
}
}The SimpleLandUseModel class (in the test folder) demonstrates how to implement the ModelOutputProvider interface:
- It maintains state variables (land allocation, production, environmental indicators)
- It implements the required methods:
prepModelOutput(): Returns time series of model variablesprepEstimatedQuantities(): Returns policy quantities (set to 1.0 in this example)prepBudget(): Returns available budget for each institution
- In its
step()method, it:- Updates land allocation based on current state
- Updates indicators based on new land allocation
- Applies policy effects from the institution output
- Records the current state for later analysis
-
Clear Variable Naming: Ensure variable names in your model match those in the institution configuration.
-
Time Series Management: Maintain time series data for all relevant variables to provide historical context for policy decisions.
-
Policy Effect Implementation: Create clear mechanisms for how policies affect your model's behaviour.
-
Budget Considerations: If using budget constraints, implement realistic estimations of policy costs.
-
Testing: Start with simple configurations and gradually increase complexity to ensure correct integration.
-
Data Collection: Implement comprehensive data collection for analysis and visualization.
This document provides a comprehensive explanation of the mathematical foundations underlying the SimpleLandUseModel implementation. The model simulates land allocation, economic production, and environmental indicators with various policy interventions.
The model tracks several state variables that evolve over time:
-
Land Allocation (hectares)
- Agricultural Land:
$A_t$ - Forest Land:
$F_t$ - Urban Land:
$U_t$
- Agricultural Land:
-
Production Outputs
- Crop Production (tons):
$C_t$ - Meat Production (tons):
$M_t$ - Sustainable Agriculture Index:
$S_t$
- Crop Production (tons):
-
Environmental Indicators
- Carbon Sequestration (tons):
$CS_t$ - Biodiversity Index:
$B_t$
- Carbon Sequestration (tons):
The model is governed by the following parameters:
- Total Land:
$L_{total} = 10,000$ hectares - Crop Yield:
$Y_c = 5.0$ tons per hectare - Meat Yield:
$Y_m = 1.0$ tons per hectare - Forest Carbon Sequestration:
$\sigma_f = 10.0$ tons per hectare - Meat Carbon Emission:
$\epsilon_m = 50.0$ tons per ton of meat - Crop Carbon Emission:
$\epsilon_c = 5.0$ tons per ton of crop - Carbon per Forest Hectare:
$\kappa_f = 100.0$ tons per hectare
Four policy instruments influence the model dynamics:
- Crop Subsidy Effect:
$\alpha_c$ - Meat Subsidy Effect:
$\alpha_m$ - Biodiversity Subsidy Effect:
$\alpha_b$ - Carbon Tax Effect:
$\alpha_t$
The model updates land allocation in each time step according to:
agriConversionPressure = 0.02 * (1 + cropSubsidyEffect/100 + meatSubsidyEffect/100)
forestProtectionFactor = 0.01 * (1 + bioSubsidyEffect/100)
carbonReductionFactor = 0.01 * (1 + carbonTaxEffect/100)
Mathematically:
Where
Forest to agricultural land conversion is calculated as:
Then the land areas are updated:
The model enforces that total land remains constant:
If this constraint is violated, an adjustment factor is applied:
And all land types are scaled:
The model uses a sigmoid function to determine the balance between crop and meat production:
Crop and meat production are calculated based on allocated agricultural land:
Where:
-
$\eta_c$ and$\eta_m$ are random noise terms from$U(-0.05, 0.05)$
The sustainable agriculture index is calculated as the proportion of crop production to total agricultural production:
The net carbon sequestration accounts for forest absorption minus agricultural emissions:
The biodiversity index is primarily based on forest cover ratio, enhanced by biodiversity subsidies:
Where:
-
$\eta_b$ is a random noise term from$U(-0.025, 0.025)$
The model uses a sigmoid function to transform the difference between crop and meat subsidies into a production weight:
This function has several important properties:
- Output always between 0 and 1
- When
$x = 0$ (equal subsidies),$\sigma(0) = 0.5$ - As
$x \rightarrow \infty$ (crop subsidies dominate),$\sigma(x) \rightarrow 1$ - As
$x \rightarrow -\infty$ (meat subsidies dominate),$\sigma(x) \rightarrow 0$ - The division by 10 in the exponent controls the steepness of the transition
The model processes policy inputs from institutional frameworks, applying them to the respective effect variables:
AgriInst:crop_subs→ cropSubsidyEffectAgriInst:meat_subs→ meatSubsidyEffectEnvInst:bio_subs→ bioSubsidyEffectEnvInst:carbon_tax→ carbonTaxEffect
The model initializes with:
- Agricultural Land:
$A_0 = 1,000$ hectares - Forest Land:
$F_0 = 8,500$ hectares - Urban Land:
$U_0 = 500$ hectares - All policy effects initialized to 0
The model incorporates several important feedback mechanisms:
-
Agricultural Expansion: Higher agricultural subsidies increase conversion pressure from forests to agricultural land.
-
Forest Protection: Biodiversity subsidies and carbon taxes reduce the rate of forest conversion.
-
Production Composition: The relative balance of crop and meat subsidies shifts production toward the more subsidized output through the sigmoid function.
-
Environmental Impact: The model captures the trade-off between agricultural production and environmental indicators (biodiversity and carbon sequestration).
For each time step, the model follows this sequence:
- Update land allocation based on current policy effects
- Calculate new production and environmental indicators
- Apply new policy effects
- Record state variables and policy values
To run a Maven project in Eclipse, you need to ensure that Maven is properly integrated with Eclipse. Eclipse does not come with Maven by default (in most distributions), so you must either install it or use an Eclipse version that already includes Maven support (like Eclipse IDE for Java Developers or Eclipse IDE for Java EE Developers). Here’s a step-by-step guide to set up Maven in Eclipse and run your Maven project:
Step 1: Install Maven Support in Eclipse
- Open Eclipse.
- Go to Help > Eclipse Marketplace.
- In the "Eclipse Marketplace", search for "Maven".
- Look for "Maven Integration for Eclipse (m2e)" and click Install.
- Follow the prompts and restart Eclipse when prompted. If you’re using a version like Eclipse IDE for Java Developers, it likely already includes Maven support (m2e).
Step 2: Import the Maven Project (if you have already imported, please ignore this)
- Go to File > Import.
- Choose: Maven > Existing Maven Projects > Click Next.
- Browse to the root folder of the downloaded Maven project (where the pom.xml file is located).
- Select the project and click Finish.
Step 3: Build and Run the Maven Project • To build the project: Right-click the project > Run As > Maven install or Maven build. • Run the program through .bat file in the Command Line Interface integrated within Eclipse. (If not exist in Eclipse, you can download it from the Marketplace like you did for Maven above.) Use the “cd” command to go to the “institution” folder where the file “run_test.bat” is located, and then type “run_test.bat” and hit “Enter” to get the model running. Please see the screenshot below, which shows how to run it on my laptop. The reason why running the program through .bat instead of using a main class directly is presented at the end of the doc.
Alternatively, you could use the default Windows Command Line Interface to do it, which means you don’t need Eclipse, steps and screenshot shown below: Open CMD Manually and Navigate
- Press Windows + R, type: cmd and press Enter.
- In the terminal, change directory to your project folder: cd path\to\EIMOD\institution Example: cd C:\EIMOD\institution
- Run the batch file: run_test.bat
Why use .bat? Using batch (.bat) files to run Java applications offers a practical alternative to running code directly within an IDE like Eclipse. While Eclipse is ideal for development and debugging, batch files allow for consistent, repeatable execution of applications, especially useful in testing, deployment, or automation scenarios. They can encapsulate build steps, environment configuration, and runtime commands, making them valuable for both developers and non-developers who need to run the application outside the IDE. In this project, .bat is best for running the program (institutions + simple land use model) as a whole. There is no issue if the user only uses the reusable snippets (related to institution decision-making) in their own model through their own “main” functions.