CISC Cloud Solutions Tutorial

About

The CISC Cloud Solutions web application is the home for CISC design modules. These design modules provide engineers with reliable resources for a variety of structural engineering problems. There are numerous calculators ranging from simple design checks to complex analysis and design problems. Simple calculations (i.e., basic member design) follow CSA S16:24 and well-established design processes. There are also calculators for complex engineering problems that are not well-defined in the code. These design solutions are drafted by the CISC based on the most up-to-date research and reviewed by engineers across Canada. While many online structural calculators are available, CISC Cloud Solutions provides complex solutions that are typically only found in design guides or research papers.

The key to this web app is transparency. While the design modules offer a simple input/output user interface, all coded logic is contained in Python notebooks. These notebooks are downloadable from each design module, allowing users to carefully inspect the solution and make adjustments as needed for their unique situations. Users can also upload their own notebooks (see Creating Custom Modules) to use their own notebooks in web app form. However, for those who have no interest in reading Python code, the program also offers detailed calculation sheets showing the design process in full detail.

Getting Started

The home page presents all design modules available on CISC Cloud Solutions. These modules are grouped by category (i.e., member design, seismic, etc.) for ease of navigation. The footer of the page contains additional navigation buttons, such as:

1. Load File: Continue work on a problem you previously saved to your computer as a .cnxn file.
2. Custom Sections: Define custom sections (see Custom Sections) to work with structural shapes not defined in the CISC Structural Section Tables.
3. Select Units Dropdown: Define your unit system. Choose between SI Units and U.S. Customary Units.

CISC Cloud Solutions includes all section sizes and properties from the CISC Handbook of Steel Construction and its Structural Section Tables. The web app also provides the option to upload custom section sizes that are not available in the program. Custom section sizes can be added either one at a time (using the "Add Row" button) or in bulk (using the "Paste from Excel" button).

Selecting the "Custom Section Table" dropdown menu in the page header allows users to select which type of section they would like to define. It is possible to define the following section types:

1. Wide-Flange Sections: W or HP Shapes
2. Standard Beam Sections: M or S Shapes
3. Channel Sections: C or MC Shapes
4. Angle Sections: Equal or unequal legged L Shapes
5. Wide WT Sections: WT Shapes
6. Square/Rectangular Hollow Structural Sections: RHS Shapes
7. Circular/Round Hollow Structural Sections: CHS Shapes
8. Double Angle Sections: Equal or unequal legged 2L Shapes (back-to-back)

To save the custom sections, click the "Save" button. This saves the sections for the specific shape currently selected. If you want to add multiple shapes, you must press "Save" after updating each shape. To remove sections, press the "Delete" button for that row, or clear the entire table using the "Clear" button.

General

The Calculation Modules all have a similar layout. The page header contains an input field for the project name, the option to return to the home page, and the ability to save the connection. The "Save" feature downloads a .cnxn file to your computer containing all the inputs entered at the time of saving. The footer contains additional buttons. The "Calculate Results" button runs the analysis. The "Export Results" button runs the Python notebook and returns a calculation sheet, drawing file if applicable (for AutoCAD or other drafting software), and the completed Python notebook. Exporting results may take significant time depending on calculation complexity. The footer also includes the option to toggle unit magnitudes. This is limited to units supported by the system defined on the home page (i.e., SI or U.S. Customary).

Below is a summary of the key buttons on each module page:

1. Main Menu: Return to the home page
2. Save: Save a file to your computer with the entered inputs
3. Calculate Results: Populate or update the displayed results
4. Export Results: Update the displayed results and produce additional downloadable resources, including a Calculation Sheet, Drawing File, and Python Notebook
5. Select Units: Change the magnitude of the units (within the selected unit system)

Input Section

The left side of the Calculation Module (or the top on smaller screens) is for user inputs. These inputs should be entered in the magnitude of the units stated in the table header (which can be toggled in the page footer). While the inputs vary depending on the calculation page, there are some common types of inputs:

1. Section Sizes: The section size for a particular member can be selected using two dropdown menus. The first, under the "Size" header, specifies the section shape—this is also where you can select custom shapes. Only shapes supported by the calculation module will appear. After specifying the shape, there is a dropdown in the table body that allows you to select the section size.
2. Steel Grade: As with section sizes, common steel grades are built into the program and can be selected from the dropdown. For values outside these options, you may toggle the "Custom" checkbox in the header and enter custom F_y and F_u values (separated by a comma).
3. Dropdowns: There are other dropdowns that are not customizable. If you need to use a value outside what is offered, you will need to download and modify the Python notebook.
4. Dynamic Tables: Some tables allow you to add and remove rows. These tables include a "+ Add Row" button below them, and an "×" button beside each row to remove it. There is also the option to "Paste CSV Data" which will paste data from Excel given that the CSV table has the same amount of columns.

The bottom of the input page may contain extra information. This could include a static image defining variables, or buttons linking to other design modules that may be useful for completing the design problem.

Results

The results are displayed on the right side of the Calculation Module (or below the input section on smaller screens). Results are generated by either the "Calculate Results" or "Export Results" buttons. The results include the following:

1. Errors: Any issues that should be addressed before finalizing the design
2. Result Tables: Table(s) of results generated by the analysis, summarizing the critical findings
3. Images: A dropdown menu lets you toggle between images. Some of these images may be dynamic images (either 2D or 3D) that can be navigated using panning, scrolling, and zooming. The linework from these images is what is exported as a drawing file for AutoCAD or other drafting software.

Each design module is associated with a certain Jupyter notebook. These notebooks contain all the code required to run the design modules. These notebooks can be downloaded from the "Export Results" feature when you select the "Download Python Notebook" button. You can edit these notebooks to tailor them to your exact design needs using any Python notebook editor (i.e., Jupyter Lab or VS Code). To successfully run these notebooks, you will need to download the folder below.

Each time you download a notebook from a design module, you should add it to this folder on your machine so that they all have access to these supporting files. The following instructions will guide you through the process of preparing to run these notebooks in your local notebook editor. These instructions are also in the template.ipynb notebook.

Step 1: Set Up Kernel

Create a Python kernel for the notebook. The latest Python version (3.13) is not compatible with handcalcs, so you will need to set up a kernel using Python 3.12 using your machine's terminal (CMD). Follow the steps below:

1. Create a new virtual environment with Python 3.12:

   python3.12 -m venv handcalcs-env

2. Activate the environment:
   • Windows:

     handcalcs-env\Scripts\activate

   • macOS/Linux:

     source handcalcs-env/bin/activate

3. Install ipykernel:

   pip install ipykernel

4. Install the kernel for Jupyter:

   python -m ipykernel install --user --name handcalcs-env --display-name "Python 3.12"

Selecting the Kernel:

• In Jupyter Lab: Open your notebook, click the kernel name in the top-right corner, and choose Python 3.12 (handcalcs).
• In VS Code: Open your notebook, click the kernel picker, or press Ctrl+Shift+P and search for "Select Kernel". Choose Python 3.12 (handcalcs).

Verify the Setup:

import sys
print(f"Python version: {sys.version}")

Step 2: Import Packages

The first notebook cell should import all required libraries. If you have installed everything from requirements.txt, no further installations should be necessary. If not, you can install missing libraries using pip.

1. Install all packages in requirements.txt:

   !pip install -r requirements.txt

2. Example of installing a single package (if needed):

   !pip install pandas

Troubleshooting Import Errors:

1. Exit Jupyter Lab and close the terminal
2. Reopen the terminal and reactivate the environment
3. Launch Jupyter Lab using:

   jupyter lab

4. Reinstall packages:

   !pip install -r requirements.txt

5. Check installed packages:

   !pip list

6. Re-run the import packages cell

Step 3: Run the Notebook

When you run the notebook, you will almost certainly encounter errors. This is mainly due to missing images or logic added specifically for the web application. You can largely ignore these errors and comment out or delete the troublesome lines of code.

Alternatively, you can add the required folders and files to build out your own project directory and make it more thorough. This will help your code run smoother and help troubleshoot any notebooks you may want uploaded to the web app (see Creating Custom Modules).

Custom Notebooks

As discussed in the Python Notebooks section, you can create your own custom design modules by uploading your own Python notebooks. However, these notebooks must follow a specific format to work correctly in the web application. The following steps outline how to set up your notebook properly.

These steps are further highlighted in the template.ipynb file in a worked example.

Step 1: Set Up Parameters (User Inputs)

This cell defines all the parameters needed in the notebook. The formatting of this cell, including commented lines (#), is essential for correctly displaying input tables in the web app.

Table Formatting:

• ###=== Text here ===### defines table headers
• parameter_name = "value" # Column name !!Special command defines each input row

Special Commands:

• !!Note: Tooltip text displayed when hovering over ⓘ
• !!Dropdown: Creates dropdown menus (e.g., [...] or Member[...])
• !!Units: Defines the units (Distance, Force, Moment, UDL, Stress)
• !!Ignore: Hides columns from HTML output
• !!Default: Default option for an input cell
• !!Add_Rows: Makes a table dynamic (add/remove rows)
• !!Collapse: Collapses a table by default when the page is first opened

Add extra HTML content between \\\ tags to include images or links.

Unit Settings:

• unitsDropdown: Sets the unit system ((N, mm), (kN, m), (lbf, in), etc.)
• units_system: Either Metric or Imperial

Tagging the Cell:

• In JupyterLab: Click the gear icon → "Add Tag" → type parameters
• In VS Code: Right-click the cell → "Add Cell Tag" → type parameters

Step 2: Set Up Python Variables from User Inputs

Create a Python object from the user inputs to represent the section. This allows you to easily access geometric and material properties defined in the CISC Structural Sections tables.

F_y, F_u = get_Fy_Fu(beam_steel_param, units_system)
beam = get_member_object(member_type_1, beam_name, F_y, F_u, units_system)

You can access attributes like beam.A, beam.d, or beam.I_x, automatically displayed in the correct unit system.

Available Attributes: