> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ntop.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom Blocks
## Automation and Custom Blocks
Utilizing nTop's automation capabilities can significantly lower the time to create your designs. If you are working with a design you plan to implement across multiple parts, it is very easy to automate and package that workflow across those designs. The key concepts to consider when automating your process are utilizing custom blocks, list processing, and nTop Automate. In this course, we will focus on creating custom blocks (CBs) and list processing to repeat workflows across multiple nTop files and to run through iterations.
The process for using a custom block is as follows:
*A flow diagram of creating and importing a Custom Block*
A custom block is a whole notebook packaged into a single block for reuse in other notebooks. You can use it both for creating small, frequently used utilities and encapsulating entire workflows in a single block. This is one of the most powerful features of nTop because it enables you to package the work of a whole notebook to replay the entire step-by-step process recorded in that notebook quickly. You can then save the new custom block and reuse it in other files or share it with other nTop users.
Custom blocks are easy to make since they are defined similarly to a notebook, and use the same file format (\*.ntop). You can customize a notebook to perform a specific function or process. Custom blocks don't require inputs (like materials) to be a valid block. An Output is required for the notebook to register as a custom block. If there is no output, an alert will appear when you try to load it.
*An example of a Custom Block, **Extrude Flat CAD Face***
Custom blocks have a double line on their left side to indicate that they are CBs. You can open the block by right-clicking and then selecting the Open Block to view the packaged nTop workflow. Then, you can modify the block or further understand how the process works.
*You can open a Custom Block using the right-click menu*
### Benefits of Using Custom Blocks
* Readability: CBs are easier for a user to digest.
* Repeatability: If you use the same process multiple times, you can use a CB instead of repeating those steps.
* Controlling the areas a user can change: If you share a workflow, you may only want a colleague to change a few parameters. Using a CB will yield a gated view of a workflow.
### Overloads
Certain blocks in nTop have what is called an Overload, which means they have multiple input configurations and may have the option to return different Output types. Not every block function has an overload. If an overload exists, a chevron icon will appear next to the block's name. Clicking this icon will open a drop-down menu that contains the block's overloads to choose from.
For example, the **Add** block has several overload configurations to choose from for both *Operand A* and *Operand B* inputs. The gif below demonstrates selecting different overloads for the **Add** block.
*The **Add** block has many available overloads depending on the block types you want to add together*
A custom block can have one or multiple overloads, which will let you switch between different forms of the block. You can do this by ensuring all relevant CBs have the same notebook name before importing them.
*An example of a CB with overloads*
In the example below, notice how the CB's name is the same, but one block has the option to specify a *Random Seed* input. This is the benefit of creating an Overload.
*A comparison of the two CBs with the same name. One of them has an additional input which creates the overload*
**Note:** In the upcoming sections, we will explain how to create your own Custom Block and Overloads.
### Creating a Custom Block
The process overview for creating a CB is shown below. First, create the nTop workflow as you normally would. We recommend saving this workflow before you create your CB, because once you begin to create the CB, you may be altering the workflow.
*A flow chart for creating a CB*
Once you have created your workflow, there are four key areas to create the CB: the notebook name, the description, the inputs section, and the output section.
*An example CB with labeled components of the nTop Notebook*
#### Notebook Title and Description
The name and description of the custom block are taken directly from the notebook's name and description. We recommend naming your custom block based on its functionality and purpose. We also recommend writing a description to help you or your colleagues understand what the CB does.
*A CB's Name and Description are used when a CB is imported into a Notebook. They are populated under the Information tab in the Right Panel*
#### Defining Inputs
To define the parameters of the CB, we need to place those variables in the Inputs section of the notebook.
1. Identify the parameters that you want to define as inputs for the CB.
2. Turn those parameters into named variables (Right-click -> select Make Variable, or *Ctrl+M*).
3. Move those named variables into the Inputs section of your notebook (drag and drop, or right-click -> select Make Notebook Input).
*You can convert a variable into an input by dragging it into the Inputs section, or by using the right-click menu*
##### Block Type
Before importing your CB into another notebook, you could change the block type of your inputs. For instance, *Spatial Weighting* is a scalar variable in the example below. However, if you intend to have varying spatial weighting and uniform values, you must change the block type to a scalar field. To do this, click the chevron icon and change it to the desired block type. Once you export this notebook, you will not be able to change that type, so we recommend changing the variable type to the broadest option.
*You can change an Inputs block type by clicking the chevron next to the block icon*
##### Commenting
The custom block input name and descriptions will be taken from the notebook's input name and description. Before exporting, we also recommend adding comments to your inputs. This will help others understand key information regarding those inputs in your CB, whether that is a longer description of the input or a recommended range of values for that input. To add a comment, right-click the variable and select “Add Comment”.
*We recommend adding comments to your inputs to help explain their function*
Once you import the CB to another notebook, input comments will become the block's input descriptions. You can see the input descriptions in the block's Information tab.
*Adding a comment to your CB input will utilize the comment as an input description*
#### Defining an Output
The other key area when creating a CB is the Output. Any notebook with a defined output can be repackaged into a single, customized block, complete with custom inputs and descriptions. To add an output, simply drag the block into the Output section of the notebook.
*Drag and drop your desired output block into the Output section of the Notebook*
#### Creating a Custom Block Overload
1. Create a valid custom block. For this example, we will use **Extrude Flat CAD Face**.
*An example CB*
2. Open the folder where the file is saved. Copy and paste the file in the same folder
*Copy and paste the CB in the same folder as the original*
3. Open the copy of the custom block, make the change you would like for the overload function, and save it. For this example, we are adding the *Random Seed* input.
*The same CB as the previous steps, but with an added input for Random Seed*
4. Your custom block is now set up for an Overload. To test that it functions correctly, you will need to import both versions of the block and verify that the chevron icon appears next to the block's name. The gif below shows our new CB with a working Overload.
**Note:** The next section will teach you how to import custom blocks so that you can test it yourself.
*Importing both versions of the CB allows you to use the Overload*
### Importing a Custom Block
Once you have created a custom block, the next step is to implement it in another workflow in a separate nTop file. There are a few ways to import a CB into your notebook:
* Importing the CB by going to the nTop menu icon → File → Import or use the shortcut *Ctrl+I* and selecting the corresponding nTop file
* Saving the CB in My Blocks Folder
* Open the Left Panel → Select the Import tab → Import Block
Some of these import methods are described in further detail below.
#### My Blocks Folder
If you use a CB frequently, we recommend saving it in your My blocks folder as shown below (file path blurred). The default folder is in the nTop folder under Myblocks.
Once the block is saved in this folder, it will automatically be imported into your notebooks and available for use. Simply search for the block in the search bar to add it to your workflow.
*The My blocks folder is located in the General tab of the nTop settings*
#### Import using the Left Panel
The last option to import a CB is to open the Left Panel, select the Imports tab, and click “Import Block” to select the corresponding nTop file. All imported files will be listed under the Custom Blocks section of the Imports tab. If you have multiple variations of the same custom block imported, the block version will be labeled next to the block name.
*Opening the Left Panel allows you to import blocks using the Imports tab*
#### Using Imported Custom Blocks
Once you import the CB, you can add it to the notebook by searching for its name in the search bar.
When imported, the CB will appear as a single block in the body of the notebook.
*Imported CBs will appear in the Search Bar results*
#### Deleting Unused Blocks
We recommend deleting unused custom blocks to decrease file size, improve opening speed, and maintain organization.
You can only delete imported blocks from the Left Panel that are unused in the notebook. You can also click the “Remove Unused Blocks” to remove all the unused imported CBs. Blocks appearing at least once in a workflow are marked with a notebook icon in the Imports tab, like in the example below.
*Imported blocks that have the highlighted icon next to them are* *actively in the notebook*
## Lists
All blocks in nTop can exist as singular entities or as a list. A list contains multiple items of the same type in a single block, like a list of points. When a process runs on a list block, it runs the process on every list item. Working with list blocks is called List Processing.
You can differentiate between a single block and a list block by a few block indicators.
* The block name will have a quantity shown next to it in parentheses. Even if a block name has (1) next to it, it still is a list with one item.
* A small icon of 3 stacked horizontal bars will appear next to the block type icon.
**A singular* ***Point*** *block compared to a* ***Point List*** *to show the list indicators**
### List Properties
Each list contains a set of List properties at the top and individual properties for each item within that list grouped under List Elements. You can drag an individual property from a List to create an item in the notebook. You can expand the dropdown arrow next to the individual entities to reveal more information on that individual list entity.
*An example Properties panel of an* ***Implicit Body List*** *of 3 bodies*
### List Processing
When applicable, blocks can accept list inputs instead of singular inputs. The block will then become a listed block of the same length as the input list. We refer to this as list processing. List processing can be helpful for:
* Testing multiple input options for the same process (e.g. multiple unit cell options for a lattice)
* Saving calculation time by processing multiple bodies
* Reducing notebook clutter by condensing a repetitive process
The gif below is an example of list processing. The example starts with an **Implicit Body List** of 3 different bodies. The bodies start by being stacked on top of each other. The list of bodies is then placed in the *Object* input of the **Translate Object** block. You can see how the **Translate Object** block converts to a list when the input is populated with a list. A **Vector List** is then inserted into the *Vector* input. The **Translate Object** block then computes by spacing out the individual list items using the vector values of the **Vector List**.
*An example of using List Processing with the **Translate Object** block*
List elements are mapped 1 to 1 based on their list index number. Using the example above, this means that the Box (index 0) uses the \[0,0,0] vector because it is index 0 of the **Vector List**. This means that list order is important when using blocks for list processing.
### List Manipulation
Regardless of block type, the method for modifying lists is the same. Select the '+' next to the View Block Details icon to add more inputs. If you add too many, use the '-' on the left of the input to remove them.
*You can add additional list items using the plus sign and remove items using the minus sign*
Lists can be powerful for automating workflows. The manipulation tools are in the Utilities Ribbon Tab, under General. Next, we will cover some of these blocks that are used to manipulate lists.
#### List Element
Extract a single entity from a list based on its index number. Note that the first item in a list is always index 0.
*The **List Element** block isolates items of a list based on the index number of the item*
#### Insert
Combine two lists into one by inserting a list into another at a specified index location.
*The **Torus** becomes the first item in the list using the **Insert** block*
#### Sub List
Extract a smaller list from a larger input list, based on a starting index and the desired size of the sublist.
*Using the **Sub List** block to extract a portion of a list*
#### Remove
Remove one or more entities from a list, based on a starting index and the number of removed entities.
*Removes items from a list based on a specified Index and Range Length*
#### Concatenate List
Multiple lists can be added together using the **Concatenate Lists** block. In order to do this, the Lists must be of the same type.
*Using **Concatenate List** to combine two **Implicit Body List** blocks into a single list*
#### Sort
The **Sort** block will rearrange a list from the lowest to the highest value. If you would like the values sorted from highest to lowest, you can use the 'reversed' scalar list in the block's properties.
*An example of using the **Sort** block to create an ordered list*
#### Filter
The **Filter** block removes items from a list based on a Bool List, which must be the same length as the List input in the block.
*An example of using the **Filter** block to isolate list items based on a condition*
#### Group
Groups in nTop are the same as lists, except they can contain a combination of block types. For example, the group below consists of a point, a sphere, and a line. The same list manipulation operations described can be performed on groups.
*A **Group** list containing 3 different block types*
### List Errors
When working with lists, it is important to understand the key errors that could occur, including invalid input errors and lists within lists, described below.
#### Invalid Input Error
If you try to insert a block into an input and nTop won't let you, the block is not a valid input. If you insert a variable into an input and it turns red, the block is not a valid input.
Causes:
1. Inserting a list into a singular type input
2. Inserting an incorrect block type list
3. Inserting a list into a list
Solutions:
1. The block that you are trying to insert a list into may have a block overload that accepts list inputs. Check if the block has overloads available that may accept your list.
*Changing the **Greater Than** block type to a list allows it to accept the **Scalar List***
2. The block type of your list needs to match the input block type. If you are getting an error due to mismatching types, you may need to convert your list to a different block type. You can also check if there is a block overload to accept that input type.
3. A list block cannot be input into another list block. If you want to input a list into a block that doesn't accept lists, you can create a custom block to run the list instead. This works because the inputs of a notebook are in variables, and variables cannot process lists.
However, once you use it as a CB, it's a block like any other and, therefore, can process lists. This is not equivalent to putting the list into the input, but rather running the custom block workflow multiple times, once for each element in the list. We will cover this in more detail later in the lesson.
Another way to solve this problem is to use **Concatenate Lists** to combine the two lists. Depending on the list type, you may also want to use **Merge Meshes**, **Merge Lattices**, **Merge Profiles**, etc.
#### Lists of One (1)
You may encounter a situation where you try to add one part to a block, and it won't let you. If your intended input block looks like “Block Name (1)“, somewhere a “list of one” was created. Lists of one are sometimes unintentionally created by the user or during CAD/Part importing.
Causes:
1. Accidentally converting a block to a list using a list input
2. Extracting a list from a block properties panel when you meant to extract a singular element
*Despite being a single **Sphere**, the block is a list due to the **Point List** in the Center Point input*
Solutions:
1. Change the input type from a list to a single entity. Once you input the singular entity instead of the list, the block parent block should also update.
*Changing the **Point List** to a singular **Point** removes the list property from the **Sphere***
2. Extract the singular list item from the List Elements section of the list's properties panel.
*You can extract the singular item from the List Elements section of the list's Properties panel*
#### Input List Length Mismatch
This occurs when two lists of different lengths are input into a block. The block can't run because it tries to match the two lists together.
Cause: The lengths of the input lists are not equal.
Solution: Ensure that the list length of both operands is the same.
*Most blocks require lists to be of equal length to compute*
### List Processing Custom Blocks
Now that we've learned how to create custom blocks and how lists work, we can combine these to use list processing in our CBs.
#### List Processing Inputs
List processing custom block inputs is the same as list processing. Below is an example of a CB that is set up to lattice an input body with a defined cell size and unit cell type. It's important to note that the inputs are not list types. If you try to make a custom block input a list, you will get an error message when you import the block. The error will inform you that it is not a valid block.
*An example CB that we will use for List Processing*
The gif below shows list processing with this CB. Each of the required inputs are lists of equal length that can be inserted into the CB inputs. The result is 3 different lattice configurations of different cell size and unit cell type.
*Using lists an inputs for **LP Lattice**, the block generates three different lattice structures*
#### List Processing Outputs
List processing custom block outputs requires us to use the **Group** block. Since **Groups** are just lists that can have multiple block types, we can use them to output different bodies, values, etc.
Here is another example of a custom block called Mesh Metrics. The gif below shows how we are setting up the **Group** block to output the merged implicit bodies, their mesh, and that mesh's face and vertex count.
*A **Group** can contain multiple block types and then be placed in the Output section*
Now we can perform a test run to see how to extract the multiple block outputs. The gif below shows the block executing **Mesh Metrics** using the two input cubes. The elements of the **Group** are then extracted from the properties panel and placed in the notebook as variables. **Group** elements are always the Any block type, so once they are converted to variables we can change them to their appropriate block types. Once the block type is changed, we can see the geometry results in the viewport, and the scalar results in their properties panels'.
*The **Group** elements can be extracted from the Properties panel*
## What to Take Away
* Custom blocks can make repetitive processes more efficient. Making a custom block of your design process can help you save time and organize your notebook.
* Lists are a powerful tool, but they can be finicky. Being aware of the quirks that come with using lists ensures users are able to troubleshoot their workflows quickly and identify potential downstream issues.
* List processing allows you to batch process blocks. This provides a similar efficiency to custom blocks. Combining them keeps your notebook incredibly organized and efficient.
## What's Next
You now have an understanding of how Custom Blocks and Lists work in nTop.
The next lesson introduces you to nTop Automate, nTop's Command Line interface. Then you will learn how to set up your notebook to run in nTop Automate.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.