Skip to content

Python API

Jump to bottom
Filipe Brandao edited this page Mar 22, 2017 · 45 revisions

Python API

The VPSolver Python API has 3 levels:

  • High-level API: high level wrapper functions (easy and direct usage);
  • Mid-level API: objects that wrap calls to VPSolver executables;
  • Low-level API: direct calls to VPSolver scripts and executables.

Jupyter Notebooks for a quick introduction:

High-level API

Example:

from pyvpsolver.solvers import vbpsolver

W = (5180, 2)
w = [(1120,1), (1250,1), (520,1), (1066,1), (1000,1), (1150,1)]
b = [9, 5, 91, 18, 11, 64]

# Solve a vector packing instance:
solution = vbpsolver.solve(
    W, w, b, script="vpsolver_glpk.sh", verbose=False
)
# Print the solution:
vbpsolver.print_solution(solution)

The high level API (pyvpsolver.solvers) includes:

  • vbpsolver - for vector packing;
  • mvpsolver - for multiple-choice vector packing;
  • additional solvers for other applications will be added soon.

Vector Packing Solver functions

How to import:

  • from pyvpsolver.solvers import vbpsolver.

How to use:

  • obj, lst_sol = vbpsolver.solve(W, w, b, script=None, script_options=None, verbose=None)
    • Important parameters:
      • W: bin capacity;
      • w: item weights;
      • b: item demands;
      • script: script that should be used to solve the model (e.g., vpsolver_glpk.sh);
      • script_options: options to pass to the script (optional).
    • Returns:
      • obj: objective value;
      • lst_sol: patterns;
      • (obj, lst_sol): solution.
  • vbpsolver.print_solution(solution)
    • Important parameters:
      • solution = (obj, lst_sol): vector packing solution.
    • Outputs:
      • The solution formatted.

Examples: example_vbp.py.

Multiple-choice Vector Packing Solver functions

How to import:

  • from pyvpsolver.solvers import mvpsolver.

How to use:

  • obj, lst_sol = mvpsolver.solve(Ws, Cs, Qs, ws, b, script=None, script_options=None, verbose=False)

    • Important parameters:
      • Ws: bin capacities for each bin type;
      • Cs: bin costs for each bin type;
      • Qs: number of bins available for each type (-1 if infinity);
      • ws: item weights;
      • b: item demands;
      • script: script that should be used to solve the model (e.g., vpsolver_glpk.sh);
      • script_options: options to pass to the script (optional).
    • Returns:
      • obj: objective value;
      • lst_sol: a list of solutions for each bin type;

  • mvpsolver.print_solution(solution)

    • Important parameters:
      • solution = (obj, lst_sol): multiple-choice vector packing solution.
    • Outputs:
      • The solution formatted.

Examples: example_mvp.py and example_vsbpp.py.

Mid-level API

Example:

from pyvpsolver import VPSolver           # from the low-level API
from pyvpsolver import VBP, AFG, MPS, LP  # from the mid-level API
from pyvpsolver.solvers import vbpsolver  # from the high-level API

# Create a vector packing instance:
instance = VBP(
    (5180,), # bin capacity
    [(1120,), (1250,), (520,), (1066,), (1000,), (1150,)], # item weights
    [9, 5, 91, 18, 11, 64] # item demands
)

# Create an arc-flow graph for the instance:
afg = AFG(instanceA, verbose=True)

# Create .mps model for the graph:
mps_model = MPS(afg, verbose=False)

# Solve the model an extract the solution:
out, solution = VPSolver.script("vpsolver_glpk.sh", mps_model, afg, verbose=True)

# Print the objective value:
obj, sol = solution
print("Objective: {}".format(obj))

# Print the solution:
vbpsolver.print_solution(solution)

How to import:

  • from pyvpsolver import VBP, MVP, AFG, MPS, LP.

Objects:

  • VBP objects: VBP(W, w, b, binary=False, verbose=False)

    • Important parameters:
      • W: bin capacity;
      • w: item weights;
      • b: item demands;
      • binary: binary patterns (if True) or general integer patterns (if False).

  • MVP objects: MVP(Ws, Cs, Qs, ws, b, binary=False, verbose=False)

    • Important parameters:
      • Ws: bin capacities for each bin type;
      • Cs: bin costs for each bin type;
      • Qs: number of bins available for each type (-1 if infinity);
      • ws: list of lists of weights of item incarnations;
      • b: item demands;
      • binary: binary patterns (if True) or general integer patterns (if False).

  • AFG objects: AFG(instance, verbose=None)

    • Important parameters:
      • instance: a VBP/MVP object.
    • Creates:
      • an arc-flow graph for the vector packing instance.

  • MPS objects: MPS(graph, verbose=None)

    • Important parameters:
      • graph: an AFG object.
    • Creates:
      • a MPS model.

  • LP objects: LP(graph, verbose=None)

    • Important parameters:
      • graph: an AFG object.
    • Creates:
      • a LP model.

Examples: example.py.

Low-level API

How to import:

  • from pyvpsolver import VPSolver.

How to use:

  • VPSolver.vbp2afg(instance_file, afg_file, verbose=None)

    • Description: creates arc-flow graphs for vector packing instances.
    • Important parameters:
      • vbp_file: a .vbp/.mvp file or a VBP/MVP object;
      • afg_file: a .afg file.
    • Actions:
      • calls bin/vbp2afg to write an arc-flow graph for vbp_file in afg_file.

  • VPSolver.afg2mps(afg_file, mps_file, verbose=None)

    • Description: converts arc-flow grafts to MPS models.
    • Important parameters:
      • afg_file: a .afg file or a AFG object;
      • mps_file: a .mps file.
    • Actions:
      • calls bin/afg2mps to write the MPS model for afg_file in mps_file.

  • VPSolver.afg2lp(afg_file, lp_file, verbose=None)

    • Description: converts arc-flow grafts to LP models.
    • Important parameters:
      • afg_file: a .afg file or a AFG object;
      • mps_file: a .lp file.
    • Actions:
      • calls bin/afg2lp to write the LP model for afg_file in lp_file.

  • VPSolver.vbpsol(afg_file, sol_file, verbose=None)

    • Description: extracts a vector packing solution from an arc-flow solution.
    • Important parameters:
      • afg_file: a .afg file or a AFG object;
      • sol_file: a .sol solution file.
    • Actions:
      • calls bin/vbpsol to extract the vector packing solution from the arc-flow solution sol_file associated with the graph afg_file.

  • VPSolver.vpsolver(instance_file, verbose=None)

    • Description: calls VPSolver.
    • Important parameters:
      • vbp_file: a .vbp/.mvp file or a VBP/MVP object;.
    • Actions:
      • calls bin/vpsolver to solve an instance (requires Gurobi).

  • output, solution = VPSolver.script(script_name, arg1=None, arg2=None, options=None, verbose=None)

    • Description: calls VPSolver scripts.
    • Important parameters:
      • script_name: VPSolver script name (e.g., vpsolver_glpk.sh);
      • arg1, arg2: parameters to be passed to the script;
      • options: options to be passed to the script.
    • Actions:
      • calls script_name to solve an instance.
    • Usage examples:
      • VPSolver.script(script name, .vbp file/VBP object);
      • VPSolver.script(script name, .mvp file/MVP object);
      • VPSolver.script(script name, .afg file/AFG object);
      • VPSolver.script(script name, .lp file/LP object);
      • VPSolver.script(script name, .mps file/MPS object);
      • VPSolver.script(script name, .mps/.lp file, .afg file/AFG object);
      • VPSolver.script(script name, MPS/LP object, .afg file/AFG object);
      • Note: the solution can only be extracted if the graph or the original instance are provided.

  • VPSolver.set_verbose(verbose)

    • Description: sets the default "verbose" behavior.
    • Parameters:
      • verbose: True or False.
    • Note: The default behavior is overridden if the verbose parameter is set to a value different from None in any API call.

Copyright © 2013-2017 Filipe Brandão < fdabrandao@dcc.fc.up.pt >. All rights reserved.

Clone this wiki locally