nrel.hive.util.h3_ops

Module Contents

Classes

H3Ops

class nrel.hive.util.h3_ops.H3Ops[source]
classmethod nearest_entity_by_great_circle_distance(geoid: nrel.hive.util.typealiases.GeoId, entities: Iterable[nrel.hive.model.entity.Entity], entity_search: immutables.Map[nrel.hive.util.typealiases.GeoId, FrozenSet[nrel.hive.util.typealiases.EntityId]], sim_h3_search_resolution: int, is_valid: Callable[[Any], bool] = lambda x: ..., max_search_distance_km: nrel.hive.util.units.Kilometers = 10) → nrel.hive.model.entity.Entity | None[source]

returns the closest entity to the given geoid. In the case of a tie, the first entity encountered is returned. invariant: the Entity has a geoid field (Entity.geoid)

Parameters:

  • geoid – the search origin

  • entities – a collection of a certain type of entity, by Id type

  • entity_search – the location of objects of this entity type, registered at a high-level grid resolution

  • sim_h3_search_resolution – the h3 resolution of the entity_search collection

  • is_valid – a function used to filter valid search results, such as checking stations for charger_id availability

  • k – the number of concentric rings to check in the high-level search

  • max_search_distance_km – the maximum distance a result can be from the search origin

Returns:

the nearest entity, or, None if not found within the constraints

classmethod nearest_entity(geoid: nrel.hive.util.typealiases.GeoId, entities: Iterable[nrel.hive.model.entity.Entity], entity_search: immutables.Map[nrel.hive.util.typealiases.GeoId, FrozenSet[nrel.hive.util.typealiases.EntityId]], sim_h3_search_resolution: int, distance_function: Callable[[Any], float], is_valid: Callable[[Any], bool] = lambda x: ..., max_search_distance_km: nrel.hive.util.units.Kilometers = 10) → nrel.hive.model.entity.Entity | None[source]

returns the closest entity to the given geoid. In the case of a tie, the first entity encountered is returned. invariant: the Entity has a geoid field (Entity.geoid)

Parameters:

  • geoid – the search origin

  • entities – a collection of a certain type of entity, by Id type

  • entity_search – the location of objects of this entity type, registered at a high-level grid resolution

  • sim_h3_search_resolution – the h3 resolution of the entity_search collection

  • is_valid – a function used to filter valid search results, such as checking stations for charger_id availability

  • distance_function – a function used to evaluate the distance metric for selection

  • k – the number of concentric rings to check in the high-level search

  • max_search_distance_km – the maximum distance a result can be from the search origin

Returns:

the nearest entity, or, None if not found within the constraints

classmethod get_entities_at_cell(search_cell: nrel.hive.util.typealiases.GeoId, entity_search: immutables.Map[nrel.hive.util.typealiases.GeoId, FrozenSet[nrel.hive.util.typealiases.EntityId]], entities: Iterable[nrel.hive.model.entity.Entity]) → Tuple[nrel.hive.model.entity.Entity, Ellipsis][source]

gives us entities within a high-level search cell

Parameters:

  • search_cell – the search-level h3 position we are looking at

  • entity_search – the upper-level search collection for this entity type

  • entities – the actual entities

Returns:

any entities which are located at this search-level cell

classmethod nearest_entity_point_to_point(geoid: nrel.hive.util.typealiases.GeoId, entities: Dict[nrel.hive.util.typealiases.EntityId, nrel.hive.model.entity.Entity], entity_locations: immutables.Map[nrel.hive.util.typealiases.GeoId, Tuple[nrel.hive.util.typealiases.EntityId, Ellipsis]], is_valid: Callable = lambda x: ...) → nrel.hive.model.entity.Entity | None[source]

A nearest neighbor search that scans all entities and returns the one with the lowest distance to the geoid.

Parameters:

  • geoid – GeoId to match to

  • entities – Entities to search over

  • entity_locations – Location of entities

  • is_valid – Optional function to filter for valid entities

Returns:

an optional entity if found

classmethod great_circle_distance(a: nrel.hive.util.typealiases.GeoId, b: nrel.hive.util.typealiases.GeoId) → nrel.hive.util.units.Kilometers[source]

computes the distance between two geoids

Parameters:

  • a – one geoid

  • b – another geoid

Returns:

the haversine distance between the two GeoIds

finds the GeoId which is some percentage between two GeoIds along a line

Parameters:

  • available_time_seconds – the amount of time to traverse

  • link – the link we are finding a mid point along

Returns:

a GeoId along the Link