$\newcommand{\deriv}[2][]{\dfrac{\partial #1}{\partial #2}} \newcommand{\tderiv}[2][]{\tfrac{\partial #1}{\partial #2}} \newcommand{\fderiv}[2][]{\dfrac{d #1}{d #2}} \newcommand{\derivII}[3][]{\dfrac{\partial^2 #1}{\partial #2 \partial #3}} \newcommand{\tderivII}[3][]{\tfrac{\partial^2 #1}{\partial #2 \partial #3}} \newcommand{\derivIII}[4][]{\dfrac{\partial^3 #1}{\partial #2 \partial #3 \partial #4}} \newcommand{\tderivIII}[4][]{\tfrac{\partial^3 #1}{\partial #2 \partial #3 \partial #4}} \newcommand{\derivIV}[5][]{\dfrac{\partial^4 #1}{\partial #2 \partial #3 \partial #4 \partial #5}} \newcommand{\half}{\tfrac{1}{2}} % Macro for 1/2 \newcommand{\ud}{\mathrm{d}} \newcommand{\op}{\circ} \newcommand{\dq}{\dot{q}} \newcommand{\ddq}{\ddot{q}} \newcommand{\dt}{\Delta t}$

Potential – Base Class for Potential Energies

class trep.Potential(system[, name=None])

Parameters:

• system (System) – An instance of System to add the potential to.
• name – A string that uniquely identifies the potential energy.

This is the base class for all potential energies in a System. It should never be created directly. Potential energies are created by instantiating a specific type of potential energy.

See trep.potentials - Potential Energies for the built-in types of potential energy. Additional potentials can be added through either the Python or C-API.

Potential energies represent conservative forces in a mechanical system like gravity and springs. Implementing these forces as potentials energies instead of generalized forces will result in improved simulations with better energetic and momentum conserving properties.

Potential Objects

Potential.system

The System that this potential belongs to.

(read-only)

Potential.name

The name of this potential energy or None.

Potential.V()

Return type:Float

Return the value of this potential energy at the system’s current state. This function should be implemented by derived Potentials.

Required for Calculations

Desired Calculation	Required
Continuous Dynamics	n
1st Derivative	n
2nd Derivative	n
Discrete Dynamics	n
1st Derivative	n
2nd Derivative	n

Note

This actual potential value is not used in discrete or continuous time dynamics/derivatives, so you do not need to implement it unless you need it for your own calculations. However, implementing it allows one to compare the derivative V_dq() with a numeric approximation based on V() to help debug your potential.

Potential.V_dq(q1)

Parameters:q1 (Config) – Derivative variable Return type:Float

Return the derivative of V with respect to q1.

Required for Calculations

Desired Calculation	Required
Continuous Dynamics	Y
1st Derivative	Y
2nd Derivative	Y
Discrete Dynamics	Y
1st Derivative	Y
2nd Derivative	Y

Potential.V_dqdq(q1, q2)

Parameters:

• q1 (Config) – Derivative variable
• q2 (Config) – Derivative variable

Return type:

Float

Return the second derivative of V with respect to q1 and q2.

Required for Calculations

Desired Calculation	Required
Continuous Dynamics	n
1st Derivative	Y
2nd Derivative	Y
Discrete Dynamics	Y
1st Derivative	Y
2nd Derivative	Y

Potential.V_dqdqdq(q1, q2, q3)

Parameters:

• q1 (Config) – Derivative variable
• q2 (Config) – Derivative variable
• q3 (Config) – Derivative variable

Return type:

Float

Return the third derivative of V with respect to q1, q2, and q3.

Required for Calculations

Desired Calculation	Required
Continuous Dynamics	n
1st Derivative	n
2nd Derivative	Y
Discrete Dynamics	n
1st Derivative	n
2nd Derivative	Y

Verifying Derivatives of the Potential

It is important that the derivatives of V() are correct. The easiest way to check their correctness is to approximate each derivative using numeric differentiation. These methods are provided to perform this test. The derivatives are only compared at the current configuration of the system. For improved coverage, try running each test several times at different configurations.

Potential.validate_V_dq(delta=1e-6, tolerance=1e-6, verbose=False)

Potential.validate_V_dqdq(delta=1e-6, tolerance=1e-6, verbose=False)

Potential.validate_V_dqdqdq(delta=1e-6, tolerance=1e-6, verbose=False)

Parameters:

• delta – Amount to add to each configuration
• tolerance – Acceptable difference between the calculated and approximate derivatives
• verbose – Boolean to print error and result messages.

Return type:

Boolean indicating if all tests passed

Check the derivatives against the approximate numeric derivative calculated from one less derivative (i.e,, approximate V_dq() from V() and V_dqdq() from V_dq()).

See System.test_derivative_dq() for details of the approximation and comparison.

Visualization

Potential.opengl_draw()

Draw a representation of this potential energy in the current OpenGL context. The OpenGL coordinate frame will be in the System’s root coordinate frame.

This function is called by the automatic visualization tools. The default implementation does nothing.