lbt_recipes.recipe module

Class to handle recipe inputs and outputs.

class lbt_recipes.recipe.Recipe(recipe_name)[source]

Bases: object

Recipe class to be used as a base for all Ladybug Tools recipes.

Note that this class is only intended for recipes that have a single output called “results”, which is typically a folder containing all of the result files of the recipe.

Parameters:

recipe_name – Text for the name of the recipe folder within this python package (eg. daylight_factor). This can also be the full path to a recipe folder (the folder containing the package.json and run.py file). If the input does not correspond to an installed package or a valid recipe folder, an exception will be raised.

Properties:

  • name

  • tag

  • path

  • default_project_folder

  • simulation_id

  • inputs

  • outputs

ToString()[source]
error_summary(project_folder=None)[source]

Get a string of the error summary after the recipe has run.

Parameters:

project_folder – The full path to the project folder containing completed recipe logs. If None, the default_project_folder on this recipe will be assumed. (Default: None).

failure_message(project_folder=None)[source]

Get a string of a recipe failure message that gives a summary of failed tasks.

Parameters:

project_folder – The full path to the project folder containing completed recipe logs. If None, the default_project_folder on this recipe will be assumed. (Default: None).

handle_inputs()[source]

Run the handlers of all inputs to ensure they are ready for simulation.

input_value_by_name(input_name, input_value)[source]

Set the value of an input given the input name.

Parameters:

  • input_name – Text for the name of the input to be set. For example, ‘radiance-parameters’.

  • input_value – The value to which the input will be set. Note that setting a value will ensure it is passed through any of the input’s handlers and cast to an appropriate data type.

luigi_execution_summary(project_folder=None)[source]

Get a string of the luigi execution summary after the recipe has run.

Parameters:

project_folder – The full path to the project folder containing completed recipe logs. If None, the default_project_folder on this recipe will be assumed. (Default: None).

output_value_by_name(output_name, project_folder=None)[source]

Set the value of an input given the input name.

Parameters:

  • output_name – Text for the name of the output to be obtained.

  • project_folder – The full path to the project folder containing completed recipe results. If None, the default_project_folder on this recipe will be assumed. (Default: None).

run(settings=None, radiance_check=False, openstudio_check=False, energyplus_check=False, queenbee_path=None, silent=False, debug_folder=None)[source]

Run the recipe using the queenbee local run command.

Parameters:

  • settings – An optional RecipeSettings object or RecipeSettings string to dictate the settings of the recipe run (eg. the number of workers or the project folder). If None, default settings will be assumed. (Default: None).

  • radiance_check – Boolean to note whether the installed version of Radiance should be checked before executing the recipe. If there is no compatible version installed, an exception will be raised with a clear error message. (Default: False).

  • openstudio_check – Boolean to note whether the installed version of OpenStudio should be checked before executing the recipe. If there is no compatible version installed, an exception will be raised with a clear error message. (Default: False).

  • energyplus_check – Boolean to note whether the installed version of EnergyPlus should be checked before executing the recipe. If there is no compatible version installed, an exception will be raised with a clear error message. (Default: False).

  • queenbee_path – Optional path to the queenbee executable. If None, the queenbee within the ladybug_tools Python folder will be used. Setting this to just ‘queenbee’ will use the system Python.

  • silent – Boolean to note whether the recipe should be run silently on Windows (True) or with a command window (False). (Default: False).

  • debug_folder – An optional path to a debug folder. If debug folder is provided all the steps of the simulation will be executed inside the debug folder which can be used for further inspection. Note that this argument here will override the debug folder specified in the settings. (Default: None).

Returns:

Path to the project folder containing the recipe results.

write_inputs_json(project_folder=None, indent=4, cpu_count=None)[source]

Write the inputs.json file that gets passed to queenbee luigi.

Note that running this method will automatically handle all of the inputs.

Parameters:

  • project_folder – The full path to where the inputs json file will be written. If None, the default_project_folder on this recipe will be used.

  • indent – The indent at which the JSON will be written (Default: 4).

  • cpu_count – An optional integer to override any inputs that are named “cpu-count”. This can be used to coordinate such recipe inputs with the number of workers specified in recipe settings. If None, no overriding will happen. (Default: None).

MODEL_EXTENSIONS = ('.hbjson', '.hbpkl', '.dfjson', '.dfpkl', '.json', '.pkl')
property default_project_folder

Get or set the directory in which the recipe’s results will be written.

If unset, this will be a folder called unnamed_project within the user’s default simulation folder

property input_names

Get a tuple of text for the recipe’s input names.

property inputs

Get a tuple of RecipeInput objects for the recipe’s inputs.

property name

Get text for recipe name.

property output_names

Get a tuple of text for the recipe’s output names.

property outputs

Get a tuple of RecipeOutput objects for the recipe’s outputs.

property path

Get the path to the recipe’s folder.

This folder contains a package.json with metadata about the recipe as well as a run.py, which is used to execute the recipe.

property simulation_id

Get or set text for the simulation ID to use within the project folder.

If unset, this will be the same as the name of the recipe.

property tag

Get text for recipe tag (aka. its version number).

class lbt_recipes.recipe.RecipeInput(input_dict)[source]

Bases: _RecipeParameter

Object to represent and manage recipe inputs.

Parameters:

input_dict – Dictionary representation of an input, taken from the package.json and following the RecipeInterface schema.

Properties:

  • name

  • description

  • value

  • default_value

  • is_required

  • is_handled

  • handlers

  • is_path

handle_value()[source]

Run the handlers of this input to yield a correct input for simulation.

INPUT_TYPES = {'DAGArrayInput': <class 'tuple'>, 'DAGBooleanInput': <class 'bool'>, 'DAGFileInput': <class 'str'>, 'DAGFolderInput': <class 'str'>, 'DAGIntegerInput': <class 'int'>, 'DAGJSONObjectInput': <class 'dict'>, 'DAGNumberInput': <class 'float'>, 'DAGPathInput': <class 'str'>, 'DAGStringInput': <class 'str'>}
PATH_TYPES = ('DAGFileInput', 'DAGFolderInput', 'DAGPathInput')
property default_value

Get the default value for this input.

property description

Get text for the description.

property handlers

Get an array of handler functions for this object.

This will be None if the object has no alias or Grasshopper handler.

property is_handled

Get a boolean for whether this input is handled and is ready for simulation.

property is_path

Get a boolean noting whether this input is a file or folder path.

property is_required

Get a boolean for whether this input is required to run the recipe.

property name

Get text for the name.

property value

Get or set a value for this input.

This will be the default_value if it has not been specified. Note that setting a value will ensure it is passed through any of the handlers and cast to an appropriate data type.

class lbt_recipes.recipe.RecipeOutput(output_dict)[source]

Bases: _RecipeParameter

Object to represent and manage recipe outputs.

Parameters:

output_dict – Dictionary representation of an output, taken from the package.json and following the RecipeInterface schema.

Properties:

  • name

  • description

  • handlers

value(simulation_folder)[source]

Get the value of this output given the path to a simulation folder.

Parameters:

simulation_folder – The path to a simulation folder that has finished running. This is the path of a project folder joined with the simulation ID.

property description

Get text for the description.

property handlers

Get an array of handler functions for this object.

This will be None if the object has no alias or Grasshopper handler.

property name

Get text for the name.