source: pyomo/trunk/pyomo/scripting/driver_help.py @ 9519

Last change on this file since 9519 was 9519, checked in by wehart, 5 years ago

Adding copyright headers for files that are missing them.

Updating some of the copyright assertions

File size: 14.0 KB
Line 
1#  _________________________________________________________________________
2#
3#  Pyomo: Python Optimization Modeling Objects
4#  Copyright (c) 2014 Sandia Corporation.
5#  Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
6#  the U.S. Government retains certain rights in this software.
7#  This software is distributed under the BSD License.
8#  _________________________________________________________________________
9
10import argparse
11import os
12import os.path
13import sys
14import glob
15import datetime
16import textwrap
17import logging
18
19import pyutilib.subprocess
20
21from pyomo.util import get_pyomo_commands
22import pyomo.scripting.pyomo_parser
23
24logger = logging.getLogger('pyomo.solvers')
25
26
27def setup_command_parser(parser):
28    parser.add_argument("--list", dest="summary", action='store_true', default=False,
29                        help="List the commands that are installed with Pyomo")
30    parser.add_argument("command", nargs='*', help="The command and command-line options")
31
32def command_exec(options):
33    cmddir = os.path.dirname(os.path.abspath(sys.executable))+os.sep
34    if options.summary:
35        print("")
36        print("The following commands are installed in the Pyomo bin directory:")
37        print("----------------------------------------------------------------")
38        for file in sorted(glob.glob(cmddir+'*')):
39            print(" "+os.path.basename(file))
40        print("")
41        if len(options.command) > 0:
42            print("WARNING: ignoring command specification")
43        return
44    if len(options.command) == 0:
45        print("ERROR: no command specified")
46        return
47    if not os.path.exists(cmddir+options.command[0]):
48        print("ERROR: the command '%s' does not exist" % (cmddir+options.command[0]))
49        return
50    pyutilib.subprocess.run(cmddir+' '.join(options.command), tee=True)
51
52#
53# Add a subparser for the pyomo command
54#
55setup_command_parser(
56    pyomo.scripting.pyomo_parser.add_subparser('run',
57        func=command_exec, 
58        help='Execute a command from the Pyomo bin (or Scripts) directory.',
59        description='This pyomo subcommand is used to execute commands installed with Pyomo.',
60        epilog="""
61This subcommand can execute any command from the bin (or Script)
62directory that is created when Pyomo is installed.  Note that this
63includes any commands that are installed by other Python packages
64that are installed with Pyomo.  Thus, if Pyomo is installed in the
65Python system directories, then this command executes any command
66included with Python.
67"""
68        ))
69
70#--------------------------------------------------
71# help
72#   --command
73#   --api
74#   --transformations
75#   --solvers
76#--------------------------------------------------
77
78def help_commands():
79    print("")
80    print("The following commands are installed with Pyomo:")
81    print("-"*75)
82    registry = get_pyomo_commands()
83    d = max(len(key) for key in registry)
84    fmt = "%%-%d%%s" % d
85    for key in sorted(registry.keys(), key=lambda v: v.upper()):
86        print(fmt % (key, registry[key]))
87    print("")
88
89def help_api(options):
90    import pyomo.util
91    services = pyomo.util.PyomoAPIFactory.services()
92    #
93    f = {}
94    for name in services:
95        f[name] = pyomo.util.PyomoAPIFactory(name)
96    #
97    ns = {}
98    for name in services:
99        ns_set = ns.setdefault(f[name].__namespace__, set())
100        ns_set.add(name)
101    #
102    if options.asciidoc:
103        print("//")
104        print("// Pyomo Library API Documentation")
105        print("//")
106        print("// Generated with 'pyomo api' on ",datetime.date.today())
107        print("//")
108        print("")
109        print("== Pyomo Functor API ==")
110        for ns_ in sorted(ns.keys()):
111            print("")
112            level = ns_+" Functors"
113            print('=== %s ===' % level)
114            for name in sorted(ns[ns_]):
115                if ns_ != '':
116                    tname = name[len(ns_)+1:]
117                else:
118                    tname = name
119                print("")
120                print('==== %s ====' % tname)
121                print(f[name].__short_doc__)
122                if f[name].__long_doc__ != '':
123                    print("")
124                    print(f[name].__long_doc__)
125                print("")
126                flag=False
127                print("- [underline]#Required Keyword Arguments:#")
128                for port in sorted(f[name].inputs):
129                    if f[name].inputs[port].optional:
130                        flag=True
131                        continue
132                    print("")
133                    print('*%s*::\n %s' % (port, f[name].inputs[port].doc))
134                if flag:
135                    # A function may not have optional arguments
136                    print("")
137                    print("- [underline]#Optional Keyword Arguments:#")
138                    for port in sorted(f[name].inputs):
139                        if not f[name].inputs[port].optional:
140                            continue
141                        print("")
142                        print('*%s*::\n %s' % (port, f[name].inputs[port].doc))
143                print("")
144                print("- [underline]#Return Values:#")
145                for port in sorted(f[name].outputs):
146                    print("")
147                    print('*%s*::\n %s' % (port, f[name].outputs[port].doc))
148                print("")
149    else:
150        print("")
151        print("Pyomo Functor API")
152        print("-----------------")
153        wrapper = textwrap.TextWrapper(subsequent_indent='')
154        print(wrapper.fill("The Pyomo library contains a set of functors that define operations that are likely to be major steps in Pyomo scripts.  This API is defined with functors to ensure a consistent function syntax.  Additionally, these functors can be accessed with a factory, thereby avoiding the need to import modules throughout Pyomo."))
155        print("")
156        for ns_ in sorted(ns.keys()):
157            print("")
158            level = ns_+" Functors"
159            print("-"*len(level))
160            print(level)
161            print("-"*len(level))
162            for name in sorted(ns[ns_]):
163                if ns_ != '':
164                    tname = name[len(ns_)+1:]
165                else:
166                    tname = name
167                print(tname+':')
168                for line in f[name].__short_doc__.split('\n'):
169                    print("    "+line)
170
171def help_transformations():
172    import pyomo.environ
173    from pyomo.core import TransformationFactory
174    wrapper = textwrap.TextWrapper()
175    wrapper.initial_indent = '      '
176    wrapper.subsequent_indent = '      '
177    print("")
178    print("Pyomo Model Transformations")
179    print("---------------------------")
180    for xform in sorted(TransformationFactory.services()):
181        print("  "+xform)
182        print(wrapper.fill(TransformationFactory.doc(xform)))
183
184def help_solvers():
185    import pyomo.environ
186    wrapper = textwrap.TextWrapper(replace_whitespace=False)
187    print("")
188    print("Pyomo Solvers and Solver Managers")
189    print("---------------------------------")
190
191    print(wrapper.fill("Pyomo uses 'solver managers' to execute 'solvers' that perform optimization and other forms of model analysis.  A solver directly executes an optimizer, typically using an executable found on the user's PATH environment.  Solver managers support a flexible mechanism for asyncronously executing solvers either locally or remotely.  The following solver managers are available in Pyomo:"))
192    print("")
193    solvermgr_list = pyomo.opt.SolverManagerFactory.services()
194    solvermgr_list = sorted( filter(lambda x: '_' != x[0], solvermgr_list) )
195    n = max(map(len, solvermgr_list))
196    wrapper = textwrap.TextWrapper(subsequent_indent=' '*(n+9))
197    for s in solvermgr_list:
198        # Disable warnings
199        _level = logger.getEffectiveLevel()
200        logger.setLevel(logging.ERROR)
201        format = '    %-'+str(n)+'s     %s'
202        # Reset logging level
203        logger.setLevel(level=_level)
204        print(wrapper.fill(format % (s , pyomo.opt.SolverManagerFactory.doc(s))))
205    print("")
206    wrapper = textwrap.TextWrapper(subsequent_indent='')
207    print(wrapper.fill("If no solver manager is specified, Pyomo uses the serial solver manager to execute solvers locally.  The pyro and phpyro solver managers require the installation and configuration of the pyro software.  The neos solver manager is used to execute solvers on the NEOS optimization server."))
208    print("")
209
210    print("")
211    print("Serial Solver Interfaces")
212    print("------------------------")
213    print(wrapper.fill("The serial, pyro and phpyro solver managers support the following solver interfaces:"))
214    print("")
215    solver_list = pyomo.opt.SolverFactory.services()
216    solver_list = sorted( filter(lambda x: '_' != x[0], solver_list) )
217    n = max(map(len, solver_list))
218    wrapper = textwrap.TextWrapper(subsequent_indent=' '*(n+9))
219    for s in solver_list:
220        # Disable warnings
221        _level = logger.getEffectiveLevel()
222        logger.setLevel(logging.ERROR)
223        # Create a solver, and see if it is available
224        opt = pyomo.opt.SolverFactory(s)
225        if s == 'asl' or s == 'py' or opt.available(False):
226            format = '    %-'+str(n)+'s   * %s'
227        else:
228            format = '    %-'+str(n)+'s     %s'
229        # Reset logging level
230        logger.setLevel(level=_level)
231        print(wrapper.fill(format % (s , pyomo.opt.SolverFactory.doc(s))))
232    print("")
233    wrapper = textwrap.TextWrapper(subsequent_indent='')
234    print(wrapper.fill("An asterisk indicates that this solver is currently available to be run from Pyomo with the serial solver manager."))
235    print('')
236    print(wrapper.fill('Several solver interfaces are wrappers around third-party solver interfaces:  asl, openopt and os.  These interfaces require a subsolver specification that indicates the solver being executed.  For example, the following indicates that the OpenOpt pswarm solver is being used:'))
237    print('')
238    print('   openopt:pswarm')
239    print('')
240    print(wrapper.fill('The OpenOpt optimization package will launch the pswarm solver to perform optimization.  Similarly, the following indicates that the ipopt solver will be used:'))
241    print('')
242    print('   asl:ipopt')
243    print('')
244    print(wrapper.fill('The asl interface provides a generic wrapper for all solvers that use the AMPL Solver Library.'))
245    print('')
246    print(wrapper.fill('Note that subsolvers can not be enumerated automatically for these interfaces.  However, if a solver is specified that is not found, Pyomo assumes that the asl solver interface is being used.  Thus the following solver name will launch ipopt if the \'ipopt\' executable is on the user\'s path:'))
247    print('')
248    print('   ipopt')
249    print('')
250    _level = logger.getEffectiveLevel()
251    logger.setLevel(logging.ERROR)
252    try:
253        #logger.setLevel(logging.WARNING)
254        import pyomo.neos.kestrel
255        kestrel = pyomo.neos.kestrel.kestrelAMPL()
256        #print "HERE", solver_list
257        solver_list = list(set([name[:-5].lower() for name in kestrel.solvers() if name.endswith('AMPL')]))
258        #print "HERE", solver_list
259        if len(solver_list) > 0:
260            print("")
261            print("NEOS Solver Interfaces")
262            print("----------------------")
263            print(wrapper.fill("The neos solver manager supports solver interfaces that can be executed remotely on the NEOS optimization server.  The following solver interfaces are available with your current system configuration:"))
264            print("")
265            solver_list = sorted(solver_list)
266            n = max(map(len, solver_list))
267            format = '    %-'+str(n)+'s     %s'
268            for name in solver_list:
269                print(wrapper.fill(format % (name , pyomo.neos.doc.get(name,'Unexpected NEOS solver'))))
270            print("")
271        else:
272            print("")
273            print("NEOS Solver Interfaces")
274            print("----------------------")
275            print(wrapper.fill("The neos solver manager supports solver interfaces that can be executed remotely on the NEOS optimization server.  This server is not available with your current system configuration."))
276            print("")
277    except ImportError:
278        pass
279    logger.setLevel(level=_level)
280
281def help_exec(options):
282    flag=False
283    if options.commands:
284        if options.asciidoc:
285            print("The '--commands' help information is not printed in an asciidoc format.")
286        flag=True
287        help_commands()
288    if options.api:
289        flag=True
290        help_api(options)
291    if options.transformations:
292        if options.asciidoc:
293            print("The '--transformations' help information is not printed in an asciidoc format.")
294        flag=True
295        help_transformations()
296    if options.solvers:
297        if options.asciidoc:
298            print("The '--solvers' help information is not printed in an asciidoc format.")
299        flag=True
300        help_solvers()
301    if not flag:
302        help_parser.print_help()
303
304#
305# Add a subparser for the pyomo command
306#
307def setup_help_parser(parser):
308    parser.add_argument("-c", "--commands", dest="commands", action='store_true', default=False,
309                        help="List the commands that are installed with Pyomo")
310    parser.add_argument("-a", "--api", dest="api", action='store_true', default=False,
311                        help="Print a summary of the Pyomo Library API")
312    parser.add_argument("--asciidoc", dest="asciidoc", action='store_true', default=False,
313                        help="Generate output that is compatible with asciidoc's markup language")
314    parser.add_argument("-t", "--transformations", dest="transformations", action='store_true', default=False,
315                        help="List the available model transformations")
316    parser.add_argument("-s", "--solvers", dest="solvers", action='store_true', default=False,
317                        help="Summarize the available solvers and solver interfaces")
318    return parser
319
320help_parser = setup_help_parser(
321  pyomo.scripting.pyomo_parser.add_subparser('help',
322        func=help_exec, 
323        help='Print help information.',
324        description="This pyomo subcommand is used to print information about Pyomo's subcommands and installed Pyomo services."
325        ))
326
327
Note: See TracBrowser for help on using the repository browser.