3.7.4 Report

The Report component enables the generation of table-style outputs that collects various results computed during model analysis. The output is typically an Excel file, or optionally multiple .csv files (WIP), with results thematically organized into tables or worksheets.

Inputs

• Model Accepts a calculated Karamba3D model as input. This is the model from which results will be extracted for reporting.

• Filepath (Path) Specifies the destination where the final report will be saved. By default, the report is written to the same directory where your Grasshopper script is stored, using the .xlsx file format. It is also possible to specify the file-path from the context menu of the component.

• Selection (Select) Defines which data or results to include in the report. More detailed information on available options is provided below. Default is the --help command - more info below.

• Write Now? (Write?) Triggers the execution of the report generation. This input typically uses a button or toggle to activate the process. Upon activation, the component processes the selections provided in the Select-input sequentially and writes the compiled report to the specified Filepath.

Outputs

• Info Describes the status of the retrieval process and provides details in case of any errors or issues encountered.

• Success (S) A boolean value indicating whether the report was created successfully.

Syntax

The syntax of commands follows the typical structure used in terminal or command-line tools. It is simple and consistent, and can be broken down into the following components:

command [option] [arguments]

Options modify the behavior of the command and can be used in two formats:

• Short form: Prefixed with a single dash (-), e.g., -id

• Long form: Prefixed with a double dash (--), e.g., --elementIds

beam-forces --elementIds beam_1, beam_2, ...
or
beam-forces -id beam_1, beam_2, ...

Both formats are functionally equivalent and can be used interchangeably.

If multiple [options] are available for a single command, they can be sequentially chained. Note that list items must always be comma-separated, and each command must be provided as a single, continuous line of text (string).

Use --help

The --help option is useful when you're unsure of what commands are available, or which arguments a specific command accepts. When --help is used as a standalone entry (e.g., in the Select input), it will list all available commands:

When used after a specific command, --help returns detailed information about that command’s structure, including all accepted options and arguments:

INPUT:

beam-disps --help

OUTPUT:

	Command Options:

  -i, --id          (Default: ) Comma separated element-ids -> e.g.:
                    beam1,beam2,beam3,...
  -l, --loadcase    Load-case selection.
  -p, --position    (Default: 0 0.5 1) Positions on the beam in normalized
                    coordinates.
  -n, --name        Name to identify generated data. e.g.: For Excel, creates a
                    new Worksheet with this name or default.
  --help            Display this help screen.
  --version         Display version information.

This is especially useful for understanding the expected syntax, available [options], and required inputs for a particular command.

Generally command-line options correspond to the input plugs of related Grasshopper-components. This allows for a seamless transition between the visual scripting interface and the command-driven workflow.

Below is a breakdown of options available in the example above: beam-disps

• -i, --id

  Defines the elements for which results should be extracted. This option expects a list of element identifiers (as defined during model creation), provided as a single string, with each ID separated by a comma.

  Copy

  beam-disps --id elem1,columns,shell_slab_1	

• -l, --loadcase

  Specifies the load case for which results should be retrieved. The format should match conventions used by the Model-View-component or outputs generated by the Result Selector-component.

  Copy

  beam-disps --loadcase SLS

• -p, --position

  Determines the number and location of sampling points along the beam’s length (in parametric space). By default, results are extracted at the start (0.0), midpoint (0.5), and end (1.0) of each beam.

  Copy

  beam-disps --position 0,0.25,0.5,0.75,1

• -n, --name

  Specifies a custom name for the results table or worksheet. By default, each command generates a table with a name based on its type. For example:

  Copy

  beam-disp → "Beam Displacements"

  While this naming convention is convenient, it can result in data being overwritten when the same command is run multiple times with different inputs.

  To prevent this, use the --name option to define a unique name for each output table:

  Copy

  beam-disp --name Displacements Column -id column
  beam-disp -n Displacements Girder -id girder

This is especially useful when comparing multiple scenarios or load cases in a single report.