For PDF version of manual see on-c-e.us
Appendix A – Example Model and Calc
Example Template / Model
[s] Example 0101 - basic model template
This example template calculates the mid-span beam moment
under uniformly distributed (UDL) floor loads. It demonstrates
section [s], term [t] equation [e] and [#] format operations.
reStructuredText inline markup is also used.
[d] beam.png | f | Simply supported beam | 70 |
[s] Beam Loads and geometry
Dead and live load contributions to beam UDL and beam layout
configuration
**Dead loads** from permanent weights
[t] joists | jst_DL = 3.8*PSF
[t] plywood | ply_DL = 2.1*PSF
[t] partitions | part_DL = 10.0*PSF
[t] fixed machinery | equip_DL = 0.5*KLF
**Live loads** from people and moveable items
[t] ASCE7-O5 | live_LL = 40*PSF
**Beam tributary width and span**
[t] distance between beams | trib_width = 2*FT
[t] beam span | span = 14*FT
[s] Maximum bending moment
Calculate factored UDL loads and bending moment at mid-span of beam
[e] 010122 | Total UDL factored dead load
DL_D = 1.4 * (trib_width *(jst_DL + ply_DL + part_DL) + equip_DL)
[e] 010122 | Total UDL factored live load
LL_D = 1.7 * trib_width * live_LL
[e] 010122 | factored UDL
omega_1 = DL_D + LL_D
[e] 010123 | Bending moment at mid-span
M_0 = omega_1 * span**2 / 8
[#] format | 3,3 | pdf
010122 | 2,2 | KLF | 2
010123 | 2,1 | KIP*FT | 3
[#] This file contains a generic on-c-e model template (the template).
[#] It is distributed under the CCO 1.0 Public Domain Dedication at
[#] www.creativecommons.org/publicdomain/zero/1.0/
[#] The template is not a structural design calculation and
[#] must be modified by the user prior to use.
[#] The template user assumes sole and complete responsibility for
[#] all existing or modified inputs and the computed model results.
UTF calc
UTF calc - continued
Appendix B – Operations
Calcs are composed of nine model operations: three operations are single lines with the tags [d], [o], [t], and six operations are multiline with tags [c], [a], [f], [e], [s], and [#] format. Project calcs are built with a multiline operation using the [p] and [#] format tags. All multiline operations are terminated with a blank line.
[d] (path)/filename | s,t,o,w,f,i,r,e | (v1) | (v2) | (v3)
The disk operation processes external disk files according to single letter options. Files for the first 5 options are located in the model folder and are specified by file name only. The model folder and name are used for the i operation. Full file paths are used for the r and e options. This approach makes a model as portable as possible across different folder organizations.
filename: file name used in disk operation. See details for each parameter type.
v1-v3: variables specific to the disk operation option. See details.
s: execute Python file in model. Typically used to process external functions.
t: add text file boilerplate to output (no operations are processed).
o: run an operating system batch or script file. Typically runs a program.
w: write values of variable to CSV file. Overwrites existing files. w+ appends files.
f: insert image from file into calc (jpg, png etc.)
i: insert and process a comodel file. Integrates sections and equation numbering.
r: read CSV file data into array variable.
e: edit line of existing text file and save in copy of file.
s: execute an external Python script in model namespace.
Executes an external Python script and includes the methods (functions) and variables in the model namespace.
t: inset text file contents into output (no operations are processed).
Inserts the text file contents at the operation location. The var parameter optionally specifies the line range to be inserted for lines n1:n2 inclusive.
o: run an operating system command or executable file
.
w: write array values to file.
Write contents of array v1 to the file specified by filename. Each line or row is written using the numpy.tofile method. To append data to an existing file use the option w+. v2 specifies the separation character (comma is default, for a space character use *). v3 is the data type (default is character format %s).
f: insert figure from file into calc (jpg, png etc.).
Insert figure from file with caption v1. Figure labels are automatically added and incremented. v2 specifies the image width in percent of document width. The figure is centered and the aspect ratio is maintained. v3 specifies a side by side arrangement for a second consecutive figure using the keyword adjacent. For UTF-8 output the following text is inserted:
Figure n: caption - file: filename
i: insert and process a comodel file.
division_folder/file: model folder and file name
Merge a comodel file into the main model file at the operation location. The comodel cannot include a comodel. Sections and equation numbers are integrated into the main model sequence. Format numbers must be unique in the two models (see format operation for suggested format numbering schemes).
r: read file data into variable
path/file: absolute path name
Read CSV contents of path/filename into variable v1 and store as array using the numpy.genfromtext method. v2 specifies the separation character (comma is default, for space character use *). v3 specifies the number of lines to skip before reading the data (default is 0).
e: edit text file
path/file: absolute path name
Edit an external file at run time. Lines immediately following the edit operation have the form:
n | replacement text for line n
where n is the line number to be replaced with the specified replacement text. The v1 parameter is appended to the file name before it is saved with edits i.e. if v1 is copy and the filename is file.tcl the edited file is saved as filecopy.tcl.
Template variables may be used in the replacement line. A template variable is created by appending a % in front of the variable name used in the model.
[o] Python or sympy expression
The symbolic operation formats a sympy symbolic expression without evaluating the terms.
[t] var = value | (description)
The term operation is used to assign values to terms used in equations. It evaluates expressions that multiply by constants or units.
var = value: define term
description: term description
[#] The hash tag is used for non-printing comments. If the comment is format the format operation is subsequently processed. If the comment is stop the program processes the model to that point along with any formats in the model. This can be useful for developing and debugging a model.
[#] format |(default deci, deci) | (output type)
format number |(deci, deci) | (units/label)` | (prt code/label) format number |(deci, deci) | (units/label) | (prt code/label)
The format operation describes decimals, units and labels for equations and arrays.
Use print code 0, 1 or 2 for equations that return arrays.
default deci: number of printed decimal places in equation and result (default 3, 3)
output type: output type is txt, rst or pdf (default is txt). Not read when running onceutf. Set command line option to –noclean to retain rst file. See Appendix D.
ref: Unique six digit equation or array format number between 1 and 99999. Typically the first four digits are the model number and the fifth digit is the section number. This pattern facilities organization and unique formats when comodels are used.
deci, deci: number of printed decimal places in equation and result
units/label: unum unit for dependent variable or label for first range variable
print code/label: For equations provide print code 0, 1, 2, 3 (default is 3) where:
0 - evaluate but do not print result
1 - print result
2 - print symbolic expansion and result
3 - print full results - symbolic expansion, substitution and result
For 2D arrays provide a label for the second range variable.
[c] decimal, decimal | description | ok
expression | operation | limit
The check operation checks an expression value (no variable assignment) against a limit for a given operation.
decimal: number of printed decimal places in equation, result (default 3, 3)
description: description of comparison
expression: expression to evaluate – typically a ratio
operation: Python expression with comparison operator (<, >, <=, >=, =)
limit: value or expression to evaluate that sets upper or lower limit
ok: phrase that prints if compare evaluates to True. If expression evaluates to False the word ‘not’ is prepended. May be blank.
[a] format ref | array description
vector variable1
(vector variable2 for 2D arrays)
var = expression
The array operation input is similar to the equation operation but outputs the results of vector equations in tables 1D or 2D table with column and row labels. Range variables and expressions must be unitless. If only one range variable is provided a single row table is output. The variable name may be a previously defined vector. Note that the number of printed decimals corresponds to the first entry in the integer pair.
variable1: a range statement or variable containing vector or array values.
variable2: a range statement for 2D tables.
var = expression: unitless equation using Python syntax
[f] var | function description
function_name(args)
The function operation executes a function and assigns the return value to variable var. The function is defined in a Python file and imported using the [d]operation with the s option. Describe the function using the function doc strings which are imported into the model. Printed decimals should be controlled by the function itself.
var : one line description of function
function description : short description of function
function_name(args): name of function and arguments to be executed
[e] format number | (description)
var = expression
The equation operation evaluates a Python math statement and optionally prints the symbolic representation, equation with substituted values and solution. The format operation ([#] format) controls the level of printing detail, decimals and units. Equation input may extend over a maximum of three lines. Terminate the operation with a blank line. Indenting equations, terms, functions and arrays may help legibility.
format ref: integer between 1 and 999999 that references a formatting operation.
description: equation description and building code references
var = expression: equation using Python syntax
[s] section heading
(description)
The section operation provides organization to the calculation. Sections are automatically numbered and labeled with the associated model. The source model designation number is added to the section heading and right justified. Equation numbers are generated within sections as s . e where e restarts at 1 in each section.
heading: left justified heading
description: up to 10 lines of text (no blank lines) describing the section. Terminate with blank line.
.
[p] (project default size) | (default background.pdf)
(keyword = data) | (format_number)
(keyword = data) |
(keyword = data) |
.
.
01(_divisionfolder) | (division title)
01yy.model.txt| size| background2.pdf
keyword = data | keyword = data | | |
02 | (division title)
02yy.model.pdf| size| nobackground
03 | (division title)
03yy.model.txt| size| background2.pdf
keyword = -1| kewyword = -1| | |
04 | (division title)
04yy.model.pdf| | omit
| | | |
04yy.model.pdf| size |
05 | (division title)
.
.
The project operation is specified in the project file and provides project calc information. Project files are located in the project folder which in turn contain division folders as subfolders.
size: size and orientation settings of PDF pages.
portrait_letter (default)
landscape_letter
landscape_tableau (11x17)
portrait_A4
landscape_A4
background.pdf: user file name for the calc background (default: none)
keyword = data: keyword-data pairs to be added to the project dictionary. Any key word may be defined except for key words reserved for project calc printing. They include:
ptitle, pname, padd1, padd2, pstate, pzip, powner, pnumber, eng, date, rev, stamp1, stamp2
xx(_divisionfolder): by default include calcs from this folder in the project calcs. If _divisionfolder is provided as part of the folder name it is used for the division name in the project calcs (i.e. table of contents). If division title is provided it is used instead.
For each model in the folder, if a PDF calc is available, it is used. Otherwise the model is run to produce the PDF calc.
Project settings may be overridden for a specified calc or model. If default background.pdf is set, then set the value to nobackground to suppress the default template and all keywords for a particular calc. To omit a calc from the project set use omit for the template value. A keyword data may be redefined for a specific calc. To suppress writing the keyword value to a calc set its value to -1. To write only keyword data without a template specify the keyword data on the keyword override line.
The project or division folder may also include the file once.sty which defines the LaTeX PDF style settings, and the unitc.py file which defines calc units. They will override the default settings in the oncepy package directory – division folder files override project folder files.
[#] pformat | format_number
The project format operation describes the print location on a calc sheet of keyword data defined in the project operation. Terminate format number definitions with a blank line.
keyword | x location | y location
keyword | x location | y location
keyword | x location | y location
.
.
keyword: project keyword
x location: x location of keyword value on page in points from upper left corner.
y location: y location of keyword value on page in points from upper left corner.
.
Appendix C – Komodo Edit
Figure 8. Komodo interface
Template files can be prepared using any text editor however Komodo Edit provides additional useful capabilities and tools. on-c-e syntax coloring and operation tools are provided to improve readability and efficiency. A on-c-e toolbar is provided to simplify program execution.
Install on-c-e utilities and fonts in Komodo
-
Download and install DejaVu fonts from
dejavu-fonts.org/wiki/Main_Page
A point size of 9 and line width of 90 is suggest.The toolbar operates on the model that has focus -
Download and unzip oncetoolsnnn.zip
-
Install the on-c-e tools folder by - right clicking in tool box pane – import folder – select the on-c-e_tools folder rom the unzipped file. Tools include a tool bar, documentation menu and code snippets that can be inserted into models by double clicking.
-
Close and reopen Komodo to complete installation. Edit a tool by right clicking on it in the tool pane and selecting Properties. Pane arrangement can be controlled by the user.
-
Install the syntax coloring plugin once-0.3.1-ko.xpi using the menu - Tools – Add On. Select the xpi file from the unzipped oncetoolsnnn folder. To see once syntax coloring in your file set the language for the .txt file type to type once using the right click context Properties and Settings when the file is open.
-
After running a model the UTF calc is automatically opened in the input pane. The associated PDF calc can then be opened in the users default PDF viewer with the tool bar when the UTF calc has focus.
-
The suggested model line length is 90 characters using mono-spaced 9pt font. Indents should be spaces, not tab characters. UTF calcs are formatted to a 90 character width.
-
PDF calcs require installation of TexLive. See Appendix D and F.
Appendix D – Linux, Windows, Mac, iOS, Android
Install local copy of onceutf.py on Linux, Windows, Mac:
Install a scientific Python distribution. Copy onceutfnnn.py and the model file into the same folder, open a console window in the folder and type:
python onceutfnnn.py modfile.m.txt (-e or –b) (-noclean)
where nnn is the program version number (i.e. 040), nnnn.modfile.txt is the file name of the input model, -e or –b are options to echo calculation results to the console or terminal or browser and –noclean retains the auxiliary PDF files (erased by default).
To open a terminal window in in Windows 7 or 8, navigate to the folder with the model, hold the shift key, right click in the folder and click on ‘open command window here’.
Change the browser encoding settings if needed:
• Chrome – type chrome:settings/fonts in url bar - scroll to the bottom of the dialog box to make the change.
• Firefox - options - content - advanced - UTF-8
• Internet Explorer - right click in window - encoding - UTF-8
For UTF font symbols install font package from
dejavu-fonts.org/wiki/Main_Page
Install local ‘site-packages’ copy of onceutf on Linux, Windows, Mac:
Install a scientific Python distribution. Copy the onceutfnnn.py file into the Python/Lib/site-packages/ folder and rename to onceutf.py. Run from any directory with the command
python –m onceutf nnnn.modfile.txt
Install a complete oncepy environment on Linux, Windows, Mac:
See Section 8 for links
- Install Anaconda 1.9.2
- Install unum and tabulate modules (using pip install)
- Install TexLive
- Install DejaVu Fonts (and set to Mono in IDE)
- Install Komodo Edit
- Install on-c-e tools for Komodo
- Unzip and copy the oncepy folder into the Python/Lib/site-packages/
- Run from any folder containing the model file with the command:
python –m oncepy nnnn.modfile.txt
Install onceutf on iOS:
onceutf runs in the iOS Pythonista App environment which includes numpy, sympy and matplotlib libraries. Copy the onceutf.py file to the site-packages folder and a model file to a division folder.
Without Dropbox integration files will need to be moved by creating new empty files in Pythonista and using copy and paste (script for downloading Dropbox files to Pythonista https://omz-forums.appspot.com/pythonista/post/4995757044137984).
Open the onceutf.py program in Pythonista and create an ‘action’ (wrench menu) for it, leaving the argument blank. Open a model or template. Run it by invoking the action. The calc will be echoed to the screen. The following script makes it convenient to iterate a model by editing in Pythonista and viewing with the Notesy App (UTF-8 fonts).
notesy.py script ( on-c-e.us)
“”"open Pythonista calc in Notesy
- Copy this script to Pythonista and set it as an action.
- Set the fixed width font in Notesy to DejaVu Sans Mono.
“”"
import editor
import webbrowser
import clipboard
base = ‘notesy://x-callback-url/append?name=calc_tmp.txt’
text = editor.get_text()
url = clipboard.set(text)
webbrowser.open(base)
Figure 9. Notesy screenshot of onceutf calc running on iPhone
Install onceutf on Android:
onceutf runs in the QPython App (Python 2) environment on Android. Copy the compiled numpy and sympy libraries into the site-packages folder at
/mnt/sdcard/com.hipipal.qpyplus/lib/python2.7/site-packages.
The compiled libraries are available through QPython sites and also at on-c-e.us. Matplotlib libraries are not yet available.
The following file arrangement and script makes it convenient to iterate and review a model. It uses the DroidEdit App to edit the model and view the calc. The Hackers Keyboard App is efficient for writing models.
once.py script ( on-c-e.us)
#qpy:console
“”"
once.py script runs a onceutf model on Android using QPython
- Copy onceutf.py to the ‘scripts’ folder (see prog path below)
- Create a division folder for the models (see model path below)
- Copy the model and this script into the division folder
- Open this script in QEdit (which is part of QPython)
- Modify folder and model names below, as needed, and save.
- Edit models and review calcs in DroidEdit (or similar editor).
- Set the editor font to DejaVu Sans Mono for calc math symbols.
- Run this script in QEdit to execute program.
“”"
import os, sys
prog =’/mnt/sdcard/com.hipipal.qpyplus/scripts/onceutf.py’
model =’/mnt/sdcard/com.hipipal.qpyplus/models/0301.deflection.txt’
os.system(sys.executable + “ “ + prog + “ “ + model)
Figure 10. DroidEdit screenshot of onceutf calc running on Android tablet
Appendix E – Wakari, PythonAnywhere
Onceutf.py runs on desktop and web platforms. Both environments are discussed in this section.
Wakari is a Python-Linux web platform that runs in the browser. Upload onceutfnnn.py and mode.01.txt to your Wakari account. Open a bash shell window (not Ipython) and type
python onceutfnnn.py 0101.simple.txt –c
at the command prompt, where nnn is the version number (i.e. 040). The program will output a model summary followed by the calc output (the –c option echoes the output to stdout; use –b to echo output to the browser when using the program locally). Use the browser file editor to review and modify the files.
Figure 11. Wakari – terminal and editor in split windows
w
PythonAnywhere is a Python-Linux web platform that runs in the browser. Upload onceutfnnn.py and mode.001.txt to your PythonAnywhere account. Open a bash shell window (not Ipython or Python) and type
python onceutfnnn.py 0101.simple.txt –c
at the command prompt, where nnn is the version number (i.e. 040). The program will output a model summary followed by the calc output (the –c option echoes the output to stdout). Edit files in the file editor.
Figure 12. PythonAnywhere – side by side browser windows
Appendix F – Minimum Programs and Libraries
Note: If the standard scientific distribution does not include a library use the pip install method or in the case of Anaconda use conda. Other installed scientific libraries including SciPy, pandas, rpy etc. may be installed by the distribution or installed separately and will be available to on-c-e through functions and script operations (see disk operations, Appendix B).
Program
Python 2
Python 3
Notes
onceutf
0.4.0
0.4.0
Python
2.7.x and above
3.4 and above
Python Platform
Numpy
1.7.x and above
1.8 and above
Python Library
SymPy
0.7.x and above
0.7.5 and above
Python Library
Matplotlib
1.2.x and above
1.3.1 and above
Python Library
DejaVu fonts
(note: Unum and tabulate are built-in classes of onceutf
2.3.4 and above
2.3.4 and above
UTF math fonts (external program)
oncepy
in addition to above
0.4.0
0.4.0
Unum
4.1.x and above
4.1.x and above
Install with pip
Tabulate
0.7.x and above
0.7.x and above
Install with pip
once.sty
0.4.0
0.4.0
Customize PDF styles
unitc.py
0.4.0
0.4.0
Customize units
oncepy with PDF
in addition to above
0.4.0
0.4.0
TeX Live
2013 and above
2013 and above
Network install (external program)
PyPDF2
1.1x and above
1.1x and above
Install with
Table 4. Minimum required versions of programs and libraries
Appendix G – Licenses
oncepy, onceutf and on-c-e Komodo tools are distributed under the MIT or compatible license. Copyright is retained by the code author.
Figure 13. opensource.org/licenses/MIT
Figure 14. creativecommons.org/publicdomain/zero/1.0/
Template files uploaded to once-db are made available to others under the CCO 1.0 Public Domain Dedication. A Komodo snippet is provided for inserting license text in a template file:
[#] This file contains a generic on-c-e model template (the template).
[#] The template is distributed under the CCO 1.0 Public Domain Dedication
[#] creativecommons.org/publicdomain/zero/1.0/
[#] The template is not a structural design calculation and
[#] must be modified by the user prior to use.
[#] The template user assumes sole and complete responsibility for
[#] all existing or modified inputs and the computed model results.
Appendix H – Security and Namespaces
on-c-e is designed to be a flexible and efficient tool for structural analysis and design. It is also designed to facilitate program verification by keeping the source code relatively compact. onceutf.py and oncepy are each about 1500 lines of source code (about 3000 lines with comments). Programming tradeoffs occur in pursuing these objectives.
The programs use Python exec and eval statements because it is the simple, straightforward way to process the model operations. It is possible to send input to exec and eval that does unexpected or undesirable things. However the chances of this happening can be controlled or eliminated with relatively little effort. Sensible model file input is tightly constrained and under the control of engineers and designers who are running the models. Appropriate inputs, in the form of structural analysis equations, arrays and functions are well known and easily recognized by the engineers using the tool. Because unsafe code in the model would appear very different from these well understood structural forms it is straightforward to spot and delete suspicious or problematic model code before it is run. Model security checks may be added in the future but the only way to ensure proper operation of the program is to check the input.
The programs also import numpy, sympy and other libraries in their entirety into the model namespace. This approach improves readability and streamlines equation input but may introduce potential problems with naming collisions. Some variable naming rules have been developed and more will be added as experience is gained using the program. The programs currently includes some tools and methods for checking collisions between model variable names and more will be added.
In summary, to make on-c-e more readable, useful and flexible, the design philosophy chosen is code simplicity and transparency, along with the obviousness of appropriate input as opposed to verbose and restrictive input and processing policies.