Welcome to the Py-Engineering tutorials. These instructions will get you up and running in no-time. More in depth information about each subject can be found in the Documentation. Ready to start, but no Py-Engineering account yet? Request a demo!

Tutorial A: Basic example

We’ll start this example covering the basic concept of a tool in Py-Engineering.com. In this basic example we will, step by step, create a simple tool to calculate the length of the sides of a triangle using the Pythagoras theorem.

Step 1: Add tool

This can be done in the platform menu directly or by clicking ‘add tool’ in Platform ‣ Tools.

The least you have to provide is a name and a slug. The name will appear as title of your tool. Slug has to be unique and defines the URL that can be used to access the tool. In this example, we’ll name our tool Pythagoras.

Go to Platform ‣ Tools ‣ Add tool

Step 2: Main script

A tool on Py-Engineering takes user input and runs a python function to print and/or return some output. Say we want to use side A and B of a right triangle to determine the length of the side C, opposite the right angle with the Pythagorean theorem. We need to write a very basic python function like this:

import math


    def main_function(input_dict):

    a = input_dict['a']
    b = input_dict['b']
    c = math.sqrt(a ** 2 + b ** 2)

    print(f'a = {a}')
    print(f'b = {b}')print(f'c = {c:.1f}')

    return {'c': c}

You’re free to define the python script with many other functions or classes, but the function that runs by clicking ‘Calculate’ has to be called main_function and takes a dictionary called input_dict as argument. Everything printed by the python script will show up in the results tab of the tool.

Step 3: Input parameters and graphical user interface

All keys as expected to be present in the input_dict have to be defined as input parameters. The least you have to provide is a code which corresponds to the key in the input_dict as used in the python function. In this example, that’s a and b. The parameter can also have a name and/or a unit. Input_type is an integer in this example and determines the type of the value in the input_dict.

Step 4: Info tab

By now, the tool is ready to be used. Just to provide the user some background information, we’ll add an extra tab that will appear in the GUI next to the ‘Results’ tab. These so called info tabs can be defined using HTML. The first tab, based on order will be visible by default. We’ll use the following html for a tab called ‘Info’.

Go to Platform ‣ Info tabs ‣ Add info tab

<p>
In mathematics, the Pythagorean theorem, also known as Pythagoras' theorem,
is a fundamental relation in Euclidean geometry among the three sides of a right triangle.
</p>

<img class="img-fluid" style="display: block; margin-left: auto; margin-right: auto;" src="https://pye-fileserver.s3.eu-central-1.amazonaws.com/media/public/images/pythagoras_AgL1OaF.png" alt="Pythagoras" width="262" height="131" />

<p>
It states that the square of the hypotenuse (the side opposite the right angle)
is equal to the sum of the squares of the other two sides. The theorem can be written
as an equation relating the lengths of the sides A, B and C, often called the "
Pythagorean equation" where C represents the length of the hypotenuse and A and B
the lengths of the triangle's other two sides.
</p>

Step 5: Result

Fill the form and click ‘Calculate’ in the embedded tool below or click here to view the tool on Py-Engineering.com.

Tutorial B: Input types

This example uses a copy of the basic tool as created in . Here we’ll explore more input types and their behavior in the GUI.

Step 1: Integer (slider)

By default, an input variable is defined as input type integer. In the GUI, a html input element for numbers will be available. If lower and upper bounds for the parameter are defined, the input type can also be a slider. In the block input parameters and graphical user interface, select integer (slider) from the input type dropdown.

Step 2: Boolean

Input type boolean can be used in the input dictionary with python values True or False. It appears in the GUI as a checkbox. Say, we want to optionally calculate the angles of the triangle. The user can check ‘Show angles’ before clicking ‘Calculate’.

In the block Main script, the python script is extended with an if statement to optionally print the angles in degrees

import math


def main_function(input_dict):

    a = input_dict['a']
    b = input_dict['b']
    c = math.sqrt(a ** 2 + b ** 2)

    print(f'a = {a}')
    print(f'b = {b}')
    print(f'c = {c:.1f}')

    angle_ac = math.atan(b / a) * (180 / math.pi)
    angle_bc = math.atan(a / b) * (180 / math.pi)

    if input_dict['calculate_angles']:
        print(f'Angle AC = {angle_ac:.1f} degrees')
        print(f'Angle BC = {angle_bc:.1f} degrees')

    return {'c': c}

Step 3: Result

Fill the form and click ‘Calculate’ in the embedded tool below or click here.

Tutorial C: Input list

Form elements that use a set of options like radio buttons and dropdowns can be created using Input lists. In this tutorial, we create a tool that includes a radio button with two options.

Step 1: Main script

Like in , a python function defines the tool. In this case we take the variables shape, r and h and calculate the surface area of either a cone or a cylinder.

import math

def main_function(input_dict):

    shape = input_dict['shape']
    r = input_dict['r']
    h = input_dict['h']

    if shape == 'cone':
        a = math.pi * r * (r + math.sqrt(r ** 2 + h ** 2))
    if shape == 'cylinder':
        a = 2 * math.pi * r * (r + h)

    print(f"The surface area of a {shape} = {a:.1f}")

    return

Step 2: Info tab

An info tab containing a HTML table shows the user the difference between a cone and a cylinder with their attributes and formula to calculate the surface area.

<table class="table">
	<thead>
		<tr>
			<th>Shape</th>
			<th>Formula</th>
			<th>Variables</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>Cylinder<br>(incl. bottom and top)</td>
			<td><i>A = 2&pi;r(r+h)</i></td>
			<td>
				<a title="Ag2gaeh, CC BY-SA 4.0 <https://creativecommons.org/licenses/by-sa/4.0>, via Wikimedia Commons" href="https://commons.wikimedia.org/wiki/File:Zylinder-1-tab.svg"><img width="128" alt="Zylinder-1-tab" src="https://upload.wikimedia.org/wikipedia/commons/thumb/8/81/Zylinder-1-tab.svg/128px-Zylinder-1-tab.svg.png"></a>
			</td>
		</tr>
		<tr>
			<td>Cone<br>(incl. bottom)</td>
			<td><i>A = &pi;r(r+&radic;(r<sup>2</sup>+h<sup>2</sup>))</i></td>
			<td>
				<a title="Ag2gaeh, CC BY-SA 4.0 <https://creativecommons.org/licenses/by-sa/4.0>, via Wikimedia Commons" href="https://commons.wikimedia.org/wiki/File:Kegel-1-tab.svg"><img width="128" alt="Kegel-1-tab" src="https://upload.wikimedia.org/wikipedia/commons/thumb/8/8e/Kegel-1-tab.svg/128px-Kegel-1-tab.svg.png"></a>
			</td>
		</tr>
	</tbody>
</table>

Step 3: Input parameters and graphical user interface

The arguments r, h and shape that are used in the python function need to be defined as input variables. For shape, well select input type radio.

Step 4: Input list

At this point, the form element for shape only shows the label ‘Shape’. We want to provide the user two radiobuttons which will set the value of shape either to ‘cone’ or ‘cylinder’. This can be achieved by adding an input list.

In this case we limit the input list to one level which basically means it’s a list of options. These options can be provided in a JSON script as shown below. The JSON object should include a list with the name ‘choices’. The list itself contains objects with at least the names ‘id’ and ‘name’. ‘id’ is the actual value provided in the input dictionary. Name is the name used in the form element.

{
  "choices": [
    {
      "id": "cylinder",
      "name": "Cylinder"
    },
    {
      "id": "cone",
      "name": "Cone"
    }
  ]
}

Result

Fill the form and click ‘Calculate’ in the embedded tool below or click here .

Tutorial D: Input related actions

This tutorial takes a copy of where we add the option ‘Cuboid’ to the input list ‘shapes’.

Step 1: Main script

We’ll modify the script so that the surface area of a cuboid is shown if that shape is selected.

import math

def main_function(input_dict):

    shape = input_dict['shape']
    r = input_dict.get('r', 0)
    h = input_dict.get('h', 0)
    a = input_dict.get('a', 0)
    b = input_dict.get('b', 0)
    c = input_dict.get('c', 0)

    if shape == 'sphere':
        area = 4 * math.pi * r ** 2
    if shape == 'cuboid':
        area = 2 * (a*b + a*c + b*c)
    if shape == 'cone':
        area = math.pi * r * (r + math.sqrt(r ** 2 + h ** 2))
    if shape == 'cylinder':
        area = 2 * math.pi * r * (r + h)

    print(f"The surface area of a {shape} = {area:.1f} mm_sup[2_sup]")

    return

Step 2: Input parameters and graphical user interface

As the main script shows: We might have a, b, and c in the input dictionary. Therefore, we need to define it as input variables. In this case integers with the label ‘Side’, abbreviation a, b and c and unit mm.

Step 2: Input list

Since shape can now also have the value ‘cuboid’, we need to add this option to the input list.

{
  "choices": [
    {
      "id": "cuboid",
      "name": "Cuboid"
    },
    {
      "id": "cylinder",
      "name": "Cylinder"
    },
    {
      "id": "cone",
      "name": "Cone"
    }
  ]
}

Step 3: Info tab

An extra row in the HTML table in the info tab shows the user the different shapes with their formula for the surface area

<table class="table table-responsive">
<thead>
<tr>
<th>Shape</th>
<th>Formula</th>
<th>Variables</th>
</tr>
</thead>
<tbody>
<td>Cuboid</td>
<td><i>A = 2(ab + ac + bc)</i></td>
<td>
<a title="Ag2gaeh, CC BY-SA 4.0 &lt;https://creativecommons.org/licenses/by-sa/4.0&gt;, via Wikimedia Commons" href="https://commons.wikimedia.org/wiki/File:Quader-1-tab.svg"><img width="88" alt="Quader-1-tab" src="https://upload.wikimedia.org/wikipedia/commons/thumb/7/7f/Quader-1-tab.svg/128px-Quader-1-tab.svg.png"></a>
</td>
</tr>
<tr>
<td>Cylinder<br>(incl. bottom and top)</td>
<td><i>A = 2&pi;r(r+h)</i></td>
<td>
<a title="Ag2gaeh, CC BY-SA 4.0 &lt;https://creativecommons.org/licenses/by-sa/4.0&gt;, via Wikimedia Commons" href="https://commons.wikimedia.org/wiki/File:Zylinder-1-tab.svg"><img width="88" alt="Zylinder-1-tab" src="https://upload.wikimedia.org/wikipedia/commons/thumb/8/81/Zylinder-1-tab.svg/128px-Zylinder-1-tab.svg.png"></a>
</td>
</tr>
<tr>
<td>Cone<br>(incl. bottom)</td>
<td><i>A = &pi;r(r+&radic;(r<sup>2</sup>+h<sup>2</sup>))</i></td>
<td>
<a title="Ag2gaeh, CC BY-SA 4.0 &lt;https://creativecommons.org/licenses/by-sa/4.0&gt;, via Wikimedia Commons" href="https://commons.wikimedia.org/wiki/File:Kegel-1-tab.svg"><img width="88" alt="Kegel-1-tab" src="https://upload.wikimedia.org/wikipedia/commons/thumb/8/8e/Kegel-1-tab.svg/128px-Kegel-1-tab.svg.png"></a>
</td>
</tr>
</tbody>
</table>

Step 4: Input related actions

At this stage, the tool actually works. It’s just not convenient that the user self has te decide if the parameters r and h need to be provided or a, b and c, depending on the selected shape. This is were input related actions come in very handy. Basically, it’s an if .. then statement, triggered by the change on a certain form element. In this case: If shape is cone, show a, b and c else show r and h. This is done in 5 rules. One rule for each affected input parameter.

Result

Fill the form and click ‘Calculate’ in the embedded tool below or click here .

Tutorial E: Show image from selection

We take a copy of . The goal of this tutorial is to add an image of the selected shape above the input field. This is done in two steps:

Step 1: Input list

To provide the actual image, we provide an extra name/value pair in the JSON data of the input list. The name is URL and the value is the link to the actual image.

{
  "choices": [
    {
      "id": "cuboid",
      "url": "https://upload.wikimedia.org/wikipedia/commons/7/7f/Quader-1-tab.svg",
      "name": "Cuboid"
    },
    {
      "id": "cylinder",
      "url": "https://upload.wikimedia.org/wikipedia/commons/8/81/Zylinder-1-tab.svg",
      "name": "Cylinder"
    },
    {
      "id": "cone",
      "url": "https://upload.wikimedia.org/wikipedia/commons/8/8e/Kegel-1-tab.svg",
      "name": "Cone"
    }
  ]
}

Step 2: Input parameters and graphical user interface

To actually show the image as provided in the input list, edit the lay-out of the input element above which the image must be shown. In this case, that is the selection of shape. Instead of the raio select button, we change the input type to ‘Select (1st level)’ so it becomes a dropdown.

Result

Fill the form and click ‘Calculate’ in the embedded tool.

Tutorial F: Input validation

For this tutorial, we create a new tool to calculate the maximum deflection of a simply supported beam. The goal is to get familiar with the different levels of input validation.

Step 1: Main script

The python function that calculates the max deflection at a certain distance x, takes force (F), length (L), stiffness (EI) and distance from the load to the closest support (a).

import math


def main_function(input_dict):

    F = input_dict.get('F')
    L = input_dict.get('L')
    EI = input_dict.get('EI')
    a = input_dict.get('a')

    u_max = (F * a * (L ** 2 - a ** 2) ** (3/2)) / (9 * math.sqrt(3) * L * EI )
    x = math.sqrt((L ** 2 - a ** 2) / 3)

    print(f"u_max = {u_max:.2f} mm")
    print(f"x = {x:.2f} m")

    return

Step 2: Input parameters and graphical user interface

The input for F, L, EI and a are defined as shown below.

By default, required is True. This is the first level of input validation. If an input element is required, but not filled, the input element is colored red and there will no python code be executed before the user provides valid input.

Step 3: Validation script

A more complex validation can be achieved using a validation script. Like the main script, this is a Python function. It takes the same argument (input_dict). If it returns something or prints something, the input is considered invalid. The keys from the input_dict can be used as keys in the return value to show specific text on the invalid form element.

In our main script, a is the distance of the force to the closest support. Therefore, it can never be more than half the length of the beam, L. See the validation script below:

def validate_input(input_dict):
    if input_dict.get('a') >= input_dict.get('L'):
        return {'a': f"Make sure a is smaller then L (< {input_dict.get('L')} m)"}

In case of invalid provided input as shown in the image below, the validation script runs, but the main script will not run until valid input is provided.

Result

Fill the form and click ‘Calculate’ in the embedded tool below or click here.

Tutorial G: Input layout

Result

Fill the form and click ‘Calculate’ in the embedded tool below or click here.

Tutorial H: Upload and use files

import pandas as pandas


def main_function(input_dict):

    pandas.set_option('display.max_rows', None)
    df = pandas.read_csv('population-and-demography.csv')
    df = df.rename(columns={'Country name': 'Continent'})
    df = df[df['Continent'].isin(input_dict.get('continents'))]
    df = df.pivot(index='Year', columns='Continent', values='Population')

    print(df)

    return

Result

Fill the form and click ‘Calculate’ in the embedded tool below or click here .

Tutorial I: HTML output

import pandas


def main_function(input_dict):

    pandas.set_option('display.max_rows', None)
    df = pandas.read_csv('population-and-demography.csv')
    df = df.rename(columns={'Country name': 'Continent'})
    df = df[df['Continent'].isin(input_dict.get('continents'))]

    df = df.pivot(index='Year', columns='Continent', values='Population')

    print(df.to_html(classes="table table-hover table-responsive table-sm"))

    return

Result

Fill the form and click ‘Calculate’ in the embedded tool below or click here .

Tutorial J: PDF output

\documentclass{article}
\usepackage{graphicx} % includegraphics command is implemented here
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{lmodern}
\usepackage{textcomp}
\usepackage{lastpage}
\usepackage{tikz}

\begin{document}
\normalsize
\section{Pythagoras}

In mathematics, the Pythagorean theorem, also known as Pythagoras' theorem, is a fundamental relation in Euclidean geometry among the three sides of a right triangle.
It states that the square of the hypotenuse (the side opposite the right angle) is equal to the sum of the squares of the other two sides. The theorem can be written as an equation relating the lengths of the sides $a$, $b$ and $c$, often called the "Pythagorean equation":

$$a^2+b^2=c^2,$$

where $c$ represents the length of the hypotenuse and $a$ and $b$ the lengths of the triangle's other two sides.

\label{sec:Pythagoras}

\begin{tikzpicture}
\draw (0,0)
-- (\VAR{b}/2, 0) node[anchor=north]{$b$=\VAR{b}}
-- (\VAR{b}, 0)
-- (\VAR{b}/2, \VAR{a}/2) node[anchor=south west]{$c$=\VAR{c}}
-- (0, \VAR{a})
-- (0, \VAR{a}/2) node[anchor=east]{$a$=\VAR{a}}
-- cycle;
\end{tikzpicture}

\begin{tabular}{r|l|l}
\hline
\hline
a&\VAR{a}&$m$\\
b&\VAR{b}&$m$\\
\hline
c&\VAR{c}&$m$\\
\hline
\end{tabular}

\end{document}

Result

Fill the form and click ‘Calculate’ in the embedded tool below or click here.

Tutorial K: XLSX output

import pandas


def main_function(input_dict):

    pandas.set_option('display.max_rows', None)
    df = pandas.read_csv('population-and-demography.csv')
    df = df.rename(columns={'Country name': 'Continent'})
    df = df[df['Continent'].isin(input_dict.get('continents'))]

    df = df.pivot(index='Year', columns='Continent', values='Population')

    print(df.to_html(classes="table table-hover table-responsive table-sm"))

    return

Result

Fill the form and click ‘Calculate’ in the embedded tool below or click here .

Tutorial L: Image output

import pandas as pandas
import plotly.express as px


def main_function(input_dict):

    df = pandas.read_csv('population-and-demography.csv')
    df = df.rename(columns={'Country name': 'Continent'})
    df = df[df['Continent'].isin(input_dict.get('continents'))]

    fig = px.line(df, x="Year", y="Population", color="Continent")
    fig.write_image('population.png')
    print('_img[population.png]')

    df = df.pivot(index='Year', columns='Continent', values='Population')
    print(df)

    return

Result

Fill the form and click ‘Calculate’ in the embedded tool below or click here .