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

This has been implemented.

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.