GuillotineModels.CommandLine

argparse_settings(models_list, solvers_list) :: ArgParseSettings

!!! Internal use.

Create an ArgParseSettings which includes the core arguments, generic arguments, and all arguments from models and solvers available (prefixed by their model or solver name).

Options of all models and solvers are added even if just one model is selected at a time. The reasons for this are: (1) we do not know the model before the parsing unless we manipulate ARGS directly; (2) if the unused solvers and models are not included in the ArgParseSettings they do not appear in the help message.

core_argparse_settings() :: ArgParseSettings

!!! Internal use.

An ArgParseSettings with the three core positional arguments model, solver, and instance_path. They cannot be modeled as Arg objects because, by design, all extra arguments must be options (i.e., be optional and preceded by dashes).

create_unprefixed_subset(prefix, p_args :: T) :: T

!!! Internal use.

Given some prefix, query the accepted_arg_list(Val{Symbol(prefix)}), to know which arguments were prefixed this way, search for them (with the prefix) in p_args and return a new typeof(p_args) object in which there is only the searched key-value pairs but the keys are changed to not have the prefix anymore.

gen_prefixed_argparse_settings(solver_or_model_name) :: ArgParseSettings

!!! Internal use.

Builds and returns an ArgParseSettings object representing all options of the given solver or model already prefixed with its name.

The solver_or_model_name may be a Symbol or String (none is prefered), and the method works because the solver or model implements accepted_arg_list(Val{Symbol(solver_or_model_name)})

generic_argparse_settings() :: ArgParseSettings

!!! Internal use.

An ArgParseSettings containing all options (not positional arguments) that are independent from the chosen solver or model.

generic_args() :: Vector{Arg}

!!! Internal use.

All the Args representing options that are independent from solver or model.

parse_args(args, models_list, solvers_list) :: Dict{String, Any}

!!! Internal use.

Given a vector of the command-line arguments args and the lists of available models and solvers, parse the arguments. If the args refer to a model or solver not in models_list or solvers_list exceptions may be thrown. If args just triggers the help message, an empty Dict is returned.

read_build_solve_and_print(problem, format, pp)

!!! Internal use.

Given the parsed parameters (pp), read the instance file, build the model, solve the model (unless pp['do-not-solve'] is true), and print statistics related to this process (unless pp['no-csv-output'] is true). The list of options recognized and implemented by this method is the list returned by generic_args() (it also needs the required arguments in core_argparse_settings()). The other arguments are solver or model specific and are extracted and passed to their specific methods.

round_instance(instance, p_args) -> old_or_new_instance

!!! Internal use.

Given a recognized instance type, uses p_args keys round-{nearest,up,down} to either: (1) return them unmodified if all keys have value one; (2) return a copy of them that is multiplied by the ratio and rounded the specified way (no two keys may have a value different than one).

round_instance(instance, factor, roundmode)

Return a new instance with all size-related fields multiplied by factor.

The roundmode (a Base.RoundingMode) specifies how the instances should be rounded back to their original types (as the factor is expected to be a Float64 and not an Integer).

This function should be extended for new instance types; if you want to use --round-{nearest,up,down} flags of GuillotineModels.CommandLine.run for new instance types just create a method that takes an instance of the new type, a Float64, and a Base.RoundingMode).

This function is called with this signature only if at least one option among round-{nearest,up,down} has a value different than one.

!!! Unmodified arrays (like d) may be shared between old and new instances.

run(args = ARGS; implemented_models = [...], supported_solvers = [...])

Parse the command-line arguments and take appropriate action: prints help or solve instance(s) in the specified file of the specified format for the specified problem using the specified solver, model, and their options.

The parameters available (listed in the help message and actually parsed) depend on the implemented_models and supported_solvers. The default values are the models and solvers made available by the GuillotineModels package. If you implement your own models or add support for more solvers you need to pass them there for them to be considered (and if you want the old ones to keep working you need to specify them also).

The best way to know everything this command is capable is to call:

import SUPPORTED_SOLVERS_YOU_HAVE_AVAILABLE
import GuillotineModels
GuillotineModels.CommandLine.run(
	["--help"];
	supported_solvers = [SUPPORTED_SOLVERS_YOU_HAVE_AVAILABLE]
)

Which will give you the help message. If you want to use it as an script you just need to remove the ["--help"] from the call.

throw_if_incompatible_options(p_args)

!!! Internal use.

Check the already parsed arguments and test if options that are incompatible with each other were used.

toy_instance(problem, format):: String

Return a String representing an instance of problem in format.

This is the function that should be extended in order to be able to call run with the --warm-jit with-toy.

warm_jit(p_args)

!!! Internal use.

Looks at p_args["warm-jit"] and implements what is said in the flag description.

See also: toy_instance, read_build_solve_and_print

warn_if_changed_unused_values(p_args, models_list, solvers_list)

!!! Internal use.

Gives warning messages if p_args has a value different from the default for an option of a model or solver that is not the one used. In other words, help a distracted user to not keep thinking it has passed an option to the used solver/model when they have not. Many solvers have the same option but with a different prefix, it is easy to change the solver used and forget to also change the prefix in the parameter options.

It is actually impossible to know if an argument was passed or not by the command-line after they are parsed by ArgParse because all of the arguments must have a default value and if the argument is not present in the command-line their default value is placed in the dict by ArgParse. This is the reason we just check if non-used options have values different from default, instead of just checking if they were provided.

This should work out-of-the-box for any third-party models or solvers given they implement their own version of accepted_arg_list and also have their identifying symbol passed in either models_list or solvers_list.