rustalgos

Low-level internals. These are the Rust-backed structures and functions that power cityseer. They carry no stability guarantee and are subject to breaking changes from time to time. Users are encouraged to use the higher-level wrappers instead, which are more stable: the CityNetwork class, or the metrics and tools modules. The basic information below is provided for those who do wish to work with the lower-level internals.

Cityseer high-performance algorithms implemented in Rust.

avg_distances_for_betas

avg_distances_for_betas
(
betas : list[float]
min_threshold_wt : float | None = None
)->[ list[float] ]

Calculate the mean distance corresponding to given beta parameters.

Parameters

betas
list[float]

β\beta parameters.

min_threshold_wt
float | None

Optional cutoff weight wminw_{min}.

Returns

list[float]

The average walking distance for each beta.

Notes

from cityseer import rustalgos

distances = [100, 200, 400, 800, 1600]
betas = rustalgos.betas_from_distances(distances)
print("betas", betas)
# betas [0.04, 0.02, 0.01, 0.005, 0.0025]

avg = rustalgos.avg_distances_for_betas(betas)
print("avg", avg)

betas_from_distances

betas_from_distances
(
distances : list[int]
min_threshold_wt : float | None = None
)->[ list[float] ]

Convert distance thresholds (dmaxd_{max}) to decay parameters (betas). Requires distances > 0 and sorted in strictly increasing order. Uses a default minimum weight threshold.

Parameters

distances
list[int]

dmaxd_{max} values (> 0, strictly increasing) to convert.

min_threshold_wt
float | None

Optional cutoff weight wminw_{min} (default: ~0.0183).

Returns

list[float]

Corresponding decay parameters β\beta.

Raises

ValueError

If inputs are invalid (empty, non-positive, not increasing).

Notes

from cityseer import rustalgos

distances = [200, 400, 800, 1600]
betas = rustalgos.betas_from_distances(distances)
print(betas)  # prints: [0.02, 0.01, 0.005, 0.0025]

The β\beta parameter controls the strength of exponential distance decay:

weight=exp(−β⋅distance)weight = exp(-\beta \cdot distance)

This reflects a decreasing willingness to walk correspondingly farther distances. For example, if β=0.005\beta=0.005 were to represent a person’s willingness to walk to a bus stop, then a location 100m distant would be weighted at 60% and a location 400m away would be weighted at 13.5%.

Example beta decays

Uses the formula:

β=−log(wmin)dmax\beta = -\frac{log(w_{min})}{d_{max}}

The default min_threshold_wt of wmin=0.01831563888873418w_{min}=0.01831563888873418 yields conveniently rounded β\beta values, for example:

dmaxd_{max}β\beta
200m0.02
400m0.01
800m0.005
1600m0.0025

Overriding the default wminw_{min} will adjust the β\beta accordingly.

check_numerical_data

check_numerical_data
(
data_arr
)

Validates that all elements in a 2D numerical array are finite.

Raises

ValueError

If any element is not finite (NaN or infinity).

clip_wts_curve

clip_wts_curve
(
distances : list[int]
betas : list[float]
spatial_tolerance : int
)->[ list[float] ]

Calculate upper weight bounds for clipping distance decay curves based on spatial tolerance. Used when data point location has uncertainty defined by spatial_tolerance. Determine the upper weights threshold of the distance decay curve for a given β\beta based on the spatial_tolerance parameter. This is used by downstream functions to determine the upper extent at which weights derived for spatial impedance functions are flattened and normalised. This functionality is only intended for situations where the location of datapoints is uncertain for a given spatial tolerance.

Use distance based clipping with caution for smaller distance thresholds. For example, if using a 200m distance threshold clipped by 100m, then substantial distortion is introduced by the process of clipping and normalising the distance decay curve. More generally, smaller distance thresholds should generally be avoided for situations where datapoints are not located with high spatial precision.

Parameters

distances
list[int]

Distance thresholds (dmaxd_{max}).

betas
list[float]

Decay parameters (β\beta).

spatial_tolerance
int

Spatial buffer distance (uncertainty).

Returns

list[float]

Maximum weights for clipping the decay curve for each beta.

clipped_beta_wt

clipped_beta_wt
(
beta : float
max_curve_wt : float
data_dist : float
)->[ float ]

Calculate a single weight using beta decay, clipped by a maximum weight. Applies weight=exp(−β⋅distance)weight = exp(-\beta \cdot distance), ensuring the result does not exceed max_curve_wt.

Parameters

beta
float

The decay parameter β\beta.

max_curve_wt
float

The maximum allowed weight (from clip_wts_curve).

data_dist
float

The distance to the data point.

Returns

float

The calculated (potentially clipped) weight. Returns 0.0 if calculation fails.

distances_from_betas

distances_from_betas
(
betas : list[float]
min_threshold_wt : float | None = None
)->[ list[int] ]

Convert decay parameters (betas) to distance thresholds (dmaxd_{max}). Requires betas > 0 and sorted in strictly decreasing order. Uses a default minimum weight threshold.

Parameters

betas
list[float]

β\beta values (> 0, strictly decreasing) to convert.

min_threshold_wt
float | None

Optional cutoff weight wminw_{min} (default: ~0.0183).

Returns

list[int]

Corresponding distance thresholds dmaxd_{max}.

Raises

ValueError

If inputs are invalid (empty, non-positive, not decreasing).

Notes

from cityseer import rustalgos

betas = [0.01, 0.02]
distances = rustalgos.distances_from_betas(betas)
print(distances)  # prints: [400, 200]

Uses the formula:

dmax=log(wmin)−βd_{max} = \frac{log(w_{min})}{-\beta}

The default min_threshold_wt of wmin=0.01831563888873418w_{min}=0.01831563888873418 yields conveniently rounded distance thresholds, for example:

β\betadmaxd_{max}
0.02200m
0.01400m
0.005800m
0.00251600m

distances_from_seconds

distances_from_seconds
(
seconds : list[int]
speed_m_s : float
)->[ list[int] ]

Convert time in seconds to distance thresholds (dmaxd_{max}) based on speed.

It is generally not necessary to utilise this function directly.

The default speed_m_s of 1.3331.333 yields the following dmaxd_{max} walking thresholds:

secondssecondsdmaxd_{max}
300400m
600800m
12001600m

Setting the speed_m_s to a higher or lower number will affect the dmaxd_{max} accordingly.]

Parameters

seconds
list[int]

Time values in seconds.

speed_m_s
float

Speed in meters per second.

Returns

list[int]

Corresponding distance thresholds dmaxd_{max}.

pair_distances_and_time

pair_distances_and_time
(
speed_m_s : float
distances : list[int] | None = None
minutes : list[float] | None = None
)->[ list[int] list[int] ]

Resolve distances and seconds from either distances or minutes. Exactly one of distances or minutes must be provided.

Parameters

speed_m_s
float

Walking speed in meters per second.

distances
list[int] | None

Distance thresholds in metres.

minutes
list[float] | None

Time in minutes.

Returns

tuple[list[int], list[int]]

A tuple containing (distances, seconds).

Raises

ValueError

If not exactly one of distances or minutes is provided, or if inputs are invalid.

seconds_from_distances

seconds_from_distances
(
distances : list[int]
speed_m_s : float
)->[ list[int] ]

Convert distance thresholds (dmaxd_{max}) to time in seconds based on speed.

It is generally not necessary to utilise this function directly.

The default speed_m_s of 1.333331.33333 yields the following walking times:

dmaxd_{max}secondsseconds
400m300
800m600
1600m1200

Setting the speed_m_s to a higher or lower number will affect the walking time accordingly.

Parameters

distances
list[int]

Distance thresholds dmaxd_{max}.

speed_m_s
float

Speed in meters per second.

Returns

list[int]

Corresponding time values in seconds.