docs: translate French comments and docstrings to English

- Update discretization_utils.jl docstrings to follow docstrings.md standards
- Translate all French comments in solution.jl, test files
- Replace 'nd' with 'multi' to avoid typos false positives
- Improve code clarity for international contributors

Author: ocots

src/OCP/Building/discretization_utils.jl

@@ -2,39 +2,44 @@
 # Used for serialization (JSON, JLD2) and solution reconstruction
 
 """
-    _discretize_function(f::Function, T::AbstractVector, dim::Int=-1)::Matrix{Float64}
+$(TYPEDSIGNATURES)
 
-Discrétise une fonction sur une grille temporelle.
+Discretize a function on a time grid.
+
+Evaluates `f` at each point in `T` and collects the results into a matrix.
+If `dim` is -1, the output dimension is auto-detected from the first evaluation of `f`.
 
 # Arguments
-- `f::Function`: Fonction à discrétiser (peut retourner scalaire ou vecteur)
-- `T::AbstractVector`: Grille temporelle (ou TimeGridModel)
-- `dim::Int`: Dimension attendue du résultat. Si -1, auto-détectée depuis la première évaluation.
+- `f::Function`: Function to discretize (can return a scalar or a vector).
+- `T::AbstractVector`: Time grid.
+- `dim::Int`: Expected dimension of the result. If -1, auto-detected from first evaluation.
 
 # Returns
-- `Matrix{Float64}`: Matrice n×dim où n = length(T)
+- `Matrix{Float64}`: n×dim matrix where n = length(T).
 
 # Examples
 ```julia
-# Fonction scalaire
+# Scalar function
 f_scalar = t -> 2.0 * t
 result = _discretize_function(f_scalar, [0.0, 0.5, 1.0], 1)
 # result = [0.0; 1.0; 2.0]
 
-# Fonction vectorielle
+# Vector function
 f_vec = t -> [t, 2*t]
 result = _discretize_function(f_vec, [0.0, 0.5, 1.0], 2)
 # result = [0.0 0.0; 0.5 1.0; 1.0 2.0]
 
-# Auto-détection de dimension
+# Auto-detect dimension
 result = _discretize_function(f_vec, [0.0, 0.5, 1.0])
 # result = [0.0 0.0; 0.5 1.0; 1.0 2.0]
 ```
+
+See also: [`_discretize_dual`](@ref)
 """
 function _discretize_function(f::Function, T::AbstractVector, dim::Int=-1)::Matrix{Float64}
     n = length(T)
 
-    # Auto-détecter dimension si nécessaire
+    # Auto-detect dimension if necessary
     if dim == -1
         first_val = f(T[1])
         dim = first_val isa Number ? 1 : length(first_val)
@@ -53,27 +58,31 @@ function _discretize_function(f::Function, T::AbstractVector, dim::Int=-1)::Matr
 end
 
 """
-    _discretize_function(f::Function, T::TimeGridModel, dim::Int=-1)::Matrix{Float64}
+$(TYPEDSIGNATURES)
 
-Surcharge pour TimeGridModel - extrait automatiquement la grille temporelle.
+Discretize a function on a `TimeGridModel` by extracting the underlying time grid.
+
+See also: [`_discretize_function`](@ref)
 """
 function _discretize_function(f::Function, T::TimeGridModel, dim::Int=-1)::Matrix{Float64}
     return _discretize_function(f, T.value, dim)
 end
 
 """
-    _discretize_dual(dual_func::Union{Function,Nothing}, T, dim::Int=-1)
+$(TYPEDSIGNATURES)
 
-Helper pour discrétiser les fonctions duales qui peuvent être `nothing`.
+Discretize a dual function, returning `nothing` if the input is `nothing`.
 
 # Arguments
-- `dual_func`: Fonction duale ou `nothing`
-- `T`: Grille temporelle
-- `dim`: Dimension (auto-détectée si -1)
+- `dual_func::Union{Function,Nothing}`: Dual function or `nothing`.
+- `T`: Time grid.
+- `dim::Int`: Dimension (auto-detected if -1).
 
 # Returns
-- `Matrix{Float64}` si `dual_func` est une fonction
-- `nothing` si `dual_func` est `nothing`
+- `Matrix{Float64}` if `dual_func` is a function.
+- `nothing` if `dual_func` is `nothing`.
+
+See also: [`_discretize_function`](@ref)
 """
 function _discretize_dual(dual_func::Union{Function,Nothing}, T, dim::Int=-1)
     return isnothing(dual_func) ? nothing : _discretize_function(dual_func, T, dim)

src/OCP/Building/solution.jl

@@ -797,52 +797,53 @@ end
 # ============================================================================== #
 
 """
-    _serialize_solution(sol::Solution)::Dict{String, Any}
+$(TYPEDSIGNATURES)
 
-Sérialise une solution en données discrètes pour export (JLD2, JSON, etc.).
-Utilise les getters publics pour accéder aux champs de la solution.
+Serialize a solution into discrete data for export (JLD2, JSON, etc.).
 
-Cette fonction extrait toutes les données d'une solution et les convertit en format
-sérialisable (matrices, vecteurs, scalaires). Les fonctions sont discrétisées sur
-la grille temporelle.
+Extracts all data from a solution and converts it into a serializable format
+(matrices, vectors, scalars). Functions are discretized on the time grid.
+Uses public getters to access solution fields.
 
 # Arguments
-- `sol::Solution`: Solution à sérialiser
+- `sol::Solution`: Solution to serialize.
 
 # Returns
-- `Dict{String, Any}`: Dictionnaire contenant toutes les données discrètes :
-  - `"time_grid"`: Grille temporelle
-  - `"state"`, `"control"`, `"costate"`: Matrices discrétisées
-  - `"variable"`: Vecteur de variables
-  - `"objective"`: Valeur scalaire
-  - Fonctions duales discrétisées (peuvent être `nothing`)
-  - Duals de boundary et variable (vecteurs)
-  - Informations du solveur
+- `Dict{String, Any}`: Dictionary containing all discrete data:
+  - `"time_grid"`: Time grid
+  - `"state"`, `"control"`, `"costate"`: Discretized matrices
+  - `"variable"`: Variable vector
+  - `"objective"`: Scalar value
+  - Discretized dual functions (can be `nothing`)
+  - Boundary and variable duals (vectors)
+  - Solver information
 
 # Notes
-- Les fonctions sont discrétisées via `_discretize_function`
-- Les duals `nothing` sont préservés comme `nothing`
-- Compatible avec `build_solution` pour reconstruction
+- Functions are discretized via `_discretize_function`.
+- `nothing` duals are preserved as `nothing`.
+- Compatible with `build_solution` for reconstruction.
 
 # Example
 ```julia
 sol = solve(ocp)
 data = CTModels._serialize_solution(sol)
 # Reconstruction
 sol_reconstructed = CTModels.build_solution(
-    ocp, data["time_grid"], data["state"], data["control"], 
-    data["variable"], data["costate"]; 
+    ocp, data["time_grid"], data["state"], data["control"],
+    data["variable"], data["costate"];
     objective=data["objective"], ...
 )
 ```
+
+See also: [`build_solution`](@ref), [`_discretize_function`](@ref)
 """
 function _serialize_solution(sol::Solution)::Dict{String, Any}
-    # Utiliser les getters publics
+    # Use public getters
     T = time_grid(sol)
     dim_x = state_dimension(sol)
     dim_u = control_dimension(sol)
 
-    # Discrétiser les fonctions principales
+    # Discretize main functions
     return Dict(
         "time_grid" => T,
         "state" => _discretize_function(state(sol), T, dim_x),
@@ -851,19 +852,19 @@ function _serialize_solution(sol::Solution)::Dict{String, Any}
         "variable" => variable(sol),
         "objective" => objective(sol),
 
-        # Discrétiser les fonctions duales (peuvent être nothing)
+        # Discretize dual functions (can be nothing)
         "path_constraints_dual" => _discretize_dual(path_constraints_dual(sol), T),
         "state_constraints_lb_dual" => _discretize_dual(state_constraints_lb_dual(sol), T),
         "state_constraints_ub_dual" => _discretize_dual(state_constraints_ub_dual(sol), T),
         "control_constraints_lb_dual" => _discretize_dual(control_constraints_lb_dual(sol), T),
         "control_constraints_ub_dual" => _discretize_dual(control_constraints_ub_dual(sol), T),
 
-        # Duals de boundary et variable (vecteurs, pas fonctions)
+        # Boundary and variable duals (vectors, not functions)
         "boundary_constraints_dual" => boundary_constraints_dual(sol),
         "variable_constraints_lb_dual" => variable_constraints_lb_dual(sol),
         "variable_constraints_ub_dual" => variable_constraints_ub_dual(sol),
 
-        # Infos solver
+        # Solver info
         "iterations" => iterations(sol),
         "message" => message(sol),
         "status" => status(sol),

test/extras/debug_stack.jl

@@ -5,21 +5,21 @@
 # JSON: [[1.0], [2.0], [3.0]]
 data_1d = [[1.0], [2.0], [3.0]]
 
-# Case 2: Multi-D path (e.g. state of dimension 2 over 3 time steps)
+# Case 2: Multi-dimensional path (e.g. state of dimension 2 over 3 time steps)
 # JSON: [[1.0, 1.1], [2.0, 2.1], [3.0, 3.1]]
-data_nd = [[1.0, 1.1], [2.0, 2.1], [3.0, 3.1]]
+data_multi = [[1.0, 1.1], [2.0, 2.1], [3.0, 3.1]]
 
 println("--- Case 1: 1D Data ---")
 stacked_1d = stack(data_1d; dims=1)
 println("Type: ", typeof(stacked_1d))
 println("Size: ", size(stacked_1d))
 println("Content: ", stacked_1d)
 
-println("\n--- Case 2: Multi-D Data ---")
-stacked_nd = stack(data_nd; dims=1)
-println("Type: ", typeof(stacked_nd))
-println("Size: ", size(stacked_nd))
-println("Content: ", stacked_nd)
+println("\n--- Case 2: Multi-dimensional Data ---")
+stacked_multi = stack(data_multi; dims=1)
+println("Type: ", typeof(stacked_multi))
+println("Size: ", size(stacked_multi))
+println("Content: ", stacked_multi)
 
 # Verify current logic for 1D
 if stacked_1d isa Vector

test/extras/test_jld2_roundtrip.jl

@@ -28,20 +28,20 @@ println("\n✓ Export successful")
 sol_imported = CTModels.import_ocp_solution(CTModels.JLD2Tag(), ocp; filename=filename)
 println("✓ Import successful")
 
-# Vérifier que les valeurs sont identiques
+# Verify that values are identical
 println("\nImported solution:")
 println("  Objective: ", CTModels.objective(sol_imported))
 println("  State at t=0.5: ", CTModels.state(sol_imported)(0.5))
 println("  Control at t=0.5: ", CTModels.control(sol_imported)(0.5))
 println("  Costate at t=0.5: ", CTModels.costate(sol_imported)(0.5))
 
-# Comparaison détaillée
+# Detailed comparison
 obj_match = CTModels.objective(sol_original) ≈ CTModels.objective(sol_imported)
 state_match = CTModels.state(sol_original)(0.5) ≈ CTModels.state(sol_imported)(0.5)
 control_match = CTModels.control(sol_original)(0.5) ≈ CTModels.control(sol_imported)(0.5)
 costate_match = CTModels.costate(sol_original)(0.5) ≈ CTModels.costate(sol_imported)(0.5)
 
-# Test sur plusieurs points temporels
+# Test on multiple time points
 t_test = [0.0, 0.25, 0.5, 0.75, 1.0]
 all_states_match = all(CTModels.state(sol_original)(t) ≈ CTModels.state(sol_imported)(t) for t in t_test)
 all_controls_match = all(CTModels.control(sol_original)(t) ≈ CTModels.control(sol_imported)(t) for t in t_test)

test/suite/ocp/test_discretization_utils.jl

@@ -9,37 +9,37 @@ function test_discretization_utils()
     @testset "Discretization utilities" begin
 
         @testset "Basic discretization - scalar function" verbose = VERBOSE showtiming = SHOWTIMING begin
-            # Fonction scalaire simple
+            # Simple scalar function
             f_scalar = t -> 2.0 * t
             T = [0.0, 0.5, 1.0]
 
-            # Avec dimension explicite
+            # With explicit dimension
             result = CTModels.OCP._discretize_function(f_scalar, T, 1)
             @test size(result) == (3, 1)
             @test result ≈ [0.0; 1.0; 2.0]
 
-            # Avec auto-détection
+            # With auto-detection
             result_auto = CTModels.OCP._discretize_function(f_scalar, T)
             @test result_auto ≈ result
         end
 
         @testset "Basic discretization - vector function" begin
-            # Fonction vectorielle
+            # Vector function
             f_vec = t -> [t, 2*t]
             T = [0.0, 0.5, 1.0]
 
-            # Avec dimension explicite
+            # With explicit dimension
             result = CTModels.OCP._discretize_function(f_vec, T, 2)
             @test size(result) == (3, 2)
             @test result ≈ [0.0 0.0; 0.5 1.0; 1.0 2.0]
 
-            # Avec auto-détection
+            # With auto-detection
             result_auto = CTModels.OCP._discretize_function(f_vec, T)
             @test result_auto ≈ result
         end
 
         @testset "TimeGridModel support" begin
-            # Test avec TimeGridModel
+            # Test with TimeGridModel
             T_grid = CTModels.TimeGridModel(LinRange(0.0, 1.0, 5))
             f = t -> [t, t^2]
 
@@ -86,8 +86,8 @@ function test_discretization_utils()
         end
 
         @testset "Scalar return from vector function" begin
-            # Fonction retourne vecteur mais on veut dim=1
-            f = t -> [2.0 * t]  # Retourne vecteur de taille 1
+            # Function returns vector but we want dim=1
+            f = t -> [2.0 * t]  # Returns vector of size 1
             T = [0.0, 0.5, 1.0]
 
             result = CTModels.OCP._discretize_function(f, T, 1)

test/suite/serialization/test_export_import.jl

@@ -772,22 +772,22 @@ function test_export_import()
             ocp, sol0 = solution_example()
 
             # First cycle
-            CTModels.export_ocp_solution(sol0; filename="idempotence_json_nd1", format=:JSON)
+            CTModels.export_ocp_solution(sol0; filename="idempotence_json_multi1", format=:JSON)
             sol1 = CTModels.import_ocp_solution(
-                ocp; filename="idempotence_json_nd1", format=:JSON
+                ocp; filename="idempotence_json_multi1", format=:JSON
             )
 
             # Second cycle
-            CTModels.export_ocp_solution(sol1; filename="idempotence_json_nd2", format=:JSON)
+            CTModels.export_ocp_solution(sol1; filename="idempotence_json_multi2", format=:JSON)
             sol2 = CTModels.import_ocp_solution(
-                ocp; filename="idempotence_json_nd2", format=:JSON
+                ocp; filename="idempotence_json_multi2", format=:JSON
             )
 
             # Verify idempotence
             Test.@test compare_solutions(sol1, sol2)
 
-            remove_if_exists("idempotence_json_nd1.json")
-            remove_if_exists("idempotence_json_nd2.json")
+            remove_if_exists("idempotence_json_multi1.json")
+            remove_if_exists("idempotence_json_multi2.json")
         end
 
         Test.@testset "JSON idempotence: with complex infos" verbose = VERBOSE showtiming = SHOWTIMING begin
@@ -910,22 +910,22 @@ function test_export_import()
             ocp, sol0 = solution_example()
 
             # First cycle
-            CTModels.export_ocp_solution(sol0; filename="idempotence_jld_nd1", format=:JLD)
+            CTModels.export_ocp_solution(sol0; filename="idempotence_jld_multi1", format=:JLD)
             sol1 = CTModels.import_ocp_solution(
-                ocp; filename="idempotence_jld_nd1", format=:JLD
+                ocp; filename="idempotence_jld_multi1", format=:JLD
             )
 
             # Second cycle
-            CTModels.export_ocp_solution(sol1; filename="idempotence_jld_nd2", format=:JLD)
+            CTModels.export_ocp_solution(sol1; filename="idempotence_jld_multi2", format=:JLD)
             sol2 = CTModels.import_ocp_solution(
-                ocp; filename="idempotence_jld_nd2", format=:JLD
+                ocp; filename="idempotence_jld_multi2", format=:JLD
             )
 
             # Verify idempotence
             Test.@test compare_solutions(sol1, sol2)
 
-            remove_if_exists("idempotence_jld_nd1.jld2")
-            remove_if_exists("idempotence_jld_nd2.jld2")
+            remove_if_exists("idempotence_jld_multi1.jld2")
+            remove_if_exists("idempotence_jld_multi2.jld2")
         end
 
         # ========================================================================