Add missing COCOS labels, standardize sign convention terminology and documentation by Simon-McIntosh · Pull Request #214 · iterorganization/IMAS-Data-Dictionary

Simon-McIntosh · 2026-03-02T09:48:29Z

Downstream consumers of the data dictionary (imas-python, imas-codex) currently rely on hard-coded lists of COCOS-dependent quantities because the schema lacks complete COCOS transformation metadata and consistent sign convention documentation. This PR closes that gap by labelling all remaining COCOS-dependent fields and ensuring every labelled field carries a clear, plain-text description of its sign convention consistent with COCOS 17.

The changes are split into three commits, each independently buildable and validated against the DD XSLT pipeline (0 validation errors).

Commit 1: feat: add psi_like, dodpsi_like, and missing b0_like COCOS labels

Adds cocos_label_transformation, cocos_transformation_expression, and cocos_leaf_name_aos_indices metadata to fields that were previously unlabelled:

psi_like (.fact_psi): poloidal flux fields (psi, psi_axis, psi_boundary, psi_magnetic_axis, psi_external_average, dpsi_drho_tor, resistive_psi_losses, psi_star_pre/post_crash) across equilibrium, core_profiles, disruption, distributions, mhd, pellets, reflectometer_fluctuation, sawteeth, summary, wall, waves, and shared types in dd_support.xsd.
dodpsi_like (.fact_dodpsi): derivatives with respect to psi (dpressure_dpsi, f_df_dpsi, dvolume_dpsi, darea_dpsi) in equilibrium.
b0_like (.sigma_b0_eff): toroidal flux and related fields (phi, phi_poloidal_current, phi_halo_boundary) in equilibrium and disruption.

12 files, 153 insertions.

Commit 2: fix: standardize sign convention terminology across all schemas

Applies consistent terminology throughout all schema documentation strings:

Replaces "anti-clockwise" and "anticlockwise" with "counter-clockwise" (25 occurrences).
Standardizes "when viewing from above" / "seen from above" to "when viewed from above".
Hyphenates "counter clockwise" to "counter-clockwise".
Removes explicit COCOS index references (e.g. "COCOS = 11") from documentation strings, since these are implementation details that belong in the transformation metadata, not in user-facing descriptions.

17 files, 62 insertions, 62 deletions.

Commit 3: docs: add sign convention documentation to all COCOS-labelled fields

Adds plain-text sign convention statements to 78 fields across 15 files that had COCOS transformation metadata but no documentation of what the sign means physically. The text varies by label type:

b0_like: "Positive sign means counter-clockwise when viewed from above"
ip_like: same for currents; "Sign is positive when j.B is in the same direction as B0" for parallel quantities
psi_like: "For a positive plasma current (counter-clockwise when viewed from above), increases from the magnetic axis to the boundary"
dodpsi_like: "Sign depends on the poloidal flux sign convention"
q_like: "Positive when toroidal current and toroidal magnetic field are in the same direction"
tor_angle_like: "Increases counter-clockwise when viewed from above"

Fields intentionally left without sign text: species names in summary (inherit context from parent velocity_phi element), measured/reconstructed constraint containers (generic by design), one_like (scaling only, no sign), pol_angle_like theta fields (already documented with right-hand rule orientation), and grid_type_*_like (topology, not sign).

15 files, 78 insertions, 78 deletions.

📚 Documentation preview 📚: https://imas-data-dictionary--214.org.readthedocs.build/en/214/

Add cocos_label_transformation metadata to all COCOS-dependent poloidal flux (psi) and toroidal flux (phi) quantities that were previously unlabeled. This enables imas-python and other consumers to perform COCOS transformations from DD metadata rather than maintaining hardcoded lists. New labels added: - psi_like (.fact_psi): poloidal flux fields (units=Wb) - dodpsi_like (.fact_dodpsi): derivatives w.r.t. psi (dpressure_dpsi, f_df_dpsi, dvolume_dpsi, darea_dpsi) - b0_like (.sigma_b0_eff): toroidal flux fields that were missing (phi_poloidal_current, ggd phi, sawteeth phi, disruption phi) Coverage by IDS: - dd_support.xsd: 16 fields in shared types (plasma_radial_grid, core_radial_grid, psi_normalization, position types, etc.) - dd_equilibrium.xsd: 19 fields (boundary, global_quantities, profiles_1d, profiles_2d, ggd, contour_tree) - dd_core_profiles.xsd: 1 field (resistive_psi_losses) - dd_disruption.xsd: 3 fields (psi/phi halo boundary) - dd_distributions.xsd: 1 field (profiles_2d grid psi) - dd_mhd.xsd: 1 field (ggd psi) - dd_pellets.xsd: 1 field (path_profiles psi) - dd_reflectometer_fluctuation.xsd: 2 fields (position psi) - dd_sawteeth.xsd: 3 fields (phi, psi_star pre/post crash) - dd_summary.xsd: 3 fields (position psi, psi_external_average) - dd_wall.xsd: 1 field (ggd psi) - dd_waves.xsd: 1 field (profiles_2d grid psi) Fields intentionally NOT labeled: - psi_norm: normalized, sign cancels - d/d(psi_norm): normalized, sign cancels - flux_loop constraints: sign determined by physical loop geometry - generic_grid_scalar values/coefficients: inherit from parent AoS

Ensure consistent terminology for sign convention documentation: - Replace 'anti-clockwise' and 'anticlockwise' with 'counter-clockwise' (25 occurrences across 17 files) - Standardize 'when viewing from above' and 'when seen from above' to 'when viewed from above' - Hyphenate 'counter clockwise' to 'counter-clockwise' - Remove explicit COCOS references from xs:documentation strings; sign convention behaviour is managed via DD metadata (cocos_label_transformation, cocos_transformation_expression) Affected documentation patterns: - Plasma current: 'Positive sign means counter-clockwise when viewed from above' - Toroidal field: same pattern, also standardize 'viewing' -> 'viewed' - Loop voltage: 'flows counter-clockwise when viewed from above' - Toroidal angle: 'oriented counter-clockwise when viewed from above' - Mode numbers: 'phi runs counter-clockwise when viewed from above' - Constraint types: replace 'cocos transform' with descriptive text

Add clear, plain-text sign convention statements to 78 COCOS-labelled fields across 15 schema files that were missing this documentation. Sign convention descriptions by COCOS label type: - b0_like: Positive sign means counter-clockwise when viewed from above - ip_like: Positive sign means counter-clockwise when viewed from above (j_parallel: sign relative to j.B and B0) (e_field_parallel: sign relative to E.B and B0) - psi_like: For a positive plasma current (counter-clockwise when viewed from above), increases from the magnetic axis to the boundary - dodpsi_like: Sign depends on the poloidal flux sign convention - q_like: Positive when toroidal current and toroidal magnetic field are in the same direction - tor_angle_like (angles/momentum): Increases/positive counter-clockwise when viewed from above Fields intentionally without sign text: - Species names (argon, carbon, etc.) in summary velocity_phi: inherit physics context from parent element - measured/reconstructed constraint containers: generic by design - one_like fields: no sign convention (scaling only) - pol_angle_like (theta): already documented with right-hand rule - grid_type_*_like: grid topology, not sign convention

github-actions · 2026-03-02T09:49:13Z

Diff of generated Data Dictionary XML file

github-actions · 2026-03-02T09:50:22Z

Diff of generated Data Dictionary XML file

schemas/sawteeth/dd_sawteeth.xsd

The previous wording 'Positive sign means counter-clockwise when viewed from above' is misleading because toroidal flux is a scalar integral over a poloidal cross-section - it cannot itself be counter-clockwise. The sign depends on the direction of the toroidal magnetic field whose integral defines the flux. Replace with 'Positive when the toroidal magnetic field is counter-clockwise when viewed from above' on all magnetic toroidal flux fields (equilibrium, sawteeth, disruption). Transport flux descriptions in edge_transport/plasma_transport are unchanged as those describe directional particle/energy flows.

Improve documentation for psi_star_pre_crash and psi_star_post_crash to clarify that psi* = psi - phi is the helical magnetic flux for the m=1, n=1 internal kink mode relevant to sawtooth reconnection. Replace vague 'Sign follows the poloidal flux convention' with the explicit psi_like sign description used consistently elsewhere.

github-actions · 2026-03-02T15:24:34Z

Diff of generated Data Dictionary XML file

schemas/core_profiles/dd_core_profiles.xsd

…_like The reviewer correctly identified that resistive_psi_losses should not transform as psi_like. The quantity is defined as: int((int(E_phi * j_ohm_phi dV) / Ip) dt) Both E_phi (toroidal electric field) and j_ohm_phi (toroidal ohmic current density) transform as ip_like (sigma_Rphi_Z * sigma_Bp), so their product is COCOS-invariant (the factors square to unity). Dividing by Ip (ip_like) gives an overall ip_like transformation. This is confirmed by the Ejima coefficient definition: C_E = resistive_psi_losses / (mu0 * R * Ip) Since C_E is a dimensionless physical constant (COCOS-invariant) and Ip is ip_like, resistive_psi_losses must also be ip_like. In DD v4 (COCOS 17), psi_like and ip_like happen to coincide because sigma_RphiZ = +1 and e_Bp = 1, but they differ for general COCOS conversions (e.g., COCOS 17 to COCOS 2). Updated both core_profiles and dd_support (plasma_initiation/summary template).

github-actions · 2026-03-04T08:19:02Z

Diff of generated Data Dictionary XML file

…ation Replace COCOS-internal language (ip_like, COCOS-invariant) with standalone physical description matching the pattern used by ip, v_loop, and other current-related fields in the same IDS: 'Positive when the plasma current flows counter-clockwise when viewed from above'. The DD documentation should be self-contained without requiring knowledge of the COCOS label system. The cocos_label_transformation and cocos_transformation_expression metadata remain correct (ip_like / .sigma_ip_eff) for programmatic use by conversion tools.

github-actions · 2026-03-04T08:38:09Z

Diff of generated Data Dictionary XML file

olivhoenen

Thanks for all the suggested improvements on the metadata and description. As we seem to have converged now and as there is no risk of impacting codes, we propose to merge this clarification now in develop and also to cherry pick the commit as a patch over 4.1.

SimonPinches · 2026-03-12T16:02:35Z

schemas/nbi/dd_nbi.xsd

 			<xs:element name="position" type="rphiz0d_static">
 				<xs:annotation>
-					<xs:documentation>R, Z, Phi position of the beamlet group centre</xs:documentation>
+					<xs:documentation>R, Z, Phi position of the beamlet group centre. The toroidal angle (phi) increases counter-clockwise when viewed from above</xs:documentation>


Shouldn't this be:

Suggested change

<xs:documentation>R, Z, Phi position of the beamlet group centre. The toroidal angle (phi) increases counter-clockwise when viewed from above</xs:documentation>

<xs:documentation>R, Phi, Z position of the beamlet group centre. The toroidal angle (phi) increases counter-clockwise when viewed from above</xs:documentation>

SimonPinches · 2026-03-12T16:07:13Z

schemas/nbi/dd_nbi.xsd

 			<xs:element name="direction">
 				<xs:annotation>
-					<xs:documentation>Direction of the beam seen from above the torus: -1 = clockwise; 1 = counter clockwise</xs:documentation>
+					<xs:documentation>Direction of the beam seen from above the torus: -1 = clockwise; 1 = counter-clockwise</xs:documentation>


For consistency:

Suggested change

<xs:documentation>Direction of the beam seen from above the torus: -1 = clockwise; 1 = counter-clockwise</xs:documentation>

<xs:documentation>Orientation of the beam when viewed from above: -1 = clockwise; 1 = counter-clockwise</xs:documentation>

SimonPinches · 2026-03-12T16:11:43Z

schemas/pf_active/dd_pf_active.xsd

 			<xs:element name="current" type="signal_flt_1d">
 				<xs:annotation>
-					<xs:documentation>Current in the circuit between the sides of the group of supplies (only for circuits with a single supply or in which supplies are grouped)</xs:documentation>
+					<xs:documentation>Current in the circuit between the sides of the group of supplies (only for circuits with a single supply or in which supplies are grouped). Positive sign means counter-clockwise when viewed from above</xs:documentation>


I think we're referring to the circuit diagram here and the concept of "viewing from above" doesn't apply:

Suggested change

<xs:documentation>Current in the circuit between the sides of the group of supplies (only for circuits with a single supply or in which supplies are grouped). Positive sign means counter-clockwise when viewed from above</xs:documentation>

<xs:documentation>Current in the circuit between the sides of the group of supplies (only for circuits with a single supply or in which supplies are grouped). Positive sign means current flows from first connection to second connection.</xs:documentation>

SimonPinches · 2026-03-12T16:14:06Z

schemas/pf_active/dd_pf_active.xsd

 			<xs:element name="current" type="signal_flt_1d">
 				<xs:annotation>
-					<xs:documentation>Current fed in the coil (for 1 turn, to be multiplied by the number of turns to obtain the generated magnetic field), positive when the current is counter-clockwise when seen from above.</xs:documentation>
+					<xs:documentation>Current fed in the coil (for 1 turn, to be multiplied by the number of turns to obtain the generated magnetic field), positive when the current is counter-clockwise when viewed from above.</xs:documentation>


Suggested change

<xs:documentation>Current fed in the coil (for 1 turn, to be multiplied by the number of turns to obtain the generated magnetic field), positive when the current is counter-clockwise when viewed from above.</xs:documentation>

<xs:documentation>Current fed into the coil (for 1 turn, to be multiplied by the number of turns to obtain the generated magnetic field). Positive when the current flows counter-clockwise in the coil when viewed from above.</xs:documentation>

SimonPinches · 2026-03-12T16:18:45Z

schemas/pulse_schedule/dd_pulse_schedule.xsd

 			<xs:element name="current" type="pulse_schedule_reference_pf_active">
 				<xs:annotation>
-					<xs:documentation>Current fed in the coil (for 1 turn, to be multiplied by the number of turns to obtain the generated magnetic field), positive when flowing from side 1 to side 2 of the coil (inside the coil), this numbering being made consistently with the convention that the current is counter-clockwise when seen from above.</xs:documentation>
+					<xs:documentation>Current fed in the coil (for 1 turn, to be multiplied by the number of turns to obtain the generated magnetic field), positive when flowing from side 1 to side 2 of the coil (inside the coil), this numbering being made consistently with the convention that the current is counter-clockwise when viewed from above.</xs:documentation>


The addition of "Reference waveform of...." may need to be applied to other nodes in this IDS....

Suggested change

<xs:documentation>Current fed in the coil (for 1 turn, to be multiplied by the number of turns to obtain the generated magnetic field), positive when flowing from side 1 to side 2 of the coil (inside the coil), this numbering being made consistently with the convention that the current is counter-clockwise when viewed from above.</xs:documentation>

<xs:documentation>Reference waveform of current to be fed into the coil (for 1 turn, to be multiplied by the number of turns to obtain the generated magnetic field). Positive when the current flows counter-clockwise in the coil when viewed from above.</xs:documentation>

SimonPinches · 2026-03-12T16:23:08Z

schemas/pulse_schedule/dd_pulse_schedule.xsd

 			<xs:element name="b_field_tor_vacuum_r" type="pulse_schedule_reference_no_aos">
 				<xs:annotation>
-					<xs:documentation>Vacuum field times major radius in the toroidal field magnet. Positive sign means anti-clockwise when viewed from above</xs:documentation>
+					<xs:documentation>Vacuum field times major radius in the toroidal field magnet. Positive sign means counter-clockwise when viewed from above</xs:documentation>


Suggested change

<xs:documentation>Vacuum field times major radius in the toroidal field magnet. Positive sign means counter-clockwise when viewed from above</xs:documentation>

<xs:documentation>Vacuum magnetic field times major radius within the cage of toroidal field coils. Positive sign means magnetic field is orientated counter-clockwise when viewed from above.</xs:documentation>

SimonPinches · 2026-03-12T16:28:37Z

schemas/sawteeth/dd_sawteeth.xsd

 			<xs:element name="psi_star_pre_crash">
 				<xs:annotation>
-					<xs:documentation>Psi* = psi - phi, just before the sawtooth crash</xs:documentation>
+						<xs:documentation>Helical magnetic flux for the m=1, n=1 mode (psi* = psi - phi), just before the sawtooth crash. For a positive plasma current (counter-clockwise when viewed from above), increases from the magnetic axis to the boundary</xs:documentation>


I think we need to check that we've got the signs right so the definition matches the text: Increases from axis to edge for positive current.

SimonPinches · 2026-03-12T16:29:01Z

schemas/sawteeth/dd_sawteeth.xsd

 			<xs:element name="psi_star_post_crash">
 				<xs:annotation>
-					<xs:documentation>Psi* = psi - phi, after the sawtooth crash</xs:documentation>
+						<xs:documentation>Helical magnetic flux for the m=1, n=1 mode (psi* = psi - phi), after the sawtooth crash. For a positive plasma current (counter-clockwise when viewed from above), increases from the magnetic axis to the boundary</xs:documentation>


Same comment, I think we need to check that we've got the signs right so the definition matches the text: Increases from axis to edge for positive current.

SimonPinches · 2026-03-12T16:30:16Z

schemas/tf/dd_tf.xsd

 				<xs:element name="b_field_phi_vacuum_r" type="signal_flt_1d">
 					<xs:annotation>
-						<xs:documentation>Vacuum field times major radius in the toroidal field magnet. Positive sign means anti-clockwise when viewed from above</xs:documentation>
+						<xs:documentation>Vacuum field times major radius in the toroidal field magnet. Positive sign means counter-clockwise when viewed from above</xs:documentation>


Suggested change

<xs:documentation>Vacuum field times major radius in the toroidal field magnet. Positive sign means counter-clockwise when viewed from above</xs:documentation>

<xs:documentation>Vacuum magnetic field times major radius within the cage of toroidal field coils. Positive sign means counter-clockwise when viewed from above.</xs:documentation>

Simon-McIntosh added 3 commits March 2, 2026 10:47

Simon-McIntosh requested review from DavidPCoster, SimonPinches, aksinghh, medvedevsyu, pankin, qsthayashi, simpla-fusion and yegakjh as code owners March 2, 2026 09:48

DavidPCoster approved these changes Mar 2, 2026

View reviewed changes

SimonPinches reviewed Mar 2, 2026

View reviewed changes

schemas/sawteeth/dd_sawteeth.xsd Show resolved Hide resolved

schemas/sawteeth/dd_sawteeth.xsd Outdated Show resolved Hide resolved

schemas/sawteeth/dd_sawteeth.xsd Outdated Show resolved Hide resolved

Simon-McIntosh added 2 commits March 2, 2026 16:23

pankin approved these changes Mar 3, 2026

View reviewed changes

imbeauf reviewed Mar 4, 2026

View reviewed changes

schemas/core_profiles/dd_core_profiles.xsd Show resolved Hide resolved

simpla-fusion approved these changes Mar 4, 2026

View reviewed changes

olivhoenen approved these changes Mar 12, 2026

View reviewed changes

SimonPinches reviewed Mar 12, 2026

View reviewed changes

qsthayashi approved these changes Mar 13, 2026

View reviewed changes

	<xs:documentation>R, Z, Phi position of the beamlet group centre. The toroidal angle (phi) increases counter-clockwise when viewed from above</xs:documentation>
	<xs:documentation>R, Phi, Z position of the beamlet group centre. The toroidal angle (phi) increases counter-clockwise when viewed from above</xs:documentation>

	<xs:documentation>Direction of the beam seen from above the torus: -1 = clockwise; 1 = counter-clockwise</xs:documentation>
	<xs:documentation>Orientation of the beam when viewed from above: -1 = clockwise; 1 = counter-clockwise</xs:documentation>

	<xs:documentation>Current in the circuit between the sides of the group of supplies (only for circuits with a single supply or in which supplies are grouped). Positive sign means counter-clockwise when viewed from above</xs:documentation>
	<xs:documentation>Current in the circuit between the sides of the group of supplies (only for circuits with a single supply or in which supplies are grouped). Positive sign means current flows from first connection to second connection.</xs:documentation>

	<xs:documentation>Current fed in the coil (for 1 turn, to be multiplied by the number of turns to obtain the generated magnetic field), positive when the current is counter-clockwise when viewed from above.</xs:documentation>
	<xs:documentation>Current fed into the coil (for 1 turn, to be multiplied by the number of turns to obtain the generated magnetic field). Positive when the current flows counter-clockwise in the coil when viewed from above.</xs:documentation>

	<xs:documentation>Current fed in the coil (for 1 turn, to be multiplied by the number of turns to obtain the generated magnetic field), positive when flowing from side 1 to side 2 of the coil (inside the coil), this numbering being made consistently with the convention that the current is counter-clockwise when viewed from above.</xs:documentation>
	<xs:documentation>Reference waveform of current to be fed into the coil (for 1 turn, to be multiplied by the number of turns to obtain the generated magnetic field). Positive when the current flows counter-clockwise in the coil when viewed from above.</xs:documentation>

	<xs:documentation>Vacuum field times major radius in the toroidal field magnet. Positive sign means counter-clockwise when viewed from above</xs:documentation>
	<xs:documentation>Vacuum magnetic field times major radius within the cage of toroidal field coils. Positive sign means magnetic field is orientated counter-clockwise when viewed from above.</xs:documentation>

Conversation

Simon-McIntosh commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 2, 2026

Uh oh!

github-actions bot commented Mar 2, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Mar 2, 2026

Uh oh!

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

github-actions bot commented Mar 4, 2026

Uh oh!

olivhoenen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

Simon-McIntosh commented Mar 2, 2026 •

edited

Loading