How to use FEMS

FEMS — OYS in Turkish — is a decision support system for forest management planning, built for the General Directorate of Forestry under the UNDP/GEF project “Integrated Approach to Management of Forests in Turkey”. It takes a measured forest and produces a comparison of management alternatives: what each way of managing a stand does to it over the planning horizon, and what the landscape totals come to when you mix them.

The growth model underneath is FVS (Forest Vegetation Simulator), calibrated for Turkish species against their North American analogues. It does not decide anything. It projects the consequences of decisions a planner makes, so that they can be compared before one is chosen.

Three pieces, and the split is forced by one thing: FVS is Fortran. The web application runs on Vercel and holds the interface and every decision a planner makes. The database is PostgreSQL with PostGIS and holds the domain model — about 250 stored functions that are the actual rules of the system; this application calls them rather than reimplementing them. FVS runs in a separate worker container, because a landscape simulation outlasts any web request.

The three are not coordinated by messages. simulation_control is a work queue: saving a grouping puts rows on it, the worker claims them, and the web application only ever reads it. A deploy cannot interrupt a running simulation.

Anyone may register. A new account arrives with its own user group, the shared library definitions every account can see, and no projects.

Usernames are 1–12 letters and digits and passwords at least 8 non-space characters — compatibility rules carried over from the Shiny system, not security policy. Passwords are stored with bcrypt. Accounts created before this rewrite used an unsalted keyed hash whose key was published in the repository; those are upgraded silently on first sign-in and should be treated as compromised until they are.

A project is one forest, one planning horizon and everything derived from it. Everything below happens inside one.

Authority comes from ownership: create a project and you are its owner, immediately, with no administrator in the loop. Access is granted to groups, never to users — to give somebody a project, put them in a group and grant the group the project. Four roles: owner, administrator, user, member. Every write in the application requires owner or administrator; user is read-only. An owner may also share a project with every account at once, read-only, which is how the Kokez example is published.

The data loader stages compartments, plots and trees and then calls fems_load_data, which builds the compartment hierarchy — project, working circle, stand — and attaches plots and trees to it. Compartment attributes are what FVS starts from: site index, site-index species, FVS variant and hemisphere. Without them the growth model has nothing to begin with, and the readiness list says so.

Loading a new inventory is not part of this version. The Kökez example was loaded through exactly this path, from the archives in the FEMS repository.

Pairs each inventory species with the FVS species it will be grown as, per variant. It is the step that gates everything downstream: no tree list, no scoping save and no simulation without it.

FVS has no Mediterranean or Anatolian variant, so every pairing is a claim about which North American species grows most like the Turkish one. That is a silvicultural judgement. The editor orders candidates so that same-genus entries come first, under a heading that says only that — a shared first word in a Latin name is a spelling match, not a statement about growth. Nothing chooses for you.

The Kokez example is mapped from the GEF-7/OYS project's own finalised calibration list.

Four kinds of shared definition, each owned by a user, granted to groups and reused across projects. A treatment is a silvicultural operation with the stand conditions that trigger it — density, diameter, stand density index — and the FVS keywords that carry it out. Regeneration says what comes back after one. A calibration adjusts FVS's growth for a species to local conditions: maximum SDI, maximum diameter and height. An objective definition is a quantity a plan is judged by, with the R function that computes it; each is defined twice, once in metric and once in imperial units, and a project uses the ones in its own units.

They are one screen in this application, because they are the same thing in different clothes. In this version the lists are read-only; species maps are the one definition with an editor.

Two calculations turn an inventory into something FVS can start from.

Missing tree values. A Turkish inventory measures diameter and expansion factor; heights, crown ratios, crown widths, ages and volumes are FVS's to predict. It fills them in and writes them back. This runs in the worker, once the species map and the site attributes are complete, and the worker then recomputes the stand structure.

Stand structure summary. One SQL call over every tree in the project, producing density, basal area, quadratic mean diameter, stand density index, canopy cover and volumes per stand. It is what scoping clusters on and what the readiness list checks. Press Recompute structure on the Stands page; it overwrites the previous answer for the whole project.

Stands that will be managed alike are clustered into scoping groups, and each group is simulated once rather than each stand — which is what makes a landscape run tractable. The weight sliders say what similar means: species composition, size, density, site.

The clustering is Ward's method with area weighting, ported from the R original and running in your browser, so every regrouping is instant. The map recolours with it, which is the only way to see whether a group is one block of hillside or twenty fragments.

Saving a grouping is what queues the simulations. There is no submit button because there is nothing to submit — trig_insert_simulation_control fires on each group insert. Saving again replaces the previous groups and everything built on them.

What may be done where. Treatments attach to compartments and are inherited down the hierarchy, so one assigned at working-circle level applies to every stand beneath it. Regeneration attaches to scoping groups.

Together they define the set of alternatives FVS will simulate for each group: every combination of the treatments available to it. A group with no regeneration and a compartment with no treatment are both flagged; an unassigned group simulates as no-action only.

The worker claims each queued row, runs FVS for that group and writes the results back. The Simulate page reads the queue and reports what is still blocking the run; the worker does not start a project until every required readiness item is satisfied.

Three steps follow the last group, in the order the original dashboard ran them. Compile pathways turns the raw simulation output into pathways — one per management alternative per group. Summarise simulated stands computes density, volume and cover for every simulated stand. Calculate management objectives runs each objective definition's R function over those stands, which is why it happens in the worker and not in the database. The first two can be re-run from the Simulate page. All three overwrite what was there, and the objectives are recalculated whenever a definition changes.

Pathways shows what each alternative does to a group over time, before any allocation is made. Its auto-name encodes the treatment sequence, which is the only place a pathway's actual silviculture is legible without opening the treatment editor.

Toggle mixes them. Set the proportion of each group's area that follows each pathway and the landscape totals move as you drag. The arithmetic runs in the browser over a table fetched once, so the sliders are instant; nothing is saved until you save, and a saved alternative is a decision rather than a sketch.

Objectives lists the quantities the project is judged by.

Compartment outlines are stored as PostGIS geometry and drawn on the Scoping page, coloured by group and recoloured as the sliders move.

The map includes optional topographic and satellite basemaps. A project whose inventory was loaded without geometry simply has no map, which is a normal state rather than a failure.

The 2021 User's Manual describes the Shiny system, and several of its sections no longer map onto anything.

Nineteen separate applications are now one, so the project is a path segment rather than something you re-select after every jump between tools. Compartment Explorer has become the map on the Scoping page. Stand Visualizer has no equivalent here. Scoping Group Explorer and Pathway Explorer are the Scoping and Pathways pages. Creating projects, the Data Loader and the four definition editors are not part of this version. The dashboard's calculation buttons became steps the worker runs by itself when the readiness checks allow. Sign-in, sessions and password storage were replaced outright.

Everything else calls the same stored functions, against the same schema — database version 0.5 of the FEMS repository.

The Kokez example cannot be simulated as shipped: its tree file carries diameter and expansion factor only, and the missing tree values step needs the worker.

Several defects in the original SQL are corrected at load time rather than forked, each asserting on what it expects so an upstream change fails loudly. Two of them mattered: a readiness check that asked about a hard-coded project and therefore reported ready for every project always, and a function that recorded a project's owner in a column nothing read back.

A project's compartments need a site index, a site-index species, an FVS variant and a hemisphere before anything downstream will run, and the dashboard is where that is reported.