celeritas/field/FieldDriverOptions.hh

0001 //----------------------------------*-C++-*----------------------------------//
0002 // Copyright 2020-2024 UT-Battelle, LLC, and other Celeritas developers.
0003 // See the top-level COPYRIGHT file for details.
0004 // SPDX-License-Identifier: (Apache-2.0 OR MIT)
0005 //---------------------------------------------------------------------------//
0006 //! \file celeritas/field/FieldDriverOptions.hh
0007 //---------------------------------------------------------------------------//
0008 #pragma once
0009
0010 #include "corecel/Macros.hh"
0011 #include "corecel/Types.hh"
0012 #include "celeritas/Units.hh"
0013
0014 namespace celeritas
0015 {
0016 //---------------------------------------------------------------------------//
0017 /*!
0018  * Configuration options for the field driver.
0019  *
0020  * TODO: replace epsilon_rel_max with 1/epsilon_rel_max^2
0021  * TODO: replace safety with step_shrink_mul (or something to indicate that
0022  *       it's a multiplicative factor for reducing the step, not anything with
0023  *       geometry)
0024  * TODO: remove errcon
0025  */
0026 struct FieldDriverOptions
0027 {
0028     //! The minimum length of the field step
0029     real_type minimum_step = 1.0e-5 * units::millimeter;
0030
0031     //! The maximum sagitta of each substep ("miss distance")
0032     real_type delta_chord = 0.25 * units::millimeter;
0033
0034     //! Accuracy of intersection of the boundary crossing
0035     real_type delta_intersection = 1.0e-4 * units::millimeter;
0036
0037     //! Discretization error tolerance for each field substep
0038     real_type epsilon_step = 1.0e-5;
0039
0040     //! Targeted discretization error for "integrate step"
0041     real_type epsilon_rel_max = 1.0e-3;
0042
0043     //! UNUSED: Targeted discretization error for "one good step"
0044     real_type errcon = 1.0e-4;
0045
0046     //! Exponent to increase a step size
0047     real_type pgrow = -0.20;
0048
0049     //! Exponent to decrease a step size
0050     real_type pshrink = -0.25;
0051
0052     //! Scale factor for the predicted step size
0053     real_type safety = 0.9;
0054
0055     //! Largest allowable relative increase a step size
0056     real_type max_stepping_increase = 5;
0057
0058     //! Smallest allowable relative decrease in step size
0059     real_type max_stepping_decrease = 0.1;
0060
0061     //! Maximum number of integrations (or trials)
0062     short int max_nsteps = 100;
0063
0064     //! Maximum number of substeps in the field propagator
0065     short int max_substeps = 10;
0066
0067     //! Initial step tolerance
0068     static constexpr inline real_type initial_step_tol = 1e-6;
0069
0070     //! Chord distance fudge factor
0071     static constexpr inline real_type dchord_tol = 1e-5 * units::millimeter;
0072
0073     //! Lowest allowable scaling factor when searching for a chord
0074     static constexpr inline real_type min_chord_shrink = 0.5;
0075
0076     //! Whether all data are assigned and valid
0077     explicit CELER_FUNCTION operator bool() const
0078     {
0079         // clang-format off
0080       return  (minimum_step > 0)
0081            && (delta_chord > 0)
0082            && (delta_intersection > minimum_step)
0083            && (epsilon_step > 0 && epsilon_step < 1)
0084            && (epsilon_rel_max > 0)
0085            && (pgrow < 0)
0086            && (pshrink < 0)
0087            && (safety > 0 && safety < 1)
0088            && (max_stepping_increase > 1)
0089            && (max_stepping_decrease > 0 && max_stepping_decrease < 1)
0090            && (max_nsteps > 0) && (max_substeps > 0);
0091         // clang-format on
0092     }
0093 };
0094
0095 //---------------------------------------------------------------------------//
0096 //! Equality operator
0097 constexpr bool
0098 operator==(FieldDriverOptions const& a, FieldDriverOptions const& b)
0099 {
0100     // clang-format off
0101     return a.minimum_step == b.minimum_step
0102            && a.delta_chord == b.delta_chord
0103            && a.delta_intersection == b.delta_intersection
0104            && a.epsilon_step == b.epsilon_step
0105            && a.epsilon_rel_max == b.epsilon_rel_max
0106            && a.errcon == b.errcon
0107            && a.pgrow == b.pgrow
0108            && a.pshrink == b.pshrink
0109            && a.safety == b.safety
0110            && a.max_stepping_increase == b.max_stepping_increase
0111            && a.max_stepping_decrease == b.max_stepping_decrease
0112            && a.max_nsteps == b.max_nsteps
0113            && a.max_substeps == b.max_substeps
0114            && a.initial_step_tol == b.initial_step_tol
0115            && a.dchord_tol == b.dchord_tol
0116            && a.min_chord_shrink == b.min_chord_shrink;
0117     // clang-format on
0118 }
0119
0120 //---------------------------------------------------------------------------//
0121 // Throw a runtime assertion if any of the input is invalid
0122 void validate_input(FieldDriverOptions const&);
0123
0124 //---------------------------------------------------------------------------//
0125 }  // namespace celeritas