Python API

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
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.