Magnetics: Energy and Co-energy

Calculate energy density, energy, and co-energy from a B–H curve. Use supplied energy gradients to derive force and torque.

Factors for real fields and phasors

For real fields in a linear material, the energy density is ½ B·H. For phasors specified as peak amplitudes, use ¼ Re(B·H*). Along a nonlinear branch, integrate H with respect to B for energy or B with respect to H for co-energy. Keep the integration direction and origin consistent. The force and torque operations take a gradient as input. Check the physical assumptions that determine its sign and units.

Operation reference

Jump to an operation

energy.density

Operands A and B are the B and H fields with matching shapes. Set the Boolean phasor for complex peak phasors and a factor of ¼. The real case uses a factor of ½.

Access
Registered in the Python Job
Arguments
Typed operands a, b, and c, with an optional typed options struct.
Shape
Fields of matching shape | optional regular grid (matching_fields;optional_regular_grid)
Units
J/m³, J
Result
Numerical and diagnostic fields
Purpose
Magnetic energy density
gxtxt_api_call("MAGNETICS_API_v1", "energy.density", args)
Recorded result · energy.density:phasor

Download the example script (ZIP).

Example operands preview

[
  {
    "kind": "array",
    "shape": [
      2,
      3
    ],
    "real": [
      1.0,
      0.0,
      2.0,
      2.0,
      0.0,
      1.0
    ],
    "imaginary": [
      1.0,
      0.0,
      0.0,
      0.0,
      0.0,
      -1.0
    ]
  },
  {
    "kind": "array",
    "shape": [
      2,
      3
    ],
    "real": [
      1.0,
      0.0,
      2.0,
      2.0,
      0.0,
      1.0
    ],
    "imaginary": [
      1.0,
      0.0,
      0.0,
      0.0,
      0.0,
      -1.0
    ]
  },
  {
    "kind": "empty"
  },
  {
    "kind": "struct",
    "fields": {
      "phasor": {
        "kind": "array",
        "shape": [
          1,
          1
        ],
        "real": [
          1
        ]
      }
    }
  }
]

Result preview

{
  "energy_density": {
    "dtype": "float64",
    "shape": [
      2,
      1
    ],
    "values": [
      1.5,
      1.5
    ]
  },
  "unit": "J/m^3"
}
Rejected input or attempted run · energy.density:phasor-required

Download the example script (ZIP).

Example operands preview

[
  {
    "kind": "array",
    "shape": [
      2,
      3
    ],
    "real": [
      1.0,
      0.0,
      2.0,
      2.0,
      0.0,
      1.0
    ],
    "imaginary": [
      1.0,
      0.0,
      0.0,
      0.0,
      0.0,
      -1.0
    ]
  },
  {
    "kind": "array",
    "shape": [
      2,
      3
    ],
    "real": [
      1.0,
      0.0,
      2.0,
      2.0,
      0.0,
      1.0
    ],
    "imaginary": [
      1.0,
      0.0,
      0.0,
      0.0,
      0.0,
      -1.0
    ]
  },
  {
    "kind": "empty"
  }
]

Result preview

"GXTXT:ScriptBridge:RemoteError: MAGNETICS_API_v1/energy.density: complex B/H energy requires phasor=true"

energy.integrated

A and B are the fields, and C contains the grid axes. The operation integrates the energy density and returns energy in J.

Access
Registered in the Python Job
Arguments
Typed operands a, b, and c, with an optional typed options struct.
Shape
Fields of matching shape | optional regular grid (matching_fields;optional_regular_grid)
Units
J/m³, J
Result
Numerical and diagnostic fields
Purpose
Magnetic energy integrated over a volume
gxtxt_api_call("MAGNETICS_API_v1", "energy.integrated", args)
Recorded result · energy.integrated

Download the example script (ZIP).

Example operands preview

[
  {
    "kind": "array",
    "shape": [
      3,
      3,
      3
    ],
    "real": [
      0.0,
      0.001,
      0.003,
      0.002,
      0.003,
      0.005,
      0.006,
      0.007,
      0.009000000000000001,
      0.003
    ]
  },
  {
    "kind": "array",
    "shape": [
      3,
      3,
      3
    ],
    "real": [
      0.0,
      1.0,
      3.0,
      2.0,
      3.0,
      5.0,
      6.0,
      7.0,
      9.0,
      3.0
    ]
  },
  {
    "kind": "cell",
    "shape": [
      1,
      3
    ],
    "items": [
      {
        "kind": "array",
        "shape": [
          3,
          1
        ],
        "real": [
          0.0,
          1.0,
          3.0
        ]
      },
      {
        "kind": "array",
        "shape": [
          3,
          1
        ],
        "real": [
          0.0,
          1.0,
          3.0
        ]
      },
      {
        "kind": "array",
        "shape": [
          3,
          1
        ],
        "real": [
          0.0,
          1.0,
          3.0
        ]
      }
    ]
  }
]

Result preview

{
  "value_real": 1.32975,
  "value_imaginary": 0.0,
  "unit": "J"
}

energy.coenergy_curve

A contains flux density B and operand B contains H. The operation integrates B dH along the material branch.

Access
Registered in the Python Job
Arguments
Typed operands a, b, and c, with an optional typed options struct.
Shape
Fields of matching shape | optional regular grid (matching_fields;optional_regular_grid)
Units
J/m³, J
Result
Numerical and diagnostic fields
Purpose
Magnetic co-energy from a B–H curve
gxtxt_api_call("MAGNETICS_API_v1", "energy.coenergy_curve", args)
Recorded result · energy.coenergy_curve

Download the example script (ZIP).

Example operands preview

[
  {
    "kind": "array",
    "shape": [
      5,
      1
    ],
    "real": [
      -0.7,
      -0.31,
      0.0,
      0.31,
      0.7
    ]
  },
  {
    "kind": "array",
    "shape": [
      5,
      1
    ],
    "real": [
      -5.0,
      -2.0,
      0.0,
      2.0,
      5.0
    ]
  },
  {
    "kind": "empty"
  }
]

Result preview

{
  "coenergy_density": 0.0,
  "unit": "J/m^3"
}

energy.energy_curve

A contains flux density B and operand B contains H at the same sample points. The operation integrates H dB along the material branch.

Access
Registered in the Python Job
Arguments
Typed operands a, b, and c, with an optional typed options struct.
Shape
Fields of matching shape | optional regular grid (matching_fields;optional_regular_grid)
Units
J/m³, J
Result
Numerical and diagnostic fields
Purpose
Magnetic energy from a B–H curve
gxtxt_api_call("MAGNETICS_API_v1", "energy.energy_curve", args)
Recorded result · energy.energy_curve

Download the example script (ZIP).

Example operands preview

[
  {
    "kind": "array",
    "shape": [
      5,
      1
    ],
    "real": [
      -0.7,
      -0.31,
      0.0,
      0.31,
      0.7
    ]
  },
  {
    "kind": "array",
    "shape": [
      5,
      1
    ],
    "real": [
      -5.0,
      -2.0,
      0.0,
      2.0,
      5.0
    ]
  },
  {
    "kind": "empty"
  }
]

Result preview

{
  "energy_density": 0.0,
  "unit": "J/m^3"
}

energy.electric_density

A is E and B is the permittivity. Set phasor=1 for peak amplitudes and a factor of ¼ in the mean energy density.

Access
Registered in the Python Job
Arguments
Typed operands a, b, and c, with an optional typed options struct.
Shape
Fields of matching shape | optional regular grid (matching_fields;optional_regular_grid)
Units
J/m³, J
Result
Numerical and diagnostic fields
Purpose
Electric energy density with explicit permittivity
gxtxt_api_call("MAGNETICS_API_v1", "energy.electric_density", args)
Recorded result · energy.electric_density

Download the example script (ZIP).

Example operands preview

[
  {
    "kind": "array",
    "shape": [
      2,
      3
    ],
    "real": [
      1.0,
      0.0,
      2.0,
      2.0,
      0.0,
      1.0
    ],
    "imaginary": [
      1.0,
      0.0,
      0.0,
      0.0,
      0.0,
      -1.0
    ]
  },
  {
    "kind": "array",
    "shape": [
      1,
      1
    ],
    "real": [
      8.854e-12
    ]
  },
  {
    "kind": "empty"
  },
  {
    "kind": "struct",
    "fields": {
      "phasor": {
        "kind": "array",
        "shape": [
          1,
          1
        ],
        "real": [
          1
        ]
      }
    }
  }
]

Result preview

{
  "energy_density": {
    "dtype": "float64",
    "shape": [
      2,
      1
    ],
    "values": [
      1.3280999999999999e-11,
      1.3280999999999999e-11
    ]
  },
  "unit": "J/m^3"
}

energy.force_from_gradient

A contains the precomputed spatial gradient of the relevant energy. The operation changes its sign and reports force in N.

Access
Registered in the Python Job
Arguments
Typed operands a, b, and c, with an optional typed options struct.
Shape
Fields of matching shape | optional regular grid (matching_fields;optional_regular_grid)
Units
J/m³, J
Result
Numerical and diagnostic fields
Purpose
Force from a supplied energy gradient
gxtxt_api_call("MAGNETICS_API_v1", "energy.force_from_gradient", args)
Recorded result · energy.force_from_gradient

Download the example script (ZIP).

Example operands preview

[
  {
    "kind": "array",
    "shape": [
      3,
      1
    ],
    "real": [
      1,
      2,
      3
    ]
  },
  {
    "kind": "empty"
  },
  {
    "kind": "empty"
  }
]

Result preview

{
  "value_real": {
    "dtype": "float64",
    "shape": [
      3,
      1
    ],
    "values": [
      -1.0,
      -2.0,
      -3.0
    ]
  },
  "value_imaginary": {
    "dtype": "float64",
    "shape": [
      3,
      1
    ],
    "values": [
      0.0,
      0.0,
      0.0
    ]
  },
  "unit": "N"
}

energy.torque_from_gradient

A contains the angular derivative of the energy. The operation changes its sign and reports torque in N·m.

Access
Registered in the Python Job
Arguments
Typed operands a, b, and c, with an optional typed options struct.
Shape
Fields of matching shape | optional regular grid (matching_fields;optional_regular_grid)
Units
J/m³, J
Result
Numerical and diagnostic fields
Purpose
Torque from a supplied angular energy derivative
gxtxt_api_call("MAGNETICS_API_v1", "energy.torque_from_gradient", args)
Recorded result · energy.torque_from_gradient

Download the example script (ZIP).

Example operands preview

[
  {
    "kind": "array",
    "shape": [
      1,
      1
    ],
    "real": [
      2.0
    ]
  },
  {
    "kind": "empty"
  },
  {
    "kind": "empty"
  }
]

Result preview

{
  "value_real": -2.0,
  "value_imaginary": 0.0,
  "unit": "N m"
}