Solver Functions
Functions and classes for solving thermomechanical boundary value problems.
-
void Lt_2_K(const arma::mat&, arma::mat&, const arma::Col<int>&, const double&)
Assemble the Newton Jacobian \( \mathbf{K} \) under mixed strain/stress control.
A stress-controlled component keeps its tangent row; a strain-controlled one is replaced by \( \lambda \) on the diagonal, so the increment it asks for is the prescribed one.
- Parameters:
Lt – [in] mechanical tangent operator
K – [out] the 6x6 Jacobian
cBC_meca – [in] per-component control flags, Voigt order [11,22,33,12,13,23]
lambda – [in] diagonal stiffness given to the prescribed components
-
void Lth_2_K(const arma::mat&, const arma::vec&, const arma::vec&, const double&, arma::mat&, const arma::Col<int>&, const int&, const double&)
Thermomechanical counterpart of Lt_2_K: the 7x7 Jacobian with the heat equation.
- Parameters:
dSdE, dSdT, dQdE, dQdT – [in] the four coupled tangent blocks (6x6, 6, 6, scalar)
K – [out] the 7x7 Jacobian
cBC_meca – [in] per-component mechanical control flags
cBC_T – [in] temperature control flag
lambda – [in] diagonal stiffness given to the prescribed components
-
void check_path_output(const std::vector<block>&, const solver_output&)
Check a loading programme against its output settings.
- Parameters:
blocks – [in] the loading blocks
so – [in] the output settings
-
int solver_run(std::vector<block> &blocks, const double &T_init, const solver_output &so, const std::string &umat_name, const arma::vec &props, const unsigned int &nstatev, const double &psi_rve, const double &theta_rve, const double &phi_rve, const int &solver_type, const int &corate_type, const solver_params &ctrl, solver_results_sink &sink, const std::vector<phase_characteristics> &sub_phases = {})
In-memory core of the solver: runs the block/cycle/step/increment loops on already-built loading blocks and streams results to a sink.
This is the single numerical engine: the loading path, the material and the sub-phases come in memory, the history goes to the sink.
The last case is the counterpart of the
inforcecontract. Withinforce== 1 an increment that did not quite converge is closed anyway and its residual carried into the next one, which absorbs it. That is a correction, and it presumes the prescribed state is reachable: a stress target above the plateau of a perfectly plastic law, or above the saturation of a surrogate model, is not. The solver therefore watches whether the carried residual is actually being absorbed over consecutive increments, and aborts rather than closing the whole step on a state it never reached. The diagnostic reports the strain increment the tangent asks for, \( -\mathbf{K}^{-1}\mathbf{r} \), which diverges as the tangent collapses.- Parameters:
blocks – Loading blocks with fully-defined steps (mutated during the run: step generation and the inforce residual carry-over write into the steps)
T_init – Initial temperature
so – Output configuration (only the per-block frequency logic and the statev/tangent selection are used by sinks)
umat_name – Constitutive model name (5 characters)
props – Material properties
nstatev – Number of internal state variables
psi_rve, theta_rve, phi_rve – Euler angles of the RVE orientation (rad)
solver_type – 0: classic Newton-Raphson, 1: RNL (control_type 1 only)
corate_type – Objective rate choice (see corate_kinematics, objective_rates.hpp)
ctrl – Numeric solver controls
sink – Results observer
sub_phases – Sub-phases of a mean-field model (MIHEN, MIMTN, MISCN, MIPLN), already built by the caller. They used to be read from Nellipsoids<N>.dat / Nlayers<N>.dat at the first increment; nothing is read from disk any more. Empty for every single-phase model.
- Returns:
0 on completion, 1 on early abort. A run aborts on an invalid solver type, an unrecognized thermal BC, a Newton loop that does not converge at the minimal increment with
inforce== 0, or a prescribed state the material cannot reach.
-
void geodesic_F_increments(const arma::mat &F_prev, const arma::vec &BC_meca, const arma::vec &inc_coef, const double &BC_Time, arma::vec ×, arma::mat &mecas, arma::mat &BC_mecas)
Increments of a kinematic step (control types 5/6, modes 1/2) on the geodesic from F_prev to the target: F_i = exp(w_i ln(F_target F_prev^-1)) F_{i-1}, weights w_i = inc_coef / sum(inc_coef). Control type 6 passes F_target = I + grad u. Shared by step_meca and step_thermomeca.
- Parameters:
F_prev – [in] deformation gradient at the start of the step
BC_meca – [in] target F, 9 components row-major
inc_coef – [in] increment weights (ones, or the sinusoidal mode’s)
BC_Time – [in] duration of the step
times – [out] time increments (sized ninc)
mecas – [out] generator of each increment, \( \Delta\mathbf{L}_i = w_i \ln(\mathbf{F}_{target}\mathbf{F}_{prev}^{-1}) \) (9 components row-major): a fraction s of increment i is \( \exp(s\,\Delta\mathbf{L}_i)\,\mathbf{F} \) (step cuts, set_driven_strain in the solver)
BC_mecas – [out] F at the end of each increment
-
void tabulated_F_increments(const arma::mat &F_prev, const arma::Col<int> &cBC_meca, const unsigned int &control_type, arma::mat &mecas, arma::mat &BC_mecas)
The tabulated (mode 3) kinematic step in the form geodesic_F_increments gives: BC_mecas holds F at the end of each increment and mecas the generator \( \Delta\mathbf{L}_i = \ln(\mathbf{F}_i\mathbf{F}_{i-1}^{-1}) \) of the increment, the row’s F reached on the geodesic between two table rows. Shared by step_meca and step_thermomeca.
- Parameters:
F_prev – [in] deformation gradient at the start of the step
cBC_meca – [in] 2 for a component absent from the table: held at its previous value
control_type – [in] 5 (the table gives F) or 6 (it gives grad u = F - I)
mecas – [out] generators, one row per increment (9 components row-major)
BC_mecas – [inout] in: the table values; out: F, one row per increment
-
class block
- #include <block.hpp>
Class representing a loading block containing multiple steps.
A block groups several loading steps that can be repeated (cycled) multiple times. This is useful for simulating cyclic loading, fatigue tests, or repeated thermomechanical cycles.
The block structure allows organizing complex loading histories:
Multiple steps within a block can represent different loading phases
The block can be cycled to simulate repetitive loading
Different control types (stress, strain, mixed) can be specified
Public Functions
-
block()
Default constructor.
-
block(const unsigned int &number, const unsigned int &nstep, const unsigned int &ncycle, const unsigned int &type, const unsigned int &control_type)
Constructor with basic parameters.
- Parameters:
number – Block identification number
nstep – Number of steps
ncycle – Number of cycles
type – Block type
control_type – Control type
Full constructor with step vector.
- Parameters:
number – Block identification number
nstep – Number of steps
ncycle – Number of cycles
type – Block type
control_type – Control type
steps – Vector of step pointers
-
virtual ~block()
Virtual destructor.
-
void generate()
Generate the steps within the block.
Public Members
-
unsigned int number
Block identification number.
-
unsigned int nstep
Number of steps in the block.
-
unsigned int ncycle
Number of cycles to repeat the block.
-
unsigned int type
Type of block (loading type identifier).
-
unsigned int control_type
Control type (0: strain, 1: stress, 2: mixed).
-
class solver_output
- #include <output.hpp>
Public Functions
-
solver_output()
Default constructor: no output requested, all types set to 0.
-
solver_output(const int &nblock)
Constructor with parameters; zero-sized output types and frequencies per block.
- Parameters:
nblock – number of blocks (size of o_type, o_nfreq, o_tfreq)
-
solver_output(const solver_output &so)
Copy constructor.
-
~solver_output()
Destructor.
-
virtual solver_output &operator=(const solver_output &so)
Copy assignment.
Public Members
-
int o_nb_strain
-
arma::Col<int> o_strain
-
int o_nb_stress
-
arma::Col<int> o_stress
-
int o_nb_T
-
int o_strain_type
-
int o_stress_type
-
int o_rotation_type
-
int o_tangent_modulus
-
int o_nw_statev
-
arma::Col<int> o_wanted_statev
-
arma::Col<int> o_range_statev
-
arma::Col<int> o_type
-
arma::Col<int> o_nfreq
-
arma::vec o_tfreq
Friends
-
friend std::ostream &operator<<(std::ostream &os, const solver_output &so)
-
solver_output()
-
struct solver_params
- #include <solver_sink.hpp>
Numeric controls of the global Newton-Raphson / adaptive time-stepping loop.
Defaults of the adaptive Newton loop.
Public Members
-
double div_tnew_dt = 0.5
time-step division factor on non-convergence
-
double mul_tnew_dt = 2.
time-step multiplication factor on fast convergence
-
int miniter = 10
iteration count below which the step may grow
-
int maxiter = 100
maximum Newton-Raphson iterations per increment
-
int inforce = 1
0: stop at Dn_mini, 1: enforce & carry residual, 2: enforce silently
-
double precision = 1.E-6
convergence tolerance on the residual norm (absolute)
-
double precision_rel = 0.
0: tolerance max(precision, precision_rel |tau|), |tau| the Euclidean norm of the Kirchhoff stress (Voigt), so that stiff or highly loaded cases are not asked for more digits than soft ones (de Souza Neto et al. 2008, sec. 4.2); 0: precision alone (default)
-
double lambda = 10000.
penalty stiffness for strain-controlled components
-
int tangent_mode = tangent_default
tangent_* constants (parameter.hpp)
-
int ncp = 0
complementarity function of the local cutting plane (NCPMethod code), see state_variables::ncp
-
double div_tnew_dt = 0.5
-
class solver_results_sink
- #include <solver_sink.hpp>
Observer that receives the solver state at output points.
solver_run() drives the cadence (solver_output frequency logic) and calls record() once per output point; implementations decide what to do with the converged state carried by the phase_characteristics.
Subclassed by solver_file_sink, solver_memory_sink
Public Functions
-
virtual ~solver_results_sink() = default
-
inline virtual void init(phase_characteristics &rve)
Called once at the very start of the simulation (start == true), after the first UMAT call, before the first increment.
-
virtual void record(phase_characteristics &rve, const solver_output &so, const int &kblock, const int &kcycle, const int &kstep, const int &kinc, const double &Time) = 0
Called at each output point. kblock/kcycle/kstep/kinc follow the same convention as phase_characteristics::output (0-based, written +1).
-
virtual ~solver_results_sink() = default
-
class solver_file_sink : public solver_results_sink
- #include <solver_sink.hpp>
File sink reproducing the historical solver() output behaviour: define_output() + phase_characteristics::output() on “global” and “local” streams.
Public Functions
-
solver_file_sink(const std::string &path_results, const std::string &outputfile_global, const std::string &outputfile_local)
-
virtual void init(phase_characteristics &rve) override
Called once at the very start of the simulation (start == true), after the first UMAT call, before the first increment.
-
virtual void record(phase_characteristics &rve, const solver_output &so, const int &kblock, const int &kcycle, const int &kstep, const int &kinc, const double &Time) override
Called at each output point. kblock/kcycle/kstep/kinc follow the same convention as phase_characteristics::output (0-based, written +1).
-
solver_file_sink(const std::string &path_results, const std::string &outputfile_global, const std::string &outputfile_local)
-
class solver_memory_sink : public solver_results_sink
- #include <solver_sink.hpp>
Memory sink capturing the canonical converged state per output point.
Stores raw state (all stress/strain measures carried by state_variables) so consumers derive whatever output measure they need; Cauchy stress is formed as tau/det(F1), consistent with phase_characteristics::output (o_stress_type 4). Thermomechanical quantities (Wt, Q, r, dSdE/dSdT/drdE/drdT) are captured when the global state variables are of type state_variables_T (sv_type == 2).
Public Functions
-
virtual void init(phase_characteristics &rve) override
Called once at the very start of the simulation (start == true), after the first UMAT call, before the first increment.
-
virtual void record(phase_characteristics &rve, const solver_output &so, const int &kblock, const int &kcycle, const int &kstep, const int &kinc, const double &Time) override
Called at each output point. kblock/kcycle/kstep/kinc follow the same convention as phase_characteristics::output (0-based, written +1).
-
void reserve(std::size_t n_records)
Capacity hint for
n_recordsmore records, for the fields of sv_type (call it after init()); solver_run passes its expected count. The move constructor of the arma objects is not noexcept, so each growth of these vectors would copy them all.
-
inline unsigned int n_records() const
number of records captured so far
Public Members
-
bool record_tangent = true
capture Lt (mechanical) or dSdE/dSdT/drdE/drdT (thermomechanical)
-
std::vector<int> blocks_i
-
std::vector<int> cycles_i
-
std::vector<int> steps_i
-
std::vector<int> incs_i
0-based indices per record
-
std::vector<double> time
-
std::vector<arma::vec> Etot
-
std::vector<arma::vec> etot
-
std::vector<arma::vec> PKII
-
std::vector<arma::vec> tau
-
std::vector<arma::vec> sigma
6-component Voigt vectors
-
std::vector<arma::mat> F1
-
std::vector<arma::mat> R
-
std::vector<arma::mat> DR
3x3 tensors
-
std::vector<double> T
-
std::vector<double> Q
-
std::vector<double> r
Q, r: thermomechanical only.
-
std::vector<arma::vec> Wm
[Wm, Wm_r, Wm_ir, Wm_d]
-
std::vector<arma::vec> Wt
[Wt, Wt_r, Wt_ir], thermomechanical only
-
std::vector<arma::vec> statev
-
std::vector<arma::mat> Lt
6x6, mechanical only
-
std::vector<arma::mat> dSdE
6x6, thermomechanical only
-
std::vector<arma::vec> dSdT
-
std::vector<arma::vec> drdE
6, thermomechanical only
-
std::vector<double> drdT
thermomechanical only
-
virtual void init(phase_characteristics &rve) override
-
class step
- #include <step.hpp>
Class representing a loading step within a simulation block.
A step defines a portion of the loading path with specified boundary conditions and time discretization parameters. It controls how the load is applied and how time increments are managed.
The step class manages:
Time discretization (initial, minimum increments)
Boundary condition mode (stress, strain, or mixed control)
Loading path definition through external files
Subclassed by step_meca, step_thermomeca
Public Functions
-
step()
Default constructor.
-
step(const int &number, const double &Dn_init, const double &Dn_mini, const double &Dn_inc, const int &mode, const unsigned int &control_type)
Constructor with parameters.
- Parameters:
number – Step identification number
Dn_init – Initial time increment fraction
Dn_mini – Minimum time increment fraction
Dn_inc – Maximum time increment fraction
mode – Loading mode
control_type – Control type
-
virtual ~step() = default
Virtual destructor; copies are memberwise (implicit).
-
virtual void generate()
Generate the time discretization for the step.
-
int mode3_ninc() const
Number of increments of a tabular (mode 3) step: the rows of tab_data.
- Throws:
exception_solver – when the step carries no table
-
arma::mat mode3_rows(const unsigned int &size_BC) const
Full tabular (mode 3) loading table, one row per increment. Returns tab_data, validated against size_BC.
- Throws:
exception_solver – when the step carries no table or its width differs
- Parameters:
size_BC – Expected number of columns (see tab_data for the layout)
-
virtual bool compute_inc(double &tnew_dt, const int &inc, double &tinc, double &Dtinc, double &Dn, const int &control)
Compute the next increment parameters.
- Parameters:
tnew_dt – Suggested new time increment ratio (output)
inc – Current increment number
tinc – Time increment (output)
Dtinc – Delta time increment (output)
Dn – Increment fraction (output)
control – Increment control flag
- Returns:
false when the increment fell below Dn_mini and inforce is off: the solver then aborts with status 1 (same protocol as a non-converged Newton loop).
Public Members
-
int number
Step identification number.
-
double Dn_init
Initial fraction of the step (initial time increment ratio).
-
double Dn_mini
Minimal fraction of the step (minimum time increment ratio).
-
double Dn_inc
Maximum fraction of the step (maximum time increment ratio).
-
int ninc
Number of milestones/increments in the step.
-
int mode
Loading mode identifier.
-
unsigned int control_type
Control type: 1 small strain, 2 Green-Lagrange, 3 logarithmic, 4 Biot, 5 F, 6 grad u (CONTROL_TYPES).
-
arma::vec times
Vector of time values for the step.
-
double BC_Time
Boundary condition application time.
-
arma::mat tab_data
Tabular loading data of a mode-3 step.
One row per increment; columns: [time, (T if cBC_T==0, or Q if cBC_T==1 for thermomechanical steps), controlled mechanical components with cBC_meca(k) < 2, in internal Voigt order (6 components for control_type <= 4, 9 for 5/6)].
-
class step_meca : public step
- #include <step_meca.hpp>
Public Functions
-
step_meca()
Default constructor: BC_T = 0, cBC_T = 0.
-
step_meca(const unsigned int &control_type)
Constructor that allocates cBC_meca and BC_meca (size 9 for control_type 5/6, else 6), BC_w = 0, BC_R = I.
- Parameters:
control_type – control type of the step
-
step_meca(const int &number, const double &Dn_init, const double &Dn_mini, const double &Dn_inc, const int &mode, const unsigned int &control_type, const arma::Col<int> &cBC_meca, const arma::vec &BC_meca, const arma::mat &mecas, const arma::mat &BC_mecas, const double &BC_T, const int &cBC_T, const arma::vec &Ts, const arma::vec &BC_Ts, const arma::mat &BC_w, const arma::mat &BC_R)
Constructor with parameters.
- Parameters:
number – step identification number
Dn_init – initial time increment fraction
Dn_mini – minimum time increment fraction
Dn_inc – maximum time increment fraction
mode – loading mode
control_type – control type
cBC_meca – type of each mechanical boundary condition (1 stress, 0 strain)
BC_meca – target values of the mechanical boundary conditions
mecas – mechanical increments, one row per increment
BC_mecas – cumulated mechanical boundary values, one row per increment
BC_T – target temperature
cBC_T – type of the thermal boundary condition
Ts – temperature increments, one per increment
BC_Ts – cumulated thermal boundary values, one per increment
BC_w – spin of the step (3x3)
BC_R – rotation of the step (3x3)
-
virtual void generate(const double&, const arma::vec&, const arma::vec&, const double&)
-
virtual void generate_kin(const double&, const arma::mat&, const double&)
Generate the increment tables for a fully kinematic step (control types 5/6).
- Parameters:
mTime – [in] current (absolute) time at the start of the step
mF – [in] current 3x3 deformation gradient \( \mathbf{F} \) (the step anchor)
mT – [in] current temperature Modes 1/2 interpolate geodesically between mF and BC_meca via the real matrix logarithm/exponential; mode 3 reads the 9-component F table (absolute time column).
-
virtual void assess_inc(const double&, double&, const double&, phase_characteristics&, double&, const double&, const arma::mat&, const int&)
-
virtual void generate()
Generate the time discretization for the step.
-
step_meca()
-
class step_thermomeca : public step
- #include <step_thermomeca.hpp>
Public Functions
-
step_thermomeca()
Default constructor: BC_T = 0, cBC_T = 0.
-
step_thermomeca(const unsigned int &control_type)
Constructor that allocates cBC_meca and BC_meca (size 9 for control_type 5/6, else 6), BC_w = 0, BC_R = I.
- Parameters:
control_type – control type of the step
-
step_thermomeca(const int &number, const double &Dn_init, const double &Dn_mini, const double &Dn_inc, const int &mode, const unsigned int &control_type, const arma::Col<int> &cBC_meca, const arma::vec &BC_meca, const arma::mat &mecas, const arma::mat &BC_mecas, const double &BC_T, const int &cBC_T, const arma::vec &Ts, const arma::vec &BC_Ts, const arma::mat &BC_w, const arma::mat &BC_R)
Constructor with parameters.
- Parameters:
number – step identification number
Dn_init – initial time increment fraction
Dn_mini – minimum time increment fraction
Dn_inc – maximum time increment fraction
mode – loading mode
control_type – control type
cBC_meca – type of each mechanical boundary condition (1 stress, 0 strain)
BC_meca – target values of the mechanical boundary conditions
mecas – mechanical increments, one row per increment
BC_mecas – cumulated mechanical boundary values, one row per increment
BC_T – target temperature or heat flux (see cBC_T)
cBC_T – type of the thermal boundary condition (1 heat flux, 0 fixed temperature)
Ts – temperature/heat increments, one per increment
BC_Ts – cumulated thermal boundary values, one per increment
BC_w – spin of the step (3x3)
BC_R – rotation of the step (3x3)
-
virtual void generate(const double&, const arma::vec&, const arma::vec&, const double&)
-
virtual void generate_kin(const double&, const arma::mat &m, const double&)
Generate the increment tables for a fully kinematic thermomechanical step (control types 5/6); same geodesic-F conventions as step_meca::generate_kin.
- Parameters:
mTime – [in] current (absolute) time at the start of the step
mF – [in] current 3x3 deformation gradient \( \mathbf{F} \) (the step anchor)
mT – [in] current temperature
-
virtual void assess_inc(const double&, double&, const double&, phase_characteristics&, double&, const double&, const arma::mat&, const int&)
-
virtual void generate()
Generate the time discretization for the step.
Public Members
-
arma::Col<int> cBC_meca
-
arma::vec BC_meca
-
arma::mat mecas
-
arma::mat BC_mecas
-
arma::mat BC_w
-
arma::mat BC_R
-
double BC_T
-
int cBC_T
-
arma::vec Ts
-
arma::vec BC_Ts
Friends
-
friend std::ostream &operator<<(std::ostream&, const step_thermomeca&)
-
step_thermomeca()