Improve ‘Policy’ class hierarchy, docs, semantics

[khaeru]

Discussing #499 with @yiyi1991 raised several points:

• There are at least 3 policy 'data' file formats (or families of formats, not necessarily stable or well-defined) in active use:
  • NewClimate Institute, as implemented by Add .tools.newclimate #499.
  • The "modeling protocol" format (MP) generated by PBL & co., based on the above.
  • The format used by an AddPolicy script/class in message_data.
• Each of the above has its own data model (set of fields). In these cases the data model seems implicit in the file format, and not separately and completely described or defined.
• None of the above is likely suitable to be a generic policy data model (GPDM below). In other words, for certain kinds of policy that are thus far not captured, we might find that those data models/formats are ill-fitted to capture necessary information.
• There is probably value in a such a generic policy data model and accompanying format. In particular, our code to implement policies in the model could avoid having to work with many different data models for policy information.
• It is not necessarily our role (or within our resources) to establish/promulgate such a data model/format.

At the moment, in message-ix-models we have the following:

• message_ix_models.tools.policy.Policy: a generic parent class with zero attributes. This was created in Transport improvements from 2025-W20 #349.
  • message_ix_models.model.transport.policy… —2 subclasses:
    • .ExogenousEmissionPrice: one attribute: the URL of a reference MESSAGE scenario from which PRICE_EMISSION values should be copied.
    • .TaxEmission: one attribute, value. (Code that uses this class constructs a future emission price trajectory that increases exponentially from this initial value.)
  • message_ix_models.tools.newclimate.structure.NewClimatePolicy —a subclass, with 24 attributes like id, reference, name etc.

Some concrete changes we could make in message-ix-models:

1. Create an intermediate class that is a subclass of Policy and parent/super class to NewClimatePolicy.
   • This class could have some of the fields that appear to be shared across NCP, MP, AddPolicy, etc. like id, reference, geo, etc.
   • Then the existing NewClimatePolicy would inherit these attributes, not redefine them. Future classes (if any prove needed) for MP, AddPolicy, or others would likewise inherit.
   • This class would not necessarily be a GPDM, but it would at least reveal what is common across the existing data models/formats.
   • We don't have a name for this, but it could be something like GenericPolicy.
2. Choose a common representation for use within message-ix-models.
   • Implement this as a subclass of (1).
   • @yiyi1991 suggests a data model including, at least, the quantitative attributes arrival, depth, and speed, of which any ≥2 can be used to construct a univariate, piecewise linear projection of a certain measure that can in turn be used to construct model data.
3. Add code to convert from (1) to (2), and/or from the MP, AddPolicy, or other visible format(s) to (2).
   • This would achieve our internal goal of having model-building code work with a single, consistent data model; abstract from the differences/imprecision of the several source formats.
   • This may involve defining further subclasses of (1).
4. Clarify language and definitions.
   • @yiyi1991 pointed out that in the IAMC the word ‘policy’ is often used with a narrow meaning, i.e. climate policy, that excludes many things that are labeled/regarded as ‘policy’ in other research domains or in the real world. From this particular viewpoint, the parent class name could be confusing.
   • My preference here would be to look for an established definition from policy research that is both precise and broad/encompassing, and then state clearly that the existing Policy class corresponds to that definition.
   • Another option is to choose another word like ‘Anchor’, ‘Phenomenon’, ‘Outcome’, etc. and rename the top-level class to that.

I can take on at least (1) and (4) in a future PR. For (2) and (3) we plan to solicit feedback in the 2026-05-07 MESSAGE meeting, but feedback from colleagues is also welcome here.

[yiyi1991]

Thanks for summarizing and making terms to them.

(I did not fully understand the design of subclass and I am not clear the purpose of having a class for Policy in MESSAGE in the first place but only in the sense that I can not so far imagine the way I use the class and its subclass. The structure you proposed is clear.)

To clarify, I proposed the depth-speed-arrival structure so that multiple data models can be converted to, also, applied in MESSAGE once converted. It is indeed something similar to what a GPDM tries to do, but general for "modelable" policies. What we are doing is at the end capturing the dynamics of how things evolve and policies (or behavior changes, converging to best practices) serve as little anchors shaping such trajectories there.

While writing the above I realized maybe you designed this class in a clean way that it "collects policies". I thought "add policies" or both "add policies" and "collect policies" need to be there in a Policy class of message-ix-models. Maybe this is what made me confused. Would it make sense if we consider a separation of these two?

Speaking of that I also have another question. What should be in the /message-ix-models/tools? My understanding was

• model features (DAC, bilateralization, cost tool),
• the utils functions that make tuning the MESSAGE model easier (add_budget)
• some functions retrieving raw data sources there

[khaeru]

While writing the above I realized maybe you designed this class in a clean way that it "collects policies". I thought "add policies" or both "add policies" and "collect policies" need to be there in a Policy class of message-ix-models. Maybe this is what made me confused. Would it make sense if we consider a separation of these two?

Yes, there definitely must be a separation of concerns of the following:

1. Formats to store/exchange information about policies.
2. Objects to carry that information about policies. This is what the Policy class is for. The different subclasses are because there are different sets of information ("data models") in some cases.
3. Code that acts on single policies or collections of policies, expressed as (2). This includes simpler actions like filtering/selection, aggregation, etc.; making quantified realizations (e.g. through A/D/S); and also "higher-level" behaviour like updating a Scenario object ("add policies").

So for (3) we do not yet have anything on the main branch of message-ix-models: it could be a module, function, class, or some combination of these. It would take Policy objects (or subclass instances) as its inputs. Because of the separation of concerns, (3) doesn't need to know what the upstream source/format is for the information it receives.

[khaeru]

What should be in the /message-ix-models/tools? My understanding was

• model features (DAC, bilateralization, cost tool),
• the utils functions that make tuning the MESSAGE model easier (add_budget)
• some functions retrieving raw data sources there

We have these parts of the documentation:

• https://docs.messageix.org/projects/models/en/latest/develop.html#code-org
• https://docs.messageix.org/projects/models/en/latest/howto/pull-request.html#add-python-submodules

I think these are mostly up to date. There is still some minor inconsistency, e.g. the general purpose Workflow class is defined in a top-level module (message_ix_models.workflow) whereas the Context class is one level lower (message_ix_models.util.context), although both are importable from message_ix_models in third-part code.

[yiyi1991]

Yes, there definitely must be a separation of concerns of the following:

1. Formats to store/exchange information about policies.
2. Objects to carry that information about policies. This is what the Policy class is for. The different subclasses are because there are different sets of information ("data models") in some cases.
3. Code that acts on single policies or collections of policies, expressed as (2). This includes simpler actions like filtering/selection, aggregation, etc.; making quantified realizations (e.g. through A/D/S); and also "higher-level" behaviour like updating a Scenario object ("add policies").

So for (3) we do not yet have anything on the main branch of message-ix-models: it could be a module, function, class, or some combination of these. It would take Policy objects (or subclass instances) as its inputs. Because of the separation of concerns, (3) doesn't need to know what the upstream source/format is for the information it receives.

Great. I think I get where we are heading. Will try preparing examples in this way before 2026-05-07 and of course they can be further "cleaned"/refactored.