GuillotineModels.Data

Data groups the instance-parsing functions and the types involved.

The parsing is extensible, as users can define any new types and extend the parsing functions to the types. It is advised to always return the same type for the same format type given as input, to avoid type-unstability and have a clear mapping. However, "auto" formats can also be created, to simplify the user's life (in special during testing) paying for a little overhead (and risk of misdetection).

The parsing function is extended for parametric types (e.g., Classic_G2KP{D, S, P}) so the data type returned (e.g., G2KP{D, S, P}) has the demand/N/M (D), length/width (S), and profit/area (P) fields with the right types. The function is also extend to Val types for convenience. They often map to a parametric type with sensible safe defaults (e.g. Val{:Classic_G2KP} -> Classic_G2KP{Int, Int, Int}). But a finer-grained control is also possible, as you can define something like (Val{:Classic_G2KP_16} -> Classic_G2KP_16{Int16, Int16, Int16}). Val parameters are also important because module CommandLine currently takes Strings that are passed to (Val ∘ Symbol) in order to define the instance format to be used.

This module already extends the instance reading for many instance formats. From the 2DCPackGen (further abbreviated here as CPG, Cutting and Packing Generator, because structs cannot start with a digit), the module supports: SLOPP, MHLOPPW, ODPW, and SSSCSP. They all follow the same pattern: SLOPP (the struct type with the data), CPG_SLOPP{D, S, P} (for the clearly typed format type), and Val{:CPG_SLOPP} for the safe defaults (i.e., the same as CPG{Int, Int, Int}, note this will be 32 in some machined and 64 in others). For details on these formats look at the 2DCPackGen tool.

Some file formats aggregate multiple instances in a single file. To allow generic functions to deal with this possibility, it is recommended to specialize GuillotineModels.Data.is_collection. This function should be specialized for the format type (not the return of the parsing). A format that does not specialize it is assumed to return a single instance upon parsing (i.e., GuillotineModels.Data.read_from_string).

The Classic_G2KP/G2KP format/data is also provided in the same fashion. The format is described in the method documentation.

The function may @warn the users of "strange" (but not incorrect) structure of the given instance, and error if the format is incorrect.

The current methods dispatch on the type of the first object, even if all current format types have empty objects. Consequently, instantiations like CPG_SLOPP{Int8, Int16, Int32}() and Val(:CPG_SLOPP) are expected, instead of just the type itself. In the future may be possible to add parsing options/configuration inside the format objects.

GenericParseError(format, error_message)

Most general error thrown by parse_from_string when it fails.

Ideally, methods extending parse_from_string should use a subtype of ParseError, either custom or this one.

abstract type ParseError <: Exception end

Supertype for parse errors.

is_collection(format) :: Bool

Indicate if a format is parsed to a single instance or to a collection.

If the format may store a variable number of instances, then passing the format object to this function should return true; if the format always store a single instance, then it should return false.

If this function is not specialized it assumes the format parses to a single instance.

If the function returns true for some format, it is assumed that the value returned by read_from_string (and its file counterpart) respect the Base.iterate interface; if a file in this format has just a single instance, this single instance should be wrapped in the same container used when there are multiple instances (any overhead caused by wrapping will probably not be larger than the overhead caused by type unstability).

Ideally, the value returned should not depend on the value of the argument, but only the type of the argument.

read_from_file(format, filepath :: AbstractString)

Reads the given file and apply read_from_string to its contents.

The (already provided) generic body of this function should be enough for most formats without the need of explicit specialization.

Note: this function remove all '\r' characters from the obtained String to avoid 'dos' vs 'unix' format inconsistencies.

See also: read_from_string

read_from_string(::Val{:CPG_MHLOPPW}, s :: AbstractString)

Convenience method. To be called as read_from_string(Val(:CPG_MHLOPPW), s). Equivalent to the call read_from_string(CPG_MHLOPPW{Int, Int, Int}(), s).

read_from_string(::Val{:CPG_ODPW}, s :: AbstractString)

Convenience method. To be called as read_from_string(Val(:CPG_ODPW), s). Equivalent to the call read_from_string(CPG_ODPW{Int, Int, Int}(), s).

read_from_string(::Val{:CPG_SLOPP}, s :: AbstractString)

Convenience method. To be called as read_from_string(Val(:CPG_SLOPP), s). Equivalent to the call read_from_string(CPG_SLOPP{Int, Int, Int}(), s).

read_from_string(::Val{:CPG_SSSCSP}, s :: AbstractString)

Convenience method. To be called as read_from_string(Val(:CPG_SSSCSP), s). Equivalent to the call read_from_string(CPG_SSSCSP{Int, Int, Int}(), s).

read_from_string(::Val{:Classic_G2KP}, s :: AbstractString)

Convenience method. To be called as read_from_string(Val(:Classic_G2KP), s). Equivalent to the call read_from_string(Classic_G2KP{Int, Int, Int}(), s).

read_from_string(::Val{:Simple_CPG_SLOPP}, s :: AbstractString)

Convenience method. To be called as read_from_string(Val(:Simple_CPG_SLOPP), s). Equivalent to the call read_from_string(Simple_CPG_SLOPP{Int, Int, Int}(), s).

read_from_string(format :: CPG_Format{D, S, P}, s :: AbstractString)

Expect a string in the format given and parse it to the adequate instance object. The format may be CPG_SLOPP{D, S, P}(), CPG_MHLOPPW{D, S, P}(), CPG_ODPW{D, S, P}(), CPG_SSSCSP{D, S, P}(). All these formats come from 2DCPackGen (10.1016/j.ejor.2014.02.059, see https://sites.google.com/gcloud.fe.up.pt/cutting-and-packing-tools/2dcpackgen for the code). Each of these formats starts with a self-explanatory header. These headers are copyied below.

***2D Rectangular Problem***
***Instances for the Single Large Object Placement Problem (SLOPP)***
Input parameter file: SLOPP_parameters.txt
***************************************************************************************************************
Total number of instances
LargeObject.Length      LargeObject.Width
Number of different item types (i)
Item[i].Length  Item[i].Width   Item[i].LowerBoundDemand        Item[i].UpperBoundDemand        Item[i].Value
***************************************************************************************************************

***2D Rectangular Problem***
***Instances for the Multiple Heterogeneous Large Object Placement Problem (MHLOPP/W)***
Input parameter file: MHLOPPW_parameters.txt
***************************************************************************************************************
Total number of instances 
Number of different large objects (j) 
LargeObject[j].Length   LargeObject[j].Width    LargeObject[j].Available
Number of different item types (i) 
Item[i].Length  Item[i].Width   Item[i].LowerBoundDemand        Item[i].UpperBoundDemand        Item[i].Value
***************************************************************************************************************

***2D Rectangular Problem***
***Problem tests for the Open Dimension Problem (ODP/W)***
Input parameter file: ODPW_parameters.txt
***********************************************************************
Total number of instances 
Number of different large objects (j)
LargeObject[j].Width    LargeObject[j].Available        LargeObject[j].Value
Number of different item types (i)
Item[i].Length  Item[i].Width   Item[i].Demand
***********************************************************************

***2D Rectangular Problem***
***Instances for the Single Stock Size Cutting Stock Problem (SSSCSP)***
Input parameter file: SSSCSP_parameters.txt
****************************************************************************************************
Total number of instances
LargeObject.Length      LargeObject.Width
Number of different item types (i)
Item[i].Length  Item[i].Width   Item[i].Demand
*****************************************************************************************************

The D, S, and P type parameters indicate the integer type which should be used to store Demand, Size, and Profit (or piece/plate area).

Returns an object of type YYY{D, S, P} in which YYY is what comes after CPG_ in the given format type.

read_from_string(_ :: Classic_G2KP{D, S, P}, s :: AbstractString)

Expect a string in the following format:

<L> <W>
<N>
<l_1> <w_1> <p_1> <d_1>
<l_2> <w_2> <p_2> <d_2>
...

L and W are the original plate length and width. N is the number of pieces in the instance. The l, w, p, and d, are the length, width, profit, and demand, of a piece.

The D, S, and P type parameters indicate the integer type which should be used to store Demand, Size, and Profit (or piece/plate area).

Returns a G2KP{D, S, P} object.

Notes

• If N is smaller than the number of lines after it, just the first N lines will be parsed and passed to the returned object.
• Empty lines and multiples spaces/tabs between columns may happen, but each non-empty line should contain the expected number of columns (i.e., the first non-empty line should have one number, the second non-empty line two numbers, all remaining non-empty lines four numbers).

See also: read_from_file

read_from_string(_ :: Simple_CPG_SLOPP{D, S, P}, s :: AbstractString)

Similar to read_from_string(CPG_SLOPP{D, S, P}(), s) which is described in read_from_string(format :: CPG_Format{D, S, P}, s :: AbstractString), the only difference in format compared to CPG_SLOPP is that Simple_CPG_SLOPP format expects just a single instance and no header.

write_to_file(format, instance, filepath :: AbstractString[, mode])
write_to_file(format, instance, io)

Wite the instance in filepath/io using format.

NOTE: this function is not yet implemented for most format and instance types.

mode is passed to open, by default it is: "w+".

New format/instance combinations should implement a method taking an io::IO third parameter (otherwise ambiguity problems may arise). The generic method taking a filename just open the file and call the io-like version over it.

Note: the write_to_string methods implemented by this package does not use '\r\n' (carriage return line endings) just '\n'.

To write to a String, pass an empty IOBuffer object and after the call execute read(seekstart(iob), String) to extract the String (this is the most efficient way).

See also: read_from_file, read_from_string