#ifndef FESA_ANALYSIS_NONLINEAR_STATIC_CONTROL_H_
#define FESA_ANALYSIS_NONLINEAR_STATIC_CONTROL_H_

#include <cstdint>
#include <string>
#include <vector>

#include "fesa/core/diagnostic.h"
#include "fesa/core/status.h"
#include "fesa/fem/dof_manager.h"
#include "fesa/math/sparse_matrix.h"
#include "fesa/math/vector.h"
#include "fesa/math/vector3.h"
#include "fesa/model/domain.h"

namespace fesa {

/// @brief Identifies one deterministic nonlinear load-factor increment.
struct LoadFactorIncrement {
  std::uint32_t increment_index;
  double load_factor;
  bool is_factor_one;
};

/// @brief Identifies the physical dimension of a convergence threshold.
enum class NewtonChannelUnit {
  kForce,
  kForceLength,
  kLength,
  kDimensionless,
};

inline constexpr double kNewtonRelativeThreshold = 1.0e-2;
inline constexpr double kNewtonZeroScaleThreshold = 1.0e-3;

/// @brief Carries one same-trial free residual convergence channel.
struct NewtonResidualChannelInput {
  std::string identity;
  Vector free_residual;
  Vector free_internal;
  Vector free_external;
};

/// @brief Carries one same-iteration free correction convergence channel.
struct NewtonCorrectionChannelInput {
  std::string identity;
  Vector fresh_correction;
  Vector current_increment;
};

/// @brief Groups the four approved Newton convergence channels.
struct NewtonConvergenceInput {
  NewtonResidualChannelInput force_residual;
  NewtonResidualChannelInput moment_residual;
  NewtonCorrectionChannelInput translation_correction;
  NewtonCorrectionChannelInput rotation_correction;
};

/// @brief Identifies the only approved Newton convergence comparison branch.
enum class NewtonConvergenceBranch { kRelative, kZeroScale };

/// @brief Records the deterministic decision for one Newton channel.
struct NewtonChannelDecision {
  std::string identity;
  double numerator_norm;
  double denominator_scale;
  NewtonConvergenceBranch branch;
  double threshold;
  NewtonChannelUnit threshold_unit;
  bool passed;
};

/// @brief Groups all four channel decisions and their logical conjunction.
struct NewtonConvergenceResult {
  NewtonChannelDecision force_residual;
  NewtonChannelDecision moment_residual;
  NewtonChannelDecision translation_correction;
  NewtonChannelDecision rotation_correction;
  bool combined_passed;
};

/// @brief Stores the full-space fixed-load vector and its exact tangent.
struct GlobalFixedLoadContribution {
  Vector generalized_external_force;
  SparseMatrix generalized_external_tangent;
  std::vector<Diagnostic> diagnostics;
};

/// @brief Derives the fixed nonlinear factor path from raw static controls.
/// @param step Immutable nonlinear static step that owns raw source controls.
/// @return Ordered factors ending in an exactly assigned factor one, or an
/// input failure.
Result<std::vector<LoadFactorIncrement>> BuildFixedLoadFactorSequence(
    const StepDefinition& step);

/// @brief Scales factor-one prescribed targets from the zero step-start state.
/// @param step Immutable nonlinear step whose boundary order fixes output
/// order.
/// @param load_factor Current finite factor in the closed interval [0, 1].
/// @return One absolute prescribed value per step boundary component, or an
/// input failure.
Result<Vector> ApplyAbsolutePrescribedDisplacementTarget(
    const StepDefinition& step, double load_factor);

/// @brief Assembles fixed-global CLOAD work once in full generalized space.
/// @param domain Immutable nonlinear semantic model with one active step.
/// @param dofs Stable full-DOF mapping for domain nodes.
/// @param trial_generalized_coordinates Current full global [u, phi] trial.
/// @param load_factor Current finite factor in the closed interval [0, 1].
/// @return External vector and tangent for r=f_int-f_ext and K=K_int-K_ext,
/// or a structured model/solver failure.
Result<GlobalFixedLoadContribution> AssembleGlobalFixedLoadContribution(
    const Domain& domain, const DofManager& dofs,
    const Vector& trial_generalized_coordinates, double load_factor);

/// @brief Rejects a nonzero source moment with director-parallel work.
/// @param director Current finite unit director in global coordinates.
/// @param source_moment Immutable fixed-global source moment.
/// @return Success when rho_M is at most 1e-12 or the source moment is zero.
Status CheckMomentAdmissibility(const Vector3& director,
                                const Vector3& source_moment);

/// @brief Evaluates the four immutable, typed Newton convergence gates.
/// @param input Same-trial free residuals and same-iteration corrections.
/// @return Per-channel decision records and their logical conjunction.
NewtonConvergenceResult EvaluateNewtonConvergence(
    const NewtonConvergenceInput& input);

}  // namespace fesa

#endif  // FESA_ANALYSIS_NONLINEAR_STATIC_CONTROL_H_