MotionSolve Subroutines

MotionSolve provides a subroutine interface for adding custom physics and behavior. Many modeling elements can reference user-written subroutines, which the solver invokes during simulation to evaluate your model. To make those subroutines practical, MotionSolve provides a small, fast utility layer you can call from within any user subroutine. The Utilities section lists these utilities.

Defining User Subroutines

MotionSolve accepts three forms of user subroutines when invoked by the msolve Python API:

1. Callable Python function (in-memory)

   • The function must be importable and present in the interpreter’s namespace.

   • Set routine to the callable object (unquoted).

   ptdsff = Ptdsff(
     i           = 30107780,
     dsurface    = 1,
     radius      = 10.0,
     force_model = "USERSUB",
     function    = "USER(100,30)",
     routine     = ptdsffsub
   )
   

2. Function defined in a Python script

   • The script must be discoverable by Python.

   • Provide the file via script=... and set routine to the function name as a quoted string.

   gra = UserGraphic(
     rm        = global_ref,
     increment = 4,
     function  = "USER(599)",
     script    = "usersubs.py",
     routine   = "my_grasub",
   )
   

3. Compiled routine in a shared library

   • The routine lives in a DLL/SO that the OS can load.

   • Set routine to a quoted string in the form "library::symbol".

   field2 = Field(
     id       = 200,
     i        = Marker(body=b1, qp=p0),
     j        = Marker(body=b2, qp=p1),
     function = "USER(1,2,3,4,5)",
     routine  = "msautoutils::fiesub",
   )
   

Notes

• Quoted routine values trigger name lookup ("my_grasub" or "lib::symbol"); an unquoted routine passes the Python callable directly.

• function="USER(...)" supplies user parameters to the subroutine and is independent of how routine is resolved.

• Ensure discoverability: Python callables/scripts on PYTHONPATH; shared libraries on the system’s loader path (for example, PATH or LD_LIBRARY_PATH). MotionSolve resolves and loads shared libraries as follows:

  • Environment variable MS_USERSUBDLL: Specifies the filename for the MotionSolve user-written subroutine DLL file.

  • Environment variable MS_USERDLL_DIR (may contain multiple paths; each is tried in sequence): Specifies the list of folders to be searched for the MotionSolve user-written subroutine DLLs/Python scripts.

Utilities

Use these utilities when your user subroutines need solver data or common math without re-implementing it. Most of these utilities act as Data Access calls and fetch runtime model parameters and states directly from MotionSolve, while general utilities (splines, polynomials, step) provide reliable signal and math helpers.

py_add_mass_property(cm1, mass1, ip1, cm2, mass2, ip2)

Combine mass properties of two bodies or body sets.

Parameters:

• cm1 (list[float]) – Length-3 [x, y, z] coordinates of the first body (or set) center of mass, in the global frame.

• mass1 (list[float] | float) – Mass of the first body (scalar) or masses of the body set.

• ip1 (list[float]) – Length-6 inertia components [Ixx, Iyy, Izz, Ixy, Ixz, Iyz] of the first body (or aggregate of the set), expressed at the body’s CM in a marker parallel to the global axes.

• cm2 (list[float]) – Length-3 [x, y, z] coordinates of the second body (or set) center of mass, in the global frame.

• mass2 (list[float] | float) – Mass of the second body (scalar) or masses of the body set.

• ip2 (list[float]) – Length-6 inertia components [Ixx, Iyy, Izz, Ixy, Ixz, Iyz] of the second body (or aggregate of the set), expressed at the body’s CM in a marker parallel to the global axes.

Returns:

(cm, mass, ip) for the combined set:

• cm: Length-3 [x, y, z] coordinates of the combined CM (global frame).

• mass: Total mass (scalar) or array for per-component aggregation, depending on inputs.

• ip: Length-6 inertia components [Ixx, Iyy, Izz, Ixy, Ixz, Iyz] for the combined set, expressed at the combined CM in a marker parallel to the global axes.

Return type:

tuple[list[float], float | list[float], list[float]]

py_akispl(xval, zval, id, iord)

Interpolate a Spline at (x, z) and optionally return first/second derivatives.

Parameters:

• xval (float) – First independent variable (x) where the spline is evaluated.

• zval (float) – Second independent variable (z) for surface splines; set to 0.0 for curve splines.

• id (int) – ID of the Spline element.

• iord (int) – Derivative order to return; one of {0, 1, 2}.

Returns:

(array, errflg)

• array: Vector of length up to 3.

  • When iord is 0: array[0] = y

  • When iord is 1: array[0] = ∂y/∂x, array[1] = ∂y/∂z

  • When iord is 2: array[0] = ∂²y/∂x², array[1] = ∂²y/∂x∂z, array[2] = ∂²y/∂z²

• errflg: True if the call failed; False on success.

Return type:

tuple[list[float], bool]

py_body_mass_property(type, id)

Return CM, mass, and inertia for a specified element or the entire model.

Parameters:

• type (str) – Element category; one of {‘Part’, ‘Point_Mass’, ‘Flex_Body’, ‘Model’}.

• id (int) – Element ID for the given type. For type == ‘Model’, set id = 0.

Returns:

(cm, mass, ip)

• cm: Length-3 [x, y, z] center-of-mass coordinates expressed in the global frame.

• mass: Mass of the requested element (global frame).

• ip: Length-6 inertia components [Ixx, Iyy, Izz, Ixy, Ixz, Iyz] expressed in the global frame.

Return type:

tuple[list[float], float, list[float]]

py_cubspl(xval, zval, id, iord)

Interpolate a Spline (cubic) at (x, z) and optionally return first/second derivatives.

Parameters:

• xval (float) – First independent variable (x) where the spline is evaluated.

• zval (float) – Second independent variable (z) for surface splines; set to 0.0 for curve splines.

• id (int) – ID of the Spline element.

• iord (int) – Derivative order to return; one of {0, 1, 2}.

Returns:

(array, errflg)

• array: Vector of length up to 3.

  • When iord is 0: array[0] = y

  • When iord is 1: array[0] = ∂y/∂x, array[1] = ∂y/∂z

  • When iord is 2: array[0] = ∂²y/∂x², array[1] = ∂²y/∂x∂z, array[2] = ∂²y/∂z²

• errflg: True if the call failed; False on success.

Return type:

tuple[list[float], bool]

py_errmes(errflg, message, id, endflg)

Emit a message to MotionSolve output and optionally terminate the solver.

Parameters:

• errflg (bool) – When True/non-zero, the message is emitted; otherwise no-op.

• message (str) – Text to print to the solver output/log files.

• id (int) – Identifier of the user-defined element invoking ERRMES (for attribution).

• endflg (str) – If ‘STOP’, the solver terminates after printing; any other value continues execution.

Returns:

No return value.

Return type:

None

py_fitspl(xval, zval, id, iord)

Uses a spline fitting method to return the interpolated value or the first/second derivative for a Spline element.

Parameters:

• xval (float) – First independent variable of the curve or surface.

• zval (float) – Second independent variable for a surface. Set to 0 for curve interpolation.

• id (int) – ID of the Reference_Spline element.

• iord (int) – Derivative order to return. Valid values are 0, 1, or 2.

Returns:

(array, errflg)

• array: Length-3 vector.

  • When iord is 0: array[0] is y (interpolated value)

  • When iord is 1: array[0] is ∂y/∂x and array[1] is ∂y/∂z

  • When iord is 2: array[0] is ∂²y/∂x², array[1] is ∂²y/∂x∂z, array[2] is ∂²y/∂z²

• errflg: False on success; True if an error occurred.

Return type:

tuple[list[float], bool]

py_get_contact_post(id, i_gra_id, j_gra_id, type, rm, index)

Query contact results for a Contact force element at a specific contact index.

Parameters:

• id (int) – ID of the Contact force modeling element.

• i_gra_id (int) – Graphic ID of the I body. Ignored for flexible bodies (any integer permitted).

• j_gra_id (int) – Graphic ID of the J body. Ignored for flexible bodies (any integer permitted).

• type (str) –

  Result to request. One of:

  • ’PD’: Penetration depth (scalar).

  • ’PD_VEL’: Penetration rate (scalar).

  • ’SLIP_VEL’: Slip velocity (scalar).

  • ’POS’: Contact point position (3-vector).

  • ’VEL’: Contact point velocity (3-vector).

  • ’NORMAL_FORCE’: Normal contact force (3-vector).

  • ’TANGENTIAL_FORCE’: Tangential contact force (3-vector).

  • ’TOTAL_FORCE’: Total contact force (3-vector).

  • ’HAS_TRIA_ID’: 1 if the geometry is tessellated; 0 otherwise (scalar flag).

  • ’TRIA_ID_I’: Triangle/element ID(s) on the I body (scalar or list).

  • ’TRIA_ID_J’: Triangle/element ID(s) on the J body (scalar or list).

  • ’INTERSECTION_ID’: Patch ID common to all points in the same contact patch (scalar).

• rm (int) – Reference marker ID used to express ‘POS’, ‘VEL’, ‘NORMAL_FORCE’, ‘TANGENTIAL_FORCE’, and ‘TOTAL_FORCE’. Ignored for other types.

• index (int) – 1-based contact index in the range [1 - py_get_ncontacts()] for the given contact at the current time.

Returns:

(result, errflg)

• result: Scalar, 3-vector, or list depending on ‘type’. Values are in model units where applicable.

• errflg: True if an error occurred; False on success.

Return type:

tuple[object, bool]

py_get_gravity()

Return gravitational acceleration components as defined in the model.

Parameters:

None –

Returns:

(gx, gy, gz)

• gx: X component of gravity (model units).

• gy: Y component of gravity (model units).

• gz: Z component of gravity (model units).

Return type:

tuple[float, float, float]

py_get_matrix_info(id)

Return metadata about a Matrix element.

Parameters:

id (int) – ID of the Matrix.

Returns:

(type, nrows, ncols, size, ierr)

• type: Matrix storage type:

  • 1: sparse

  • 2: full, row-order

  • 3: full, column-order

• nrows: Number of rows.

• ncols: Number of columns.

• size: Total entries:

  • sparse: number of nonzero entries

  • full: nrows * ncols

• ierr: Status code:

  • 0: success

  • 1: ID not found (call ignored)

Return type:

tuple[int, int, int, int, int]

py_get_ncontacts(id, i_gra_id, j_gra_id)

Return the number of active contacts for a Contact force at the current time step.

Parameters:

• id (int) – ID of the Contact modeling element.

• i_gra_id (int) – Graphic ID of the I body. Ignored for flexible bodies; any integer permitted.

• j_gra_id (int) – Graphic ID of the J body. Ignored for flexible bodies; any integer permitted.

Returns:

(ncontacts, errflg)

• ncontacts: Number of active contacts at the current simulation step.

• errflg: True if an error occurred; False on success.

Return type:

tuple[int, bool]

py_get_post_states(type, elem_id)

Extract the state vector for a specified element at the current post-processing step.

Parameters:

• type (str) – Element class. One of {‘PART’, ‘REQUEST’, ‘FLEX_BODY’, ‘POINT_MASS’, ‘FRF_INPUT’}.

• elem_id (int) – ID of the element whose states are requested.

Returns:

States array or None if states are unavailable.

Return type:

list[float] | None

Notes

State vector layout by element type:

TYPE	SIZE	STATES
PART	7	X, Y, Z, E0, E1, E2, E3 of LPRF frame
POINT_MASS	3	X, Y, Z of LPRF frame
FLEX_BODY	20+nmodes	X, Y, Z, E0, E1, E2, E3 (CG frame); velocities (6); accelerations (6); modal participation (nmodes); strain energy
REQUEST	8	Request values

States returned by a REQUEST during a Frequency Response Analysis depend on request type:

• DISPLACEMENT (12): X_MAG, X_PHASE, Y_MAG, Y_PHASE, Z_MAG, Z_PHASE, B1_MAG, B1_PHASE, B2_MAG, B2_PHASE, B3_MAG, B3_PHASE

• VELOCITY (12): VX_MAG, VX_PHASE, VY_MAG, VY_PHASE, VZ_MAG, VZ_PHASE, WX_MAG, WX_PHASE, WY_MAG, WY_PHASE, WZ_MAG, WZ_PHASE

• ACCELERATION (12): ACCX_MAG, ACCX_PHASE, ACCY_MAG, ACCY_PHASE, ACCZ_MAG, ACCZ_PHASE, WDTX_MAG, WDTX_PHASE, WDTY_MAG, WDTY_PHASE, WDTZ_MAG, WDTZ_PHASE

• FORCE (12): FX_MAG, FX_PHASE, FY_MAG, FY_PHASE, FZ_MAG, FZ_PHASE, TX_MAG, TX_PHASE, TY_MAG, TY_PHASE, TZ_MAG, TZ_PHASE

• EXPRESSION (16): F1_MAG, F1_PHASE, F2_MAG, F2_PHASE, F3_MAG, F3_PHASE, F4_MAG, F4_PHASE, F5_MAG, F5_PHASE, F6_MAG, F6_PHASE, F7_MAG, F7_PHASE, F8_MAG, F8_PHASE

py_get_step_info()

Return the phase flag for the current simulation step.

Parameters:

None –

Returns:

Step flag:

• 0: converged step

• 1: predictor step

• 2: corrector step

• -1: not a transient analysis

Return type:

int

py_getidlist(type, arylen)

Return the IDs of model entities of a specified type.

Parameters:

• type (str) –

  Entity category. One of:

  • ’PART’: Rigid bodies (Part).

  • ’POINT_MASS’: Point masses (PointMass).

  • ’FLEX_BODY’: Flexible bodies (FlexBody).

  • ’VFORCE’: Vector forces (Vforce).

  • ’VTORQUE’: Vector torques (Vtorque).

  • ’GFORCE’: General forces (Gforce).

  • ’YFORCE’: Control forces (Yforce).

  • ’SFORCE’: Scalar forces (Sforce).

  • ’REQUEST’: Output requests (Request).

  • ’PLANT_INPUT’: Plant inputs (Pinput).

  • ’PLANT_OUTPUT’: Plant outputs (Poutput).

• arylen (int) – Size of the output array. Typically set to py_getnumid(type).

Returns:

(idary, errflg)

• idary: List of entity IDs for the specified type; length is up to arylen.

• errflg: True if an error occurred; False on success.

Return type:

tuple[list[int], bool]

py_getmod()

Return the current analysis mode identifier.

Parameters:

None –

Returns:

Mode code indicating the analysis type:

• 1: Kinematics analysis

• 2: Reserved

• 3: Reserved

• 4: Dynamics analysis

• 5: Statics analysis

• 6: Quasi-statics analysis

• 7: Linear analysis

• 9: CONSUB initialization

• 10: Frequency response analysis

• 35: Assembly

Return type:

int

py_getnumid(type)

Return the number of model entities of a specified type.

Parameters:

type (str) –

Entity category. One of:

• ’PART’: Rigid bodies (Part).

• ’POINT_MASS’: Point masses (PointMass).

• ’FLEX_BODY’: Flexible bodies (FlexBody).

• ’VFORCE’: Vector forces (Vforce).

• ’VTORQUE’: Vector torques (Vtorque).

• ’GFORCE’: General forces (Gforce).

• ’YFORCE’: Control forces (Yforce).

• ’SFORCE’: Scalar forces (Sforce).

• ’REQUEST’: Output requests (Request).

• ’PLANT_INPUT’: Plant inputs (Pinput).

• ’PLANT_OUTPUT’: Plant outputs (Poutput).

Returns:

Count of entities of the specified type in the current model.

Return type:

int

py_getstm()

Return the current simulation time.

Parameters:

None –

Returns:

Current simulation time (model time units).

Return type:

float

py_gtaray(id)

Retrieve values stored in an Array.

Parameters:

id (int) – ID of the Array.

Returns:

(array, istat)

• array: Values extracted from the Array (double precision).

• istat: Status code:

  • 0: success

  • -1: incorrect Array type

  • -2: Array not found

Return type:

tuple[list[float], int]

py_gtcmat(mkid)

Compute the compliance matrix between a set of Markers.

Parameters:

mkid (list[int]) – IDs of the Markers.

Returns:

(cmat, istat)

• cmat: Compliance matrix as an array of shape (6*NM, 6*NM) where NM is the number of Markers.

• istat: Status code indicating success or reason for failure.

Return type:

tuple[list[list[float]], int]

py_gtcurv()

py_gtcrv(id, alpha, iord) Evaluate a ParamCurve at parameter alpha and optionally return derivatives.

Parameters:

• id (int) – ID of the ParamCurve.

• alpha (float) – Independent parameter. For B-splines, -1 <= alpha (α) <= 1. For CURSUB-defined curves, MINPAR <= alpha <= MAXPAR.

• iord (int) – Derivative order. 0: coordinates; 1: first derivatives; 2: second derivatives.

Returns:

(array, istat)

• array: Length-3 result, all evaluated at alpha:

  • When iord is 0: [x, y, z]

  • When iord is 1: [∂x/∂α, ∂y/∂α, ∂z/∂α]

  • When iord is 2: [∂²x/∂α², ∂²y/∂α², ∂²z/∂α²]

• istat: Status code indicating success or reason for failure.

Return type:

tuple[list[float], int]

py_gtinam()

Return the base name of the MotionSolve input file.

Returns:

Input file name.

Return type:

str

py_gtonam()

Return the base name of the MotionSolve output file.

Returns:

Output file base name.

Return type:

str

py_gtstrg(id)

Retrieve the value stored in a String.

Parameters:

id (int) – ID of the String.

Returns:

(string, istat)

• string: The requested string value.

• istat: Status code:

  • 0: success

  • -2: String not found

Return type:

tuple[str, int]

py_gtunts()

Retrieve model unit settings and SI conversion factors.

Parameters:

None –

Returns:

(exist, scales, units)

• exist: True if units are explicitly set for the model.

• scales: Conversion factors from model units to SI in the order [time, length, force, mass].

• units: Abbreviations for model units in the order [time, length, force, mass] (two-character abbreviations where applicable).

Return type:

tuple[bool, list[float], list[str]]

py_havsin(x, x0, h0, x1, h1, irod)

Evaluate a Haversine smooth step between (x0, h0) and (x1, h1); optionally return derivatives.

Parameters:

• x (float) – Independent variable (for example, time).

• x0 (float) – Start abscissa where the transition begins.

• h0 (float) – Function value at x0.

• x1 (float) – End abscissa where the transition ends.

• h1 (float) – Function value at x1.

• iord (int) – Derivative order to return; one of {0, 1, 2}.

Returns:

(value, errflg)

• value: Quantity at x

  • When iord is 0: function value

  • When iord is 1: first derivative with respect to x

  • When iord is 2: second derivative with respect to x

• errflg: True if an error was detected; False on success.

Return type:

tuple[float, bool]

py_impact(x, xd, x1, k, e, cmax, d, irod)

Evaluate a unilateral impact/contact function with optional derivatives.

Parameters:

• x (float) – Independent variable (for example, deformation or gap).

• xd (float) – Time derivative of x.

• x1 (float) – Lower bound of x. If x < x1, the function returns a positive value; otherwise it returns 0.

• k (float) – Stiffness of the boundary interaction; must be non-negative.

• e (float) – Exponent of the force–deformation characteristic; must be positive. (>1 stiffening, <1 softening.)

• cmax (float) – Maximum damping coefficient; must be non-negative.

• d (float) – Penetration at which full damping (cmax) is applied; must be positive.

• iord (int) – Derivative order to return; one of {0, 1, 2}.

Returns:

(value, errflg)

• value: Requested quantity at x

  • When iord is 0: function value

  • When iord is 1: first derivative with respect to x

  • When iord is 2: second derivative with respect to x

• errflg: True if an error was detected; False on success.

Return type:

tuple[float, bool]

py_linspl(xval, zval, id, iord)

Linearly interpolate a Spline at (x, z) and optionally return first/second derivatives.

Parameters:

• xval (float) – First independent variable (x) where the spline is evaluated.

• zval (float) – Second independent variable (z) for surface splines; set to 0.0 for curve splines.

• id (int) – ID of the Spline element.

• iord (int) – Derivative order to return; one of {0, 1, 2}.

Returns:

(array, errflg)

• array: Vector of length up to 3.

  • When iord is 0: array[0] = y

  • When iord is 1: array[0] = ∂y/∂x and array[1] = ∂y/∂z

  • When iord is 2: array[0] = ∂²y/∂x², array[1] = ∂²y/∂x∂z, array[2] = ∂²y/∂z²

• errflg: False on success; True if the call failed.

Return type:

tuple[list[float], bool]

py_modinf(id)

Retrieve active mode numbers and modal frequencies for a flexible body.

Parameters:

id (int) – ID of the FlexBody.

Returns:

(mode, freq, errflg)

• mode: List of mode numbers for all active modes.

• freq: Modal frequencies, in cycles per time unit, aligned with mode.

• errflg: True if an error occurred; False on success.

Return type:

tuple[list[int], list[float], bool]

py_nmodes(id)

Retrieve the total number of modal generalized coordinates for a flexible body.

Parameters:

id (int) – ID of the FlexBody.

Returns:

(nq, errflg)

• nq: Total number of modal generalized coordinates for the flexible body.

• errflg: True if an error occurred; False on success.

Return type:

tuple[int, bool]

py_poly(x, x0, par, iord)

Evaluate a polynomial in (x - x0) with optional derivatives.

Parameters:

• x (float) – Independent variable (for example, time).

• x0 (float) – Shift applied to the independent variable.

• par (list[float]) – Coefficients [c0, c1, …, c_{n-1}]; length defines the polynomial order.

• iord (int) – Derivative order to return; one of {0, 1, 2}.

Returns:

(value, errflg)

• value: Quantity at x.

  • When iord is 0: polynomial value

  • When iord is 1: first derivative with respect to x

  • When iord is 2: second derivative with respect to x

• errflg: False or 0 on success; True or nonzero on error.

Return type:

tuple[float, bool]

py_put_marker(id, pos, angle_type, angle)

Set marker position and orientation.

Parameters:

• id (int) – ID of the Marker element.

• pos (list[float]) – Length-3 coordinate components specifying the location of the Marker.

• angle_type (int) –

  Specifies the type of angle being passed in the angle argument. One of:

  • 0: Direction Cosine Matrix

  • 1: Euler angles

  • 2: Yaw, Pitch, Roll (YPR)

  • 3: Euler parameters

• angle (list[float]) –

  An array containing angles or parameters that set the orientation of the marker.

  • When angle is 0: Length-6 array containing the x, z direction cosine columns. y direction cosine is computed internally using a cross product between x, z.

  • When angle is 1: Length-3 array containing the Euler angles (Body 3-1-3)

  • When angle is 2: Length-3 array containing the YPR angles (Body 3-2-1)

  • When angle is 4: Length-4 array containing Euler parameters

Returns:

errflg

• errflg: True if an error occurred; False on success.

Return type:

int

py_put_spline(id, nx, nz, x, y, z)

Store Spline data.

Parameters:

• id (int) – ID of the Spline element.

• nx (int) – The number of elements in the array x. Must be greater than or equal to 4.

• nz (int) – The number of elements in the array Z. Must be greater than or equal to 1.

• x (float) – An array containing x values of the Spline. Length must be greater than or equal to nx.

• y (float) – An array containing x values of the Spline. Length must be greater than or equal to nx * nz.

• z (float) – An array containing x values of the Spline. Length must be greater than or equal to nz.

Returns:

errflg

• errflg: True if an error occurred; False on success.

Return type:

int

py_quispl(xval, zval, id, iord)

Interpolate a Spline (quintic) at (x, z) and optionally return first/second derivatives.

Parameters:

• xval (float) – First independent variable (x) where the spline is evaluated.

• zval (float) – Second independent variable (z) for surface splines; set to 0.0 for curve splines.

• id (int) – ID of the Spline element.

• iord (int) – Derivative order to return; one of {0, 1, 2}.

Returns:

(array, errflg)

• array: Vector of length up to 3.

  • When iord is 0: array[0] = y

  • When iord is 1: array[0] = ∂y/∂x, array[1] = ∂y/∂z

  • When iord is 2: array[0] = ∂²y/∂x², array[1] = ∂²y/∂x∂z, array[2] = ∂²y/∂z²

• errflg: True if the call failed; False on success.

Return type:

tuple[list[float], bool]

Notes

QUISPL is a quintic, spline-based interpolation (5th order) that requires a minimum of six points on a curve.

py_rcnvrt(sys1, coord1, sys2)

Convert rotational coordinates between supported representations.

Parameters:

• sys1 (str) – Input rotational coordinate system (per MotionSolve documentation).

• coord1 (list[float]) – Input rotational coordinates; angles should be in radians where applicable.

• sys2 (str) – Output rotational coordinate system (per MotionSolve documentation).

Returns:

(coord2, istat)

• coord2: Converted rotational coordinates; angles are in radians where applicable.

• istat: Status code:

  • 0: success in conversion

  • -10: error in conversion (for example, misspelled sys1 or sys2)

Return type:

tuple[list[float], int]

py_set_dae_error(error)

Set the integration error tolerance for the DSTIFF (and FIM_D) DAE integrator.

Parameters:

error (float) – Error tolerance; must be greater than 0.

Returns:

No return value.

Return type:

None

Notes

Usable from a TUNSUB to adjust the integrator’s error tolerance on the fly to balance accuracy and performance during simulation.

py_set_dae_hmax(hmax)

Set the maximum step size (h_max) for the DSTIFF DAE integrator.

Parameters:

hmax (float) – Maximum step size; must be greater than 0.

Returns:

No return value.

Return type:

None

Notes

Can be called from a TUNSUB to adjust DSTIFF’s maximum time step on the fly during a transient simulation.

py_set_discrete_interface()

Request discrete calls to a user subroutine at successful integration steps.

py_sysary(fncnam, ipar)

Obtain system states (e.g., displacement, velocity) for use inside user subroutines.

Parameters:

• fncnam (str) – Name of the SYSARY function to evaluate (per MotionSolve documentation).

• ipar (list[float]) – Real-valued input parameters for fncnam.

Returns:

(states, errflg)

• states: Returned values; length and meaning depend on fncnam.

• errflg: False or 0 on success; True or nonzero on error.

Return type:

tuple[list[float], bool]

py_sysfnc(fncnam, ipar)

Query a single system state inside a user subroutine.

Parameters:

• fncnam (str) – Name of the system function to query. Valid names are per MotionSolve documentation.

• ipar (list[float]) – Real-valued input parameters for the specified function.

Returns:

(state, errflg)

• state: Real value returned by the function.

• errflg: False or 0 on success; True or nonzero on error.

Return type:

tuple[float, bool]

py_tcnvrt(sys1, coord1, sys2)

Convert coordinates between CARTESIAN, SPHERICAL, and CYLINDRICAL systems.

Parameters:

• sys1 (str) – Input coordinate system. One of {‘CARTESIAN’, ‘SPHERICAL’, ‘CYLINDRICAL’}.

• coord1 (list[float]) –

  Input coordinates (length 3), interpreted by sys1 as:

  • CARTESIAN: [x, y, z]

  • SPHERICAL: [rho, phi, theta] # angles in radians

  • CYLINDRICAL: [r, theta, z] # theta in radians

• sys2 (str) – Output coordinate system. One of {‘CARTESIAN’, ‘SPHERICAL’, ‘CYLINDRICAL’}.

Returns:

(coord2, istat)

• coord2: Converted coordinates expressed in sys2 (angles in radians).

• istat: Status code indicating success or reason for failure.

Return type:

tuple[list[float], int]

py_timget()

Return the last successful integration time.

Parameters:

None –

Returns:

Last successful integration time (model time units).

Return type:

float

py_usrmes(msgflg, message, id, msgtyp)

Emit a user-defined message with selectable type and destination.

Parameters:

• msgflg (bool) – When True or non-zero, the message is emitted; otherwise no-op.

• message (str) – Text to print to MotionSolve outputs.

• id (int) – Identifier of the invoking user-defined element.

• msgtyp (str) –

  Message type. One of:

  • ’INFO’: Information

  • ’INFO_NOPAD’: Information without the standard ‘USERMES: USER [id]’ prefix

  • ’INFO_LOG’: Information written only to the LOG file (not to screen)

  • ’WARN’: Warning

  • ’WARN_NOPAD’: Warning without the standard prefix

  • ’WARN_LOG’: Warning written only to the LOG file (not to screen)

  • ’ERROR’: Error

  • ’FAULT’: Fatal error

Returns:

No return value.

Return type:

None

Notes

Unsupported msgtyp values are treated as ‘INFO’.