How to set up a new item

A new node, object, marker, load or sensor. Short: write the definition, generate, write the .cpp, build, test. The details of each part are in the documents linked here; this page says what to do in which order.

0. First in Python

Try the model with the generic items and user functions: ObjectGenericODE2/ODE1 with user functions for a body or a system, ObjectConnectorCoordinateVector for a constraint, a spring-damper with a force user function for a connector, SensorUserFunction for a sensor. A C++ item is worth it when that prototype works and is too slow.

1. How it works

An item is one ItemDefinition(...) in definitions/itemDefs<Kind>.py. The generators read it and write everything that follows from it; the computation is hand-written C++.

written	for item ObjectMyBody of kind Object	by
the definition	definitions/itemDefsObjects.py	you
C++ headers: parameters, the three classes	src/Autogenerated/objects/CObjectMyBody.h, MainObjectMyBody.h, VisuObjectMyBody.h	generator
registration in the object factory: mbs.AddObject({'objectType':'MyBody', ...}) creates the three	src/Autogenerated/objectFactoryAutoReg.h (ARCHITECTURE.md)	generator
the Python class ObjectMyBody (and its short name) and the typed stub	python/exudyn/itemInterface.py, python/exudyn/types/items.py	generator
the reference manual page, and the item in the index of its kind	docs/generated/items/ObjectMyBody.md	generator
the MiniExample file and its entry in the list the test suite runs	python/MiniExamples/ObjectMyBody.py, miniExamplesFileList.py	generator
the computation, the output variables and the drawing (UpdateGraphics)	src/ImplObjects/CObjectMyBody.cpp; loads in src/System/CLoad.cpp, sensors in src/System/CSensor.cpp	you
the checks before assembly, if the definition declares CheckPreAssembleConsistency	src/System/checkPreAssembleConsistencies<Kind>.cpp	you
a new .cpp in the build	msvc/cppsrc.vcxproj, then python tools/gen_sources.py writes sources.json	you
the reference value of the MiniExample	python/testing/runTestSuiteRefSol.py, MiniExamplesReferenceSolution	you

Never edit a generated file; a hand edit is overwritten by the next generation.

2. The definition

Copy the definition of the item that is most like yours, in the same file, and change it. The vocabulary is in definitions/README.md.

• Header: className, classType, objectType (objects), the parents cParentClass, mainParentClass, visuParentClass, pythonShortName.

• Parameters: ItemParameter(type=..., destination=..., pythonName=..., defaultValue=..., description=...). A description that starts with a symbol in $...$ puts the symbol into the table, (symbol: ...).

• Functions: ItemFunctionDef('Name') for a function that overrides a base-class function - the declaration comes from the library; implementation= for a one-line body, otherwise the body is in your .cpp. ItemFunction(...) for a function new in this item. Each with a description where it is not obvious.

• Types: what the item provides and needs - ItemTypes, ItemRequestedTypes, ItemAccessFunctionTypes() (objects: the types are derived from the access functions the object provides; ownMarkers= for a super element or kinematic tree with markers of its own), requestedNodeTypes (node markers). They decide which items fit together; Assemble() checks them, and the page lists the fitting items from them.

• outputVariables: ItemOutputVariable(OVPosition, r"""$symbol$description""") for every output variable; the generator writes GetOutputVariableTypes from the list, you implement GetOutputVariable... for exactly these.

• overallDescription: one or two sentences, what it is and what for.

• detailedDescription: the equations - headings and contents by kind in definitions/README.md §The page of an item, the rules of the text in §Writing a description.

• miniExample: a short model that uses the item and sets exu.sys['testResult']; rules in §The mini example.

• optional: createFunctions, examples (§The page of an item).

3. Generate

In venvExuP313:

python tools/regenerate.py --check     # validates the definitions, generates, reports what changed
exudev generate --all-checks           # the same with all checks

The validator fails on a function that overrides nothing, a wrong type, a description that breaks the text rules. Then read the page, docs/generated/items/<Item>.md.

4. The C++

Copy the .cpp of the same item as in step 2 and rewrite its functions; the class declarations are in the generated headers.

kind	functions to implement
body	ComputeMassMatrix, ComputeODE2LHS, the access functions GetPositionJacobian, GetRotationJacobian, GetMassWeightedPositionJacobian, GetJacobianTransposedTimesVectorDerivative (how a force or torque reaches the body; each gives the body its access function type, derived by ItemAccessFunctionTypes()) and IsValidLocalPosition where they are defined at restricted local positions only, GetOutputVariableBody, GetPosition, GetVelocity, … as far as they apply, GetAvailableJacobians
connector	ComputeODE2LHS (the forces on the markers), ComputeJacobianODE2_ODE2 unless GetAvailableJacobians says it is not a function, GetOutputVariableConnector
constraint	ComputeAlgebraicEquations, ComputeJacobianAE, GetOutputVariableConnector
node	GetPosition, GetVelocity, …, GetOutputVariable
marker	ComputeMarkerData (values and Jacobians), GetPosition, …
load	GetLoadVector or GetLoadValue
sensor	GetSensorValues
every item	UpdateGraphics of Visualization<Item>, in the same .cpp

Checks of parameters and of the items it is attached to go into CheckPreAssembleConsistency, with a message that names the parameter; errors raised from C++ follow CODING_STYLE.md §10.

5. Build and test

exudev build --env venvExuP313
exudev test --env venvExuP313          # runs the MiniExample; add its value to runTestSuiteRefSol.py

A test model in python/TestModels/ for what the MiniExample does not cover (WORKFLOW.md §What a test model looks like); then the four gates of WORKFLOW.md.