For PDF version of manual see on-c-e.us
O pe N Calculation Environment for
Structural Calculations and Documents
USER MANUAL and SPECIFICATION
CONTENTS
- INTRODUCTION 5
- ADD A SIMPLE TEMPLATE TO ONCE-DB 6
- GENERATE A CALC FROM A TEMPLATE 7
- ON-C-E OVERVIEW 8
- FILES AND PATHS 9
- MODEL OPERATIONS 11
- PROJECT OPERATIONS 11
- WEB RESOURCES 13
- INTERACTIVE ANALYSIS 15
APPENDIX A – EXAMPLE MODEL AND CALC 17
APPENDIX B – OPERATIONS 23
APPENDIX C – KOMODO EDIT 30
APPENDIX D – LINUX, WINDOWS, MAC, IOS, ANDROID 32
APPENDIX E – WAKARI, PYTHONANYWHERE 36
APPENDIX F – MINIMUM PROGRAMS AND LIBRARIES 38
APPENDIX G – LICENSES 39
APPENDIX H – SECURITY AND NAMESPACES 41
APPENDIX I – EXAMPLES 42
INDEX 43
Figures
Figure 1. Program and interface structure 5
Figure 2. Basic environment components 9
Figure 3. Model, calc and project content 13
Figure 4. Screenshots of equation history in IPython terminal and QT shells 16
Figure 5. Example PDF calc 20
Figure 6. Example PDF calc (continued) 21
Figure 7. Example PDF calc (continued) 22
Figure 8. Komodo interface 30
Figure 9. Notesy screenshot of onceutf calc running on iPhone 33
Figure 10. DroidEdit screenshot of onceutf calc running on Android tablet 35
Figure 11. Wakari – terminal and editor in split windows 36
Figure 12. PythonAnywhere – side by side browser windows 37
Figure 13. opensource.org/licenses/MIT 39
Figure 14. creativecommons.org/publicdomain/zero/1.0/ 40
Tables
Table 1. Open source components (See Appendices D, E for details) 8
Table 2. File and folder structure 10
Table 3. Operations summary 12
Table 4. Minimum required versions of programs and libraries 38
- Introduction
on-c-e (pronounced once) implements a readable, sequentially organized markup language for writing and publishing structural engineering calculations. Calculations are stored in text files called models or templates that describe structural behavior using equations, text, tables and figures. Relative to Mathematica ™, Mathcad ™ or MATLAB ™ it has several advantages: it is much easier to use, files will never be incompatible, and the program can be freely shared.
Models generate design or analysis calculations. Templates are similar but they do not represent specific designs. The same model generates calculations in two types of formatted documents referred to as calcs (see Appendices A and H for examples). A UTF calc is used for iterative design and study and is formatted with UTF-8 characters. It is generated instantly and can be easily edited. A PDF calc includes graphics and LaTeX math and is used for reports or construction documents. It takes a few seconds to generate. Models can interact with other models, files and external structural engineering programs to produce calcs or input to IPython notebooks for interactive analysis. Typical models are less than a few hundred lines. Because they are text they can be searched and stored in many types of databases. From a software point of view, models are instructions given in a structural calculation markup language to Python scientific and engineering libraries and external programs.
Calcs may be standalone PDF or UTF-8 files, or combined into a single PDF project calc file. Typical calcs are less than one or two dozen pages but project calcs can be as large as needed. A project calc is defined in a project file that specifies organization, numbering, title blocks and table of contents. From a software point of view, calcs are produced by wrapping the numpy and sympy libraries in a structural document formatting language. PDF and project calcs are produced by processing the calc through reStructuredText, docutils, LaTeX and PyPDF2 libraries.
on-c-e runs on workstations, web and mobile platforms on top of Python. The interface is an Interactive Development Environment on workstations (Section 4), a browser on web platforms, and Apps on mobile platforms (Appendix D).
Figure 1. Program and interface structure - Add a simple template to once-db
This page describes the simplest approach to adding a template to the once-db database. The purpose of the exercise is to gain an initial familiarity with the process.
We will use the template 0001.simple.txt and modify it to make a new template. Everything will be done in a browser – no installation is needed.
Step 1. Go to on-c-e.org. Click on [Download Model Templates] at the top of the page.
Step 2. Scroll down to search once-db, click on the description dropdown box and select contains. Enter the search term ‘simple example’. Click on the Search button. One or more results should appear at the bottom of the page.
Step 3. Look for the template name 0001.simple.txt and the associated calc names cal0001.simple.txt and cal0001.simple.pdf. Click on the links that begin with cal to view the two different calc formats in a browser window.
Step 4. Select the window for cal0001.simple.txt. Press the keys CTRL-A or select all of the template text by dragging the mouse. Press CTRL-C or right click in the browser window and select copy to copy the text to the clipboard.
Step 5. Click on [Upload Model Templates] at the top of the page. Scroll down to the box labeled Template Text and enlarge it by left clicking on the handle in the lower right corner and dragging it. Click in the box and press CTRL-V or right click and select paste. You should now have a copy of the template in the box.
Upload Template
Edit Template
Step 5. Read over the template and edit the text, terms, and equations to represent your own idea. Maybe you want to change it to a calculation of calories or driving time to work. The only rules you need to follow are to leave the tags and vertical bars in place and just edit the text between them or delete the whole line with the tag. Section 6 provides an overview and Appendix B describes what each tag does in more detail.
When you finish editing the template, type a brief template summary in the Template Summary Description box above. Include the phrase ‘learning template’ in the description. Delete all of the words ‘example’ from the template and description (so it doesn’t show up in the search). Don’t worry about the template contents; the learning templates will be removed from the database every few days.
Step 6. Click on the Submit button. You should receive a confirmation message that the template was submitted.
That’s it! Thanks for learning how to contribute.
(note: typically the template file will be prepared on your computer and uploaded)
- Generate a calc from a template
This page describes the simplest approach to running an example template. It uses a web platform that does not require program installation.
ICON KEY
- Web Document
- Exercise
E Summary
on-c-e is designed to run on workstations with Python installed, but it can also run in the cloud on Python web platforms like Wakari and PythonAnywhere. They provide an in-browser editor and shell terminal interface. Wakari and PythonAnywhere are discussed in the manual but other Python web platforms can be used. Appendix E provides additional details for web execution. Appendix D discusses installation of the program on a computer or mobile device.
For this exercise a simple example model is run on a Python web platform using the program onceutfnnn.py. You can preview and download other models at on-c-e.org. Printed example models and calc output are provided in Appendix I. onceutf.py is a single file subset of on-c-e that does not include project options, PDF calcs, or unit overrides. It was written to simplify program testing and implementation on web and mobile platforms.
Run
template
- Sign up for a Wakari account at continuum.io/
or at
PythonAnywhere at https://www.pythonanywhere.com/ - Download onceutfnnn.py and 0101.simple.txt or 0101.template.txt from on-c-e.us
- Upload the program and template files to a folder on your Wakari or PythonAnywhere account. Choose a bash shell terminal from the drop-down list and open it (Appendix E). At the shell command line check that both files are in the folder you selected (type ls or dir). Enter the command
python onceutfnnn.py 0001.simple.txt -e
where nnn is the program version number (i.e. 040).
The model will write several files to the directory (Table 2) and echo the log file and calc, cal0101.simple.txt, to the screen. You can open the calc using the browser editor provided by the web platform. The switches following the model name echo the calc to the console (–e) or browser
(–b). The browser option works when run on local computer.
Congratulation on running your first model!
(note: refer to Appendix D for on-c-e installation instructions)
- on-c-e Overview
The OpeN Calculation Environment is defined by:
- oncepy - Python package
- onceutf.py – single file program and subset of oncepy
- onceipy.py – updates the IPython database with on-c-e equations for interactive analysis
- once-db - online browser accessible database for sharing template files.
- Komodo Edit - a multilanguage IDE for Windows, Linux, OSX (others may be used)
- Anaconda 1.9.2 - scientific Python distribution for Windows, Linux, OSX (others may be used)
- Wakari – web based scientific Python distribution with browser interface (others may be used)
- Pythonista - Python platform for iOS
- QPython - Python platform for Android
oncepy is written for Python 2 or 3 and IPython. Python is a dynamic, high-level, general-purpose language widely used for engineering and scientific scripting and programs. For comparisons with other numerical computing environments, such as MATLAB, see for example:
MATLAB
vs
Python
www.stat.washington.edu/~hoytak/blog/whypython.html
https://sites.google.com/site/pythonforscientists/python-vs-matlab
A single file program called onceutf.py, was written to simplify testing and implementation in web and mobile environments. It produces UTF calcs and does not require any installation other than copying the file to a folder.
Table 1. Open source components (See Appendices D, E for details)
- Files and Paths
The fundamental program component is a model file xxyy.model.txt, where model is a user-created file name and xxyy is a four digit model designation. The first two digits refer to the model division number and the last two to the model number. The designation is used for calc and project organization and must be unique. Models are stored in division folders and division folders are stored in a project folder (one level deep). When a model is run it produces the following output files (Figure 2, Table 2):
- UTF-8 calc calxxyy.model.txt.
- calc description file sumxxyy.model.txt that can be pasted in the once-db form.
- IPython input file _onceeq.py for interactive analysis.
- execution log file _modelog.txt, also (partially) echoed to screen.
- optional PDF calc calxxyy.model.pdf and supporting files
(.rst, .tex, .log, .out, fls, fdb_latexmk – see Appendix D for file handling). - optional project calc project.pdf assembled from a specified set of division folders.
Models are grouped in division folders and may include references to other models, external functions, data, and batch or script control files. External model files are generally located in the model division folder and are identified by file name only. The program recreates the full path name internally, which allows division folders to be moved without changing the models. The exceptions include files manipulated by the disk operation parameters r (read) and e (edit) which require a full path name, and comodels imported with option i which require the division folder name (see operation [d] with options i, r, e in Appendix B).
A division folder has the name xx_division_name where xx is the unique division number. Each division or project folder may contain up to 100 models or divisions respectively. The project folder contains the project definition file if needed, and it may contain unit and PDF style definition files (unitc.py, once.sty) that override the program defaults for the entire project. Definition files in a division file override all other definition files.
Figure 2. Basic environment components
Project Files
Project / Division Folder Structure
Division Files
xxyy.model.txt
Model
(project.txt)
Project file
(unitc.py)
Custom units
(background.pdf)
Calc background
(unitc.py)
Custom units
(once.sty)
Custom PDF style
(once.sty)
Custom PDF style
calxxyy.model.txt
UTF-8 calc
sumxxyy.model.txt
Model description
(project.pdf)
Project calc
_onceeq.py
IPython file
(project.log.txt)
Project execution log
_log.txt
Model execution log
(calxxyy.model.pdf)
PDF calc
Notes:
- Input files are in blue; output in green
- Optional files are in parenthesis
- PDF calc auxillary files are erased by default (Appendix D)
To keep auxillary files use ‘–noclean’ command line option
Table 2. File and folder structure
- Model Operations
Models are composed of a dozen operations. The basic operations are sections, terms, equations checks, arrays, functions, and format (see Figure 3, Table 3, and Appendix B). When operations are processed the calc sections and equations are sequentially numbered. Equations are first formatted symbolically and then with numerical substitutions. The degree of printed detail is controlled by formatting statements. Tables are created from arrays and vectors. Units and decimal places are reduced and formatted (see unitc.py file). PDF calcs start a new page at every section and figures are inserted.
Operations are identified by bracketed tags and may occur in any order or frequency as long as each term or variable is defined before use. Operations are executed sequentially, in the order they are entered. Nesting is not permitted. Parameters and options associated with tags are provided on the same line, separated by vertical bars (|). Parameters with defaults or empty parameters may be omitted but the bar delimiters (with at least one space in between) must be provided. Arrays do not include unit processing. Operations may extend over single or multiple lines. Tags for single line operations include [d], [o], [t]. Tags for multi-line operations include [c], [a], [f], [e], [s]. Multi-line operations are terminated with a blank line.
The disk operation [d] performs several file functions depending on the option selected. Options are designated by s, t, o, w, f, i, r, e. The option s reads external Python files that can define functions available to the function tag [f]. The option i imports a comodel into the main model. A comodel is a model that does not import other models (only one level of model recursion is permitted). Other options import figures and text, and execute read, write, edit and run operations on external files and programs.
Tags may be indented to improve model readability (4 spaces is standard). Any text in the model not associated with an operation tag is passed through to the output unchanged, including reStructuredText markup. For example, surrounding text with double asterisks will print bold, single asterisks will print italics and a vertical bar in the first column will force a new line in PDF calcs. See the reST quick reference for further documentation.
7. Project Operations
Project operations are identified with tags [p] and [#] pformat. The operation writes a project calc with the name project.pdf to the project folder, overwriting an existing file. The project operation is divided into a project data definition section and a division (folder) inclusion list (Table 3 and Appendix B). Each division designation includes the option to override the project defaults on a calc by calc basis. Project data is defined by a dictionary of keyword-data pairs that can easily be incorporated into databases. The project format operation defines the page print location, if any, for a specific piece of project data.
Project calcs produced from the project operation are simply ordered assemblies of calcs that include a title page, table of contents, title blocks and navigational links.
Tags
Operations (optional parameters)
Notes
[d]
Disk file
[d] folder/file | option | (var1) | (var2) | (var3)
option is one of
s,t,o,w,f,i,r,e
[o]
Symbolic representation
[o] sympy symbolic expression
Expression is printed but not evaluated.
[t]
Term
[t] description | var = value
[c]
Check expression against limit
[c] decimal | description | ok
expression | op | limit
[a]
Array table
[a] format_number | table description
range variables
var = expression
For format reference numbers see format operation.
[f]
Function
[f] var | function description
function_name()
Functions are defined in external files and imported with [d] | s |
[e]
Equation
[e] format_number | equation description
var = expression
[s]
Section
[s] section heading
section description
[#]
format
stop
Comment or equation and array formats
[#] format | (deci, deci) | (out type)
format_number | (deci, deci) | (units) | (label/prnt code)
[#] stop
[#] comment line
[#] followed by format or stop are special cases. stop terminates model processing.
[p]
Project data (requires oncepy)
[p] (pdf size) | (background.pdf)
keyword = data | (format_number)
keyword = data |
01_divisionfolder | (division title)
model_name1 | (pdf size) | (background1.pdf)
keyword = format_number | keyword = format_number | | |
model_name2 | |
keyword = format_number | | | |
02_divisionfolder
03_divisionfolder
Model files (.txt suffix) are first processed to PDF.
[#]
pformat
Project formats (requires oncepy)
[#] pformat | format_number
keyword | x location | y location
keyword | x location | y location
[#] followed by format is a special cases. Terminate with blank line
Table 3. Operations summary
- Interactive Analysis
In some cases equation level interactive analysis and design is preferred over complete model runs. An import equation file, _onceeq.py, is written when on-c-e is run and may be used for interactive analysis. Three interactive interfaces are available:
o Komodo IDE (commercial version): Cut and paste the entire onceeq.py file into the interactive shell for access to equations and terms.
o IPython Notebook: ipython.org/notebook.html Cut and paste the entire onceeq.py file into a notebook cell for interactive access to equations and terms.
o IPython Terminal and Qt shell: ipython.org/
Equations from _onceeq.py are loaded into a shell in two steps:
-
The script onceipy.py updates the history.sqlilte database with the equations. Copy onceipy.py to the Python /lib/site-packages directory.
-
_onceeq.py is loaded into Ipython using the ‘run’ command.
Both steps are executed by the IPy macro button on the Komodo on-c-e toolbar (see Appendix C). Run this macro after running the model and when the division file for the model has focus. Prior to using the button, modify the command “run_onceipy” (at the end of the tool list in the Komodo toolbox) by adding the location of the history.sqlite directory to the command line entry (do not type brackets), i.e.
python -m onceipy.py [C:\Users\rhh\.ipython\profile_default]
When onceipy is run, the equations are read from the onceeq.py file generated when on-c-e is run. They are assigned the next session number and added to the end of the history.sqlite file. A backup copy of the file is made before the new equation records are added.
If the history.sqlite file becomes too large or corrupted it may be deleted and reinitialized simply by running IPython from the command line.
Equations and terms are available in the shell through command history scrolling or using the %rep ref command, where ref is the equation history reference.
Figure 4. Screenshots of equation history in IPython terminal and QT shells
StructureLabs
15 Blanca Drive
Novato, CA 94947
Phone 415.314.8453 • rholland@structurelabs.com