G.1 | Quick Ref#
[1] API#
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 |
Execute shell scripts and external programs |
rv.D (rS) |
Doc |
Publish docs |
rv.S;X (rS) |
Skip |
Skip section or exit (comments and debugging) |
where rS is a rivt string. The first line of a rivt string (rS) is the header substring.
Header Defaults
rv._(r"""Section Label
Content text and rivt markup - indented four spaces.
...
""")
Header Modifications
rv._(r"""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 settings
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
text - literal text
rst - reStructuredText
html - HTML markup
mermaid - Mermaid diagram (requires mermaid installation)
latex - LaTeX (requires LaTeX installation)
[4] Assignment Summary#
Assign values to expressions
API Scope |
Command |
Description |
|---|---|---|
rv.V |
a ==: 1*IN | unit1, unit2, decimal | label |
|
rv.V |
c <=: expression | unit1, unit2, decimal | label |
|
rv.V |
c :=: func(x,y) | unit1, unit2, decimal | label |
|
rv.V |
a <= c | unit, decimal, text1, text2 | label |
[5] Commands#
Read and format files
API Scope |
Command |
Description |
|---|---|---|
rv.R |
| COPY | abs src path | abs dest path | file pattern |
|
rv.R |
| SHELL | abs path | os, wait |
|
rv.I, V |
| TABLE | file name | title,width,head;nohead,num;non |
|
rv.I, V |
| IMAGE | file name | caption, scale, num;non, time;not |
|
rv.I, V |
| IMAGE2 | file1, file2 | c1,c2,s1,s2,n1,n2 |
|
rv.V |
| VALTABLE | file name | title, width, num;non |
|
rv.V |
| VALSTOR | file name | title, width, num;non |
|
rv.V |
| FUNCTION | function, arg, var, type | label |
|
rv.D |
| ATTACHPDF | file name | front;back, title |
|
rv.D |
| PUBLISH | doc title | type |
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
[5] rivt 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
...
[6] 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
...
[7] 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")
[8] 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 |
[9] VSCode Profile#
Workspace extension and other settings are stored in the .vscode folder and should be included as part of a report folder. Settings that affect the rivt editing and execution environment incldue:
rivt.code-snippets
settings.json (extension settings)
tasks.json
launch.json
Global settings can be exported and imported using VSCode Profiles. VSCode rivt extensions and settings may be installed from this link.
Snippets and extensions
Extension |
description |
|---|---|
BUTTONS |
— |
tombonnike.vscode-status-bar-format-toggle |
format button |
gsppvo.vscode-commandbar |
command buttons |
AdamAnand.adamstool |
command buttons |
nanlei.save-all |
save all button |
Ho-Wan.setting-toggle |
toggle settings |
yasukotelin.toggle-panel |
toggle panel |
fabiospampinato.vscode-commands |
user command buttons |
jerrygoyal.shortcut-menu-bar |
menu bar |
EDITING |
— |
henryclayton.context-menu-toggle-comments |
toggle comments |
TroelsDamgaard.reflow-paragraph |
wrap paragraph |
streetsidesoftware.code-spell-checker |
spell check |
jmviz.quote-list |
quote elements in a list |
njpwerner.autodocstring |
insert doc string |
oijaz.unicode-latex |
unicode symbols from latex |
jsynowiec.vscode-insertdatestring |
insert date string |
janisdd.vscode-edit-csv |
csv editor |
VIEWS |
— |
GrapeCity.gc-excelviewer |
excel viewer |
SimonSiefke.svg-preview |
svg viewer |
tomoki1207.pdf |
pdf viewer |
RandomFractalsInc.vscode-data-preview |
data viewing tools |
Fr43nk.seito-openfile |
open file from path |
vikyd.vscode-fold-level |
line folding tool |
file-icons.file-icons |
icon library |
tintinweb.vscode-inline-bookmarks |
inline bookmarks |
MANAGEMENT |
— |
alefragnani.project-manager |
folder, project management |
Anjali.clipboard-history |
clipboard history |
dionmunk.vscode-notes |
notepad |
hbenl.vscode-test-explorer |
test explorer |
mightycoco.fsdeploy |
save file to second location |
lyzerk.linecounter |
count lines in files |
sandcastle.vscode-open |
open files in default app |
zjffun.snippetsmanager |
snippet manager |
spmeesseman.vscode-taskexplorer |
task explorer |
GITHUB |
— |
GitHub.codespaces |
run files in codespaces |
GitHub.remotehub |
run remote files |
ettoreciprian.vscode-websearch |
search github within VSCode |
donjayamanne.githistory |
git history |
MichaelCurrin.auto-commit-msg |
git auto commit message |
github.vscode-github-actions |
github actions |
GitHub.vscode-pull-request-github |
github pull request |
k9982874.github-gist-explorer |
gist explorer |
vsls-contrib.gistfs |
gist tools |
PYTHON |
— |
ms-python.autopep8 |
python pep8 formatting |
ms-python.isort |
python sort imports |
donjayamanne.python-environment-manager |
python library list |
ms-python.python |
python tools |
ms-python.vscode-pylance |
python language server |
ms-toolsai.jupyter |
jupyter tools |
ms-toolsai.jupyter-keymap |
jupyter tools |
ms-toolsai.jupyter-renderers |
jupyter tools |
ms-toolsai.vscode-jupyter-cell-tags |
jupyter tools |
ms-toolsai.vscode-jupyter-slideshow |
jupyter tools |
LANGUAGES |
— |
qwtel.sqlite-viewer |
sqlite tools |
RDebugger.r-debugger |
R tools |
REditorSupport.r |
R tools |
ms-vscode-remote.remote-wsl |
windows linux tools |
James-Yu.latex-workshop |
latex tools |
lextudio.restructuredtext |
restructured text tools |
trond-snekvik.simple-rst |
restructured syntax |
yzane.markdown-pdf |
markdown to pdf |
yzhang.markdown-all-in-one |
markdown tools |
Keystrokes |
Description |
|---|---|
api |
insert import statement for API |
rvr |
API Run |
rvi |
API Insert |
rvv |
API Values |
rvt |
API Tools |
rvd |
API Docs |
at
|
attach command |
im
|
image command |
i2
|
side by side image command |
pu
|
publish command |
ta
|
table command |
va
|
value command |
vs
|
value table command |
_ce |
center bold line of text |
_ma |
utf-8 text math |
_la |
LaTeX math |
_ta |
number table |
_ur |
URL link |
_gl |
glossary term link |
_se |
section link |
_en |
endnote link |
_do |
download link |
_[m |
markup block |
_[p |
python block |
_[e |
end block |
Modified Keyboard Shortcuts
Keystroke |
Description |
|---|---|
alt+q |
rewrap paragraph with hard line feeds (80 default) |
alt+p |
open file under cursor |
alt+. |
select correct spelling under cursor |
alt+8 |
insert date |
alt+9 |
insert time |
ctl+1 |
focus on first editor |
ctl+2 |
focus on next editor |
ctl+3 |
focus on previous editor |
ctl+8 |
focus on explorer pane |
ctl+9 |
focus on github pane |
ctl+alt+x |
reload window |
ctl+alt+u |
unfold all code |
ctl+alt+f |
fold code level 2 (rivt sections visible) |
ctl+alt+a |
fold code - all levels |
ctl+alt+t |
toggle local fold |
ctl+alt+e |
toggle explorer sort order |
ctl+alt+s |
toggle spell check |
ctl+alt+g |
next editor group |
ctl+shift+u |
open URL under cursor in browser |
ctl+shift+s |
open GitHub rivt README search |
ctl+shift+a |
commit all |
ctl+shift+z |
commit current editor |
ctl+shift+x |
post to remote |