# SimulationSettings (sec-simulationsettingsmain)= ## Simulation settings This section includes hierarchical structures for simulation settings, e.g., time integration, static solver, Newton iteration and solution file export. (sec-solutionfileexportsettings)= ### 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: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | name | type | default | description | |---|---|---|---| | `accelerations` | bool | True | add {ref}`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 {ref}`ODE2 ` velocities to the solution file | (sec-solutionfilesettings)= ### 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: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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 [](#sec-utf8), 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 | (sec-solutionsensorssettings)= ### SolutionSensorsSettings Storing and writing of the sensors. Reached as `simulationSettings.solution.sensors`. SolutionSensorsSettings has the following items: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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 | (sec-solutionrestartsettings)= ### 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: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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 | (sec-solutionsettings)= ### 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: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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 | (sec-solutionsettingsdeprecated)= ### 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.)* (sec-numericaldifferentiationsettings)= ### 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: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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 {ref}`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 {ref}`ODE2 ` equations w.r.t. all {ref}`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 | (sec-discontinuoussettings)= ### 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: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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 | (sec-newtonsettings)= ### NewtonSettings Settings for Newton method used in static or dynamic simulation. Reached as `simulationSettings.timeIntegration.newton`, `simulationSettings.staticSolver.newton`. NewtonSettings has the following items: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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 {ref}`ODE2 ` and {ref}`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 | (sec-generalizedalphasettings)= ### GeneralizedAlphaSettings Settings for generalized-alpha, implicit trapezoidal or Newmark time integration methods. Reached as `simulationSettings.timeIntegration.generalizedAlpha`. GeneralizedAlphaSettings has the following items: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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 | (sec-explicitintegrationsettings)= ### 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: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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! | (sec-explicitintegrationsettingsdeprecated)= ### 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.)* (sec-realtimesettings)= ### 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: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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 | (sec-timeintegrationsettings)= ### 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: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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 [](#sec-explicitsolver) | | `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 [](#sec-explicitsolver) | | `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, [](#sec-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 [](#sec-explicitsolver); 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 [](#sec-explicitsolver). 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 | (sec-staticsolversettings)= ### StaticSolverSettings Settings for static solver linear or nonlinear (Newton). Reached as `simulationSettings.staticSolver`. StaticSolverSettings has the following items: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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 {ref}`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 | (sec-linearsolversettings)= ### LinearSolverSettings Settings for linear solver, both dense and sparse (Eigen). Reached as `simulationSettings.linearSolver`. LinearSolverSettings has the following items: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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) | (sec-linearsolversettingsdeprecated)= ### 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.)* (sec-parallel)= ### Parallel Settings for linear solver, both dense and sparse (Eigen). Reached as `simulationSettings.parallel`. Parallel has the following items: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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) | (sec-showsettings)= ### ShowSettings What the solvers show in the console at the end of solving. Reached as `simulationSettings.show`. ShowSettings has the following items: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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, ... | (sec-simulationsettings)= ### 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: ```{tabularcolumns} \Y{0.26}\Y{0.12}\Y{0.14}\Y{0.48} ``` | 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)