Skip to main content
`Ctrl`+`K`

# 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