simcoon 2.1.0__tar.gz → 2.2.0__tar.gz

{simcoon-2.1.0 → simcoon-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: simcoon
-Version: 2.1.0
+Version: 2.2.0
 Summary: Simulation in Mechanics and Materials: Interactive Tools - A library for the simulation of multiphysics systems and heterogeneous materials
 Keywords: simulation,mechanics,materials,composites,homogenization,constitutive-models,finite-element,micromechanics
 Author-Email: Yves Chemisky <yves.chemisky@gmail.com>

simcoon-2.2.0/docs/continuum_mechanics/functions/doc_tensor.rst

@@ -0,0 +1,308 @@
+Typed Tensors (Tensor2 / Tensor4)
+=================================
+
+``simcoon.Tensor2`` and ``simcoon.Tensor4`` are unified typed wrappers for 2nd-
+and 4th-order tensors. A single object transparently represents either one tensor
+or a batch (scipy ``Rotation`` style): shape ``(6,)`` / ``(6,6)`` is a single
+tensor, ``(N,6)`` / ``(N,6,6)`` a batch. ``Tensor4`` stores its data internally
+in the **Kelvin-Mandel** convention, so the double contraction, inverse and
+composition of 4th-order tensors become ordinary 6x6 linear algebra; the
+engineering Voigt form is recovered on demand via ``.mat`` / ``.voigt``.
+
+Objects are built through typed factories, e.g. ``Tensor2.stress(v)``,
+``Tensor2.strain(v)``, ``Tensor4.stiffness(m)``, ``Tensor4.compliance(m)``,
+``Tensor4.from_voigt(v, type_str)``.
+
+Batch operations
+----------------
+
+Batch ``contract``, ``rotate``, ``push_forward``, ``pull_back`` and ``inverse``
+dispatch to vectorised kernels over the ``(N, ...)`` data.
+
+.. tip:: **Shared-tangent contraction is ~20x faster — pass a single Tensor4.**
+
+   When the same 4th-order tensor is contracted against many 2nd-order tensors
+   (a shared elastic tangent applied at every integration point), pass a
+   **single** ``Tensor4`` and contract it with a **batch** ``Tensor2``::
+
+       L   = Tensor4.stiffness(L6x6)     # single (6,6)
+       eps = Tensor2.strain(eps_Nx6)     # batch  (N,6)
+       sig = L.contract(eps)             # one BLAS GEMM  ->  ~20x
+
+   This collapses to a single ``L @ X`` matrix-matrix product (BLAS ``dgemm``):
+   measured ~3.7 ns/point vs ~74 ns/point for the per-point path (N = 1e5).
+   The C++ ``batch_contract`` implements the same fast path when the tensor4
+   cube has a single slice (``N4 == 1``).
+
+   **Anti-pattern:** materialising the shared tangent as a *tiled* ``(N,6,6)``
+   batch of identical slices — that forces ``N`` independent 6x6 matrix-vector
+   products and the GEMM speed-up is lost. Tile the tangent **only** when it
+   genuinely differs per point (a distinct consistent tangent, e.g. plasticity);
+   there a GEMM collapse is not possible and per-point evaluation is correct.
+
+.. note:: A dedicated symmetric ``symtensor2`` (Kelvin-Mandel 6-vector storage)
+   was benchmarked as a way to speed the general contraction path and
+   **rejected**: it yields only ~1.1x on a single contraction and ~1.07x on
+   realistic distinct-tangent batch work, and Armadillo fixed-size containers
+   negate the 6-vs-9-double storage saving. The real ~20x lever is the
+   shared-tangent GEMM path above, which needs no new type; the C++ ``tensor2``
+   stays the general 3x3 type (the only one able to hold a non-symmetric tensor
+   such as ``F``, ``L``, ``R``). The Python ``Tensor2`` stores the 6 Voigt
+   components for the symmetric types (``"stress"``, ``"strain"``,
+   ``"symmetric"``) and the 9 components of any 3x3 for the type ``"none"`` (no
+   Voigt convention); a non-symmetric matrix given to a
+   symmetric type is refused rather than silently symmetrised.
+
+Basis: the reference system of the components
+---------------------------------------------
+
+Objectivity implies that the physical laws are independent of the choice of reference frame. 
+The components of a tensor only mean something together with the basis they are
+written in. By default that basis is the fixed orthonormal laboratory basis
+:math:`\mathbf{e}_i`: ``t.basis`` is ``None`` and nothing is stored. A
+``simcoon.Basis`` makes another choice explicit. It holds the basis vectors
+:math:`\mathbf{g}_i` through the matrix :math:`\mathbf{A}` whose columns are
+their laboratory frame components, and comes in two kinds:
+
+* **orthonormal**, built from a rotation, :math:`\mathbf{g}_i = \mathbf{R}\,\mathbf{e}_i`
+  (a material frame, a corotational frame). Its metric is the identity, so every
+  formula is the one of the lab.
+* **natural**, any three independent vectors, typically the convected basis
+  :math:`\mathbf{g}_i = \mathbf{F}\,\mathbf{G}_i` (``Basis.from_F``). Its metric
+  :math:`g_{ij} = \mathbf{g}_i \cdot \mathbf{g}_j`, i.e.
+  :math:`\mathbf{g} = \mathbf{A}^T \mathbf{A}`, enters the invariants.
+  'Natural' definition come from the convected basis of a material point.
+
+The type tag gives the variance of the components: a stress is contravariant,
+:math:`\boldsymbol{\sigma} = \sigma^{ij}\,\mathbf{g}_i \otimes \mathbf{g}_j`, a
+strain covariant, :math:`\boldsymbol{\varepsilon} = \varepsilon_{ij}\,\mathbf{g}^i
+\otimes \mathbf{g}^j`; a stiffness is contravariant on its four indices, a
+compliance covariant, the concentration tensors mixed. The lab components follow:
+
+.. math::
+
+   \boldsymbol{\sigma}_{lab} = \mathbf{A}\,\hat{\boldsymbol{\sigma}}\,\mathbf{A}^T,
+   \qquad
+   \boldsymbol{\varepsilon}_{lab} = \mathbf{A}^{-T}\,\hat{\boldsymbol{\varepsilon}}\,\mathbf{A}^{-1}.
+
+.. list-table:: Default variance of each type (``t.variance``)
+   :header-rows: 1
+   :widths: 30 22 48
+
+   * - Type
+     - Components
+     - Transport by :math:`\mathbf{F}` (``push_forward``)
+   * - ``Tensor2`` ``"stress"``
+     - :math:`\sigma^{ij}` (contravariant)
+     - :math:`\mathbf{F}\,\boldsymbol{\sigma}\,\mathbf{F}^T`, weight :math:`1/J` with ``metric=True``
+   * - ``Tensor2`` ``"strain"``
+     - :math:`\varepsilon_{ij}` (covariant)
+     - :math:`\mathbf{F}^{-T}\,\boldsymbol{\varepsilon}\,\mathbf{F}^{-1}`
+   * - ``Tensor2`` ``"symmetric"``, ``"none"`` (any 3x3, no Voigt convention)
+     - lab or orthonormal-frame components only
+     - none: no variance, hence no natural basis and no transport
+   * - ``Tensor4`` ``"stiffness"``, ``"generic"``
+     - :math:`C^{ijkl}`
+     - :math:`\mathbf{F}` on the four indices, weight :math:`1/J`
+   * - ``Tensor4`` ``"compliance"``
+     - :math:`M_{ijkl}`
+     - :math:`\mathbf{F}^{-T}` on the four indices, weight :math:`J`
+   * - ``Tensor4`` concentrations
+     - mixed, :math:`A_{ij}{}^{kl}` / :math:`B^{ij}{}_{kl}`
+     - pair-wise: :math:`\mathbf{F}^{-T}` on the covariant pair, :math:`\mathbf{F}` on the contravariant one
+
+The variance is a tag of the components, ``t.variance``, carried next to the type
+and the basis: ``"contravariant"`` or ``"covariant"`` for a ``Tensor2``, a pair
+``(output, input)`` for a ``Tensor4``. The table gives its default; it is read,
+not the type, by the transports, by ``to_basis`` and by the metric invariants.
+Two things the default is **not**:
+
+* It is not the only possible representation. Variance is a choice made for the
+  components, not a property of the tensor: with the metric any tensor can be
+  given contravariant or covariant components (``det`` and ``eigvals`` use the
+  mixed ones :math:`T^i{}_j = T^{ik} g_{kj}` internally). The default is the
+  one under which the conjugate pairs :math:`\mathbf{S} : \mathbf{E}` and
+  :math:`\boldsymbol{\tau} : \mathbf{e}` contract without a metric and the
+  convected components stay constant under transport. ``t.to_variance(v)``
+  gives the same tensor with components of the other variance: a retag in the
+  lab or an orthonormal basis (the numbers do not change), a contraction with
+  the metric in a natural basis, :math:`\sigma_{ij} = g_{ik}\,\sigma^{kl}\,g_{lj}`
+  (or its inverse), pair by pair for a ``Tensor4``. The Voigt shear factors stay
+  those of the type. Mixed components of a single pair are not representable in
+  6 components (they are not symmetric), hence a tag per pair. The variance is
+  part of what a transport means: a covariantly tagged stiffness pushes forward
+  with :math:`\mathbf{F}^{-T}` on its four indices, which is another tensor than
+  the push-forward of the contravariant one. A ``"symmetric"`` ``Tensor2`` has no
+  default variance: ``to_variance`` declares it before any transport or natural
+  basis; type ``"none"`` has none.
+* It is not a statement about every strain measure. The covariant transport is
+  that of the Green-Lagrange / Almansi pair. A logarithmic strain is a tensor
+  function of a stretch, not the transport of anything: ``push_forward`` on a
+  strain-typed :math:`\ln \mathbf{V}` is accepted by the type tag and has no
+  meaning.
+
+Two-point tensors have no basis
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The deformation gradient :math:`\mathbf{F} = F^i{}_J\,\mathbf{g}_i \otimes
+\mathbf{G}^J` has one index in each configuration, so there is no single basis
+to attach it to; in the convected pair :math:`(\mathbf{G}_i, \mathbf{g}_i =
+\mathbf{F}\,\mathbf{G}_i)` its mixed components are :math:`\delta^i_J`: it *is*
+the relation between the two bases. This is why ``F`` is always a plain array of
+lab components in the API, consumed by ``Basis.from_F`` and by the transports,
+never wrapped. The same holds for the rotation :math:`\mathbf{R}` of the polar
+decomposition, the rotation increment :math:`\Delta\mathbf{R}` and the first
+Piola-Kirchhoff stress. They can be held in a ``Tensor2`` of type ``"none"`` (no
+Voigt convention: 9 components, lab-lab). Such a tensor has no variance, hence no
+transport and no natural basis (re-expressing its components would need the
+variance of each leg); it does accept an orthonormal ``Basis``, both legs being
+read in that frame, since :math:`\mathbf{Q}^T \mathbf{X}\,\mathbf{Q}` is the same
+for every variance. It offers the trace, determinant, norm and eigenvalues, but
+no Voigt vector.
+
+Three operations, three meanings:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 72
+
+   * - Call
+     - Meaning
+   * - ``t.to_basis(b)``
+     - The same tensor, its components re-expressed in ``b`` (``None`` = lab).
+   * - ``t.with_basis(b)``
+     - The same components in another basis: a transport, hence another tensor.
+       No arithmetic, no copy.
+   * - ``t.rotate(R, active=False)``
+     - The same tensor in the frame turned by ``R``; the result carries that basis.
+
+Tensors written in different bases cannot be combined: ``+``, ``-``, ``@``,
+``%`` and the dyadic products raise ``ValueError("Mixed basis")``. A ``name``
+given to a basis is a label for ``repr`` and error messages; two bases are the
+same when their vectors are.
+
+.. code-block:: python
+
+   import numpy as np
+   import simcoon as sim
+
+   material = sim.Basis(rotation=sim.Rotation.from_euler("z", 30, degrees=True),
+                        name="material")
+   sigma = sim.Tensor2.stress(np.array([100., 0., 0., 0., 0., 0.]))
+   sigma_m = sigma.to_basis(material)     # material-frame components
+   sigma + sigma_m                        # ValueError: Mixed basis
+   sigma_m.to_basis(None)                 # lab components again
+
+One basis can serve a whole batch (it is stored once and shared by reference by
+every tensor derived from it), or a batch of N bases can give one per tensor.
+
+A basis also knows its reciprocal vectors :math:`\mathbf{g}^i` (``reciprocal``,
+the columns of :math:`\mathbf{A}^{-T}`, on which covariant components live), its
+right stretch :math:`\mathbf{U} = \sqrt{\mathbf{g}}` (``stretch``) and the
+orthonormal basis closest to it, the rotation of the polar decomposition
+:math:`\mathbf{A} = \mathbf{R}\,\mathbf{U}` (``polar``). For a convected basis
+these are the right stretch and the rotation of :math:`\mathbf{F}`; ``polar`` is
+the rotated orthonormal frame a convected tensor is often read in.
+
+Push-forward and pull-back carry the basis along
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A push-forward is a transport, not a change of basis: the result is another
+tensor, living in the current configuration. But in the convected basis its
+components are those the original tensor had in the reference basis:
+
+.. math::
+
+   \tau^{ij} = S^{IJ}, \qquad e_{ij} = E_{IJ}, \qquad
+   (\mathcal{L}_v \boldsymbol{\tau})^{ij} = \mathbb{C}^{IJKL}\,\dot{E}_{KL},
+
+with :math:`\boldsymbol{\tau}` the Kirchhoff stress, :math:`\mathbf{S}` the
+second Piola-Kirchhoff stress, :math:`\mathbf{e}` the Almansi and
+:math:`\mathbf{E}` the Green-Lagrange strain. Pushing forward carries the basis
+:math:`\mathbf{G}_i` to :math:`\mathbf{g}_i = \mathbf{F}\,\mathbf{G}_i` and keeps
+the components; the familiar :math:`\mathbf{F}\,\mathbf{S}\,\mathbf{F}^T` is that
+statement followed by "write the result in the lab". Accordingly:
+
+* on a lab tensor, ``push_forward(F)`` returns lab components, as before;
+* on a tensor that has its own basis, it keeps the components and returns the
+  convected basis :math:`\mathbf{F}\,\mathbf{A}` (``pull_back``:
+  :math:`\mathbf{F}^{-1}\mathbf{A}`). Only the weight :math:`1/J` of
+  ``metric=True`` (Kirchhoff to Cauchy, a density) touches the numbers.
+
+.. code-block:: python
+
+   F = np.array([[1., 0.5, 0.], [0., 1., 0.], [0., 0., 1.]])    # simple shear
+   S = sim.Tensor2.stress(np.array([0., 80., 0., 0., 0., 0.]))  # PK2 components
+   tau = S.with_basis(sim.Basis.from_F(F))    # Kirchhoff stress, same numbers
+   tau.to_basis(None)                         # == S.push_forward(F, metric=False)
+   tau.trace()                                # 100.0 = g_22 * 80, not 80
+
+The same holds for an active rotation: a lab tensor is rotated in the lab, a
+tensor with its own basis keeps its components while its basis vectors turn
+(:math:`\mathbf{A} \to \mathbf{Q}\,\mathbf{A}`), which leaves the metric and
+every invariant unchanged.
+
+Invariants with the metric
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Contractions between dual variances need no metric and act on the components in
+any basis: :math:`\boldsymbol{\sigma} : \boldsymbol{\varepsilon} = \sigma^{ij}
+\varepsilon_{ij}`, :math:`\mathbb{L} : \boldsymbol{\varepsilon}`, the inverse of
+a stiffness. Contracting two indices of the same variance does. For
+contravariant components (covariant ones exchange :math:`\mathbf{g}` and
+:math:`\mathbf{g}^{-1}`):
+
+.. math::
+
+   \mathrm{tr}\,\mathbf{T} = g_{ij}\,T^{ij}, \qquad
+   \mathrm{dev}\,\hat{\mathbf{T}} = \hat{\mathbf{T}} - \tfrac13\,(\mathrm{tr}\,\mathbf{T})\,\mathbf{g}^{-1}, \qquad
+   \mathbf{a} : \mathbf{b} = \mathrm{tr}(\hat{\mathbf{a}}\,\mathbf{g}\,\hat{\mathbf{b}}\,\mathbf{g}),
+
+.. math::
+
+   \sigma_{eq} = \sqrt{\tfrac32\,\mathbf{s} : \mathbf{s}}, \qquad
+   \det\mathbf{T} = \det\hat{\mathbf{T}}\,\det\mathbf{g}, \qquad
+   \det(\hat{\mathbf{T}} - \lambda\,\mathbf{g}^{-1}) = 0 .
+
+``trace``, ``dev``, ``mises``, ``norm``, ``det``, ``eigvals`` and ``%`` use these
+forms in a natural basis and the usual ones otherwise. The identity tensor is the
+metric itself: ``Tensor2.identity("stress", basis=b)`` has components
+:math:`g^{ij}`, ``Tensor2.identity("strain", basis=b)`` has :math:`g_{ij}`. For
+fourth-order tensors, ``Tensor4.identity``, ``volumetric`` and ``deviatoric``
+take the same ``basis`` argument; the stiffness-type identity becomes
+:math:`\tfrac12 (g^{ik} g^{jl} + g^{il} g^{jk})` and the volumetric projector
+:math:`\tfrac13\,g^{ij} g^{kl}`.
+
+.. note::
+
+   The Kelvin-Mandel form is an isometry only in an orthonormal basis. In a
+   natural basis ``.mandel`` and ``.voigt`` still return the stored components,
+   but ``eye(6)`` is no longer the stiffness-type identity and the plain
+   Frobenius norm of the 6x6 is not the norm of the tensor.
+
+Cost: with ``basis=None`` nothing changes. A basis costs one reference per
+tensor object, not per point; ``with_basis`` and the transports of a tensor with
+its own basis are free; ``to_basis`` costs one transport (the same kernel as
+``push_forward``); the metric of a natural basis is computed on first use and
+cached, and its invariants cost about one 3x3 product per point more than in the
+lab.
+
+API reference
+-------------
+
+.. autoclass:: simcoon.Basis
+   :members:
+
+.. autoclass:: simcoon.Tensor2
+   :members:
+   :inherited-members:
+
+.. autoclass:: simcoon.Tensor4
+   :members:
+   :inherited-members:
+
+.. autofunction:: simcoon.dyadic
+.. autofunction:: simcoon.auto_dyadic
+.. autofunction:: simcoon.sym_dyadic
+.. autofunction:: simcoon.auto_sym_dyadic
+.. autofunction:: simcoon.double_contract

{simcoon-2.1.0 → simcoon-2.2.0}/docs/cpp_api/continuum_mechanics_overview.md

@@ -23,7 +23,6 @@ Mathematical functions and tensor operations that form the foundation of continu
 - **recovery_props.hpp** - Material property recovery from stiffness/compliance tensors
 - **transfer.hpp** - Conversions between tensor and Voigt notations
 - **derivatives.hpp** - Tensor derivatives for sensitivity analysis
-- **natural_basis.hpp** - Natural basis transformations for curvilinear coordinates
 
 ### 2. **Homogenization** - Effective Property Calculations
 
@@ -59,8 +58,9 @@ User Material subroutines (UMAT) for finite element analysis, organized by strai
 - Isotropic, Orthotropic, Transversely Isotropic
 
 **Plasticity:**
-- `plastic_isotropic_ccp` - J2 plasticity with isotropic hardening (kept as a readable reference implementation)
-- `plastic_chaboche_ccp` - Chaboche multi-kinematic hardening model (kept as a readable reference implementation)
+- `plastic_isotropic` - J2 plasticity with isotropic hardening (kept as a readable reference implementation)
+- `plastic_chaboche` - Chaboche multi-kinematic hardening model (kept as a readable reference implementation)
+- `plastic_johnson_cook_ccp` - Johnson-Cook rate- and temperature-dependent J2 plasticity (`EPJCK`, mechanical and thermomechanical kernels)
 - All other plasticity variants (kinematic-isotropic `EPKCP`, Hill `EPHIL`/`EPTRI`/`EPHIN`,
   Hill-Chaboche `EPHAC`, anisotropic Chaboche `EPANI`/`EPDFA`/`EPCHG`) are served since 2.0
   by the **modular UMAT engine** through `umat_legacy_modular` name adapters — legacy names
@@ -202,7 +202,7 @@ vec eta = eta_stress(sigma);  // Returns 3/2 * s / sigma_eq
 ### UMAT Integration
 
 ```cpp
-#include <simcoon/Continuum_mechanics/Umat/Mechanical/Plasticity/plastic_isotropic_ccp.hpp>
+#include <simcoon/Continuum_mechanics/Umat/Mechanical/Plasticity/plastic_isotropic.hpp>
 
 using namespace simcoon;
 
@@ -216,7 +216,7 @@ vec statev = zeros(8);
 vec DEtot = {0.001, 0, 0, 0, 0, 0};
 
 // Call UMAT
-umat_plasticity_iso_CCP(Etot, DEtot, sigma, Lt, L, sigma_in, DR,
+umat_plasticity_iso(Etot, DEtot, sigma, Lt, L, sigma_in, DR,
                         6, props, 8, statev, T, DT, Time, DTime,
                         Wm, Wm_r, Wm_ir, Wm_d, 3, 3, false, 0, tnew_dt);
 ```

{simcoon-2.1.0 → simcoon-2.2.0}/docs/simulation/abaqus.rst

@@ -325,6 +325,10 @@ The following constitutive models are available through ``select_umat_M()``:
      - Von Mises + Voce + 2× Armstrong-Frederick
      - :math:`E, \nu, \alpha, \sigma_Y, Q, b, C_1, D_1, C_2, D_2`
      - 33
+   * - EPJCK
+     - Von Mises + Johnson-Cook yield stress (rate and temperature dependent)
+     - :math:`E, \nu, \alpha, A, B, n, C, \dot{\varepsilon}_0, m, T_{\mathrm{ref}}, T_{\mathrm{melt}}`
+     - 9 (T_init, p, EP, edot_p)
    * - EPHIL / EPTRI
      - Hill yield + power-law isotropic hardening
      - :math:`E, \nu, \alpha, \sigma_Y, k, m, F, G, H, L, M, N`

{simcoon-2.1.0 → simcoon-2.2.0}/docs/simulation/ansys.rst

@@ -142,6 +142,10 @@ Model Codes
      - EPCHA
      - Von Mises + Voce + 2× Armstrong-Frederick
      - :math:`E, \nu, \alpha, \sigma_Y, Q, b, C_1, D_1, C_2, D_2`
+   * - 29
+     - EPJCK
+     - Von Mises + Johnson-Cook yield stress (rate and temperature dependent)
+     - :math:`E, \nu, \alpha, A, B, n, C, \dot{\varepsilon}_0, m, T_{\mathrm{ref}}, T_{\mathrm{melt}}`
    * - 8
      - SMADI
      - SMA unified model

{simcoon-2.1.0 → simcoon-2.2.0}/docs/simulation/output.rst

@@ -74,10 +74,16 @@ run gives every conjugate pair:
      - Content
    * - ``Strain``
      - (6, N)
-     - Eulerian strain integrated along the path with the objective rate of the run (``corate``): the strain the constitutive law sees. With the logarithmic rates (``"logarithmic"``, ``"logarithmic_R"``, the default, ``"logarithmic_F"``) it is the logarithmic strain :math:`\ln \mathbf{V}` up to the integration error; with ``"jaumann"`` or ``"green_naghdi"`` it is the integral of :math:`\mathbf{D}` along the spin of the rate: path dependent, not a function of :math:`\mathbf{F}`, equal to :math:`\ln\mathbf{V}` only on paths whose principal axes do not rotate (in simple shear it departs at third order in :math:`\gamma`); with ``"truesdell"`` it is the **Almansi strain** :math:`\mathbf{e}_A = \frac{1}{2}(\mathbf{I} - \mathbf{b}^{-1})`, exactly, not a logarithmic strain
+     - Eulerian strain integrated along the path with the objective rate of the run (``corate``): the strain the constitutive law sees. With the logarithmic rates (``"logarithmic"``, ``"logarithmic_R"``, the default, ``"logarithmic_F"``) it is the logarithmic strain :math:`\ln \mathbf{V}` up to the integration error; with ``"jaumann"`` or ``"green_naghdi"`` it is the integral of :math:`\mathbf{D}` along the spin of the rate: path dependent, not a function of :math:`\mathbf{F}`, equal to :math:`\ln\mathbf{V}` only on paths whose principal axes do not rotate (in simple shear it departs at third order in :math:`\gamma`); with ``"truesdell"`` it is the **Almansi strain** :math:`\mathbf{e}_A = \frac{1}{2}(\mathbf{I} - \mathbf{b}^{-1})`, exactly, not a logarithmic strain. Under ``kinematic_form="total"`` no rate is involved: it is the material logarithmic strain :math:`\ln \mathbf{U}` in reference components, exact at any step size
    * - ``LogStrain``
      - (6, N)
-     - Logarithmic strain :math:`\ln \mathbf{V} = \frac{1}{2}\ln(\mathbf{F}\mathbf{F}^T)`, computed from :math:`\mathbf{F}`: exact whatever the rate. Use it, not ``Strain``, when the logarithmic strain is wanted under ``"truesdell"``, ``"jaumann"`` or ``"green_naghdi"``
+     - Logarithmic strain :math:`\ln \mathbf{V} = \frac{1}{2}\ln(\mathbf{F}\mathbf{F}^T)`, computed from :math:`\mathbf{F}`: exact whatever the rate. Under ``kinematic_form="total"`` it is the spatial counterpart of ``Strain``, which then holds the material :math:`\ln \mathbf{U}` in reference components. ``LogStrainV`` is the same field. Use it, not ``Strain``, when the logarithmic strain is wanted under ``"truesdell"``, ``"jaumann"`` or ``"green_naghdi"``
+   * - ``LogStrainU``
+     - (6, N)
+     - Material logarithmic strain :math:`\ln \mathbf{U} = \frac{1}{2}\ln(\mathbf{F}^T\mathbf{F})`, computed from :math:`\mathbf{F}`, in reference components: the strain of the total formulation. :math:`\ln\mathbf{V} = \mathbf{R}\,\ln\mathbf{U}\,\mathbf{R}^T`. Offered (policy) under ``kinematic_form="total"`` and under the rates whose strain is a function of :math:`\mathbf{F}`, exactly or in the limit of small steps: ``"logarithmic"``, ``"logarithmic_R"`` and ``"truesdell"``
+   * - ``LogStressU``
+     - (6, N)
+     - Stress :math:`\mathbf{T}` dual to :math:`\ln \mathbf{U}` (:math:`\mathbf{T}:\mathrm{d}\ln\mathbf{U} = \boldsymbol{\tau}:\mathbf{D}`), computed from ``Kirchhoff`` and :math:`\mathbf{F}`, in reference components: the stress of the total formulation. A change of measure of the stress of the run, whatever its formulation: it is what the law returned only under ``kinematic_form="total"`` (and, to first order in the step, under ``"logarithmic_R"`` for a log-strain box law), and not what a total run would have given. Offered with ``LogStrainU``
    * - ``GreenLagrange``
      - (6, N)
      - Green-Lagrange strain :math:`\mathbf{E} = \frac{1}{2}(\mathbf{F}^T\mathbf{F} - \mathbf{I})`, from :math:`\mathbf{F}`: exact whatever the rate
@@ -95,10 +101,10 @@ run gives every conjugate pair:
      - 2nd Piola-Kirchhoff stress :math:`\mathbf{S}`
    * - ``R``
      - (3, 3, N)
-     - Rotation accumulated by the objective rate of the run; it is the :math:`\mathbf{R}` of the polar decomposition :math:`\mathbf{F} = \mathbf{R}\mathbf{U}` for ``"green_naghdi"`` and ``"logarithmic_R"``, differs from it for ``"jaumann"`` and ``"logarithmic"``, and for the convected rates ``"truesdell"`` and ``"logarithmic_F"`` it is not a rotation: it accumulates the frame increments :math:`\Delta\mathbf{F}`, i.e. it is :math:`\mathbf{F}` itself (to round-off: runs start at :math:`\mathbf{F} = \mathbf{I}`)
+     - Rotation accumulated by the objective rate of the run; it is the :math:`\mathbf{R}` of the polar decomposition :math:`\mathbf{F} = \mathbf{R}\mathbf{U}` for ``"green_naghdi"`` and ``"logarithmic_R"``, differs from it for ``"jaumann"`` and ``"logarithmic"``, and for the convected rates ``"truesdell"`` and ``"logarithmic_F"`` it is not a rotation: it accumulates the frame increments :math:`\Delta\mathbf{F}`, i.e. it is :math:`\mathbf{F}` itself (to round-off: runs start at :math:`\mathbf{F} = \mathbf{I}`). Under ``kinematic_form="total"`` no frame is carried and it is the identity: take the polar rotation from ``F``
    * - ``DR``
      - (3, 3, N)
-     - Frame increment of the objective rate over the increment: the rotation :math:`\Delta\mathbf{R}`, or :math:`\Delta\mathbf{F} = \mathbf{F}_1\mathbf{F}_0^{-1}` for ``"truesdell"`` and ``"logarithmic_F"``
+     - Frame increment of the objective rate over the increment: the rotation :math:`\Delta\mathbf{R}`, or :math:`\Delta\mathbf{F} = \mathbf{F}_1\mathbf{F}_0^{-1}` for ``"truesdell"`` and ``"logarithmic_F"``; the identity under ``kinematic_form="total"``
 
 .. note::
 

{simcoon-2.1.0 → simcoon-2.2.0}/docs/simulation/solver.rst

@@ -52,7 +52,7 @@ The last part is to define the loading path. Create a folder ``data`` and a file
 
     {
       "initial_temperature": 293.5,
-      "corate": "logarithmic_R",
+      "kinematic_form": "logarithmic_R",
       "blocks": [
         {
           "control_type": "small_strain",
@@ -132,9 +132,12 @@ Solver parameters
    * - T_init
      - float
      - Initial temperature in Kelvin (default 293.15); ``load_path_json`` returns the value read from the path file
+   * - kinematic_form
+     - string or int
+     - ``"total"``, an objective rate, or ``"rate"`` (default, the rate ``"logarithmic_R"``): see below
    * - corate
-     - int or string
-     - Corotational spin rate type (see below)
+     - string or int
+     - Former name of ``kinematic_form``: the same value under either name
    * - tangent_mode
      - int
      - Tangent-operator mode (default 2): see below
@@ -184,8 +187,11 @@ constitutive models (also exposed as named constants:
        renumbering)
    * - 3
      - closest-point
-     - Reserved for the closest-point-projection exact operator (future
-       release); currently raises an error
+     - Closest-point-projection integrator: the plastic strain uses the flow of
+       the converged state, so the consistent operator is the exact Jacobian
+       of the discrete update for every criterion and hardening law the
+       integrator supports (rolling out law by law in this version; a law
+       without it returns the algorithmic operator of mode 2)
 
 .. note::
    **Scope of the algorithmic tangent (2.1).** The plastic return mapping is a
@@ -197,22 +203,68 @@ constitutive models (also exposed as named constants:
    path, and no tangent can be its exact derivative: the algorithmic operator is
    then a close approximation (about :math:`10^{-4}` to :math:`10^{-2}` relative,
    more for Tresca), which slows the global Newton iteration but leaves the
-   converged response unchanged. The closest-point integrator that makes it exact
-   (mode 3) is planned for the next version.
+   converged response unchanged. Mode 3 replaces the cutting-plane scheme by a
+   closest-point projection, which makes the operator exact for the laws that
+   carry it.
 
 .. note::
    **2.0 renumbering.** Pre-2.0, ``tangent_mode 0`` meant *continuum* and
-   ``1`` meant *algorithmic*; there was no "none" mode. The converged
-   response is identical in every mode (the tangent steers the global
-   Newton iteration, not the residual) — only iteration counts and run
-   time change. Scripts passing explicit values should shift them by +1;
+   ``1`` meant *algorithmic*; there was no "none" mode. Modes 0, 1 and 2
+   share the same integrator, so their converged response is identical (the
+   tangent steers the global Newton iteration, not the residual) — only
+   iteration counts and run time change; mode 3 integrates differently and
+   its converged response differs from theirs by the increment's second
+   order wherever the flow direction rotates within the step. Scripts
+   passing explicit values should shift them by +1;
    scripts relying on the default silently upgrade from continuum to the
    (faster) algorithmic operator.
 
+.. _finite-strain-formulation:
+
+Finite-strain formulation
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``kinematic_form`` parameter selects how a law is updated at finite strain. It fixes the pair
+of measures the law works on. It is one value: ``"total"``, or an objective rate of the table
+below (by name or by code), which means the rate formulation with that rate, or ``"rate"``, the
+rate formulation with its default rate ``"logarithmic_R"`` (also the default when nothing is
+given). ``corate`` is the former name of the same parameter and takes the same values; given
+together, the two must agree.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 14 22 22 42
+
+   * - kinematic_form
+     - Strain of the law
+     - Stress of the law
+     - Update
+   * - ``"rate"`` or an objective rate
+     - :math:`\ln\mathbf{V}` (spatial) under the logarithmic rates, the default included
+     - Kirchhoff :math:`\boldsymbol{\tau}`
+     - Integrated with the objective rate (table below); the stored state is
+       transported with the frame increment of that rate
+   * - ``"total"``
+     - :math:`\ln\mathbf{U}` (material)
+     - :math:`\mathbf{T}`, dual to :math:`\ln\mathbf{U}`
+     - No rate: the strain is a state function of :math:`\mathbf{F}` in reference components,
+       exact at any step size, and nothing is transported
+
+``"total"`` is the strain-space framework of Miehe, Apel and Lambrecht (2002). It involves no
+objective rate, serves the laws listed in
+:ref:`the total formulation <strain-space-route>`, and refuses ``"logarithmic"`` and
+``"small_strain"`` control. **Its**
+``Strain`` **output is** :math:`\ln\mathbf{U}`. Under the default rate ``"logarithmic_R"`` the two
+formulations run a log-strain box law on the same strain and read its output differently; on a
+path of prescribed :math:`\mathbf{F}` they coincide whenever the stress is coaxial with the
+stretch, up to the first-order quadrature of the log_R strain. A hyperelastic law built on
+:math:`\mathbf{F}` gives the same stress in both. The outputs ``LogStrainU``, ``LogStrainV`` and
+``LogStressU`` express either run in the measures of the other (see :doc:`output`).
+
 Corotational spin rate types
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The ``corate`` parameter controls the corotational formulation used in finite deformation problems:
+As an objective rate, ``kinematic_form`` (or ``corate``) controls the corotational formulation used in finite deformation problems:
 
 .. list-table::
    :header-rows: 1
@@ -278,7 +330,7 @@ General structure
 
     {
       "initial_temperature": 293.15,
-      "corate": "logarithmic_R",
+      "kinematic_form": "logarithmic_R",
       "blocks": [
         {
           "control_type": "small_strain",
@@ -295,7 +347,9 @@ Path and block parameters
 
 **initial_temperature**: initial temperature of the simulation (Kelvin); ``load_path_json`` returns it as ``T_init`` for ``solve``.
 
-**corate**: objective rate of the finite-strain control types (``"jaumann"``, ``"green_naghdi"``, ``"logarithmic"``, ``"logarithmic_R"``, ``"truesdell"``, ``"logarithmic_F"``, see the table above); returned by ``load_path_json`` for ``solve(corate=...)``.
+**kinematic_form**: ``"total"``, or the objective rate of the finite-strain control types (``"jaumann"``, ``"green_naghdi"``, ``"logarithmic"``, ``"logarithmic_R"``, ``"truesdell"``, ``"logarithmic_F"``, see the table above), or ``"rate"`` for the default rate ``"logarithmic_R"`` (also when absent). ``load_path_json`` returns it as its third element, for ``solve(kinematic_form=...)``.
+
+**corate**: former name of ``kinematic_form``, still read.
 
 **blocks**: the loading blocks, run in order. A block is mechanical or thermomechanical (coupled heat equation) according to its steps: all the steps of a block are :class:`~simcoon.solver.StepMeca` (``"thermomechanical": false``) or all are :class:`~simcoon.solver.StepThermomeca` (``"thermomechanical": true``).
 
@@ -347,7 +401,10 @@ Path and block parameters
    With ``"jaumann"``, ``"logarithmic"`` (XBM) or ``"logarithmic_F"`` under combined
    stretching and rotation, strain-controlled components are approximate and a difference
    is expected; this is one more reason to run with ``"logarithmic_R"`` (see the corate
-   table above).
+   table above). Under ``kinematic_form="total"`` the stored strain is :math:`\ln\mathbf{U}` and the
+   law's tangent is :math:`\partial\mathbf{T}/\partial\mathbf{H}`, so ``"logarithmic"`` control
+   is refused, and ``"small_strain"`` blocks as well (their strain is not carried by
+   :math:`\mathbf{F}`): use ``"green_lagrange"``, ``"biot"``, ``"F"`` or ``"gradU"``.
 
 **ncycle**: number of times the step sequence of the block is repeated (cyclic loading). A block holding a tabular step cannot be cycled.
 
@@ -497,7 +554,7 @@ Stress-controlled tension/compression cycle, 1000 increments per step:
 
     {
       "initial_temperature": 293.15,
-      "corate": "logarithmic_R",
+      "kinematic_form": "logarithmic_R",
       "blocks": [
         {
           "control_type": "small_strain",
@@ -540,7 +597,7 @@ Hyperelasticity with deformation gradient control
 
     {
       "initial_temperature": 293.5,
-      "corate": "logarithmic_R",
+      "kinematic_form": "logarithmic_R",
       "blocks": [
         {
           "control_type": "F",
@@ -575,7 +632,7 @@ Finite deformation with spin (logarithmic strain)
 
     {
       "initial_temperature": 290.0,
-      "corate": "logarithmic_R",
+      "kinematic_form": "logarithmic_R",
       "blocks": [
         {
           "control_type": "logarithmic",
@@ -607,7 +664,7 @@ Adiabatic strain-controlled loading/unloading (heat equation on, no heat flux):
 
     {
       "initial_temperature": 290.0,
-      "corate": "logarithmic_R",
+      "kinematic_form": "logarithmic_R",
       "blocks": [
         {
           "control_type": "small_strain",