gemseo.disciplines.wrappers.disc_from_exe module#

Make a discipline from an executable.

class DiscFromExe(input_template, output_template, root_directory, command_line, input_filename, output_filename, directory_naming_method=DirectoryNamingMethod.NUMBERED, name='', parse_outfile_method=Parser.TEMPLATE, write_input_file_method=None, parse_out_separator='=', clean_after_execution=False)[source]#

Bases: _BaseDiscFromExe

Specific wrapper for executables.

This Discipline uses template files describing the input and output variables.

The templates can be generated with a graphical user interface (GUI). by executing the module template_grammar_editor.

An input template file is a JSON file formatted as

{
   "a": GEMSEO_INPUT{a::1.0},
   "b": GEMSEO_INPUT{b::2.0},
   "c": GEMSEO_INPUT{c::3.0}
}

where "a" is the name of an input, and 1.0 is its default value. Similarly, an output template file is a JSON file formatted as

{
   "a": GEMSEO_OUTPUT{a::1.0},
   "b": GEMSEO_OUTPUT{b::2.0},
   "c": GEMSEO_OUTPUT{c::3.0}
}

where "a" is the name of an output, and 1.0 is its default value.

The current limitations are

  • Only one input and one output template file, otherwise, inherit from this class and modify the parsers. Only limited input writing and output parser strategies are implemented. To change that, you can pass custom parsing and writing methods to the constructor.

  • The only limitation in the current file format is that it must be a plain text file and not a binary file. In this case, the way of interfacing it is to provide a specific parser to the DiscFromExe, with the write_input_file_method() and parse_outfile_method() arguments of the constructor.

  • For security reasons, the executable is executed via the Python subprocess library with no shell. If a shell is needed, you may override this in a derived class.

Initialize self. See help(type(self)) for accurate signature.

Parameters:
  • input_template (str | Path) -- The path to the input template file. The input locations in the file are marked by GEMSEO_INPUT{input_name::1.0}, where input_name is the name of the input variable, and 1.0 is its default value.

  • output_template (str | Path) -- The path to the output template file. The output locations in the file are marked by GEMSEO_OUTPUT{output_name::1.0}, where output_name is the name of the output variable, and 1.0 is its default value.

  • root_directory (str | Path) -- The base path of the execution directories.

  • command_line (str) -- The command line to run the executable. E.g. python my_script.py -i input.txt -o output.txt

  • input_filename (str | Path) -- The name of the input file to be generated in the output folder. E.g. "input.txt".

  • output_filename (str | Path) -- The name of the output file to be generated in the output folder. E.g. "output.txt".

  • directory_naming_method (DirectoryNamingMethod) --

    The method to create the execution directories.

    By default it is set to "NUMBERED".

  • name (str) --

    The name of the discipline. If empty, use the name of the class.

    By default it is set to "".

  • parse_outfile_method (Parser | OutputParser) --

    The optional method that can be provided by the user to parse the output template file. If the KEY_VALUE is used as output parser, the user may specify the separator key.

    By default it is set to "TEMPLATE".

  • write_input_file_method (InputWriter | None) -- The method to write the input data file. If None, use write_input_file().

  • parse_out_separator (str) --

    The separator used for the KEY_VALUE output parser.

    By default it is set to "=".

  • clean_after_execution (bool) --

    Whether to clean the last created directory after execution.

    By default it is set to False.

cache: BaseCache | None#

The execution and linearization data saved according to the cache type.

property command_line#

The command line.

execution_statistics: ExecutionStatistics#

The execution statistics of the process.

execution_status: ExecutionStatus#

The execution status of the process.

input_filename: str#

The name of the input file.

input_template: Path#

The path to the input template file.

jac: JacobianData#

The Jacobian matrices of the outputs.

The structure is {output_name: {input_name: jacobian_matrix}}.

name: str#

The name of the process.

output_filename: str#

The name of the output file.

output_template: Path#

The path to the output template file.

parse_outfile: OutputParser#

The function used to parse the output template file.

write_input_file: InputWriter#

The function used to write the input template file.

class Parser(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: StrEnum

Built-in parser types.

KEY_VALUE = 'KEY_VALUE'#

The output file is expected to have a key-value structure for each line.

TEMPLATE = 'TEMPLATE'#

The output is expected as a JSON file with the following format:

{
   "a": GEMSEO_OUTPUT{a::1.0},
   "b": GEMSEO_OUTPUT{b::2.0},
   "c": GEMSEO_OUTPUT{c::3.0}
}
parse_key_value_file(_, out_lines, separator='=')[source]#

Parse the output file from the expected text positions.

Parameters:
  • out_lines (Sequence[str]) -- The lines of the output file template.

  • separator (str) --

    The separating characters of the key=value format.

    By default it is set to "=".

Returns:

The output data in .Discipline friendly data structure.

Raises:

ValueError -- If the amount of separators in the lines are not consistent with the keys and values. If the float values cannot be parsed.

Return type:

dict[str, float]

parse_outfile(output_positions, out_lines)[source]#

Parse the output template file from the expected text positions.

Parameters:
  • output_positions (Mapping[str, tuple[int]]) -- The output position for each output variable, specified as {"name": (start, end, line_number)}, where "name" is the name of the output variable, start is the index of the starting point in the file, end is the index of the end character in the file, and line_number is the index of the line in the file. An index is a line index, i.e. a character number on the line.

  • out_lines (Sequence[str]) -- The lines of the file.

Returns:

The output data.

Return type:

dict[str, ndarray]

parse_template(template_lines, grammar_is_input)[source]#

Parse the input or output template.

This function parses the input (or output) template. It returns the tuple (names_to_values, names_to_positions), where:

  • names_to_values is the {name:value} dict:

    • name is the data name

    • value is the parsed input or output value in the template

  • names_to_positions describes the template format {name:(start,end,line_number)}:

    • name is the name of the input data

    • start is the index of the starting point in the input file template. This index is a line index (character number on the line)

    • end is the index of the end character in the template

    • line_number is the index of the line in the file

Parameters:
  • template_lines (Sequence[str]) -- The lines of the template file.

  • grammar_is_input (bool) -- Whether the template file describes input variables.

Returns:

A data structure containing the parsed input or output template.

Return type:

tuple[dict[str, str], dict[str, tuple[int, int, int]]]

write_input_file(input_file_path, data, input_positions, input_lines, float_format='{:1.18g}')[source]#

Write the input file template from the input data.

Parameters:
  • input_file_path (str | Path) -- The absolute path to the file to be written.

  • data (Mapping[str, ndarray]) -- The local data of the discipline.

  • input_positions (Mapping[str, tuple[int, int, int]]) -- The positions of the input variables, formatted as {"name": (start, end, line_number)}, where "name" is the name of the input variable, start is the index of the starting point in the file, end is the index of the end character in the file, and line_number is the index of the line in the file. An index is a line index, i.e. a character number on the line.

  • input_lines (MutableSequence[str]) -- The lines of the file.

  • float_format (str) --

    The format of the input data in the file.

    By default it is set to "{:1.18g}".

Return type:

None

InputWriter(*args, **kwargs)#

Input writer type.

alias of Callable[[str | Path, Mapping[str, ndarray], Mapping[str, tuple[int, int, int]], MutableSequence[str]], None]

OutputParser(*args, **kwargs)#

Output parser type.

alias of Callable[[Mapping[str, tuple[int]], Sequence[str]], Mapping[str, ndarray | float]]