As we have described in Chapter 5, there are two interfaces that can be used to generate layouts: a web application and a command-line interface.
In its core, the web tool only acts as a way to load input files into the program and retrieve the output files. All the files use the JSON format. On the right-hand side of the webpage, there are four tabs:
input form,
input JSON file,
output form,
output JSON file.
The forms display the JSON files in a user-friendly way.
In the middle of the page, there is a canvas that suits for viewing both the input kitchen scheme and the output layout of the fixtures. It is also possible to modify the position and orientation of the kitchen parts there.
To simplify the manipulation with the objects on the canvas, there are tabs dividing the whole process of working with the web application into six stages:
drawing the border (walls) of the kitchen,
adding the lower kitchen parts,
adding the upper kitchen parts,
checking that the kitchen groups were assigned correctly,
viewing the placement rules,
viewing the final layout.
The border is a polygonal chain (several connected line segments, polyline). Its vertices can be moved with a mouse. When the add new checkbox is checked, a new vertex can be added by clicking the canvas. The border is not used by the solver; it is only a piece of visual information displayed to the designer.
To add a lower or upper kitchen part, it is necessary to activate the add new checkbox. Otherwise, they can be moved and resized by selecting them and dragging their vertices. When a kitchen part is selected, its data are highlighted in the input form.
In the edit stage, the kitchen parts in the same kitchen group have the same colors. If the groups were assigned incorrectly, it is possible to correct them in the input form by changing the group numbers. The green circles mark the beginning of the kitchen group as they were calculated from offsets of the kitchen parts and should be all at one side of the group. If the kitchen parts are modified through the canvas, the kitchen groups and offsets are recalculated.
The fixtures can be entered solely through the input form on the right. However, it is possible to view them on the canvas by activating the fixture preview checkbox. Each fixture has to belong to a kitchen zone; these can be defined in the input form as well.
Similarly, the constants and preferences can be set through the form.
The most important constant is avg_fixture_width as it notably reduces
the solving time when set correctly. It directly determines the maximum
number of fixtures that can be fit in each kitchen part, see Subsection 3.2.1 and the constant .
After typing the placement rules in the input form, you can view them in the rules mode. However, they are not editable on the canvas.
It is possible to generate the layout using a platform and solver that are different than the default ones (Pyomo, Gurobi) or to use multiple solvers at once. This can also be configured in the input form.
You can load the input file from a local JSON file or load the demo input using the buttons at the bottom of the page. The current input and output files can be downloaded. If you make a mistake when editing the input, you can use the buttons above the upper right corner of the canvas to navigate the history of changes.
To send the input to be solved, you can click the solve button in the upper left corner. Immediately, your kitchen scheme is sent to the server to be solved. After some time, the solution is automatically fetched from the server and displayed on the canvas.
After submitting the input file, you are assigned an URL address pointing to the kitchen scheme. It is even possible to save the address and open it later if the solving takes too long. You can also cancel the solving if you change your mind. Even though the solutions are fetched automatically, you can press the button get solution to check for the solutions manually.
When viewing the generated layout, you can select the clear view checkbox to shift the upper kitchen parts so that the view of the lower kitchen parts is clear.
There is also an option to show labels that were assigned to different kitchen parts or segments by the evaluation function. To read the contained information, click on the labels. If the evaluation function detects any errors, they are shown in the form of red labels that are always visible.
The evaluation function can be run manually on the input and output data at any given time. You can change the output file in the web interface and let it be evaluated using the evaluate button.
If multiple solutions were returned by the server, you can switch between them using the arrows on top of the page.
To run the command-line tool, you first need to install the required Python packages using the following command:
pip install -r requirements.txt
To use MILP solvers, you have to download them and make sure that Pyomo
can access them. The Gurobi solver is contained in its Python package
gurobipy, you only need to provide the license file.
To use MiniZinc, you need to install it from the official website. Most of the MiniZinc solvers are included in the package.
The main way to use the program is by running experiments. An experiment is usually described by a single JSON file, but the file can be overridden by command-line flags. You can even run an experiment described only by the flags without any experiment file.
These are the supported flags:
-x, --experiment followed by a path of an experiment file,
-i, --input with one or multiple paths to input files or
directories containing input files,
-o, --output defining the output directory,
-s, --solver setting the platform and solver as
platform.solver,
-m, --model, if used, the Pyomo model is written into a file,
-nw, if used, the layout is not displayed in a window.
The program may then be used as follows:
python kitchendesigner -i input.json -o solutions -nw
There are also two other flags that can only be used together with a single input file. To assess a given solution using the evaluation function, run this command:
python kitchendesigner -i <input_file> -e <output_file>
To debug the MILP model by fixing the values of variables (see Subsection 5.2.3), you can use the following command:
python kitchendesigner -i <input_file> -f <output_file>
For all the three types of files we provide JSON Schema descriptions. Input files are validated against the schema.
An input file is a JSON object that may contain the following fields:
constants – an object containing constants (required),
preferences – an object with preferences (optional),
kitchen_parts – a list of kitchen parts (required),
zones – a list of kitchen zones (required),
available_fixtures – a list of fixtures (required),
placement_rules – a list of placement rules (optional),
solve – a list of solving instructions (optional),
tests – a list of tests used to evaluate the solutions in the
command-line tool (optional),
visual – an object used exclusively by the web application to
display additional visual information (optional).
As the MILP model was originally larger, there are some (optional) fields that are supported but not currently in use. We ignore these fields in this documentation.
These are the constants that can be specified:
min_fixture_width – a minimum allowed width of a fixture
(optional, inferred from minimum widths of individual fixtures),
max_fixture_width – a maximum allowed width of a fixture
(optional, inferred from maximum widths of individual fixtures),
avg_fixture_width – an average width of a fixture, affects the
number of segments in a kitchen part (optional but recommended, by
default equal to the value of min_fixture_width),
multiple_fixture_copy_count – a number of duplicates that is
created for fixtures selected to be duplicated (3 by default).
The following preferences with numeric values (modifying the objective function) can be stated:
width_bonus,
fixture_penalty,
vertical_discontinuity_penalty,
worktop_discontinuity_penalty,
width_not_same_penalty.
When using the Chuffed solver, the values of the preferences have to be integers.
Also, to activate the piecewise formulation of vertical continuity, we
can set the preference vertical_discontinuity_alternative to true. To
only look at the upper fixtures when penalizing different widths of
neighboring fixtures, we can set the preference width_not_same_only_top
to true.
A kitchen part can have the following fields:
name of the kitchen part (required, should be unique),
width (required),
depth (required),
position – an object containing its x and y coordinates,
angle of rotation (in degrees), group_number specifying the
number of its kitchen group (can be any positive integer) and
group_offset (all is required),
is_top – Boolean value indicating if it is an upper kitchen part
(optional),
edge_left and edge_right (both optional).
Every zone should have a unique name and a color (HEX color
code).
Each fixture can have the following fields:
name of the fixture (required, should be unique),
type – a more general descriptor of the fixture, can be used to
select multiple similar fixtures in position rules (required),
zone – name of the kitchen zone the fixture belongs to,
width_min (required),
width_max (required),
position_top and position_bottom Boolean fields – both of them
are true for tall fixtures, otherwise only one of them is true (for
upper fixtures, only position_top should be true),
has_worktop – a Boolean field (optional),
allow_edge_left, allow_edge_right (both optional),
allow_multiple – a Boolean field indicating that the fixture
should be duplicated (optional).
Every placement rule can have the listed fields:
rule_type – exclude or include (required),
area – kitchen, group, or group_section (required),
attribute_name – indicates the attribute that will be used to
select the affected fixtures, possible values: name, type,
zone, height (required),
attribute_value – states the value of the attribute used to
select the affected fixtures (required); if the attribute height
is used, we can select either tall or other;
for group and section rules, we need to specify group,
for section rules, we also specify section_width and
section_offset.
An object of solving instructions can contain information about
platform – pyomo or minizinc (required),
solver – gurobi, highs, scip, chuffed, or cp-sat
(optional),
count – number of requested solutions (optional, 1 by default),
settings – other solver-specific settings (optional); some
solvers support setting a number of threads that can be used for the
computation (it has to be provided to achieve multithreading in
MiniZinc), it can be defined using a threads field.
An output file consists of three objects: config, metadata, and
solution.
The config object contains the solving instructions that were used to
obtain the solution. In the metadata object, there is a number of the
solution (if the solver returned multiple solutions, it can be greater
than 1), the time needed to find the solution, the value of the
objective function, the time and date of generating the solution, the
score returned by the evaluation function, and components of the
evaluation function.
The solution object describes the fitting of the fixtures in the
kitchen parts. Each field in the object corresponds to a single kitchen
part identified by its name. There is a padding indicating the left
padding of the kitchen part. Then there is a list of fixtures. Each
has a name, an original_name, and a width. The original_name
corresponds to the name stated in the input file. It is possible that
multiple output fixtures map to a single input fixture (due to the
duplication and the division of tall fixtures).
The experiment file may contain the following fields (all optional):
input – a list of input files or directories of input files (a leading underscore causes the file or directory to be ignored),
output – a path to an output directory,
benchmark_repetitions – how many times each model should be
solved; used to achieve better quality of the benchmarks (the times
are averaged over all attempts);
report – an object specifying all the information that should be
reported or saved,
common – an object used to replace some portions of the input
files; any field we specify here will be replaced in the input
files;
variant_a and variant_b – can be used for A/B testing, function
similarly to common,
variants – a list of named variants (keys are the names, values
are the replacement objects).
The report object may contain the following optional Boolean fields (the first two are true by default):
json – the JSON output should be saved,
window – the layout should be displayed in a window,
image – the layout should be saved as an image,
model – the Pyomo model should be saved in a file.