fastmob-core 0.2.0

Rust compute kernels for fastmob mobility analysis.
Documentation
use rand::{Rng, SeedableRng};
use rand_xoshiro::Xoshiro256PlusPlus;
use rayon::prelude::*;

use crate::models::od::{validate_equal_lengths, CachedGravityOdRows};
use crate::models::shared::{
    cdf_choice, derive_agent_seed, estimate_records_per_agent, sample_tpl_rng,
    validate_starting_locs_length, weighted_choice_excluding,
};

type EprResult = Result<(Vec<i64>, Vec<f64>, Vec<f64>, Vec<i64>), String>;

#[derive(Clone, Copy)]
pub struct EprConfig<'a> {
    pub od_rows: &'a CachedGravityOdRows<'a>,
    pub n: usize,
    pub rho: f64,
    pub gamma: f64,
    pub alpha: f64,
    pub lambda_: f64,
    pub xmin: f64,
    pub start_ts: u64,
    pub end_ts: u64,
}

struct AgentThreadState {
    visited_locs: Vec<usize>,
    visit_counts: Vec<u32>,
    total_visits: f64,
}

impl AgentThreadState {
    fn new(n: usize) -> Self {
        Self {
            visited_locs: Vec::with_capacity(300),
            visit_counts: vec![0u32; n],
            total_visits: 0.0,
        }
    }
}

#[inline(always)]
fn record_visits(
    visited_locs: &mut Vec<usize>,
    visit_counts: &mut [u32],
    total_visits: &mut f64,
    loc: usize,
) {
    if visit_counts[loc] == 0 {
        visited_locs.push(loc);
    }
    visit_counts[loc] += 1;
    *total_visits += 1.0;
}

#[inline(always)]
fn clear_visits(visited_locs: &mut Vec<usize>, visit_counts: &mut [u32], total_visits: &mut f64) {
    for &loc in visited_locs.iter() {
        visit_counts[loc] = 0;
    }
    visited_locs.clear();
    *total_visits = 0.0;
}

#[allow(clippy::too_many_arguments)]
pub fn simulate_one_epr_agent(
    agent_id: usize,
    starting_loc: usize,
    seed: u64,
    config: EprConfig,
    lats: &[f64],
    lons: &[f64],
    out_agents: &mut Vec<i64>,
    out_ts: &mut Vec<i64>,
    out_lats: &mut Vec<f64>,
    out_lons: &mut Vec<f64>,
    visited_locs: &mut Vec<usize>,
    visit_counts: &mut [u32],
    total_visits: &mut f64,
) {
    let mut rng = Xoshiro256PlusPlus::seed_from_u64(seed);

    let mut cur_loc = starting_loc.min(config.n.saturating_sub(1));
    let mut cur_ts = config.start_ts;
    out_agents.push(agent_id as i64);
    out_ts.push(cur_ts as i64);
    out_lats.push(lats[cur_loc]);
    out_lons.push(lons[cur_loc]);
    record_visits(visited_locs, visit_counts, total_visits, cur_loc);

    let wait_h = sample_tpl_rng(&mut rng, config.xmin, config.alpha, config.lambda_);
    cur_ts += (wait_h * 3600.0) as u64;

    while cur_ts < config.end_ts {
        let n_visited = visited_locs.len();
        let p_new: f64 = rng.gen_range(0.0_f64..1.0);
        let explore = n_visited == 1
            || (n_visited < config.n
                && p_new <= config.rho * (n_visited as f64).powf(-config.gamma));
        let next_loc = if explore {
            let row = config.od_rows.get(cur_loc);
            cdf_choice(&mut rng, &row)
        } else {
            weighted_choice_excluding(&mut rng, visited_locs, visit_counts, *total_visits, cur_loc)
        };
        cur_loc = next_loc;
        out_agents.push(agent_id as i64);
        out_ts.push(cur_ts as i64);
        out_lats.push(lats[cur_loc]);
        out_lons.push(lons[cur_loc]);
        record_visits(visited_locs, visit_counts, total_visits, cur_loc);
        let wait_h = sample_tpl_rng(&mut rng, config.xmin, config.alpha, config.lambda_);
        cur_ts += (wait_h * 3600.0) as u64;
    }
}

#[allow(clippy::too_many_arguments)]
pub fn simulate_epr_agents_from_cached_od_impl(
    lats: &[f64],
    lons: &[f64],
    rels: &[f64],
    deterrence_type: &str,
    deterrence_arg: f64,
    origin_exp: f64,
    destination_exp: f64,
    rho: f64,
    gamma: f64,
    beta: f64,
    tau: f64,
    xmin: f64,
    start_ts: i64,
    end_ts: i64,
    n_agents: usize,
    master_seed: Option<u64>,
    starting_locs_slice: Option<&[i64]>,
) -> EprResult {
    let n = validate_equal_lengths(&[
        ("longitudes", lons.len()),
        ("relevances", rels.len()),
        ("latitudes", lats.len()),
    ])?;
    validate_starting_locs_length(starting_locs_slice, n_agents)?;
    if n == 0 || n_agents == 0 {
        return Ok((Vec::new(), Vec::new(), Vec::new(), Vec::new()));
    }
    let master_seed = master_seed.unwrap_or_else(rand::random);

    let od_rows = CachedGravityOdRows::new(
        lats,
        lons,
        rels,
        deterrence_type,
        deterrence_arg,
        origin_exp,
        destination_exp,
    );
    let records_per_agent = estimate_records_per_agent(start_ts, end_ts, xmin);

    let epr_config = EprConfig {
        od_rows: &od_rows,
        n,
        rho,
        gamma,
        alpha: 1.0 + beta,
        lambda_: 1.0 / tau,
        xmin,
        start_ts: start_ts as u64,
        end_ts: end_ts as u64,
    };

    let agent_trajectories: Vec<(Vec<i64>, Vec<f64>, Vec<f64>, Vec<i64>)> = (0..n_agents)
        .into_par_iter()
        .map_init(
            || AgentThreadState::new(n),
            |state, agent| {
                let seed = derive_agent_seed(master_seed, agent, 0);
                let sl =
                    match starting_locs_slice {
                        Some(starts) => (starts[agent].max(0) as usize).min(n - 1),
                        None => {
                            let mut start_rng = Xoshiro256PlusPlus::seed_from_u64(
                                derive_agent_seed(master_seed, agent, 1),
                            );
                            start_rng.gen_range(0..n)
                        }
                    };
                let mut out_agents = Vec::with_capacity(records_per_agent);
                let mut out_lats = Vec::with_capacity(records_per_agent);
                let mut out_lons = Vec::with_capacity(records_per_agent);
                let mut out_ts = Vec::with_capacity(records_per_agent);
                simulate_one_epr_agent(
                    agent + 1,
                    sl,
                    seed,
                    epr_config,
                    lats,
                    lons,
                    &mut out_agents,
                    &mut out_ts,
                    &mut out_lats,
                    &mut out_lons,
                    &mut state.visited_locs,
                    &mut state.visit_counts,
                    &mut state.total_visits,
                );
                clear_visits(
                    &mut state.visited_locs,
                    &mut state.visit_counts,
                    &mut state.total_visits,
                );
                (out_agents, out_lats, out_lons, out_ts)
            },
        )
        .collect();

    let total: usize = agent_trajectories.iter().map(|(a, _, _, _)| a.len()).sum();
    let mut out_agents: Vec<i64> = Vec::with_capacity(total);
    let mut out_lats: Vec<f64> = Vec::with_capacity(total);
    let mut out_lons_: Vec<f64> = Vec::with_capacity(total);
    let mut out_ts: Vec<i64> = Vec::with_capacity(total);

    for (agents, lats_chunk, lons_chunk, ts) in agent_trajectories {
        out_agents.extend_from_slice(&agents);
        out_lats.extend_from_slice(&lats_chunk);
        out_lons_.extend_from_slice(&lons_chunk);
        out_ts.extend_from_slice(&ts);
    }

    Ok((out_agents, out_lats, out_lons_, out_ts))
}

pub fn model_truncated_power_law_samples(
    xmin: f64,
    alpha: f64,
    lambda_: f64,
    n: usize,
    seed: u64,
) -> Vec<f64> {
    let mut rng = Xoshiro256PlusPlus::seed_from_u64(seed);
    let mut result = Vec::with_capacity(n);
    while result.len() < n {
        let u: f64 = rng.gen_range(0.0_f64..1.0);
        let x = xmin - (1.0 / lambda_) * (1.0 - u).ln();
        if rng.gen_range(0.0_f64..1.0) < (x / xmin).powf(-alpha) {
            result.push(x);
        }
    }
    result
}