Skip to contents

Changelog

Source: NEWS.md

blvim (development version)

Breaking changes

  • the quadratic parameter of blvim() and grid_blvim() has been replaced by the more flexible algorithm parameter.

New features

Most of the new features are based on the potential introduced by Osawa, Akamatsu, and Kogure in a recent paper (https://arxiv.org/abs/2011.06778v2).

  • sim_potential() computes the potential of a spatial interaction model using the definition proposed by Osawa, Akamatsu, and Kogure. The potential is also included in the data frames produced by sim_df().
  • blvim() and grid_blvim() now support multiple ways to specify the initial values of the attractivenesses of the destination locations. In particular, an automatically balanced vector of values is used when the initial attractivenesses are not provided. When multiple initial configurations are provided, the functions select the best solution, that is the one with the largest potential. Summaries of the individual runs are available with sim_logs(), the corresponding models with sim_runs() (when they are kept) and the initial attractivenesses with initial_attractiveness().
  • Initial values for blvim() and grid_blvim() can now be generated by arbitrary generators, using the new function blvim_initialise() to specify the generator and its parameters. The default blvim_simplex_initialise() uses the new function sample_weighted_simplex() to sample, in a structured way, the simplex associated with the spatial interaction model.
  • blvim() and grid_blvim() now support two new algorithms to find an equilibrium. Both are instances of projected gradient ascent on the potential and differ only in the geometry used for the gradient steps: "gradient" uses the geometry of the attractivenesses while "gradient_unit" uses that of rescaled attractivenesses that sum to one.
  • sim_diagnostic() gives details about the behaviour of the iterative algorithms for blvim() while blvim_gradient_control() can be used to set the parameters of the line search used in the projected gradient ascent methods.
  • blvim_gradient_control() also accepts an arbitrary diagonal preconditioner for the gradient algorithms, given as one strictly positive value per destination location. It changes the path followed by the algorithms (and therefore possibly the local maximum they reach), while the initial step rho_init keeps the same meaning.
  • the gradient algorithms can record the history of their iterations (duality gap, potential, line search steps, etc.) using blvim_gradient_control(history = TRUE). The new function sim_history() returns this history for the models kept by blvim() and grid_blvim(). When applied to a sim_list (or with grid_sim_history()), it returns the histories of all the models in a single data frame.
  • the logs of the runs of blvim() (see sim_logs()) identify the final configuration of each run (number of active destinations and identifier shared by the runs that reach the same configuration) and the selected run. summary() and autoplot() methods for the results of sim_logs() and sim_history() describe the runs (distinct configurations found, share of the runs that reach the best one, convergence) and the iterations (convergence rate of the duality gap, line search, changes of the number of active destinations, now recorded in the history).
  • blvim() and grid_blvim() now support conversion factors between attractivenesses and incoming flows, together with the new function sim_conversion().
  • sim_residual_jacobian() computes the Jacobian of the residual map with respect to the attractivenesses.

Documentation

  • the theoretical vignette has been expanded with new content based on the recent paper by Osawa et al. https://arxiv.org/abs/2011.06778v2
  • the documentation has been proofread, with more cross-references between related functions and corrections of several inaccuracies.

Minor improvements and bug fixes

  • improved test compatibility between different platforms

blvim 0.1.1

CRAN release: 2026-01-14

  • Simplify examples in grid_autoplot() to have them run in less than 5 seconds.

blvim 0.1.0

  • Initial CRAN submission.