SimulationSettings

Simulation settings

This section includes hierarchical structures for simulation settings, e.g., time integration, static solver, Newton iteration and solution file export.

SolutionFileExportSettings

The quantities written into the coordinates solution file in addition to the coordinates.

Reached as simulationSettings.solution.file.export.

SolutionFileExportSettings has the following items:

name	type	default	description
accelerations	bool	True	add ODE2 accelerations to the solution file
algebraicCoordinates	bool	True	add algebraicCoordinates (=Lagrange multipliers) to the solution file
dataCoordinates	bool	True	add DataCoordinates to the solution file
ODE1Velocities	bool	True	add coordinatesODE1_t to the solution file
velocities	bool	True	add ODE2 velocities to the solution file

SolutionFileSettings

The coordinates solution file: all coordinates of the system versus time, read by the SolutionViewer and exudyn.utilities.LoadSolutionFile.

Reached as simulationSettings.solution.file.

SolutionFileSettings has the following items:

name	type	default	description
export	SolutionFileExportSettings		which quantities are written in addition to the coordinates
append	bool	False	flag (true/false); if true, the solution and the solver information are appended to existing files (otherwise created); in BINARY mode, files are always replaced and this parameter is ineffective!
binary	bool	False	if true, the solution file is written in binary format for improved speed and smaller file sizes; setting solution.precision >= 8 uses double (8 bytes), otherwise float (4 bytes) is used; note that append is ineffective and files are always replaced without asking! If not provided, file ending will read .sol in case of binary files and .txt in case of text files
flushAboveCoordinates	PInt	10000	number of coordinates above which the buffers of the solution file are always flushed, irrespectively of solution.flushFilesImmediately; for larger files, writing takes so much time that flushing does not add considerable time
information	String	‘’	special information added to header of solution file (e.g. parameters and settings, modes, …); character encoding my be UTF-8, restricted to characters in Character encoding: UTF-8, but for compatibility, it is recommended to use ASCII characters only (95 characters, see wiki)
name	FileName	‘solution/coordinatesSolution’	filename and (relative) path of the solution file containing all multibody system coordinates versus time; the default is in the directory solution/, like every file a run writes by default, so that nothing is written beside the script; directory will be created if it does not exist; character encoding of string is up to your filesystem, but for compatibility, it is recommended to use letters, numbers and ‘_’ only; filename ending will be added automatically if not provided: .txt in case of text mode and .sol in case of binary solution files (binary=True)
write	bool	True	flag (true/false), which determines if the coordinates are written to the solution file; standard quantities that are written are: solution is written as displacements and coordinatesODE1; for additional quantities, see export
writeFooter	bool	True	flag (true/false); if true, information at end of simulation is written: convergence, total solution time, statistics
writeHeader	bool	True	flag (true/false); if true, file header is written (turn off, e.g. for multiple runs of time integration)
writeInitialValues	bool	True	flag (true/false); if true, initial values are exported for the start time; applies to the solution file and the sensor files; this may not be wanted in the append file mode if the initial values are identical to the final values of a previous computation
writePeriod	UReal	0.01	time span (period), determines how often the solution file is written during a simulation

SolutionSensorsSettings

Storing and writing of the sensors.

Reached as simulationSettings.solution.sensors.

SolutionSensorsSettings has the following items:

name	type	default	description
active	bool	True	flag (true/false); if false, no sensor files will be created and no sensor data will be stored; this may be advantageous for benchmarking as well as for special solvers which should not overwrite existing results (e.g. ComputeODE2Eigenvalues); settings this value to False may cause problems if sensors are required to perform operations which are needed e.g. in UserSensors as input of loads, etc.
append	bool	False	flag (true/false); if true, sensor output is appended to existing file (otherwise created) or in case of internal storage, it is appended to existing currently stored data; this allows storing sensor values over different simulations
writeFooter	bool	False	flag (true/false); if true, file footer is written for sensor output (turn off, e.g. for multiple runs of time integration)
writeHeader	bool	True	flag (true/false); if true, file header is written for sensor output (turn off, e.g. for multiple runs of time integration)
writePeriod	UReal	0.01	time span (period), determines how often the sensor output is written to file or internal storage during a simulation

SolutionRestartSettings

The restart file of a dynamic simulation: its state - time, coordinates, velocities, accelerations, the algorithmic accelerations of the generalized-alpha method, the step size and the sizes of the output files - written every writePeriod and at the end, from which the same script continues with continueIfAvailable; for a job that is stopped (e.g. by exudyn.special.solver.timeout or on a cluster) and started again unchanged. The model itself, its user functions and their Python state come from the script; the static solver writes no restart file.

Reached as simulationSettings.solution.restart.

SolutionRestartSettings has the following items:

name	type	default	description
continueIfAvailable	bool	False	flag (true/false); if true and the restart file exists, a dynamic solver continues from its state instead of starting at startTime: it takes time, state and step size from the file, appends to the solution and sensor files - shortened to what was written up to that state - and writes no initial values; a file that does not fit the system or the solver raises an error; without a file, the simulation starts as usual. Sensors with storeInternal hold only the values after the restart.
name	FileName	‘solution/restartFile.txt’	filename and (relative) path of the restart file
write	bool	False	flag (true/false); if true, the dynamic solvers write the restart file every writePeriod and at the end of the simulation; the file is written to name.tmp and renamed, the previous one kept as name.bck
writePeriod	UReal	0.01	time span (period) in which the restart file is updated

SolutionSettings

General settings for exporting the solution (results) of a simulation: the solution file, the sensors and the restart file.

Reached as simulationSettings.solution.

SolutionSettings has the following items:

name	type	default	description
file	SolutionFileSettings		the coordinates solution file
restart	SolutionRestartSettings		the restart file
sensors	SolutionSensorsSettings		storing and writing of the sensors
flushFilesImmediately	bool	False	flush file buffers after every period written (solution file and sensor files); if set False, the output is written through a buffer, which is highly efficient, but during simulation, files may be always in an incomplete state; if set True, this may add a large amount of CPU time as the process waits until files are really written to hard disc (especially for simulation of small scale systems, writing 10.000s of time steps; at least 5us per step/file, depending on hardware)
precision	UInt	10	precision for floating point numbers written to the solution and sensor files; the precision of the output to the console is consolePrecision
recordImagesInterval	Real	-1.	record frames of the main view in the renderer (images) during solving: amount of time to wait until next image (frame) is recorded; set recordImages = -1. if no images shall be recorded; set, e.g., recordImages = 0.01 to record an image every 10 milliseconds (requires that the time steps / load steps are sufficiently small!); for file names, etc., see VisualizationSettings.exportImages; note that only the main view (0) can be saved in this way, while for multiple views, you have to aquire data via renderer.RedrawAndGetImage()
solverInformationFileName	FileName	‘solution/solverInformation.txt’	filename and (relative) path of text file showing detailed information during solving; detail level according to yourSolver.verboseModeFile; if file.append is true, the information is appended in every solution step; directory will be created if it does not exist; character encoding of string is up to your filesystem, but for compatibility, it is recommended to use letters, numbers and ‘_’ only

SolutionSettingsDeprecated

The settings of the solution as they were named up to Exudyn 1.11: each forwards to its place in simulationSettings.solution, with a DeprecationWarning.

Reached as simulationSettings.solutionSettings.

SolutionSettingsDeprecated has the following items:

(none: this structure has no items in the Python interface. A deprecated item keeps working and is described where it moved to.)

NumericalDifferentiationSettings

Settings for numerical differentiation of a function (needed for computation of numerical jacobian e.g. in implizit integration).

Reached as simulationSettings.timeIntegration.newton.numericalDifferentiation, simulationSettings.staticSolver.newton.numericalDifferentiation.

NumericalDifferentiationSettings has the following items:

name	type	default	description
addReferenceCoordinatesToEpsilon	bool	False	True: for the size estimation of the differentiation parameter, the reference coordinate \(q^{Ref}_i\) is added to ODE2 coordinates –> see; False: only the current coordinate is used for size estimation of the differentiation parameter
doSystemWideDifferentiation	bool	False	True: system wide differentiation (e.g. all ODE2 equations w.r.t. all ODE2 coordinates); False: only local (object) differentiation
forAE	bool	False	flag (true/false); false = perform direct computation of jacobian for algebraic equations (AE), true = use numerical differentiation; as there must always exist an analytical implemented jacobian for AE, ‘true’ should only be used for verification
forODE2	bool	False	flag (true/false); false = perform direct computation (e.g., using autodiff) of jacobian for ODE2 equations, true = use numerical differentiation; numerical differentiation is less efficient and may lead to numerical problems, but may smoothen problems of analytical derivatives; sometimes the analytical derivative may neglect terms
forODE2Connectors	bool	False	flag (true/false); false: if also forODE2==false, perform direct computation of jacobian for ODE2 terms for connectors; else: use numerical differentiation; NOTE: THIS FLAG IS FOR DEVELOPMENT AND WILL BE ERASED IN FUTURE
jacobianConnectorDerivative	bool	True	True: for analytic Jacobians of connectors, the Jacobian derivative is computed, causing additional CPU costs and not beeing available for all connectors or markers (thus switching to numerical differentiation); False: Jacobian derivative is neglected in analytic Jacobians (but included in numerical Jacobians), which often has only minor influence on convergence
minimumCoordinateSize	UReal	0.01	minimum size of coordinates in relative differentiation parameter
relativeEpsilon	UReal	1e-7	relative differentiation parameter epsilon; the numerical differentiation parameter \(\varepsilon\) follows from the formula (\(\varepsilon = \varepsilon_\mathrm{relative}*max(q_{min}, \vert q_i + [q^{Ref}_i]\vert )\), with \(\varepsilon_\mathrm{relative}\)=relativeEpsilon, \(q_{min} = \)minimumCoordinateSize, \(q_i\) is the current coordinate which is differentiated, and \(qRef_i\) is the reference coordinate of the current coordinate

DiscontinuousSettings

Settings for discontinuous iterations, as in contact, friction, plasticity and general switching phenomena.

Reached as simulationSettings.timeIntegration.discontinuous, simulationSettings.staticSolver.discontinuous.

DiscontinuousSettings has the following items:

name	type	default	description
ignoreMaxIterations	bool	True	continue solver if maximum number of discontinuous (post Newton) iterations is reached (ignore tolerance)
iterationTolerance	UReal	1	absolute tolerance for discontinuous (post Newton) iterations; the errors represent absolute residuals and can be quite high
maxIterations	UInt	5	maximum number of discontinuous (post Newton) iterations
useRecommendedStepSize	bool	True	some objects (contact-related) provide a recommendedStepSize; if True, this recommendation is used, but may lead to very small step sizes and solver could fail if restrictions are too hard; set to False to ignore this recommendation

NewtonSettings

Settings for Newton method used in static or dynamic simulation.

Reached as simulationSettings.timeIntegration.newton, simulationSettings.staticSolver.newton.

NewtonSettings has the following items:

name	type	default	description
numericalDifferentiation	NumericalDifferentiationSettings		numerical differentiation parameters for numerical jacobian (e.g. Newton in static solver or implicit time integration)
absoluteTolerance	UReal	1e-10	absolute tolerance of residual for Newton (needed e.g. if residual is fulfilled right at beginning); condition: sqrt(q*q)/numberOfCoordinates <= absoluteTolerance
active	bool	True	flag (true/false); false = linear computation, true = use Newton solver for nonlinear solution
adaptInitialResidual	bool	True	flag (true/false); false = standard; True: if initialResidual is very small (or zero), it may increase significantely in the first Newton iteration; to achieve relativeTolerance, the initialResidual will by updated by a higher residual within the first Newton iteration
maximumSolutionNorm	UReal	1e38	this is the maximum allowed value for solutionU.L2NormSquared() which is the square of the square norm (i.e., value=\(u_1^2\)+\(u_2^2\)+…), and solutionV/A…; if the norm of solution vectors is larger, Newton method is stopped; the default value is chosen such that it would still work for single precision numbers (float)
maxIterations	UInt	25	maximum number of iterations (including modified + restart Newton iterations); after that total number of iterations, the static/dynamic solver refines the step size or stops with an error
maxModifiedNewtonIterations	UInt	8	maximum number of iterations for modified Newton (without Jacobian update); after that number of iterations, the modified Newton method gets a jacobian update and is further iterated
maxModifiedNewtonRestartIterations	UInt	7	maximum number of iterations for modified Newton after a Jacobian update; after that number of iterations, the full Newton method is started for this step
modifiedNewtonContractivity	PReal	0.5	maximum contractivity (=reduction of error in every Newton iteration) accepted by modified Newton; if contractivity is greater, a Jacobian update is computed
modifiedNewtonJacUpdatePerStep	bool	False	True: compute Jacobian at every time step (or static step), but not in every Newton iteration (except for bad convergence ==> switch to full Newton)
relativeTolerance	UReal	1e-8	relative tolerance of residual for Newton (general goal of Newton is to decrease the residual by this factor)
residualMode	UInt	0	0 … use residual for computation of error (standard); 1 … use ODE2 and ODE1 newton increment for error (set relTol and absTol to same values!) ==> may be advantageous if residual is zero, e.g., in kinematic analysis; TAKE CARE with this flag
useModifiedNewton	bool	False	True: compute Jacobian only at first call to solver; the Jacobian (and its factorizations) is not computed in each Newton iteration, even not in every (time integration) step; False: Jacobian (and factorization) is computed in every Newton iteration, which may be costly; the default is True for timeIntegration.newton and False for staticSolver.newton
weightTolerancePerCoordinate	bool	False	flag (true/false); false = compute error as L2-Norm of residual; true = compute error as (L2-Norm of residual) / (sqrt(number of coordinates)), which can help to use common tolerance independent of system size

GeneralizedAlphaSettings

Settings for generalized-alpha, implicit trapezoidal or Newmark time integration methods.

Reached as simulationSettings.timeIntegration.generalizedAlpha.

GeneralizedAlphaSettings has the following items:

name	type	default	description
computeInitialAccelerations	bool	True	True: compute initial accelerations from system EOM in acceleration form; NOTE that initial accelerations that are following from user functions in constraints are not considered for now! False: use zero accelerations
lieGroupAddTangentOperator	bool	True	True: for Lie group nodes, in case that lieGroupSimplifiedKinematicRelations=True, the integrator adds the tangent operator for stiffness and constraint matrices, for improved Newton convergence; not available for sparse matrix mode (EigenSparse)
lieGroupSimplifiedKinematicRelations	bool	False	True: for Lie group nodes, the integrator uses the original kinematic relations of the Bruls and Cardona 2010 paper; False (recommended): higher accuracy as proposed in paper by Holzinger, Arnold, Gerstmayr, sigma-modified Lie group generalized alpha methods for constrained multibody systems, 2025 (to be sumitted)
newmarkBeta	UReal	0.25	value beta for Newmark method; default value beta = \(\frac 1 4\) corresponds to (undamped) trapezoidal rule
newmarkGamma	UReal	0.5	value gamma for Newmark method; default value gamma = \(\frac 1 2\) corresponds to (undamped) trapezoidal rule
resetAccelerations	bool	False	this flag only affects if computeInitialAccelerations=False: if resetAccelerations=True, accelerations are set zero in the solver function InitializeSolverInitialConditions; this may be unwanted in case of repeatedly called SolveSteps() and in cases where solutions shall be prolonged from previous computations
spectralRadius	UReal	0.9	spectral radius for Generalized-alpha solver; set this value to 1 for no damping or to 0 < spectralRadius < 1 for damping of high-frequency dynamics; for position-level constraints (index 3), spectralRadius must be < 1
storeInitialAlgebraicCoordinates	bool	True	True: IF computeInitialAccelerations=True, store initial algebraic coordinates (usually the Lagrange multipliers) in the initial coordinates vector (and thus in the first line of the coordinates solution file); for further details on limitations, see computeInitialAccelerations
useIndex2Constraints	bool	False	set useIndex2Constraints = true in order to use index2 (velocity level constraints) formulation
useNewmark	bool	False	if true, use Newmark method with beta and gamma instead of generalized-Alpha

ExplicitIntegrationSettings

Settings for explicit solvers, like Explicit Euler, RK44, ODE23, DOPRI5 and others. The settings may significantely influence performance.

Reached as simulationSettings.timeIntegration.explicit.

ExplicitIntegrationSettings has the following items:

name	type	default	description
computeEndOfStepAccelerations	bool	True	accelerations are computed at stages of the explicit integration scheme; if the user needs accelerations at the end of a step, this flag needs to be activated; if True, this causes a second call to the RHS of the equations, which may DOUBLE COMPUTATIONAL COSTS for one-step-methods; if False, the accelerations are re-used from the last stage, being slightly different
computeMassMatrixInversePerBody	bool	False	If true, the solver assumes the bodies to be independent and computes the inverse of the mass matrix for all bodies independently; this may lead to WRONG RESULTS, if bodies share nodes, e.g., two MassPoint objects put on the same node or a beam with a mass point attached at a shared node; however, it may speed up explicit time integration for large systems significantly (multi-threaded) - together with a sparse solver, linearSolver.solverType = exu.LinearSolverType.EigenSparse: with the dense default the inverse is stored as a dense matrix and every step costs O(n^2) (#2400)
eliminateConstraints	bool	True	True: make explicit solver work for simple CoordinateConstraints, which are eliminated for ground constraints (e.g. fixed nodes in finite element models). False: incompatible constraints are ignored (BE CAREFUL)!
useLieGroupIntegration	bool	True	True: use Lie group integration for rigid body nodes; must be turned on for Lie group nodes (without data coordinates) to work properly; does not work for nodes with data coordinates!

ExplicitIntegrationSettingsDeprecated

The settings of the explicit solvers as they were named up to Exudyn 1.11: each forwards to its place in simulationSettings.timeIntegration, with a DeprecationWarning.

Reached as simulationSettings.timeIntegration.explicitIntegration.

ExplicitIntegrationSettingsDeprecated has the following items:

(none: this structure has no items in the Python interface. A deprecated item keeps working and is described where it moved to.)

RealtimeSettings

Simulation in realtime: the time integration waits until the CPU time has reached the simulation time.

Reached as simulationSettings.timeIntegration.realtime.

RealtimeSettings has the following items:

name	type	default	description
active	bool	False	True: simulate in realtime; the solver waits for computation of the next step until the CPU time reached the simulation time; if the simulation is slower than realtime, it simply continues
factor	PReal	1	if active=True, this factor is used to make the simulation slower than realtime (factor < 1) or faster than realtime (factor > 1)
waitMicroseconds	PInt	1000	if active=True, a loop runs which waits waitMicroseconds until checking again if the realtime is reached; using larger values leads to less CPU usage but less accurate realtime accuracy; smaller values (< 1000) increase CPU usage but improve realtime accuracy

TimeIntegrationSettings

General parameters used in time integration; specific parameters are provided in the according solver settings, e.g. for generalizedAlpha.

Reached as simulationSettings.timeIntegration.

TimeIntegrationSettings has the following items:

name	type	default	description
discontinuous	DiscontinuousSettings		parameters for treatment of discontinuities
explicit	ExplicitIntegrationSettings		special parameters for explicit time integration
generalizedAlpha	GeneralizedAlphaSettings		parameters for generalized-alpha, implicit trapezoidal rule or Newmark (options only apply for these methods)
newton	NewtonSettings		parameters for Newton method; used for implicit time integration methods only; the modified Newton method is the default here; starts from useModifiedNewton=True; every other value is the default of the type
realtime	RealtimeSettings		simulation in realtime
absoluteTolerance	UReal	1e-8	\(a_{tol}\): if automaticStepSize=True, absolute tolerance for the error control; must fulfill \(a_{tol} > 0\); see Explicit solvers
adaptiveStep	bool	True	True: the step size may be reduced if step fails; no automatic stepsize control
adaptiveStepDecrease	UReal	0.5	Multiplicative factor (MUST BE: 0 < factor < 1) for step size to decrese due to discontinuousIteration or Newton errors
adaptiveStepIncrease	UReal	2	Multiplicative factor (MUST BE > 1) for step size to increase after previous step reduction due to discontinuousIteration or Newton errors
adaptiveStepRecoveryIterations	UInt	7	Number of max. (Newton iterations + discontinuous iterations) at which a step increase is considered; in order to immediately increase steps after reduction, chose a high value
adaptiveStepRecoverySteps	UInt	10	Number of steps needed after which steps will be increased after previous step reduction due to discontinuousIteration or Newton errors
automaticStepSize	bool	True	True: for specific integrators with error control (e.g., DOPRI5), compute automatic step size based on error estimation; False: constant step size (step may be reduced if adaptiveStep=True); the maximum stepSize reads \(h = h_{max} = \frac{t_{end} - t_{start}}{n_{steps}}\)
computeLoadsJacobian	UInt	0	0: jacobian of loads not considered (may lead to slow convergence or Newton failure); 1: in case of implicit integrators, compute (numerical) Jacobian of ODE2 and ODE1 coordinates for loads, causing additional computational costs; this is advantageous in cases where loads are related nonlinearly to coordinates; 2: also compute ODE2_t dependencies for jacobian; note that computeLoadsJacobian has no effect in case of doSystemWideDifferentiation, as this anyway includes all load dependencies
endTime	UReal	1	\(t_{end}\): end time of time integration
initialStepSize	UReal	0	\(h_{init}\): if automaticStepSize=True, initial step size; if initialStepSize==0, max. stepSize, which is (endTime-startTime)/numberOfSteps, is used as initial guess; a good choice of initialStepSize may help the solver to start up faster.
minimumStepSize	PReal	1e-8	\(h_{min}\): if automaticStepSize=True or adaptiveStep=True: lower limit of time step size, before integrator stops with adaptiveStep; lower limit of automaticStepSize control (continues but raises warning)
numberOfSteps	PReal	100	\(n_{steps}\): number of steps in time integration; (maximum) stepSize \(h\) is computed from \(h = \frac{t_{end} - t_{start}}{n_{steps}}\); for automatic stepsize control, this stepSize is the maximum steps size, \(h_{max} = h\); numberOfSteps can also be a float type, but must be close to an integer (relative tolerance \(100\cdot\varepsilon\)) as it is silently rounded to int
relativeTolerance	UReal	1e-8	\(r_{tol}\): if automaticStepSize=True, relative tolerance for the error control; must fulfill \(r_{tol} \ge 0\); see Explicit solvers
reuseConstantMassMatrix	bool	True	True: does not recompute constant mass matrices (e.g. of some finite elements, mass points, etc.); if False, it always recomputes the mass matrix (e.g. needed, if user changes mass parameters via Python)
solverType	DynamicSolverType	DynamicSolverType::GeneralizedAlpha	the solver of mbs.SolveDynamic(…): an implicit one (GeneralizedAlpha, TrapezoidalIndex2, …) or an explicit one (DOPRI5, ExplicitEuler, RK44, …), see DynamicSolverType, DynamicSolverType; the argument solverType of mbs.SolveDynamic, if given, takes its place for that run
startTime	UReal	0	\(t_{start}\): start time of time integration (usually set to zero)
stepInformation	UInt	67	add up the following binary flags: 0 … show only step time, 1 … show time to go, 2 … show newton iterations (Nit) per step or period, 4 … show Newton jacobians (jac) per step or period, 8 … show discontinuous iterations (Dit) per step or period, 16 … show step size (dt), 32 … show CPU time spent; 64 … show adaptive step reduction warnings; 128 … show step increase information; 1024 … show every time step; time is usually shown in fractions of seconds (s), hours (h), or days
stepSizeMaxIncrease	UReal	2	\(f_{maxInc}\): if automaticStepSize=True, maximum increase of step size per step, see Explicit solvers; make this factor smaller (but \(> 1\)) if too many rejected steps
stepSizeSafety	UReal	0.9	\(r_{sfty}\): if automaticStepSize=True, a safety factor added to estimated optimal step size, in order to prevent from many rejected steps, see Explicit solvers. Make this factor smaller if many steps are rejected.
verboseMode	UInt	0	0 … no output, 1 … show short step information every 2 seconds (every 30 seconds after 1 hour CPU time), 2 … show every step information, 3 … show also solution vector, 4 … show also mass matrix and jacobian (implicit methods), 5 … show also Jacobian inverse (implicit methods)
verboseModeFile	UInt	0	same behaviour as verboseMode, but outputs all solver information to file

StaticSolverSettings

Settings for static solver linear or nonlinear (Newton).

Reached as simulationSettings.staticSolver.

StaticSolverSettings has the following items:

name	type	default	description
discontinuous	DiscontinuousSettings		parameters for treatment of discontinuities
newton	NewtonSettings		parameters for Newton method (e.g. in static solver or time integration)
adaptiveStep	bool	True	True: use step reduction if step fails; False: fixed step size
adaptiveStepDecrease	UReal	0.25	Multiplicative factor (MUST BE: 0 < factor < 1) for step size to decrese due to discontinuousIteration or Newton errors
adaptiveStepIncrease	UReal	2	Multiplicative factor (MUST BE > 1) for step size to increase after previous step reduction due to discontinuousIteration or Newton errors
adaptiveStepRecoveryIterations	UInt	7	Number of max. (Newton iterations + discontinuous iterations) at which a step increase is considered; in order to immediately increase steps after reduction, chose a high value
adaptiveStepRecoverySteps	UInt	4	Number of steps needed after which steps will be increased after previous step reduction due to discontinuousIteration or Newton errors
computeLoadsJacobian	bool	True	True: compute (currently numerical) Jacobian for loads, causing additional computational costs; this is advantageous in cases where loads are related nonlinearly to coordinates; False: jacobian of loads not considered (may lead to slow convergence or Newton failure); note that computeLoadsJacobian has no effect in case of doSystemWideDifferentiation, as this anyway includes all load dependencies
constrainODE1Coordinates	bool	True	True: ODE1coordinates are constrained to initial values; False: undefined behavior, currently not supported
loadStepDuration	PReal	1	quasi-time for all load steps (added to current time in load steps)
loadStepGeometric	bool	False	if loadStepGeometric=false, the load steps are incremental (arithmetic series, e.g. 0.1,0.2,0.3,…); if true, the load steps are increased in a geometric series, e.g. for \(n=8\) numberOfLoadSteps and \(d = 1000\) loadStepGeometricRange, it follows: \(1000^{1/8}/1000=0.00237\), \(1000^{2/8}/1000=0.00562\), \(1000^{3/8}/1000=0.0133\), …, \(1000^{7/8}/1000=0.422\), \(1000^{8/8}/1000=1\)
loadStepGeometricRange	PReal	1000	if loadStepGeometric=true, the load steps are increased in a geometric series, see loadStepGeometric
loadStepStart	UReal	0	a quasi time, which can be used for the output (first column) as well as for time-dependent forces; quasi-time is increased in every step i by loadStepDuration/numberOfLoadSteps; loadStepTime = loadStepStart + i*loadStepDuration/numberOfLoadSteps, but loadStepStart untouched ==> increment by user
minimumStepSize	PReal	1e-8	lower limit of step size, before nonlinear solver stops
numberOfLoadSteps	PInt	1	number of load steps; if numberOfLoadSteps=1, no load steps are used and full forces are applied at once
stabilizerODE2term	UReal	0	add mass-proportional stabilizer term in ODE2 part of jacobian for stabilization (scaled ), e.g. of badly conditioned problems; the diagnoal terms are scaled with \(stabilizer = (1-loadStepFactor^2)\), and go to zero at the end of all load steps: \(loadStepFactor=1\) -> \(stabilizer = 0\)
stepInformation	UInt	67	add up the following binary flags: 0 … show only step time, 1 … show time to go, 2 … show newton iterations (Nit) per step or period, 4 … show Newton jacobians (jac) per step or period, 8 … show discontinuous iterations (Dit) per step or period, 16 … show step size (dt), 32 … show CPU time spent; 64 … show adaptive step reduction warnings; 128 … show step increase information; 1024 … show every time step; time is usually shown in fractions of seconds (s), hours (h), or days
useLoadFactor	bool	True	True: compute a load factor \(\in [0,1]\) from static step time; all loads are scaled by the load factor; False: loads are always scaled with 1 – use this option if time dependent loads use a userFunction
verboseMode	UInt	1	0 … no output, 1 … show errors and load steps, 2 … show short Newton step information (error), 3 … show also solution vector, 4 … show also jacobian, 5 … show also Jacobian inverse
verboseModeFile	UInt	0	same behaviour as verboseMode, but outputs all solver information to file

LinearSolverSettings

Settings for linear solver, both dense and sparse (Eigen).

Reached as simulationSettings.linearSolver.

LinearSolverSettings has the following items:

name	type	default	description
ignoreSingularJacobian	bool	False	[ONLY implemented for dense, Eigen matrix mode] False: standard way, fails if jacobian is singular; True: use Eigen’s FullPivLU (thus only works with LinearSolverType.EigenDense) which handles over- and underdetermined systems; can often resolve redundant constraints, but MAY ALSO LEAD TO ERRONEOUS RESULTS!
pivotThreshold	UReal	0	[ONLY available for EXUdense and EigenDense (FullPivot) solver] threshold for dense linear solver, can be used to detect close to singular solutions, setting this to, e.g., 1e-12; solver then reports on equations that are causing close to singularity
reuseAnalyzedPattern	bool	False	[ONLY available for sparse matrices] True: the Eigen SparseLU solver offers the possibility to reuse an analyzed pattern of a previous factorization; this may reduce total factorization time by a factor of 2 or 3, depending on the matrix type; however, if the matrix patterns heavily change between computations, this may even slow down performance; this flag is set for SparseMatrices in InitializeSolverData(…) and should be handled with care!
showCausingItems	bool	True	False: no output, if solver fails; True: if redundant equations appear, they are resolved such that according solution variables are set to zero; in case of redundant constraints, this may help, but it may lead to erroneous behaviour; for static problems, this may suppress static motion or resolve problems in case of instabilities, but should in general be considered with care!
solverType	LinearSolverType	LinearSolverType::EXUdense	selection of numerical linear solver: exu.LinearSolverType.EXUdense (dense matrix inverse), exu.LinearSolverType.EigenSparse (sparse matrix LU-factorization), … (enumeration type)

LinearSolverSettingsDeprecated

The settings of the linear solver as they were named up to Exudyn 1.11: each forwards to its place in simulationSettings.linearSolver, with a DeprecationWarning.

Reached as simulationSettings.linearSolverSettings.

LinearSolverSettingsDeprecated has the following items:

(none: this structure has no items in the Python interface. A deprecated item keeps working and is described where it moved to.)

Parallel

Settings for linear solver, both dense and sparse (Eigen).

Reached as simulationSettings.parallel.

Parallel has the following items:

name	type	default	description
multithreadedLowerLimitJacobians	PInt	20	compute jacobians (ODE2, AE, …) multi-threaded; this is the limit number of according objects from which on parallelization is used; flag is copied into MainSystem internal flag at InitializeSolverData(…)
multithreadedLowerLimitLoads	PInt	20	compute loads multi-threaded; this is the limit number of loads from which on parallelization is used; flag is copied into MainSystem internal flag at InitializeSolverData(…)
multithreadedLowerLimitMassMatrices	PInt	20	compute bodies mass matrices multi-threaded; this is the limit number of bodies from which on parallelization is used; flag is copied into MainSystem internal flag at InitializeSolverData(…)
multithreadedLowerLimitResiduals	PInt	20	compute RHS vectors, AE, and reaction forces multi-threaded; this is the limit number of objects from which on parallelization is used; flag is copied into MainSystem internal flag at InitializeSolverData(…)
numberOfThreads	PInt	1	number of threads used for parallel computation (1 == scalar processing); do not use more threads than available threads (in most cases it is good to restrict to the number of cores); currently, only one solver can be started with multithreading; if you use several mbs in parallel (co-simulation), you should use serial computing
taskSplitMinItems	PInt	50	number of items from which on the tasks are split into subtasks (which slightly increases threading performance; this may be critical for smaller number of objects, should be roughly between 50 and 5000; flag is copied into MainSystem internal flag at InitializeSolverData(…)
taskSplitTasksPerThread	PInt	16	this is the number of subtasks that every thread receives; minimum is 1, the maximum should not be larger than 100; this factor is 1 as long as the taskSplitMinItems is not reached; flag is copied into MainSystem internal flag at InitializeSolverData(…)
useLoadBalancing	bool	True	if True, parallel computation uses load balancing, which may give better performance in case of non-equilibrated loads; (mobile) Intel CPUs may perform better without load balancing; this flag is coupled to exudyn.special.solver.multiThreadingLoadBalancing (overwritten when solver starts with multithreading)

ShowSettings

What the solvers show in the console at the end of solving.

Reached as simulationSettings.show.

ShowSettings has the following items:

name	type	default	description
computationTime	bool	False	display computation time statistics at end of solving
globalTimers	bool	True	display global timer statistics at end of solving (e.g., for contact, but also for internal timings during development)
statistics	bool	False	display general computation information at end of time step (steps, iterations, function calls, step rejections, …

SimulationSettings

General Settings for simulation; according settings for solution and solvers are given in subitems of this structure.

Reached as simulationSettings.

SimulationSettings has the following items:

name	type	default	description
linearSolver	LinearSolverSettings		linear solver parameters (used for dense and sparse solvers)
parallel	Parallel		parameters for vectorized and parallelized (multi-threaded) computations
show	ShowSettings		what the solvers show in the console at the end of solving
solution	SolutionSettings		settings for solution files
staticSolver	StaticSolverSettings		static solver parameters
timeIntegration	TimeIntegrationSettings		time integration parameters
cleanUpMemory	bool	False	True: solvers will free memory at exit (recommended for large systems); False: keep allocated memory for repeated computations to increase performance
consolePrecision	UInt	6	precision for floating point numbers written to the console, e.g. the values written by the solver; the precision of the solution and sensor files is solution.precision
pauseAfterEachStep	bool	False	pause after every time step or static load step(user press SPACE)

The following parameter changes have been made:

• simulationSettings.solutionSettings.appendToFile → simulationSettings.solution.file.append (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.binarySolutionFile → simulationSettings.solution.file.binary (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.coordinatesSolutionFileName → simulationSettings.solution.file.name (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.exportAccelerations → simulationSettings.solution.file.export.accelerations (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.exportAlgebraicCoordinates → simulationSettings.solution.file.export.algebraicCoordinates (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.exportDataCoordinates → simulationSettings.solution.file.export.dataCoordinates (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.exportODE1Velocities → simulationSettings.solution.file.export.ODE1Velocities (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.exportVelocities → simulationSettings.solution.file.export.velocities (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.flushFilesDOF → simulationSettings.solution.file.flushAboveCoordinates (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.flushFilesImmediately → simulationSettings.solution.flushFilesImmediately (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.outputPrecision → simulationSettings.solution.precision (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.recordImagesInterval → simulationSettings.solution.recordImagesInterval (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.restartFileName → simulationSettings.solution.restart.name (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.restartWritePeriod → simulationSettings.solution.restart.writePeriod (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.sensorsAppendToFile → simulationSettings.solution.sensors.append (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.sensorsStoreAndWriteFiles → simulationSettings.solution.sensors.active (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.sensorsWriteFileFooter → simulationSettings.solution.sensors.writeFooter (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.sensorsWriteFileHeader → simulationSettings.solution.sensors.writeHeader (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.sensorsWritePeriod → simulationSettings.solution.sensors.writePeriod (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.solutionInformation → simulationSettings.solution.file.information (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.solutionWritePeriod → simulationSettings.solution.file.writePeriod (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.solverInformationFileName → simulationSettings.solution.solverInformationFileName (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.writeFileFooter → simulationSettings.solution.file.writeFooter (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.writeFileHeader → simulationSettings.solution.file.writeHeader (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.writeInitialValues → simulationSettings.solution.file.writeInitialValues (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.writeRestartFile → simulationSettings.solution.restart.write (changed in version 1.12.256, expires: 2031)

• simulationSettings.solutionSettings.writeSolutionToFile → simulationSettings.solution.file.write (changed in version 1.12.256, expires: 2031)

• simulationSettings.timeIntegration.newton.numericalDifferentiation.forODE2connectors → simulationSettings.timeIntegration.newton.numericalDifferentiation.forODE2Connectors (changed in version 1.12.256, expires: 2031)

• simulationSettings.staticSolver.newton.numericalDifferentiation.forODE2connectors → simulationSettings.staticSolver.newton.numericalDifferentiation.forODE2Connectors (changed in version 1.12.256, expires: 2031)

• simulationSettings.timeIntegration.newton.newtonResidualMode → simulationSettings.timeIntegration.newton.residualMode (changed in version 1.12.256, expires: 2031)

• simulationSettings.staticSolver.newton.newtonResidualMode → simulationSettings.staticSolver.newton.residualMode (changed in version 1.12.256, expires: 2031)

• simulationSettings.timeIntegration.newton.useNewtonSolver → simulationSettings.timeIntegration.newton.active (changed in version 1.12.256, expires: 2031)

• simulationSettings.staticSolver.newton.useNewtonSolver → simulationSettings.staticSolver.newton.active (changed in version 1.12.256, expires: 2031)

• simulationSettings.timeIntegration.explicitIntegration.computeEndOfStepAccelerations → simulationSettings.timeIntegration.explicit.computeEndOfStepAccelerations (changed in version 1.12.256, expires: 2031)

• simulationSettings.timeIntegration.explicitIntegration.computeMassMatrixInversePerBody → simulationSettings.timeIntegration.explicit.computeMassMatrixInversePerBody (changed in version 1.12.256, expires: 2031)

• simulationSettings.timeIntegration.explicitIntegration.dynamicSolverType → simulationSettings.timeIntegration.solverType (changed in version 1.12.256, expires: 2031)

• simulationSettings.timeIntegration.explicitIntegration.eliminateConstraints → simulationSettings.timeIntegration.explicit.eliminateConstraints (changed in version 1.12.256, expires: 2031)

• simulationSettings.timeIntegration.explicitIntegration.useLieGroupIntegration → simulationSettings.timeIntegration.explicit.useLieGroupIntegration (changed in version 1.12.256, expires: 2031)

• simulationSettings.timeIntegration.realtimeFactor → simulationSettings.timeIntegration.realtime.factor (changed in version 1.12.256, expires: 2031)

• simulationSettings.timeIntegration.realtimeWaitMicroseconds → simulationSettings.timeIntegration.realtime.waitMicroseconds (changed in version 1.12.256, expires: 2031)

• simulationSettings.timeIntegration.simulateInRealtime → simulationSettings.timeIntegration.realtime.active (changed in version 1.12.256, expires: 2031)

• simulationSettings.staticSolver.constrainODE1coordinates → simulationSettings.staticSolver.constrainODE1Coordinates (changed in version 1.12.256, expires: 2031)

• simulationSettings.linearSolverSettings.ignoreSingularJacobian → simulationSettings.linearSolver.ignoreSingularJacobian (changed in version 1.12.256, expires: 2031)

• simulationSettings.linearSolverSettings.pivotThreshold → simulationSettings.linearSolver.pivotThreshold (changed in version 1.12.256, expires: 2031)

• simulationSettings.linearSolverSettings.reuseAnalyzedPattern → simulationSettings.linearSolver.reuseAnalyzedPattern (changed in version 1.12.256, expires: 2031)

• simulationSettings.linearSolverSettings.showCausingItems → simulationSettings.linearSolver.showCausingItems (changed in version 1.12.256, expires: 2031)

• simulationSettings.parallel.multithreadedLLimitJacobians → simulationSettings.parallel.multithreadedLowerLimitJacobians (changed in version 1.12.244, expires: 2031)

• simulationSettings.parallel.multithreadedLLimitLoads → simulationSettings.parallel.multithreadedLowerLimitLoads (changed in version 1.12.244, expires: 2031)

• simulationSettings.parallel.multithreadedLLimitMassMatrices → simulationSettings.parallel.multithreadedLowerLimitMassMatrices (changed in version 1.12.244, expires: 2031)

• simulationSettings.parallel.multithreadedLLimitResiduals → simulationSettings.parallel.multithreadedLowerLimitResiduals (changed in version 1.12.244, expires: 2031)

• simulationSettings.displayComputationTime → simulationSettings.show.computationTime (changed in version 1.12.256, expires: 2031)

• simulationSettings.displayGlobalTimers → simulationSettings.show.globalTimers (changed in version 1.12.256, expires: 2031)

• simulationSettings.displayStatistics → simulationSettings.show.statistics (changed in version 1.12.256, expires: 2031)

• simulationSettings.linearSolverType → simulationSettings.linearSolver.solverType (changed in version 1.12.256, expires: 2031)

• simulationSettings.outputPrecision → simulationSettings.consolePrecision (changed in version 1.12.256, expires: 2031)