champpy.MobModel

The MobModel class is used to generate synthetic mobility profiles based on a trained model. It uses a Markov chain process to model vehicle locations over time and beta distributions to model speed and distance for each journey.

The model is initialized with pre-calculated parameters (ModelParams) from the parameterization step. After initialization, you can generate synthetic mobility profiles for a specified number of vehicles over a defined time period using the generate_mob_profiles() method.

Basic workflow:

  1. Initialize the model MobModel with ModelParams (from Parameterizer or ParamsLoader)

  2. Configure user parameters using UserParamsMobModel

  3. Call generate_mob_profiles() to generate synthetic mobility profiles

  4. Access the generated MobProfiles instance

class champpy.MobModel(model_params)[source]

Mobility model for generating synthetic vehicle mobility profiles.

The MobModel class uses a Markov chain approach to generate realistic mobility profiles (MobProfiles) for a fleet of vehicles. The model simulates vehicle locations over time, journey starts and ends, speeds, and distances based on statistical parameters defined in ModelParams.

Parameters:

model_params (ModelParams) – Dataclass containing calibrated mobility model parameters including transition matrices, speed distributions, and other statistical parameters for different vehicle clusters.

model_params

Stored model parameters used for profile generation.

Type:

ModelParams

Examples

import pandas as pd
import champpy

# Load model parameters
params_loader = champpy.ParamsLoader()
model_params = params_loader.load_params(id_params=1)

# Initialize the mobility model with the model parameters
mob_model = champpy.MobModel(model_params=model_params)

# Define user parameters for generation
user_params = UserParamsMobModel(
    number_vehicles=10,
    start_date=pd.Timestamp("2025-01-01"),
    end_date=pd.Timestamp("2025-12-31"),
    random_seed=42
)

# Generate mobility profiles
mob_profiles = mob_model.generate_mob_profiles(user_params)
generate_mob_profiles(user_params)[source]

Generate synthetic mobility profiles for a fleet of vehicles.

This method creates mobility profiles by simulating vehicle movements using a Markov chain approach. For each time step, the model determines vehicle locations based on transition probabilities, identifies journey starts and ends, and calculates speeds and distances.

Parameters:

user_params (UserParamsMobModel) – User-defined parameters specifying the number of vehicles, simulation period, and other configuration settings.

Returns:

Generated mobility profiles containing logbooks, vehicles, clusters, and locations data.

Return type:

MobProfiles

class champpy.UserParamsMobModel(number_vehicles=50, start_date=Timestamp('2025-01-01 00:00:00'), end_date=Timestamp('2025-12-31 00:00:00'), random_seed=1, days_buffer=1, first_loc=1)[source]

User parameters for configuring the mobility profile generation.

This dataclass contains all user parameters for generating synthetic mobility profiles with the MobModel. It defines the simulation period, number of vehicles, random seed, and other settings that control the profile generation process.

Raises:

  • ValueError – If number_vehicles is less than 1.

  • ValueError – If start_date is not at least one day before end_date.

days_buffer: int = 1
end_date: Timestamp = Timestamp('2025-12-31 00:00:00')

End date for the mobility profile generation period. Must be at least one day after start_date. Default is “2025-12-31”.

first_loc: int = 1
number_vehicles: int = 50
random_seed: int = 1

Random seed for reproducibility of the generated profiles. Default is 1.

start_date: Timestamp = Timestamp('2025-01-01 00:00:00')

Start date for the mobility profile generation period. Default is “2025-01-01”.