F.1 | Quick Reference#

[1] Reference Summary#

API Summary
Line Tags
Block Tags
Assignment Summary
Commands
rivt Report Folders
rivtbook Folders
Unit Definitions

[2] API Summary#

API methods

API Function	Name	Purpose
rv.R (rS)	Run	Run scripts and markup
rv.I (rS)	Insert	Insert static sources
rv.V (rS)	Values	Calculate values
rv.T (rS)	Tools	Shell scripts and programs
rv.D (rS)	Doc	Publish docs
rv.S; X (rS)	Skip; Exit	Skip section or exit

where rS is a rivt string. The first line of a rivt string (rS) is the header substring.

Header Defaults

rv._("""Section Label

     Content text and rivt markup - indented four spaces.

    ...

    """)

Header Modifications

rv._("""Section Label | shmpn | type | template or script file


     Content text and rivt markup - indented four spaces.
     Content may be ommitted if a template file or script
     is specified.

    ...

    """)

The first set of parameters in the header substring specify handling of the content substring. The second and third parameters specify a type and file or script that is processed by the API method before processing any content.

Parameters

Section parameters may be specified in any order or ommitted if defaults are acceptable. The default parameters are shown in the

s stores the section content in _rvstored/sect as a .rvt file.
h processes the section but suppresses the doc output.
m merges the section with the previous section.
p toggles the public/private status of the section. The rivt file default is private unless overridden by a comment setting
n starts a new pdf page.

File and Type Settings

The second parameter specifies a template file or script that is processed by the API method before processing any content. The file is read from the rvsrc/data folder unless a relative path is specified. The file type is determined by the API method. The type setting for all API methods, except rv.T, is rvt. A rvt file type is a section content string stored as a file. It is written by the s parameter.

For the rv.T method the type settings are:

PYTHON - run Python script
python - insert Python script code
text - literal text
rst - reStructuredText
html - HTML markup
mermaid - Mermaid diagram (requires mermaid installation)
latex - LaTeX (requires LaTeX installation)
dot - Graphviz (requires graphviz installation)

[3] Line Tags Summary#

Format a line of text

API Scope	Line Tag	Description
rv.I	text word word text	italicize words
rv.I	text word word text	bold words
rv.I	text _[D] label, filename \| text	[3] Download link
rv.I	text _[G] glossary term \| text	[7] Glossary link
rv.I	text _[S] label, section \| text	[8] Section link
rv.I	text _[U] label, url \| text	[9] URL link
rv.I,V	text _[#] text	[6] Endnote number
rv.I,V	text _[R]	[2] Right justify text
rv.I,V	text _[B]	[2] Bold text
rv.I,V	text _[C]	[2] Bold center text
rv.I,V	title _[T]	[11] Table number
rv.I,V	ASCII text math _[M] description	[4] Text math
rv.I,V	LaTeX math _[L] description	[5] LaTeX math
rv.I,V	text _[V] var_name \| text	[10] Substitute value
all	## text	nonprinting comment

[4] Block Tags Summary#

Format or run blocks of text or scripts

API Scope	Block Tag	Description
rv.R	_[[WRITE]] var name	[5] Write
rv.R	_[[SHELL]] os, wait;nowait	[6] Shell script
rv.I,V	_[[TABLE]] label	[3] Table Block
rv.V	_[[ARGS]] arg dict name	[4] Argument block
rv.D	_[[METADATA]] label	[7] Metadata
all	_[[END]]	[8] End block

[5] Assignment Summary#

Assign values to expressions

API Scope	Command	Description
rv.V	a ==: 1*IN \| unit1, unit2, decimal \| label	[2] Define values \| ==:
rv.V	c <=: expression \| unit1, unit2, decimal \| label	[3] Assign expression values \| <=:
rv.V	c :=: func(x,y) \| unit1, unit2, decimal \| label	[4] Assign function values \| :=:
rv.V	a <= c \| unit, decimal, text1, text2 \| label	[5] Compare values \| <=

[6] Command Summary#

Read and format files

API Scope	Command	Description
rv.R	\| COPY \| abs src path \| abs dest path \| file pattern	[10] Copy Files
rv.R	\| SHELL \| abs path \| os, wait	[2] Shell file
rv.I, V	\| TABLE \| file name \| title,width,head;nohead,num;non	[4] Table file
rv.I, V	\| IMAGE \| file name \| caption, scale, num;non, time;not	[5] Image file
rv.I, V	\| IMAGE2 \| file1, file2 \| c1,c2,s1,s2,n1,n2	[6] Adjacent images
rv.V	\| VALTABLE \| file name \| title, width, num;non	[7] Valtable file
rv.V	\| VALSTOR \| file name \| title, width, num;non	[7] Valtable file
rv.V	\| FUNCTION \| function, arg, var, type \| label	[9] Function
rv.D	\| ATTACHPDF \| file name \| front;back, title	[11] Attach PDF
rv.D	\| PUBLISH \| doc title \| type	[12] Publish doc

Relative paths for commands

Command	Default Path [1]	R/W
\| COPY \|	os root	R
\| SHELL \|	os root	R
\| IMAGE \|	rivt-report/image	R
\| IMAGE2 \|	rivt-report/image	R
\| TABLE \|	rivt-report/data	R
\| VALTABLE \|	rivt-report/data	R
\| VALSTOR \|	_rvstor/data [2]	R
\| ATTACHPDF \|	rivt-report/image	R
\| PUBLISH \|	rivt-report/_published/ [3]	W

[1] The relative path is the absolute path to the rivt-report folder [2] values written by rivt are read from rv_stor/vals [3] docs are written to subdirectories of _published

[7] Report Folders#

[rivt-]Report-Label/             report folder
    ├── .help/                        help files
    ├── .vscode/                      optional VSCode settings
    ├── README.txt                    rivt-generated text report
    ├── [_rivt-public]/               rivt-generated public files
        ├── rvsrc/                        author source files
        ├── rv-101-filename1.py           public rivt file
        ├── rv-102-filename2.py           public rivt file
        ├── rv-201-filename3.py           public rivt file
         ...
    ├── [rivt-report]/                 report folder
        ├── [rivt-report]-1.py            report generating script
        ├── [rv101-]filename1.py          rivt file
        ├── [rv102-]filename2.py          rivt file
        ├── [rv201-]filename3.py          rivt file
            ...
        ├── [rvsrc]/                      author provided files and folders
            ├── [downloads]/                    files to download
                └── conc-vals.txt
            ├── [img]/                          page layout images
                ├── favicon.png
                ├── covlogo1.png
                └── runlogo1.png
            ├── [data]/                         tables
                └── steel-vals.csv
            ├── tools/                          OS shell commands
                └── opensees.sh
            ├── fig1.png
            └── fig2.jpg
        ├── [rv_stor]/                    rivt-generated source files
            ├── [logs]/                          log files
                ├── rv101-log.txt
                └── rv102-log.txt
            ├── [sect]/                          sections not printed
                ├── rv202-5d.txt
                ├── rv103-4t.txt
                └── rv301-2r.txt
            ├── [temp]/                          temp files
                └── rv101-label3.tex
            ├── output.dat
            ├── v101-2.csv
            └── v102-3.csv
        ├── [_published]/                 rivt-published docs and reports
            ├── [docs]/                          html docs
                ├── html auxiliary folders
                ├── index.html
                ├── rv101-filename1.html
                ├── rv102-filename2.html
                ├── rv201-filename3.html
                    ...
            ├── [pdfdocs]/                       pdf docs
                ├── pdf auxiliary folders
                ├── report-title.pdf
                ├── rv101-filename1.pdf
                ├── rv102-filename1.pdf
                ├── rv201-filename3.pdf
                    ...
            └── [txtdocs]/                       text docs
                ├── report-title.txt
                ├── rv101-filename1.txt
                ├── rv102-filename1.txt
                ├── rv201-filename3.txt
                    ...
        └── [_rstdocs]/                     rivt-generated rst files
            ├── _downloads/
            ├── _static/
            ├── rv101-filename1.rst
            ├── rv102-filename2.rst
            ├── rv201-filename3.rst
                ...

[8] rivtbook Folders#

[rivtbk-]Book-Label/             rivtbook report folder
    ├── .help/                        help files
    ├── .vscode/                      optional VSCode settings
    ├── README.txt                    rivt-generated book as text
    ├── [rivtbook-report]-1.py        rivtbook generating script
    ├── [_rivtbk-public]/             public subset of rivt files
        ├── [rvbk-101-]folder name    rivtbook folder
        ├── [rvbk-102-]folder name    rivtbook folder
        ├── [rvbk-201-]folder name    rivtbook folder
            ...
    ├── [_rstdocs]/                   rivt-generated rst files
        ├── _downloads/
        ├── _static/
        ├── rv101-filename1.rst
        ├── rv102-filename2.rst
        ├── rv201-filename3.rst
            ...
    ├── [_pdfdocs]/                   pdf docs and rivtbook report
        ├── pdf auxiliary folders
        ├── report-title.pdf
        ├── rv101-filename1.pdf
        ├── rv102-filename1.pdf
        ├── rv201-filename3.pdf
    └── [_rv_stor]/                    rivt-generated source files
        ├── [logs]/                          log files
            ├── rv101-log.txt
            └── rv102-log.txt
        ├── [sect]/                          sections not printed
            ├── rv202-5d.txt
            ├── rv103-4t.txt
            └── rv301-2r.txt
        ├── [temp]/                          temp files
            └── rv101-label3.tex
        ├── [vals]/                          values files
            ├── v101-2.csv
            └── v102-3.csv
        └── output.dat
    ├── [bk1-]folder name              rivtbook chapter folder
        ├── [rv001-]filename1.py          rivt file
        ├── [downloads]/                    files to download
            └── conc-vals.txt
        ├── [img]/                          page layout images
            ├── favicon.png
            ├── covlogo1.png
            ├── runlogo1.png
            └── fig1.png
        ├── [data]/                          tables
            └── steel-vals.csv
        ├── [vals]/                          values files
            ├── v101-2.csv
            └── v102-3.csv
        └── tools/                           OS shell commands
            └── opensees.sh
    ├── [bk2-]folder name             rivtbook chapter folder
            ...
    └── [bk3-]folder name             rivtbook chapter folder
            ...

[9] Unit Definitions#

# standard SI units ==== DO NOT MODIFY BETWEEN DOUBLE LINES  ============
#
# temperature - relative degree, not offset
K = new_unit("K", 0, "kelvin")
CELSIUS = new_unit("deg C", K, "degree Celsius")
FAHR = new_unit("degF", K * 9.0 / 5, "degree Fahrenheit")
# time
sec = S = new_unit("sec", 0, "second")
HZ = new_unit("Hz", 1 / S, "hertz")
# length
m = M = new_unit("m", 0, "meter")
nm = new_unit("nm", 10**-9 * M, "nanometer")
um = new_unit("um", 10**-6 * M, "micrometer")
mm = new_unit("mm", 10**-3 * M, "millimeter")
cm = new_unit("cm", 10**-2 * M, "centimeter")
dm = new_unit("dm", 10**-1 * M, "decimeter")
# mass
kg = KG = new_unit("kg", 0, "kilogram")
gram = new_unit("gram", 10**-3 * KG, "gram")
rad = new_unit("rad", M / M, "radian")
sr = new_unit("sr", M**2 / M**2, "steradian")
mol = new_unit("mol", 0, "mole")
# force
N = new_unit("N", M * KG / S**2, "newton")
cd = new_unit("cd", 0, "candela")
lm = new_unit("lm", cd * sr, "lumen")
lx = new_unit("lx", lm / M**2, "lux")
# charge
J = new_unit("J", N * M, "joule")
W = new_unit("W", J / S, "watt")
A = new_unit("A", 0, "ampere")
mA = new_unit("mA", 10**-3 * A, "milliampere")
C = new_unit("C", S * A, "coulomb")
VO = new_unit("V", W / A, "volt")
F = new_unit("F", C / VO, "farad")
OHM = new_unit("ohm", VO / A, "ohm")
SIEMENS = new_unit("siemens", A / VO, "siemens")
WB = new_unit("Wb", VO * SIEMENS, "weber")
TS = new_unit("TS", WB / M**2, "tesla")
HENRY = new_unit("H", WB / A, "henry")
#
#
# ============  DO NOT MODIFY FILE ABOVE THIS LINE  ===========================
#
# --------------------------------------------------- metric
#
g = new_unit("G", 9.80665 * M / S**2, "gravity acceleration")
# pressure
PA = new_unit("PA", N / M**2, "pascal")
MPA = new_unit("MPA", PA * (10**6), "megapascals")
kPA = new_unit("kPA", PA * (10**3), "kilopascals")
# force
kN = new_unit("kN", N * (10**3), "kilonewton")
MN = new_unit("mN", N * (10**6), "meganewton")
km = new_unit("kM", M * (10**3), "kilometer")
kN_m3 = new_unit("kN_m3", kN / (M**3), "kilonewton per cubic meter")
kN_m = new_unit("kN_m", kN / M, "kilonewton per meter")
kN_cm = new_unit("kN_cm", kN / cm, "kilonewton per centimeter")
mkN = new_unit("mkN", (kN * M), "meter-kilonewton")
# area
sqm = new_unit("sqm", (M**2), "square meter")
cm2 = new_unit("cm2", (cm**2), "square centimeter")
cm3 = new_unit("cm3", (cm**3), "cubic centimeter")
cm4 = new_unit("cm4", (cm**4), "cm to fourth power")
#
# ------------------------------------------------- imperial
#
# length
inch = new_unit("inch", M / 39.370079, "inch")
ft = new_unit("ft", M / 3.2808399, "foot")
miles = new_unit("miles", ft * 5280, "miles")
# mass
lbm = new_unit("lbm", KG / 2.2046226, "pound-mass")
# force
lbf = new_unit("lbf", 4.4482216 * N, "pound-force")
kips = new_unit("kips", lbf * 1000.0, "kilopound")
ftkips = new_unit("ft-kip", ft * lbf * 1000.0, "foot-kips")
inkips = new_unit("in-kips", inch * lbf * 1000.0, "inch-kips")
k_in = new_unit("k_in", kips / inch, "kips per inch")
k_ft = new_unit("k_ft", kips / ft, "kips per foot")
p_in = new_unit("lb_in", lbf / inch, "pounds per inch")
p_ft = new_unit("lb_ft", lbf / ft, "pounds per foot")
# area
sf = new_unit("sf", ft**2, "square feet")
in2 = new_unit("in2", inch**2, "square inches")
in3 = new_unit("in3", inch**3, "cubic inches")
in4 = new_unit("in4", inch**4, "inches to fourth")
# pressure
p_sf = new_unit("p_sf", lbf / ft**2, "pounds per square foot")
p_si = new_unit("p_si", lbf / inch**2, "pounds per square inch")
k_sf = new_unit("k_sf", kips / ft**2, "kips per square foot")
k_si = new_unit("k_si", kips / inch**2, "kips per square inch")
# density
p_ci = new_unit("p_ci", lbf / inch**3, "pounds per cubic inch")
p_cf = new_unit("p_cf", lbf / ft**3, "pounds per cubic ft")
# time
hr = new_unit("hr", 60 * 60 * sec, "hours")
# velocity
mph = new_unit("mph", miles / hr, "miles per hour")
fps = new_unit("fps", ft / sec, "feet per second")

[10] rivt Python Dependencies#

The minimum Python version is 3.14. In addition to rivtlib, rivt packages include the following categories:

IDE and REPL	description
“pyzo>=4.20.0”	a lightweight IDE
“ipython>=8.16.2”	interactive Python shell
“ipykernel>=6.28.1”	Jupyter kernel for Python

Image and Compilation	description
“pyside6>=6.10.1”	QT bindings
“fastcore>=1.8.16”	code simplification
“pillow>=11.2.1”	image processing

Symbolic, Numerical Processing	description
“matplotlib>=3.10.1”	data visualization
“sympy>=1.13.3”	symbolic analysis
“numpy>=2.2.5”	numerical processing
“scipy>=1.16.3”	numerical analysis
“pandas>=2.2.3”	data analysis

Formatting	description
“tabulate>=0.9.0”	format tables
“docutils>=0.21.2”	reStructuredText processing
“reportlab>=4.4.0”	PDF document generation
“rst2pdf>=0.103.1”	PDF document generation
“pypdf>=1.0.3”	PDF document manipulation
“Sphinx>=8.2.3”	HTML/PDF doc generation
“pydata-sphinx-theme>=0.16.1”	HTML document generation
“sphinx-copybutton>=0.5.2”	HTML document generation
“sphinx_design>=0.6.1”	HTML document generation
“sphinx-favicon>=1.0.1”	HTML document generation
“sphinx-togglebutton>=0.3.2”	HTML document generation
“sphinxcontrib-applehelp>=2.0.0”	HTML document generation
“sphinxcontrib-devhelp>=2.0.0”	HTML document generation
“sphinxcontrib-email>=0.3.6”	HTML document generation
“sphinxcontrib-htmlhelp>=2.1.0”	HTML document generation
“sphinxcontrib-jquery>=4.1”	HTML document generation
“sphinxcontrib-jsmath>=1.0.1”	HTML document generation
“sphinxcontrib-qthelp>=2.0.0”	HTML document generation
“sphinxcontrib-serializinghtml>=2.0.0”	HTML document generation

API Scope	Command	Description
rv.V	a ==: 1*IN \| unit1, unit2, decimal \| label	[2] Define values \| ==:
rv.V	c <=: expression \| unit1, unit2, decimal \| label	[3] Assign expression values \| <=:
rv.V	c :=: func(x,y) \| unit1, unit2, decimal \| label	[4] Assign function values \| :=:
rv.V	a <= c \| unit, decimal, text1, text2 \| label	[5] Compare values \| <=