{"id":"beecac07-6f30-48c7-ad4f-cf4a331adc71","arxiv_id":"2607.07262","paper_version":1,"verdict":"CONDITIONAL","confidence":"MODERATE","novelty_score":6.0,"correctness_risk":"unknown","formal_verification":"none","parameter_count":6,"one_line_summary":"GalPort computes multi-timescale action-angle variables and orbital classifications for evolving barred galaxy simulations, with specialised bar phase-space analysis tools.","lead":"GalPort is a Python package that computes action-angle variables for simulated disc galaxies, classifying orbits by their resonance behaviour and mapping bar phase-space structure. It provides a practical toolkit for galactic dynamicists studying bar formation and evolution in N-body models.","discovery_kind":"unclear","skeptic_critique":{"model":"glm-5.2","headline":"Reader's two-resonance gap is overstated: Appendix A explicitly handles two slow angles; the real concern is lack of independent validation of the averaging procedure near resonance overlap.","rationale":"The reader correctly identifies that the theoretical justification for the averaging procedure near resonances is a load-bearing assumption. However, the specific framing — that there is an unbridged gap between single-resonance theory and the two-resonance bar application — is inaccurate. Appendix A explicitly handles two slow angles and derives the averaging error for the two-resonance case. The Sec. 2.2 non-applicability statement refers to the analytical pendulum construction, not the numerical averaging. The real concern is narrower: first-order perturbation theory breaks down near resonance overlap and separatrix, and the empirical parameters lack sensitivity analysis. These are standard limitations for a methods/software contribution. The CONDITIONAL verdict is appropriate — the methods are novel and the code is public, but independent validation against established techniques would strengthen confidence. The concern does not warrant a stronger verdict than CONDITIONAL, nor does it require weakening to REJECT, since the empirical results (Figs. 3-7) are self-consistent and the theoretical framework is sound to first order.","tokens_in":34222,"tokens_out":3124,"duration_ms":245450,"concrete_test":"Select ~1000 bar particles from the N-body model that are classified as librating at ILR. For each, compute the averaged action J_v = J_R + J_z + L_z/2 using the GalPort averaging procedure, and independently compute the same quantity using a standard frequency analysis method (e.g., NAFF or the Ceverino & Klypin 2007 least-squares approach) on the same orbits. If the two estimates disagree by more than ~10% for more than ~5% of particles, the averaging procedure has a systematic bias near resonance that would weaken the package's core utility.","verdict_should_be":"UNCHANGED","load_bearing_attack":"The reader identifies a gap between single-resonance perturbative theory and the two-resonance bar Hamiltonian (Eq. 18), citing Sec. 2.2's statement that the approach 'is not applicable in a system with two resonances.' However, this conflates two distinct things. The Sec. 2.2 statement refers to the analytical pendulum construction (Eq. 16), which is indeed single-resonance. The numerical averaging procedure (Sec. 3.1.2) is a different approach, and Appendix A explicitly derives its error for TWO slow angles (θ_1, θ_2) and one fast angle (θ_0), with the canonical transformation in Eq. (28) introducing two resonances N_1, N_2. The error analysis (Eq. 31-33) shows suppression by the ratio of slow to fast frequencies, valid for the two-resonance bar case. So the specific gap the reader identifies is smaller than claimed. The more genuine concern is that Appendix A's argument is first-order perturbation theory assuming clean frequency separation between fast and slow angles. Near resonance overlap or for orbits with large libration amplitudes approaching the separatrix, this separation degrades, and the averaging procedure's accuracy is unquantified. The paper does not systematically test this regime or compare averaged variables against independent frequency analysis methods on the same orbits. The empirical parameters (eccentricity cutoff 0.1, period ratio 1.4 in Sec. 3.1.2) are stated as empirically determined without sensitivity analysis, making it hard to assess robustness across different galaxy models. These are real but standard limitations for a methods paper, not structural flaws.","agreement_with_reader":"partial"},"referee_report":{"model":"glm-5.2","summary":"This paper presents GalPort, a Python package for analyzing the orbital dynamics of evolving disc galaxy N-body models in action-angle space. The package implements numerical methods for estimating actions, angles, and frequencies across particle-specific timescales: instantaneous (short-term), averaged (medium-term, associated with radial/vertical oscillations), and secular (long-term, associated with libration/circulation near resonances). The key algorithmic contributions are: (1) a mean-preserving spline averaging procedure that eliminates short-term oscillations from instantaneous action-angle variables computed via the Stäckel fudge method, yielding variables approximating the averaged Hamiltonian dynamics; (2) an orbit classification scheme based on resonant angle behavior (positive/negative circulation, libration, resonance passage); and (3) a phase-portrait fitting procedure that fits an analytical two-dimensional Hamiltonian to orbit ensembles in the (J, theta) plane. The package is demonstrated on an N-body model of a barred galaxy, producing action/frequency distributions, a dynamical decomposition (48% bar, 40% disc, 11% central, 0.5% x2), and phase-space portraits of bar orbits. The code is publicly available under an MIT license.","tokens_in":34717,"tokens_out":1644,"duration_ms":346275,"significance":"The paper addresses a genuine methodological gap: while action-angle variables are well-established for axisymmetric systems (via AGAMA, Galpy), their practical computation and interpretation in evolving non-axisymmetric potentials—particularly for bar dynamics—remains challenging. The package's ability to compute time series of averaged and secular action-angle variables simultaneously at all simulation timesteps, with particle-specific averaging windows, is a useful contribution. The orbit classification scheme based on angle evolution rather than frequency analysis is a practical alternative that avoids fixed time-window constraints. The phase-portrait fitting procedure, which condenses many orbits into a single analytical Hamiltonian, is a novel and potentially valuable tool. The public release of the code under MIT license is commendable and enhances reproducibility. The work builds on the authors' prior theoretical papers (Zozulia et al. 2024a,b, 2025) but the algorithmic implementation and fitting procedure constitute new contributions.","major_comments":[{"comment":"Sec. 3.1.2 and Appendix A: The averaging procedure is justified perturbatively in Appendix A for the case of two slow angles and one fast angle (Eq. 28-33), which is the relevant configuration for the bar Hamiltonian (Eq. 18). However, the error analysis is first-order perturbation theory assuming clean frequency separation between fast and slow angles. Near resonance overlap or for orbits with large libration amplitudes approaching the separatrix, this separation degrades. The paper does not systematically test the averaging procedure's accuracy in these regimes, nor does it compare averaged variables against independent methods (e.g., frequency analysis) on the same orbits. Given that the bar region is precisely where resonance overlap and large-amplitude libration occur, some quantitative validation—even on a small subset of orbits—would substantially strengthen the paper's central方法论","section":null},{"comment":"Sec. 3.1.2: The empirical parameters for apocentre merging (eccentricity cutoff 0.1, period ratio threshold 1.4) and the interpolation factor (100x via cubic spline) are stated as 'empirically determined through extensive numerical experiments' but no sensitivity analysis is provided. Since these parameters affect frequency estimates and could introduce systematic biases, a brief discussion of how robust the results are to their variation would be appropriate, particularly for the frequency distributions in Fig. 4 that are used to argue against using instantaneous axisymmetric frequencies.","section":null},{"comment":"Sec. 3.3, Eq. (27): The phase-portrait fitting procedure minimizes a loss function with a weighting factor w_theta (stated as typically unity with 'negligible' effect), but no justification is given for the particular form of the loss function (why normalize by sqrt(J_i) and 2*pi respectively?). Additionally, the polynomial representation of h(J) as sum of a_k * J^(k/2) is motivated by the epicycle approximation, but the maximum order n_max and k_max are not specified in the main text. For reproducibility, these choices and their impact on the fitted Hamiltonian should be documented.","section":null}],"minor_comments":[{"comment":"Sec. 2.2: The sentence containing 'Fortunately, even unperturbed axisymmetric action-angle variables...' has a stray period before it ('. . Fortunately'), creating a formatting artifact.","section":null},{"comment":"Sec. 2.3, Table 1: The table header says 'up to 7-th order' but the 'Order' column values (0, 2, 3, 4, 5, 6, 7) appear to count the sum of absolute values of the integer coefficients in the angle combination, not the perturbation order per se. Clarifying this terminology would avoid confusion.","section":null},{"comment":"Sec. 3.1.1: The statement 'we do not recommend using instantaneous frequencies, even for rough estimates' is strong. It would help to quantify the typical systematic offset (the 'constant value that varies between individual orbits' mentioned in Eq. 20) to give readers a sense of magnitude.","section":null},{"comment":"Fig. 3: The 'mean secular' panels are described as secular actions averaged between t=350 and t=450 with resolution 5 time units. It would help to state how many averaging intervals this corresponds to and whether the structures visible are robust to this window choice.","section":null},{"comment":"Sec. 4.3: The 'Not disc, not bar' component (11%) is described with three circulation criteria that are model-specific. The text notes 'in other models, these orbits may have other angular behaviour.' Given this caveat, it would be useful to flag this classification as provisional in the figure caption or the text more prominently.","section":null},{"comment":"Sec. 4.4, Fig. 6: The Poincaré maps for instantaneous vs. averaged variables are compared, and it is stated that averaged variables 'do not alter the position of the fixed point.' This is an important claim; a brief quantitative comparison (e.g., fixed point location shift) would strengthen it.","section":null},{"comment":"The paper references 'BT8' and 'BT08' for Binney & Tremaine (2008) inconsistently (Sec. 2.1 uses 'BT8', Sec. 2.1 Stäckel section uses 'BT8', while Sec. 2.1 cylindrical section uses 'BT08'). Standardize.","section":null},{"comment":"Sec. 4.1: The time unit conversion (13.8 Myr per time unit) is given but the pattern speed Omega_p value is not explicitly stated, though it appears in figures. Stating it in the text would aid reproducibility.","section":null}],"recommendation":"minor_revision","confidential_remarks":"The reader's concern about the two-resonance gap is partially valid but somewhat overstated: Appendix A does handle two slow angles explicitly. The more genuine concern is the lack of independent validation near resonance overlap, which I have elevated to a major comment. The paper is primarily methodological/software and the central claims are defensible; the issues raised are about validation depth rather than correctness. The code being public mitigates some concerns as the community can test it. The novelty is incremental over the authors' prior work but the software package and phase-portrait fitting are genuine new contributions. I recommend minor revision with the validation and sensitivity analysis points addressed."},"author_rebuttal":null,"desk_editor":{"model":"glm-5.2","letter":"Short version: this is a methods/software paper that ships a publicly available Python package for analyzing barred galaxy simulations in action-angle space. The core contribution is a particle-specific multi-timescale averaging algorithm that smooths instantaneous actions and frequencies into medium-term (averaged) and long-term (secular) variables, plus an angle-based orbit classification scheme and a phase-portrait fitting procedure for bar-aligned orbits. The code is on GitHub under MIT license, which is good practice and earns credit for reproducibility. The N-body demonstration is sensible — the 48% bar / 40% disc decomposition is reasonable, and the frequency-ratio distributions clearly show why axisymmetric frequencies fail for bar orbits, which is a useful pedagogical point. The phase-portrait fitting producing an analytic 2D Hamiltonian that captures the separatrix structure (Figs. 6-7) is a nice touch. The theoretical framework for the bar Hamiltonian (Eq. 18, Table 1) is well-organized and gives a clear roadmap for which perturbative terms matter physically. The perturbative justification in Appendix A does handle two slow angles, not just one — so the reader's concern about a single-resonance gap is partially overstated. The real soft spot is narrower: Appendix A is first-order perturbation theory assuming clean frequency separation between fast and slow angles. Near resonance overlap or for orbits with large libration amplitudes approaching the separatrix, this separation degrades and the averaging accuracy is unquantified. The paper doesn't systematically test this regime or benchmark averaged variables against independent frequency analysis on the same orbits. The empirical parameters (eccentricity cutoff 0.1, period ratio 1.4) are stated as empirically determined without sensitivity analysis, which makes cross-model robustness hard to assess. These are standard limitations for a methods paper, not structural flaws. The package is a genuine contribution for galactic dynamics researchers working with barred galaxy simulations. It deserves a serious referee who can push on the resonance-overlap regime and request at least one benchmark comparison against existing frequency analysis methods.","headline":"Useful action-angle toolkit for barred galaxies; averaging theory has a real but non-fatal gap near resonance overlap","tokens_in":35225,"tokens_out":488,"would_cite":true,"duration_ms":136714,"reading_group":"yes","serious_thinker":"yes","would_accept_peer_review":true},"rs_alignment":null,"lean_confirmation":null,"pith_extraction":{"msc":[],"pacs":[],"model":"glm-5.2","headline":"New method decodes galactic bar orbits across timescales","keywords":["galactic dynamics","action-angle variables","barred galaxies","orbital classification","resonance trapping","N-body simulations","perturbation theory","Hamiltonian systems"],"falsifier":"If orbits classified as librating by the averaged-angle method systematically fail to satisfy independent resonance-trapping criteria (e.g., frequency analysis or direct Poincaré sections), the classification scheme would be unreliable.","tokens_in":34297,"feed_emoji":"🌌","tokens_out":805,"duration_ms":282039,"temperature":0.7,"pith_summary":"The paper introduces GalPort, a Python package that tracks how stars move inside barred galaxies by computing their action-angle variables (quantities that describe orbital shape and position) at multiple timescales simultaneously. The key innovation is an averaging algorithm that smooths away short-period fluctuations to reveal the slow resonant dynamics governing whether a star is trapped inside the bar, circulates past it, or swings through a resonance. Applied to an N-body galaxy simulation, the method produces a dynamical decomposition of the bar into its constituent orbital families and yields analytic two-dimensional Hamiltonians that capture the bar's phase-space structure.","feed_headline":"New method decodes galactic bar orbits across timescales","feed_subtitle":"Averaging algorithm strips fast oscillations from stellar trajectories, revealing which stars are trapped in the bar and which swing past.","key_machinery":"Mean-preserving quadratic splines applied to piecewise-averaged actions and frequencies, computed between successive orbital turning points (apocentres for radial motion, z-maxima and z-minima for vertical motion), producing smooth time series that approximate the dynamics of the averaged Hamiltonian near resonances.","core_discovery":"The central claim is that one can recover meaningful averaged action-angle variables for individual orbits in a time-varying non-axisymmetric galactic potential by piecewise-averaging instantaneous actions between successive apocentres and vertical extrema, then applying mean-preserving splines. This procedure suppresses fast oscillatory perturbations and yields variables governed by the resonant (slow) part of the Hamiltonian, enabling orbit classification by whether the resonant angle librates, circulates, or transits between regimes.","pith_inferences":["If the averaging procedure generalises to potentials with multiple overlapping resonances beyond the ILR and vILR pair considered here, it could become a standard tool for studying resonance overlap and chaotic diffusion in galactic discs more broadly.","The fitted two-dimensional Hamiltonians could be chained across time snapshots to produce a movie of separatrix migration, offering a quantitative measure of how much stellar mass crosses the bar boundary per unit time.","Applying the same averaging strategy to real stellar data (e.g., Gaia) rather than simulations would require orbit integration in an assumed potential; the method's sensitivity to potential errors is not explored and may limit direct observational application."],"forward_implications":["The method enables tracking how individual stars join or leave the bar over cosmic time, providing a particle-by-particle history of bar growth and trapping.","Secular action-angle variables reveal fine structure in the frequency-ratio plane that instantaneous axisymmetric estimates obscure, potentially improving dynamical modelling of the Milky Way bar from Gaia data.","The two-dimensional fitted Hamiltonians for bar-aligned orbits offer a compact analytical portrait of phase-space geometry that could replace expensive full three-dimensional Fourier computations for bar structure analysis.","Orbit classification by resonant-angle behaviour (libration vs. circulation vs. swing-by) provides a time-localised alternative to frequency-analysis methods, which are constrained by fixed time windows."],"fun_headline_variants":["Python tool traces bar orbits via action-angle variables","Averaging algorithm classifies trapped and passing bar orbits","Action-angle method separates trapped and circulating stars","GalPort maps resonant trapping in evolving galactic bars","Orbit decomposition reveals which stars lock into galactic bar"],"cache_read_input_tokens":0,"weakest_assumption_plain":"The averaging algorithm is perturbatively justified for orbits near a single resonance, but the bar Hamiltonian involves two simultaneous slow resonant angles; the paper does not rigorously bridge this gap, relying instead on empirical validation through the N-body demonstration.","fun_headline_variants_meta":{"raw":{"variants":["Python tool traces bar orbits via action-angle variables","Averaging algorithm classifies trapped and passing bar orbits","Action-angle method separates trapped and circulating stars","GalPort maps resonant trapping in evolving galactic bars","Orbit decomposition reveals which stars lock into galactic bar"]},"model":"glm-5.2","effort":"low","cost_usd":0.0,"raw_usage":{"total_tokens":570,"prompt_tokens":506,"completion_tokens":64,"prompt_tokens_details":null},"tokens_in":506,"tokens_out":64,"duration_ms":54195,"temperature":1.0,"reasoning_tokens":null,"cache_read_input_tokens":0,"cache_creation_input_tokens":0},"cache_creation_input_tokens":0},"created_at":"2026-07-09T15:40:34.657141+00:00","model_set":{"reader":"glm-5.2"},"falsifier":"If orbits classified as librating by the averaged-angle method systematically fail to satisfy independent resonance-trapping criteria (e.g., frequency analysis or direct Poincaré sections), the classification scheme would be unreliable.","supporting_citations":[],"review_version":1}