aequilibrae.distribution.GravityApplication

class aequilibrae.distribution.GravityApplication(project=None, **kwargs)

Applies a synthetic gravity model.

Model is an instance of SyntheticGravityModel class. Impedance is an instance of AequilibraEMatrix. Row and Column vectors are instances of AequilibraeData.

>>> import pandas as pd
>>> from aequilibrae import Project
>>> from aequilibrae.matrix import AequilibraeMatrix, AequilibraeData
>>> from aequilibrae.distribution import SyntheticGravityModel, GravityApplication

>>> project = Project.from_path("/tmp/test_project_ga")

# We define the model we will use
>>> model = SyntheticGravityModel()

# Before adding a parameter to the model, you need to define the model functional form
>>> model.function = "GAMMA" # "EXPO" or "POWER"

# Only the parameter(s) applicable to the chosen functional form will have any effect
>>> model.alpha = 0.1
>>> model.beta = 0.0001

# Or you can load the model from a file
# model.load('path/to/model/file')

# We load the impedance matrix
>>> matrix = AequilibraeMatrix()
>>> matrix.load('/tmp/test_project_ga/matrices/skims.omx')
>>> matrix.computational_view(['distance_blended'])

# We create the vectors we will use
>>> query = "SELECT zone_id, population, employment FROM zones;"
>>> df = pd.read_sql(query, project.conn)
>>> df.sort_values(by="zone_id", inplace=True)

# You create the vectors you would have
>>> df = df.assign(production=df.population * 3.0)
>>> df = df.assign(attraction=df.employment * 4.0)

>>> zones = df.index.shape[0]

# We create the vector database
>>> args = {"entries": zones, "field_names": ["productions", "attractions"],
...     "data_types": [np.float64, np.float64], "memory_mode": True}
>>> vectors = AequilibraeData()
>>> vectors.create_empty(**args)

# Assign the data to the vector object
>>> vectors.productions[:] = df.production.values[:]
>>> vectors.attractions[:] = df.attraction.values[:]
>>> vectors.index[:] = df.zone_id.values[:]

# Balance the vectors
>>> vectors.attractions[:] *= vectors.productions.sum() / vectors.attractions.sum()

# Create the problem object
>>> args = {"impedance": matrix,
...         "rows": vectors,
...         "row_field": "productions",
...         "model": model,
...         "columns": vectors,
...         "column_field": "attractions",
...         "output": '/tmp/test_project_ga/matrices/matrix.aem',
...         "nan_as_zero":True
...         }
>>> gravity = GravityApplication(**args)

# Solve and save the outputs
>>> gravity.apply()
>>> gravity.output.export('/tmp/test_project_ga/matrices/omx_file.omx')

# To save your report into a file, you can do the following:
# with open('/tmp/test_project_ga/report.txt', 'w') as file:
#     for line in gravity.report:
#         file.write(f"{line}\n")

__init__(project=None, **kwargs)

Instantiates the Ipf problem

Arguments:

model (SyntheticGravityModel): Synthetic gravity model to apply

impedance (AequilibraeMatrix): Impedance matrix to be used

rows (AequilibraeData): Vector object with data for row totals

row_field (str): Field name that contains the data for the row totals

columns (AequilibraeData): Vector object with data for column totals

column_field (str): Field name that contains the data for the column totals

project (Project, optional): The Project to connect to. By default, uses the currently active project

core_name (str, optional): Name for the output matrix core. Defaults to “gravity”

parameters (str, optional): Convergence parameters. Defaults to those in the parameter file

nan_as_zero (bool, optional): If Nan values should be treated as zero. Defaults to True

Results:

output (AequilibraeMatrix): Result Matrix

report (list): Iteration and convergence report

error (str): Error description

Methods

__init__([project])	Instantiates the Ipf problem
apply()	Runs the Gravity Application instance as instantiated
save_to_project(name, file_name[, project])	Saves the matrix output to the project file