# Exudyn module ## Module functions These are the access functions to the Exudyn module. General usage is explained in [](#sec-generalpythoninterface) and examples are provided there. The C++ module `exudyn` is the root level object linked between Python and C++.In the installed site-packages, the according file is usually denoted as `exudynCPP.pyd` for the regular module, which is compiled for the baseline instruction set and runs on any 64-bit CPU, and `exudynCPPfast.pyd` for the optional module without range checks, which additionally uses the AVX2 vector extensions (may depend on your installation). ```python #import exudyn module: import exudyn as exu #create systemcontainer and mbs: SC = exu.SystemContainer() mbs = SC.AddSystem() ``` ```{container} notebookorigin `python/Notebooks/reference/generalInformation.ipynb` ``` The class **exudyn** has the following **functions and structures**: - **`Help()`**: Show basic help information - **`RequireVersion(requiredVersionString)`**: Checks if the installed version is according to the required version. Major, micro and minor version must agree the required level. This function is defined in the `__init__.py` file *Example*: ```python exu.RequireVersion("1.0.31") ``` - **`SetWriteToFile(filename, flagWriteToFile = True, flagAppend = False, flagFlushAlways = False)`**: set flag to write (True) or not write to console; default value of flagWriteToFile = False; flagAppend appends output to file, if set True; in order to finalize the file, write `exu.SetWriteToFile('', False)` to close the output file; in case of flagFlushAlways=True, file will be finalized immediately in every print command, but may be slower; the filename is relative to exudyn.config.outputDirectory, which is prepended when the file is opened; an absolute filename together with a non-empty outputDirectory raises an error; *Example*: ```python exudyn.config.printToConsole = False #no output to console exu.SetWriteToFile(filename='testOutput.log', flagWriteToFile=True, flagAppend=False, flagFlushAlways=False) exu.Print('print this to file') exu.SetWriteToFile('', False) #terminate writing to file which closes the file ``` - **`Print()`**: this allows printing via exudyn with similar syntax as in Python print(args) except for keyword arguments: exu.Print('test=',42,sep=' ',end='',flush=True); allows to redirect all output to file given by SetWriteToFile(...); does not print to console in case that exudyn.config.printToConsole is set to False - **`InvalidIndex()`**: This function provides the invalid index, which may depend on the kind of 32-bit, 64-bit signed or unsigned integer; e.g., node index or item index in list; currently, the InvalidIndex() gives -1, but it may be changed in future versions, therefore you should use this function - **`__version__`**: contains the current version of the Exudyn package - **`symbolic`**: the symbolic submodule for creating symbolic variables in Python, see documentation of Symbolic; For details, see Section Symbolic. (sec-exudyn-config)= ## exudyn.config - **`config`**: global config settings, like precision, print behavior, warnings, etc. - **`config.suppressWarnings`**: flag to suppress all warnings (default=False) - **`config.outputDirectory`**: directory which is prepended to all files written by the solver: the coordinates solution file, the solver information file, sensor files and exported images; default="" (files are written exactly as given). An absolute file name together with a non-empty outputDirectory raises an error when the file is opened. NOTE: this setting is global and stays active as long as the exudyn module is loaded, so running two models one after the other in the same process will put both outputs into the same directory; normally you should specify the output folder directly in the file names and use this setting only for a test runner or a batch script. The rule is: everything WRITTEN as output of a run follows the setting, while a file is READ from there only if its name comes from Exudyn itself. Writing: the coordinates solution file, the solver information file, sensor files, exported images, the exudyn.Print log (SetWriteToFile), the figure saved by PlotSensor and the results file of ParameterVariation/GeneticOptimization. Reading: SolutionViewer (name taken from the simulation settings) and PlotSensor for a sensor given by its number (name taken from the sensor). NOT affected: a file name you pass yourself, e.g. to LoadSolutionFile, LoadBinarySolutionFile, RecoverSolutionFile or PlotSensor as a string, and all model data such as mesh import, FEMinterface/ObjectFFRFreducedOrderInterface SaveToFile/LoadFromFile and SaveDictToHDF5/LoadDictFromHDF5; use exudyn.basicUtilities.OutputFilePath(fileName, callerInfo) in your script if you want those in the output directory as well - **`config.outputPrecision`**: change precision (number of digits) in C++ and Python output - **`config.linalgOutputFormatPython`**: True (default): use Python format for output of vectors and matrices; False: use Matlab format - **`config.printDelayMilliSeconds`**: add some delay (in milliSeconds) to printing to console (exudyn.Print), in order to let console (e.g., Spyder) process the output; default = 0 - **`config.printFlushAlways`**: flush always buffers when using exudyn.Print(...) to write to file or console; this is needed if you are streaming text or showing counters in parameter variation; default=False - **`config.printToConsole`**: enables or disables writing to console with exudyn.Print(...); default=True - **`config.printToFile`**: flag that shows if writing to file with exudyn.Print(...) is enabled; flag is readonly - **`config.printFileName`**: file name for writing to file with exudyn.Print(...), as resolved when the file was opened: it is relative to config.outputDirectory, which is prepended by SetWriteToFile(...); flag is readonly - **`config.printToFileAppend`**: flag that shows if append mode is used for writing to file with exudyn.Print(...); flag is readonly - **`config.Version(addDetails = False)`**: Get Exudyn built version as string (if addDetails=True, adds more information on compilation Python version, platform, etc.; the Python micro version may differ from that you are working with; AVX2 shows that you are running a AVX2 compiled version) - **`config.GetDictionary()`**: all settings of `exudyn.config` as a dictionary, the way a settings structure gives them; `printToFile`, `printFileName` and `printToFileAppend` are in it but only report what the output is doing - **`config.SetDictionary(values)`**: set the settings named in the dictionary and leave the others; a name that `exudyn.config` does not have, and one of the three that only report, is ignored - **`config.GetDefaults()`**: the defaults of `exudyn.config`: what Exudyn started with, taken while the module was imported and before a script, an override setting or an environment variable could change one. This is what tells a setting somebody chose from one nobody touched, which is how `overrideSettings.Store(config=...)` knows what to store. They cannot be constructed - `exudyn.config` reads global state, so a second one reports the current values - so they are taken once (sec-exudyn-experimental)= ## exudyn.experimental - **`experimental`**: Experimental features, not intended for regular users; for available features, see the C++ code class PyExperimental - **`experimental.eigenFullPivotLUsolverDebugLevel`**: debug output of the EigenDense solver with full pivoting: 0 (default) = none, 1 = rank and information, 2 = also the matrices - **`experimental.markerSuperElementRigidTexpSO3`**: if nonzero (default), MarkerSuperElementRigid uses the additional tangent operator TexpSO3 of the rotation parameters (sec-exudyn-special)= ## exudyn.special - **`special`**: special attributes and functions, such as global (solver) flags or helper functions; not intended for regular users; for available features, see the C++ code class PySpecial - **`special.InfoStat(writeOutput = True)`**: Retrieve list of global information on memory allocation and other counts as list:[array_new_counts, array_delete_counts, vector_new_counts, vector_delete_counts, matrix_new_counts, matrix_delete_counts, linkedDataVectorCast_counts]; May be extended in future; if writeOutput==True, it additionally prints the statistics; counts for new vectors and matrices should not depend on numberOfSteps, except for some objects such as ObjectGenericODE2 and for (sensor) output to files; Not available if code is compiled with __FAST_EXUDYN_LINALG flag - **`special.currentRendererSystemContainer`**: the `SystemContainer` the renderer is attached to, or `None`; the render engine can hold one at a time, which is why this is module-wide. It is set when a container attaches to the render engine and cleared when it detaches or is destroyed, and it is what the dialogs of `exudyn.misc.GUI` ask for; not intended for regular users - **`special.overrideSettings`**: the settings that persist between runs, read once by `import exudyn` from `~/.exudyn/config.json`: a dictionary with one key per section, `config`, `visualizationSettings`, `dialogs` and `resultsMonitor`; it is empty unless something was stored, and both Python and the C++ side read it. See Section [](#sec-usersettings) (sec-exudyn-special-solver)= ### exudyn.special.solver - **`special.solver`**: special solver attributes and functions; not intended for regular users; for available features, see the C++ code class PySpecialSolver - **`special.solver.timeout`**: if >= 0, the solver stops after reaching accoring CPU time specified with timeout; makes sense for parameter variation, automatic testing or for long-running simulations; default=-1 (no timeout) - **`special.solver.throwErrorWithCtrlC`**: if True, pressing CTRL-C during a simulation raises an error in Python; if False (default), the solver stops and returns; the error works in a console, the default also in Spyder - **`special.solver.multiThreadingLoadBalancing`**: if True (=default), multithreaded code parts (in particular solver and raytracing) use load balancing, which may give better performance in case of non-equilibrated loads; (mobile) Intel CPUs may perform significantly better without load balancing (sec-exudyn-special-exceptions)= ### exudyn.special.exceptions - **`special.exceptions`**: special flags for exceptions and checks; not intended for regular users; for available features, see the C++ code class PySpecialExceptions - **`special.exceptions.dictionaryVersionMismatch`**: if True (=default), SetDictionary(...) of a settings structure warns if the dictionary comes from another version of Exudyn - **`special.exceptions.dictionaryNonCopyable`**: if True (=default), GetDictionary(...) raises an error if a value cannot be copied into the dictionary - **`special.exceptions.writeErrorsToLogFile`**: if True (=default), the message of a user or system error is also written into the log file of exudyn.SetWriteToFile(...), as a record of an unattended run; set False for a run that provokes and catches many errors, whose exceptions carry the same message - **`special.exceptions.parameterRangeChecks`**: if True (=default), writing an item or settings parameter outside its range (e.g. a negative mass or a non-positive number of steps) raises an error, on every write path (item classes, dictionaries, SetObjectParameter, ...); set False to accept any value, e.g. if a range limit turns out to be wrong (sec-exudyn-special-beams)= ### exudyn.special.beams - **`special.beams`**: switches of the beam elements, for tests and comparisons; a model keeps the defaults; for available features, see the C++ code class PySpecialBeams - **`special.beams.geometricallyExactLumpedMass`**: if True, ObjectBeamGeometricallyExact uses the lumped mass matrix of its nodes and their quadratic velocity vector instead of the element-consistent ones (default False); for comparisons and tests (sec-exudyn-special-userinterface)= ### exudyn.special.userInterface - **`special.userInterface`**: flags that stop Exudyn from opening windows; meant for automated runs (test runners, CI, AI-assisted development), where a window that waits for a human stops everything; not intended for regular users; for available features, see the C++ code class PySpecialUserInterface - **`special.userInterface.suppressRenderer`**: if True, SC.renderer.Start() returns immediately without opening a window, IsActive() is False - so that a "while SC.renderer.IsActive()" loop ends at once - and DoIdleTasks() does nothing; default=False - **`special.userInterface.suppressSolutionViewer`**: if True, mbs.SolutionViewer(...) and AnimateModes(...) return immediately instead of opening the viewer; default=False - **`special.userInterface.suppressPlots`**: if True, PlotSensor and the other plotting helpers do not show a plot window; figures are still drawn and a figure given a file name is still saved; setting the environment variable EXUDYN_SUPPRESS_UI_WINDOW_OPEN additionally switches matplotlib to the non-interactive Agg backend, which also silences a plt.show() written in a script; default=False - **`special.userInterface.suppressDialogs`**: if True, InteractiveDialog and the other tkinter dialogs return their defaults instead of opening a window; default=False - **`special.userInterface.SuppressAll(flag = True)`**: set all four suppress flags at once; a run either wants windows or does not (sec-exudyn-special-deprecations)= ### exudyn.special.deprecations - **`special.deprecations`**: how a deprecated name - a setting, an item parameter, a function - is reported: a DeprecationWarning once per session and name, or on every use, and a count of every use in the dictionary exudyn.sys[deprecationUse], by source (simulationSettings, visualizationSettings, items, functions) and name; see the C++ code class PySpecialDeprecations - **`special.deprecations.warnOnce`**: if True (=default), each deprecated name warns once per session; if False, every use warns, e.g. to find all places in a script that use it - **`special.deprecations.recordUse`**: if True (=default), every use of a deprecated name is counted in exudyn.sys[deprecationUse], by source and name, also when no warning is shown; a test reads it instead of catching warnings - **`special.deprecations.Reset()`**: forget which names were warned about in this session, so that each one warns once more - **`special.deprecations.Warn(source, name, message, stackLevel = 2)`**: report the use of a deprecated name from Python, as the C++ side does: a DeprecationWarning, once per session unless warnOnce is False, and a count in exudyn.sys[deprecationUse]; stackLevel=2 attributes the warning to the caller of the function that calls Warn (sec-exudyn-variables)= ## exudyn.variables and exudyn.sys - **`variables`**: this dictionary may be used by the user to store exudyn-wide data in order to avoid global Python variables; usage: exu.variables["myvar"] = 42; can be used in particular to exchange data between different mbs or between packages by importing exudyn.variables wherever needed. - **`sys`**: this dictionary is used and reserved by the system, e.g., for testsuite, graphics or system function to store module-wide data in order to avoid global Python variables; the variable exu.sys['renderState'] contains the last render state after SC.renderer.Stop() and can be used for subsequent simulations