Set parameters

Use set_params to define the folders you want to work, to initiate the R libraries or to debug your code.

mobility.config.apply_import_time_memory_reclaim_policy()

Applies the startup memory reclaim policy before Polars is imported.

Parameters: Returns: str: Applied memory reclaim policy.

Why this exists: heavy Polars workloads can keep a high amount of reserved native memory after peak operations. More aggressive allocator reclaim settings can reduce retained RAM a lot on long simulations, which is usually a better default for Mobility users than maximizing raw throughput.

The startup config is read from ~/.mobility/mobility_config.json on purpose. It must be available before runtime setup, because custom package data folders are usually only known later in the process.

Upstream context: - https://github.com/pola-rs/polars/issues/22871 - https://github.com/pola-rs/polars/issues/23128 - https://github.com/pola-rs/polars/issues/27061 - https://github.com/pola-rs/polars/pull/27395

mobility.config.set_env_variable(key, value)

Sets an environment variable.

Parameters: key (str): The name of the environment variable. value (str): The value to be set for the environment variable.

mobility.config.set_params(package_data_folder_path=None, project_data_folder_path=None, path_to_pem_file=None, http_proxy_url=None, https_proxy_url=None, inject_into_ssl=False, r_packages=True, r_packages_force_reinstall=False, r_packages_download_method='auto', debug=False, logging_level='INFO', feedback=None, progress=None, r_timeout_seconds=None, r_max_retries=0, r_retry_delay_seconds=5, r_heartbeat_interval_seconds=30, r_idle_timeout_seconds=None, r_idle_cpu_percent=1.0, r_idle_memory_change_mb=1.0, r_cpu_check_interval_seconds=5)

Sets up the necessary environment for the Mobility package.

This function configures logging, sets various environment variables, and establishes default paths for package and project data folders.

Parameters: package_data_folder_path (str, optional): The file path for storing common datasets used by all projects. project_data_folder_path (str, optional): The file path for storing project-specific datasets. path_to_pem_file (str, optional): The file path to the PEM file for SSL certification. http_proxy_url (str, optional): The URL for the HTTP proxy. https_proxy_url (str, optional): The URL for the HTTPS proxy. inject_into_ssl (bool, optional): Whether to inject the truststore package into Python’s SSL handling. r_packages (boolean, optional): whether to install R packages or not by running RScriptRunner (does not work for github actions so is handled by a separate r-lib github action) r_packages_force_reinstall (bool, optional) r_packages_download_method (str, optional): set this parameter to “wininet” to be able to install packages on some proxies. See the installation.md page for details. debug (bool, optional): set debug to True to see the R logs, including error messages logging_level (str|int, optional): root logging level, e.g. “INFO” or “DEBUG” feedback (str, optional): controls normal run feedback.

Use “progress” for Rich progress bars, “logs” for regular INFO logs, or “debug” for detailed DEBUG logs and R logs. When omitted, Mobility uses “progress” in an interactive console and “logs” in CI or other non-interactive shells, except when debug=True or logging_level=”DEBUG”.

progress (str|bool, optional): old name for feedback. Prefer feedback. r_timeout_seconds (int, optional): timeout applied to each R script run. Leave as None to disable the timeout. r_max_retries (int, optional): number of times to retry a failed or timed out R script run. r_retry_delay_seconds (int, optional): waiting time between two R script attempts. r_heartbeat_interval_seconds (int, optional): frequency of the R runner heartbeat logs. r_idle_timeout_seconds (int, optional): stop an R attempt after this many idle seconds. Leave as None or set to 0 to disable. r_idle_cpu_percent (float, optional): CPU threshold used by the R idle monitor. r_idle_memory_change_mb (float, optional): RAM-change threshold used by the R idle monitor. r_cpu_check_interval_seconds (int, optional): frequency of the R idle monitor checks.

mobility.config.setup_logging(logging_level='INFO')

Configures the logging for the Mobility package.

This function sets up basic logging configuration including format, level, and date format.

mobility.config.setup_package_data_folder_path(package_data_folder_path)

Sets up the package data folder path.

If a path is provided, it is used; otherwise, a default path is set. This function also ensures the creation of the default folder if it doesn’t exist, after user confirmation.

Parameters: package_data_folder_path (str, optional): The file path for storing common datasets.

mobility.config.setup_project_data_folder_path(project_data_folder_path)

Sets up the project data folder path.

If a path is provided, it is used; otherwise, a default path is set. This function also ensures the creation of the default folder if it doesn’t exist, after user confirmation.

Parameters: project_data_folder_path (str, optional): The file path for storing project-specific datasets.

mobility.config.setup_ssl_truststore(inject_into_ssl=False)

Optionally inject truststore into Python’s SSL handling.

Parameters: inject_into_ssl (bool, optional): Whether to inject truststore into ssl.

mobility.config.update(memory_reclaim_policy=None)

Creates or updates the Mobility user config file.

Parameters: memory_reclaim_policy (str, optional): Startup memory reclaim policy. Returns: pathlib.Path: Path to the updated config file.

This function persists the preferred startup policy for future Python sessions in ~/.mobility/mobility_config.json. It does not try to reconfigure the current process, because allocator settings are usually applied too early for a live update to be reliable once Polars has already been imported.