A.1 | Start#

[1] Overview#

rivt is an open source project for writing, sharing and reusing engineering calculation documents [1]. This user manual is written in rivt. It runs on the desktop and in the cloud. The project includes rivtlib - a Python package that formats and compiles rivt files, rivtStudio - an integrated desktop editor that manages and publishes rivt docs, and rivtRemote - a containerized version of rivtStudio that runs on a server in the cloud with a browser interface. Python knowledge is not required to use rivt, but adding custom Python scripts increases its capabilities.

A rivt file (.py) uses rivt markup to organize text, calculations, images, code and external programs to publish rivt doc. A doc is a formatted text, HTML and PDF document. The rivt folder structure provides a replicable format for organizing a wide variety of file types. Groups of docs can be assembled into a structured rivt report.

This tutorial provides examples of a rivt file and its text, PDF, and HTML docs. To get started running examples see install. For rivt with AI see here.

rivt projects, reports and handbooks may be shared and distributed as zip files through any cloud storage service. Examples are available on Google Drive and searchable at openmodels.info. A convenient interface for searching public rivt READMEs on GitHub is here.

[2] Motivation#

Broadly sharing engineering documents has been a challenge because they are complex and because commercial software objectives do not align with this goal. They may include text, images, tables, calculations, active models and computer code. They are also dynamic and are frequently updated and recalculated as project designs evolve and change.

The need for reuse of engineering documents is a matter of improving efficiency and making time for independent and creative thought. Most engineering calculations are not fundamentally unique. The basic equations and methods are shared across many projects. However they are always organized in a unique way for the specific project requirements. The commercial market response to this need has been to develop a number of siloed programs with barriers to sharing and reuse including:

incompatible documents across different programs
costly software updates that are backward incompatible
software limited to specific platforms
limited version control
limited report generation
limited collaboration

rivt produces organized, formatted engineering documents from active calculation files that can be shared anywhere. The primary use cases for rivt are:

A. producing reusable engineering documents that are easier to write, edit and maintian compared to LaTeX, Excel, or Word.

B. producing documents that need to be partitioned into public and private parts prior to sharing.

using Python and AI tools to write engineering documents

functioning as a front and back end for external software.

Engineering document types include:

internal communications

research documentation

government permits

technical reports

funding applications

teaching and presentation materials

homework

Quarto is likely a better fit for documents with highly specific format requirements including journal articles and books and that do not need live recalculation . For interactive calculation documents that do not need organized reports or partitioning into private and public sections Jupyter Notebooks is likely a better tool. Finally, the table below summarizes and compares limitations between specific programs that rivt is designed to complement or replace.

Software Comparison (commercial programs in italics)

Program	Reprt [2]	Ver [3]	Txt [4]	Priv [5]	Unts [6]	Comp [7]	C-P [8]	Coll [9]	Pub [10]
Matlab	no	no	no	no	no	no	no	no	yes
Mathcad	no	no	no	no	no	no	no	no	no
Mathematica	no	no	no	no	no	no	no	no	yes
Cloud SaaS	limited	no	no	no	no	no	yes	limited	limited
Excel	limited	no	no	no	no	yes	no	yes	yes
Jupyter	no	no	no	no	no	yes	yes	yes	yes
Quarto	yes	yes	no	no	no	no	yes	yes	yes
rivt	yes	yes	yes	yes	yes	yes	yes	yes	yes