Skip to main content

Crate fieldopt_core

Crate fieldopt_core 

Source
Expand description

§fieldopt-core

Field-survey design under real field cost. The crate provides the computational pieces behind the R package fieldopt: travel matrices, routing of field work (exact for small instances, hybrid genetic search otherwise, with service times, stops and capacity limits), spatially balanced sampling with the local pivotal method, balanced sampling with the cube method and the Voronoi measure of spatial balance, Horvitz-Thompson estimation with the local-mean variance estimator, and cost-aware allocation across strata or frames, for one or several study variables, in dual frames and in two stages. It has no dependencies and every randomised step is reproducible from a seed.

use fieldopt_core::distance::euclidean_matrix;
use fieldopt_core::routing::{grasp_routes, GraspOptions, RouteLimits};
use fieldopt_core::sampling::{inclusion_probabilities, local_pivotal};

// a 6 x 6 grid of segments plus a depot at the origin
let mut x = vec![0.0]; let mut y = vec![0.0];
for i in 0..36 { x.push(1.0 + (i % 6) as f64); y.push(1.0 + (i / 6) as f64); }
let m = euclidean_matrix(&x, &y).unwrap();

// select 12 segments, spatially balanced, with equal probabilities
let coords: Vec<f64> = (1..37).flat_map(|i| vec![x[i], y[i]]).collect();
let pi = inclusion_probabilities(&vec![1.0; 36], 12).unwrap();
let sampled = local_pivotal(&coords, 2, &pi, 1).unwrap();
let units: Vec<usize> = (0..36).filter(|&i| sampled[i]).map(|i| i + 1).collect();

// route the field work from the depot with at most 5 segments per day
let limits = RouteLimits { max_length: f64::INFINITY, max_stops: 5, capacity: f64::INFINITY };
let sol = grasp_routes(&m, 0, &units, limits, GraspOptions::default()).unwrap();
assert_eq!(sol.routes.iter().map(|r| r.len()).sum::<usize>(), 12);
assert!(sol.total >= sol.lower_bound);

Re-exports§

pub use allocation::allocate_for_budget;
pub use allocation::allocate_for_variance;
pub use allocation::allocate_multivariate;
pub use allocation::Allocation;
pub use allocation::MultiAllocation;
pub use allocation::Stratum;
pub use balance::cube;
pub use balance::spatial_balance;
pub use certify::certify_tour;
pub use certify::Certificate;
pub use distance::euclidean_matrix;
pub use distance::haversine_matrix;
pub use distance::Matrix;
pub use dualframe::dual_frame_allocation;
pub use dualframe::Domain;
pub use dualframe::DualFrame;
pub use dualframe::DualFrameAllocation;
pub use dualframe::Target;
pub use estimation::ht_total;
pub use estimation::local_mean_variance;
pub use estimation::srs_variance;
pub use routing::grasp_routes;
pub use routing::grasp_routes_with_service;
pub use routing::route_duration;
pub use routing::route_length;
pub use routing::GraspOptions;
pub use routing::RouteLimits;
pub use routing::Solution;
pub use sampling::inclusion_probabilities;
pub use sampling::local_pivotal;
pub use spatial::hilbert_order;
pub use spatial::systematic_replicates;
pub use twostage::two_stage_for_budget;
pub use twostage::two_stage_for_variance;
pub use twostage::TwoStage;
pub use twostage::TwoStageAllocation;

Modules§

allocation
Cost-aware allocation across strata (or frames treated as strata).
balance
Balanced sampling and the measure of spatial balance.
certify
Proof of optimality for a single tour: branch-and-bound on Held-Karp 1-trees (Held and Karp 1971; Volgenant and Jonker 1982). Each node of the search fixes some edges in the tour and forbids others; its bound is the best 1-tree under those constraints, improved by subgradient ascent on the node penalties. Branching takes a node of degree three or more in the 1-tree and either forbids one of its free edges or forces it. A 1-tree that is itself a tour gives an upper bound. The search stops when the bound of every open node reaches the best tour, within a relative tolerance, or when it runs out of nodes or time.
distance
Travel matrices from coordinates.
dualframe
Dual-frame allocation (Hartley 1962, 1974).
estimation
Design-based estimation for the sample.
rng
A small, dependency-free, seedable pseudo-random generator.
routing
Routing of field work: one team (a tour from a depot) or several teams or days (routes with a maximum duration, a maximum number of stops and a capacity).
sampling
Probability sampling of field units.
spatial
Spatially ordered systematic sampling.
twostage
Two-stage allocation with a cost function (Cochran 1977, Section 10.6).
vrp
The routing solver behind crate::routing::solve_routes: a hybrid genetic search in the spirit of Vidal (2022) with an optimal split of giant tours (Prins 2004), a local search with granular neighbourhoods (Toth and Vigo 2003) made of intra-route 2-opt and Or-opt and inter-route relocate, swap, SWAP* (Vidal 2022: exchange two units, each inserted at its best position in the other route) and 2-opt* moves, an exact dynamic programme for small instances, and the Held-Karp 1-tree bound for single tours. The genetic search keeps feasible and infeasible subpopulations with adaptive penalties on the excess load, duration and stops, prices moves from route totals and prefix sums in constant time, restarts its population after a long run without improvement and can stop on a time limit.

Constants§

VERSION
Version of this crate, for reports.