YTEP-0003: Standardizing field names¶
Abstract¶
Created: December 11, 2012
Author: Casey Stark, Nathan Goldbaum, Matt Turk
Let’s clean up field names in yt, ex “SoundSpeed” -> “sound_speed”. The proposed work will serve to remove Enzo-isms and encourage more consistent field names across frontends.
Status¶
Completed
Project Management Links¶
yt 3.0 goals doc https://docs.google.com/document/d/17Q-rbmTj9PyaTgtN1h6C8vqoWeIZjw_OjFbQp8L3Tkg/edit
Universal field names doc https://docs.google.com/document/d/1Qbt6z27S8VWh8h0kOx–ZYih4BDFAgGlH9pE55I51So/edit
Detailed Description¶
Background¶
The universal field names are PascalCased, while lowercase_underscored names are more standard in Python.
Solution¶
The field names must be updated to lowercase_underscored format. This means all of the common field names, frontend-specific field names, and all references to field names elsewhere in the code base need to be updated.
Additionally, we will take the opportunity to reorganize the field definitions.
Currently all of the field definitions live in the monolithic
universal_fields.py file, which in yt 2.6 is just shy of 1700 lines long.
In the reference implimentation, we have created a new top-level namespace,
yt.fields. The fields module is container for a number of submodules
that contain field definitions or macros to create classes of field
definitions. Currently, the following submodules are attributes of yt.fields:
angular_momentum- Gas and particle angular momentum fields and field creation macros.
fluid_fields- Useful fields that are simple functions of the primitive variables in a hydrodynamic simulation. cell_mass, sound_speed, pressure, entropy, and kinetic_energy all live here.
geometric_fields- Fields that are functions only of the geometry of the data. This includes radius, x, y, z, curvilinear coordinat fields, zeros, ones, and grid_level.
magnetic_fields- Derived fields useful for analyzing simulation that include magnetic fields.
particle_fields- Particle derived fields, including all non-local particle deposition fields and local fields that are functions of primitive particle properties.
species_fields- Fields for chemical species. This is currently a stub.
vector_operations- Fields that are the gradient, divergence or curl of another field as well as macros for setting up these fields.
universal_fields- Fields that have so far not been assigned to one of the other field submodules. Eventually this module will be removed once the remaining fields have been reorganized.
Additionally, the fields module now contains the logic for field detection
as well as the DerivedField class.
Testing¶
The existing unit testing framework as well as an updated set of field detection tests. If there are additional fixes required in untested parts of the code base, we will update them as we find them.
Backwards Compatibility¶
We will provide a compatibility layer, allowing yt to map from the old field names to the new ones. This compatibility layer will not be enabled by default.
Right now, one can turn it on via the _setup_deprecated_fields function:
import yt
ds = yt.load('IsolatedGalaxy/galaxy0030/galaxy0030')
ds._setup_deprecated_fields()
In the future we might also enable this via a config parameter.
Field Names¶
- Naming rules:
- must be lowercase underscored.
- should be as verbose as possible.
- should not include units.
- vector fields are separated into 4 scalar fields with endings _x, _y, _z, and _magnitude.
This is a listing of all field names currently defined in the yt-3.0 universal_fields module and the proposed replacement names.
| Current name | Proposal |
|---|---|
| GridLevel | grid_level |
| GridIndices | grid_indices |
| OnesOverDx | ones_over_dx |
| Ones | ones |
| CellsPerBin | cells_per_bin |
| SoundSpeed | sound_speed |
| RadialMachNumber | radial_mach_number |
| MachNumber | mach_number |
| CourantTimeStep | courant_time_step |
| ParticleVelocityMagnitude | particle_velocity_magnitude |
| VelocityMagnitude | velocity_magnitude |
| TangentialOverVelocityMagnitude | tangential_over_velocity_magnitude |
| Pressure | pressure |
| Entropy | entropy |
| sph_r | spherical_r |
| sph_theta | spherical_theta |
| sph_phi | spherical_phi |
| cyl_R | cylindrical_r |
| cyl_RCode | remove (unit duplicate) |
| cyl_z | cylindrical_z |
| cyl_theta | cylindrical_theta |
| DiskAngle | remove (replaced by theta) |
| Height | remove (replaced by z) |
| HeightAU | remove (unit duplicate) |
| cyl_RadialVelocity | cylindrical_radial_velocity |
| cyl_RadialVelocityABS | cylindrical_radial_velocity_absolute |
| cyl_RadialVelocityKMS | remove (unit duplicate) |
| cyl_RadialVelocityKMSABS | remove (unit duplicate) |
| cyl_TangentialVelocity | cylindrical_tangential_velocity |
| cyl_TangentialVelocityABS | cylindrical_tangential_velocity_absolute |
| cyl_TangentialVelocityKMS | remove (unit duplicate) |
| cyl_TangentialVelocityKMSABS | remove (unit duplicate) |
| DynamicalTime | dynamical_time |
| JeansMassMsun | jeans_mass (possible unit change) |
| CellMass | cell_mass |
| CellMassMsun | remove (unit duplicate) |
| CellMassCode | remove (unit duplicate) |
| TotalMass | total_mass |
| TotalMassMsun | remove (unit duplicate) |
| StarMassMsun | star_mass (possible unit change) |
| Matter_Density | matter_density |
| ComovingDensity | comoving_density |
| Overdensity | overdensity |
| DensityPerturbation | density_perturbation |
| Baryon_Overdensity | baryon_overdensity |
| WeakLensingConvergence | weak_lensing_convergence |
| CellVolumeCode | remove (unit duplicate) |
| CellVolumeMpc | remove (unit duplicate) |
| CellVolume | cell_volume |
| ChandraEmissivity | chandra_emissivity |
| XRayEmissivity | xray_emissivity |
| SZKinetic | sz_kinetic |
| SZY | szy |
| AveragedDensity | averaged_density |
| DivV | div_v |
| AbsDivV | div_v_absolute |
| Contours | contours |
| tempContours | temp_contours |
| SpecificAngularMomentumX | specific_angular_momentum_x |
| SpecificAngularMomentumY | specific_angular_momentum_y |
| SpecificAngularMomentumZ | specific_angular_momentum_z |
| AngularMomentumX | angular_momentum_x |
| AngularMomentumY | angular_momentum_y |
| AngularMomentumZ | angular_momentum_z |
| ParticleSpecificAngularMomentumX | particle_specific_angular_momentum_x |
| ParticleSpecificAngularMomentumY | particle_specific_angular_momentum_y |
| ParticleSpecificAngularMomentumZ | particle_specific_angular_momentum_z |
| ParticleSpecificAngularMomentumXKMSMPC | remove (unit duplicate) |
| ParticleSpecificAngularMomentumYKMSMPC | remove (unit duplicate) |
| ParticleSpecificAngularMomentumZKMSMPC | remove (unit duplicate) |
| ParticleAngularMomentumX | particle_angular_momentum_x |
| ParticleAngularMomentumY | particle_angular_momentum_y |
| ParticleAngularMomentumZ | particle_angular_momentum_z |
| ParticleRadius | particle_radius |
| Radius | radius |
| RadiusMpc | remove (unit duplicate) |
| ParticleRadiusMpc | remove (unit duplicate) |
| ParticleRadiuskpc | remove (unit duplicate) |
| Radiuskpc | remove (unit duplicate) |
| ParticleRadiuskpch | remove (unit duplicate) |
| Radiuskpch | remove (unit duplicate) |
| ParticleRadiuspc | remove (unit duplicate) |
| Radiuspc | remove (unit duplicate) |
| ParticleRadiusAU | remove (unit duplicate) |
| RadiusAU | remove (unit duplicate) |
| ParticleRadiusCode | remove (unit duplicate) |
| RadiusCode | remove (unit duplicate) |
| RadialVelocity | radial_velocity |
| RadialVelocityABS | radial_velocity_absolute |
| RadialVelocityKMS | remove (unit duplicate) |
| RadialVelocityKMSABS | remove (unit duplicate) |
| TangentialVelocity | tangential_velocity |
| CuttingPlaneVelocityX | cutting_plane_velocity_x |
| CuttingPlaneVelocityY | cutting_plane_velocity_y |
| CuttingPlaneBX | cutting_plane_bx |
| CuttingPlaneBy | cutting_plane_by |
| MeanMolecularWeight | mean_molecular_weight |
| JeansMassMsun | remove (duplicate) |
| particle_density | particle_density |
| MagneticEnergy | magnetic_energy |
| BMagnitude | b_magnitude |
| PlasmaBeta | plasma_beta |
| MagneticPressure | magnetic_pressure |
| BPoloidal | b_poloidal |
| BToroidal | b_toroidal |
| BRadial | b_radial |
| VorticitySquared | vorticity_squared |
| gradPressureX | grad_pressure_x |
| gradPressureY | grad_pressure_y |
| gradPressureZ | grad_pressure_z |
| gradPressureMagnitude | grad_pressure_magnitude |
| gradDensityX | grad_density_x |
| gradDensityY | grad_density_y |
| gradDensityZ | grad_density_z |
| gradDensityMagnitude | grad_density_magnitude |
| BaroclinicVorticityX | baroclinic_vorticity_x |
| BaroclinicVorticityY | baroclinic_vorticity_y |
| BaroclinicVorticityZ | baroclinic_vorticity_z |
| BaroclinicVorticityMagnitude | baroclinic_vorticity_magnitude |
| VorticityX | vorticity_x |
| VorticityY | vorticity_y |
| VorticityZ | vorticity_z |
| VorticityMagnitude | vorticity_magnitude |
| VorticityStretchingX | vorticity_stretching_x |
| VorticityStretchingY | vorticity_stretching_y |
| VorticityStretchingZ | vorticity_stretching_z |
| VorticityStretchingMagnitude | vorticity_stretching_magnitude |
| VorticityGrowthX | vorticity_growth_x |
| VorticityGrowthY | vorticity_growth_y |
| VorticityGrowthZ | vorticity_growth_z |
| VorticityGrowthMagnitude | vorticity_growth_magnitude |
| VorticityGrowthMagnitudeABS | vorticity_growth_magnitude_absolute |
| VorticityGrowthTimescale | vorticity_growth_timescale |
| VorticityRadPressureX | vorticity_radiation_pressure_x |
| VorticityRadPressureY | vorticity_radiation_pressure_y |
| VorticityRadPressureZ | vorticity_radiation_pressure_z |
| VorticityRadPressureMagnitude | vorticity_radiation_pressure_magnitude |
| VorticityRPGrowthX | vorticity_radiation_pressure_growth_x |
| VorticityRPGrowthY | vorticity_radiation_pressure_growth_y |
| VorticityRPGrowthZ | vorticity_radiation_pressure_growth_z |
| VorticityRPGrowthMagnitude | vorticity_radiation_pressure_growth_magnitude |
| VorticityRPGrowthTimescale | vorticity_radiation_pressure_growth_timescale |
| x-velocity | velocity_x |
| y-velocity | velocity_y |
| z-velocity | velocity_z |
Molecular and Atomic Species Names¶
Particular care must be taken to name molecular and atomic species in a way that is unambiguous as well as terse. We need to be able to resolve the following types of species:
- CO (Carbon monoxide)
- Co (Cobalt)
- OVI (Oxygen ionized five times)
- H2+ (Molecular Hydrogen ionized once)
- H- (Hydrogen atom with an additional electron)
The naming scheme we have decided upon is of the form MM[_[mp][NN]].
MM is the molecule, defined as a concatenation of atomic symbols and
numbers, with no spaces or underscores. The second sequence is only required
if the ionization state is not neutral, and is of the form p and m to
indicate “plus” or “minus” respectively, followed by the number. Our examples
above would be CO, Co, O_p5, H2_p1, and H_m1. Note that we
are not using an exclusively-lowercase convention here, as we did for the
other field names. The name El will be reserved for electron fields, as it
is unambiguous and will not be utilized elsewhere. Additionally, the isotope
of 2H will be included as D.
Neutral ionic species (e.g. H I, O I) are represented as MM_p0.
For backwards compatibility, neutral species will be mirrored to
MM_ fields, but this practice is deprecated as it is somewhat ambiguous
if we are referring to just the neutral species or all atoms of that type.
As an example, the neutral hydrogen density field will now be
called H_p0_density, but it will be mirrored to the H_density field for
backwards compatibility.
Finally, in those frontends which are single-fluid, we will define these fields for each species:
_fraction_number_density_density_mass
This means that if a frontend only has color fields and species fields (as is
the most common case), it will have ("gas", "H2_fraction") for instance.
Otherwise, for multi-fluid calculations (where gas is joined by other
fields) the other fields will have their own mass and density and so on.
This will require some parsing, and initially we will only support those fields
we expect to find. Additionally, because different frontends define these
fields in different ways, we will detect which one is the output and define the
rest from that. For example, if the frontend finds a _density field, the
rest will be computed as derived fields from that.
As a point of clarification, the El_density currently defined for
Enzo is scaled with respect to the ratio of the electron to proton mass ratio.
This means that dividing it by m_h will result in the number density.
Moving forward, this will not be the case. We will instead give correct
results for mass density when the alias is queried. The original name,
Electron_Density, will still be defined the way it currently is, to
preserve access to the original, on-disk fields. (It will be able to be
converted to CGS, as well, and will not be scaled in doing so.)
To refer to the number density of the entirety of a single atom or molecule
(regardless of its ionization state), please use the MM_nuclei_density
fields, as opposed to MM_number_density fields.