v11.3.0

[11.3.0] - 2026-10-14

Added

• Add mechanics.Item, a runtime-checkable protocol which describes the interface of an item for a Step, a Job and newtonraphson(): the field container field, the methods assemble.vector(field, parallel) and assemble.matrix(parallel) with the scale factor assemble.multiplier and the results results with results.update_statevars(). The optional methods of an item, e.g. update(value) for a ramp in a Step and checkpoint() / restore(checkpoint) for the CutbackPlugin, are documented. Every object with these attributes is an item, i.e. isinstance(item, mechanics.Item) is True for all built-in items and for custom items, which are not derived from mechanics.Item.

Changed

• The state variables of the items are updated by newtonraphson() after a converged iteration (by item.results.update_statevars()), instead of by the default function of the argument check. Hence, check() has no side effects and the state variables are also updated with a custom check-function (before, they were not updated, unless the custom function did it). The documented signature of check is corrected, xnorm, fnorm, success = check(dx, x, f, xtol, ftol, dof1, dof0, items).
• Split the module of the contacts with rigid surfaces into the package mechanics._contact with a module for ContactRigidBase, for ContactRigidPlane and for ContactRigidCylinder. The classes and their import paths are unchanged. The docstring of ContactRigidBase documents its parameters and the method _kinematics(dx), which defines the geometry of a custom rigid surface in a subclass, with an example of a rigid sphere.
• Split the module of the multi-point constraints into the package mechanics._multipoint with a module for MultiPointConstraint, for MultiPointContact, for the shared helpers of the assembly and for the rotation matrix by Rodrigues' formula. The classes and their import paths are unchanged.
• Evaluate arrays in chunks of cells by the shared helpers of math._chunks: chunk_slices() divides an axis into chunks and map_chunks() evaluates the chunks in serial or by the pool of threads. Both are used by math._einsum.einsum_chunks() and constitution._chunks.evaluate_chunks(). The module documents the two rules for the size of a chunk: about CHUNKSIZE_BYTES (2 MiB) if the memory of the arrays per cell is known (the assembly of the stiffness matrix) and about CHUNKSIZE_POINTS (8192) evaluation points if not (the default value of ConstitutiveMaterial.chunksize). The sizes are unchanged. With parallel=True and a single usable CPU, the chunks of a constitutive material are evaluated in serial, like the contractions of einsum_chunks() (before, by a pool with one thread).
• Evaluate the Kirchhoff and the Cauchy stress tensors and the mass matrix of SolidBody and SolidBodyNearlyIncompressible by the shared helpers mechanics._helpers.kirchhoff_stress(P, F), cauchy_stress(P, F) and mass_matrix(field, density), instead of duplicated code. The solid bodies still define which stress tensor P (e.g. including the internal pressure of a SolidBodyNearlyIncompressible) and which deformation gradient tensor F are transformed. The results are unchanged.
• Evaluate the integral forms of vector-valued axisymmetric fields by the cartesian integral forms of all pairs of the in-plane and the out-of-plane parts (v_r / R) of the test and the trial field, instead of eight internal modes with hard-coded slices and paddings of the results. The out-of-plane parts are added to the radial components. The results are equal up to the order of the summation of the parts. A bilinear form of an axisymmetric test field and a field without an out-of-plane component now takes the given flags of the gradients (before, the gradient of the test field and the values of the trial field were used).

Deprecated

• Deprecate the argument callback of Job and CharacteristicCurve and its keyword-arguments **kwargs, which will be removed in v12.0.0. Use a callable plugin instead, which is called after each completed substep with the context and the state of the substep. Both are called with the same arguments, e.g. Job(steps, callback=callback, a=1) is replaced by Job(steps, plugins=[lambda context, state: callback(state.stepnumber, state.substepnumber, context.substep, a=1)]). The old callback is called before the hook after_substep of all plugins, i.e. a callable plugin is called in the same order if it is the first plugin in the list. The migration is documented in the notes of Job. Keyword-arguments of a job without a callback, e.g. a typo of plugins, also raise the warning (before, they were passed silently to the default callback).
• Deprecate the argument callback of newtonraphson(), which is also passed by Job.evaluate(callback=callback). It will be removed in v12.0.0. Use a plugin with the hook after_iteration instead, which gets the same values from the state of the iteration, e.g. newtonraphson(..., plugins=[NewtonCallback()]) or Job(steps, plugins=[NewtonCallback()]) with class NewtonCallback(Plugin): def after_iteration(self, context, state): callback(state.dx, state.x, state.iteration, state.xnorm, state.fnorm, state.success). The migration is documented in the notes of newtonraphson().
• Deprecate the arguments progress_bar and callback_kwargs of newtonraphson(), which have no effect. They will be removed in v12.0.0.
• The warnings of the deprecated callbacks and arguments are attributed to the line of the code of the user, also if a deprecated argument is passed by FElupe, e.g. by Job.evaluate() or by a subclass of Job. Python shows a DeprecationWarning by default only if it is attributed to the code of __main__, e.g. a script or a notebook.
• Announce the removal of newtonrhapson() and tools.newtonrhapson(), of the argument bounds of dof.symmetry() and of return_loadcase=None of dof.uniaxial(), dof.biaxial() and dof.shear() in v12.0.0. The new default value will be return_loadcase=False, i.e. only the dict of boundaries is returned (this was announced for v11.0.0, but not done).

Fixed

• Fix the bilinear forms of IntegralFormAxisymmetric without the gradient of the trial field (grad_u=False) of two axisymmetric fields. The block of the out-of-plane test basis (v_r / R) and the in-plane values of the trial field was transposed, i.e. its contribution of the axial trial component was added to the coupling of the axial test and the radial trial components. The forms of all combinations of gradients are tested against a reference with the three-dimensional values and gradients of the basis functions. The built-in items are not affected (the mass matrix has no out-of-plane component).
• Fix the mass matrix of SolidBody and SolidBodyNearlyIncompressible with an axisymmetric field, e.g. for a FreeVibration. The assembly failed with a ValueError, because the integral form of axisymmetric fields takes a function with an additional out-of-plane component. The displacements of an axisymmetric field have no circumferential component, i.e. the out-of-plane component of the function is now zero and the mass matrix is the in-plane mass matrix of the volumes of the rings, dV = 2 pi R dA.
• Fix ConstitutiveMaterial.optimize() for a MaterialStrain. The flag tangent is not stored in the keyword-arguments MaterialStrain.kwargs anymore, it is passed to the material function on each evaluation (tangent=False for the gradient and tangent=True for the hessian, unchanged). Before, tangent was optimized like a material parameter, which failed for its initial value None. A given keyword-argument tangent is ignored (unchanged).
• Fix the documentation of the loadcases: the default values of dof.uniaxial(clamped=False) and dof.biaxial(clampes=(False, False)), the name of the field boundaries of the returned LoadcaseResult and the default positions of the end faces of dof.shear(). Document the arguments boundary and plugins of CharacteristicCurve and the callable plugins of Plugin and EventDispatcher.
• Remove the unused keyword-argument boundary of the Job in the example of FormItem, which was passed silently to the default callback of the job.

What's Changed

• Don't store the flag tangent in the kwargs of MaterialStrain by @adtzlr in #1174
• Add mechanics.Item and update the state variables in newtonraphson() by @adtzlr in #1175
• Split the rigid contacts into a package and document ContactRigidBase._kinematics() by @adtzlr in #1176
• Split the multi-point constraints into a package by @adtzlr in #1177
• Evaluate arrays in chunks of cells by the shared helpers of math._chunks by @adtzlr in #1178
• Evaluate the stresses and the mass matrix of the solid bodies by shared helpers by @adtzlr in #1179
• Fix the mass matrix of solid bodies with an axisymmetric field by @adtzlr in #1180
• Fix the transposed coupling block of axisymmetric forms without trial gradient by @adtzlr in #1181
• Evaluate the axisymmetric integral forms by their in-plane and out-of-plane parts by @adtzlr in #1183
• Deprecate the callbacks of Job and newtonraphson() in favour of plugins by @adtzlr in #1184
• Release 11.3.0 by @adtzlr in #1185

Full Changelog: v11.2.0...v11.3.0