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.

Vectors are a pandas DataFrame.

>>> import pandas as pd
>>> from aequilibrae.distribution import SyntheticGravityModel, GravityApplication

>>> project = create_example(project_path)

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

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

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

# We load the impedance matrix
>>> matrix = project.matrices.get_matrix("skims")
>>> 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)
>>> df.set_index("zone_id", inplace=True)

# You create the vectors you would have
>>> df = df.assign(productions=df.population * 3.0)
>>> df = df.assign(attractions=df.employment * 4.0)
>>> vectors = df[["productions", "attractions"]]

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

# Create the problem object
>>> args = {"impedance": matrix,
...         "vectors": vectors,
...         "row_field": "productions",
...         "model": model,
...         "column_field": "attractions",
...         "output": os.path.join(project_path, 'matrices/gravity_matrix.aem'),
...         "nan_as_zero":True
...         }
>>> gravity = GravityApplication(**args)

# Solve and save the outputs
>>> gravity.apply()
>>> gravity.output.export(os.path.join(project_path, 'matrices/gravity_omx.omx'))

__init__(project=None, **kwargs)

Instantiates the IPF problem

Arguments:

model (SyntheticGravityModel): Synthetic gravity model to apply

impedance (AequilibraeMatrix): Impedance matrix to be used

vectors (pd.DataFrame): Dataframe with data for row and column totals

row_field (str): Field name that contains the data for the row 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

apply()

Runs the Gravity Application instance as instantiated

Resulting matrix is the output class member

save_to_project(name: str, file_name: str, project=None) → None

Saves the matrix output to the project file

Arguments:

name (str): Name of the desired matrix record

file_name (str): Name for the matrix file name. AEM and OMX supported

project (Project, Optional): Project we want to save the results to. Defaults to the active project