From 9bda39cff60e55a0659bfb38f2eade027cde95f6 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Tue, 16 Jan 2018 15:25:05 +0000 Subject: [PATCH 01/18] Add new PLEP-0007 and update header info --- PLEP-0007.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 PLEP-0007.md diff --git a/PLEP-0007.md b/PLEP-0007.md new file mode 100644 index 0000000..dd3be1f --- /dev/null +++ b/PLEP-0007.md @@ -0,0 +1,53 @@ +# PLEP-*number* -- *PLEP title* + +| PLEP | 7 | +|---------------|------------------------------| +| title | A New General-Purpose Plasma Object | +| author(s) | Drew Leonard | +| contact email | andy.j.leonard@gmail.com | +| date created | 2017-01-16 | +| date last revised | 2017-01-16 | +| type | standard | +| status | discussion | + +# Abstract + +*Briefly describe this PLEP in a paragraph, including a statement of +the problem that this PLEP addresses.* + +# Detailed Description + +*Provide an extended description of the problem and the proposed +changes, including usage examples when needed.* + +# Implementation + +*Describe the steps necessary to implement this PLEP, if necessary.* + +# Issues, Pull Requests, and Branches + +*Provide repository links related to this PLEP, and include +descriptions.* + +# Backward Compatibility + +*State whether or not this PLEP will maintain backward compatibility +and describe the proposed changes, if necessary. Backward +compatibility does not need to be maintained between development +releases (with a major version number of zero). Starting with version +1.0, backward incompatible changes can only happen when the major +version number is incremented.* + +# Alternatives + +*Summarize alternative possibilities to address (or not address) the +problem described in this PLEP, if necessary.* + +# Decision Rationale + +*Summarize the discussion on this PLEP and describe the reasoning +behind the decision, if necessary.* + +*Not all PLEPs require all of these sections, and occasionally +additional sections may be necessary. Emphasized text should be +deleted.* From c02cf13d4d9134468cacfdc4f617b9489972385f Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Tue, 16 Jan 2018 16:10:17 +0000 Subject: [PATCH 02/18] Add description of PLEP --- PLEP-0007.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/PLEP-0007.md b/PLEP-0007.md index dd3be1f..c206cff 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -12,8 +12,11 @@ # Abstract -*Briefly describe this PLEP in a paragraph, including a statement of -the problem that this PLEP addresses.* +The current implementation of PlasmaPy's Plasma object does not adequately fulfill the intended use case. +It is written primarily for use in simulations and is instantiated with direct input of data arrays. +However, plasma physics is a broad discipline which makes use of many different kinds of data structure from a variety of sources and a variety of purposes. +If PlasmaPy is to provide useful tools for all plasma physicists, its core data object needs to be appropriately flexible. +This PLEP therefore presents a new more general framework for the Plasma object. # Detailed Description From 6f44cf4595f00b284d90d0b4363f42cf05b12bc3 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Tue, 16 Jan 2018 16:34:05 +0000 Subject: [PATCH 03/18] Backward compatibility discussion, such as it is --- PLEP-0007.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/PLEP-0007.md b/PLEP-0007.md index c206cff..a1903ec 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -34,12 +34,7 @@ descriptions.* # Backward Compatibility -*State whether or not this PLEP will maintain backward compatibility -and describe the proposed changes, if necessary. Backward -compatibility does not need to be maintained between development -releases (with a major version number of zero). Starting with version -1.0, backward incompatible changes can only happen when the major -version number is incremented.* +This PLEP will not maintain backward compatibility. # Alternatives From 82793a1cc0d495303d278994708b3a0db0e91948 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Mon, 22 Jan 2018 16:44:36 +0000 Subject: [PATCH 04/18] Forgot number and title at the top of the plep. Might be useful --- PLEP-0007.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PLEP-0007.md b/PLEP-0007.md index a1903ec..9a63459 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -1,4 +1,4 @@ -# PLEP-*number* -- *PLEP title* +# PLEP-0007 -- A New General-Purpose Plasma Object | PLEP | 7 | |---------------|------------------------------| From 98bc273873397bcf6358a8b3a886bd6b98fc1975 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Mon, 22 Jan 2018 17:02:57 +0000 Subject: [PATCH 05/18] Tweak abstract --- PLEP-0007.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/PLEP-0007.md b/PLEP-0007.md index 9a63459..95bf084 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -12,11 +12,10 @@ # Abstract -The current implementation of PlasmaPy's Plasma object does not adequately fulfill the intended use case. -It is written primarily for use in simulations and is instantiated with direct input of data arrays. -However, plasma physics is a broad discipline which makes use of many different kinds of data structure from a variety of sources and a variety of purposes. -If PlasmaPy is to provide useful tools for all plasma physicists, its core data object needs to be appropriately flexible. -This PLEP therefore presents a new more general framework for the Plasma object. +The current implementation of PlasmaPy's `Plasma` object does not adequately fulfill the intended use case. +Plasma physics is a broad discipline which makes use of many different kinds of data structure from a variety of sources and a variety of purposes. +If PlasmaPy is to provide useful tools for all plasma physicists, its core data object therefore needs to be appropriately flexible. +This PLEP therefore presents a new more general framework for the `Plasma` object. # Detailed Description From 24f5757794321cc768644ee681f529fea6716e1a Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Mon, 22 Jan 2018 17:03:43 +0000 Subject: [PATCH 06/18] Add paragraph on problems with current `Plasma` class --- PLEP-0007.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/PLEP-0007.md b/PLEP-0007.md index 95bf084..6c17dd1 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -22,6 +22,12 @@ This PLEP therefore presents a new more general framework for the `Plasma` objec *Provide an extended description of the problem and the proposed changes, including usage examples when needed.* +## Issues with current Plasma object + +The existing Plasma class was written primarily for use in simulations and is instantiated with direct input of data arrays. +This is largely because it was originally intended for use with an entirely different package and flexibility was not a significant issue. +So far no major problems have arisen from this lack of flexibility, but as PlasmaPy grows its user-base and its functionality it will have to be able to load, store and analyse a wide variety of different kinds of plasma. +The `Plasma` class as it is currently written will not be able to do these things. # Implementation *Describe the steps necessary to implement this PLEP, if necessary.* From 3eb33c2df878e07425a2c461d8d54f7c0476219d Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Tue, 23 Jan 2018 13:17:16 +0000 Subject: [PATCH 07/18] Tidy up header table because no --- PLEP-0007.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/PLEP-0007.md b/PLEP-0007.md index 6c17dd1..7866f59 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -1,14 +1,14 @@ # PLEP-0007 -- A New General-Purpose Plasma Object -| PLEP | 7 | -|---------------|------------------------------| -| title | A New General-Purpose Plasma Object | -| author(s) | Drew Leonard | -| contact email | andy.j.leonard@gmail.com | -| date created | 2017-01-16 | -| date last revised | 2017-01-16 | -| type | standard | -| status | discussion | +| PLEP | 7 | +|-------------------|-------------------------------------| +| title | A New General-Purpose Plasma Object | +| author(s) | Drew Leonard | +| contact email | andy.j.leonard@gmail.com | +| date created | 2017-01-16 | +| date last revised | 2017-01-16 | +| type | standard | +| status | discussion | # Abstract From 12e804c7d93db6e427d70659e2ddfcdf602f0c06 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Tue, 23 Jan 2018 14:47:03 +0000 Subject: [PATCH 08/18] Add some paragraphs on aims for the new `Plasma` class --- PLEP-0007.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/PLEP-0007.md b/PLEP-0007.md index 7866f59..83d3564 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -28,6 +28,26 @@ The existing Plasma class was written primarily for use in simulations and is in This is largely because it was originally intended for use with an entirely different package and flexibility was not a significant issue. So far no major problems have arisen from this lack of flexibility, but as PlasmaPy grows its user-base and its functionality it will have to be able to load, store and analyse a wide variety of different kinds of plasma. The `Plasma` class as it is currently written will not be able to do these things. + +## Intentions for new Plasma object + +There are a few ways in which PlasmaPy might deal with multiple different kinds of plasma. +One would be to implement multiple classes with different methods of instantiation and with attributes and methods appropriate for the kind of plasma. +Another would be to continue using a single class but to build in all functionality needed for every kind of plasma we would wish to be able to work with. + +Of these options, both have some drawbacks. +The latter would result in the class being extremely difficult to develop and maintain, and likely also problematic to use productively. +On the other hand, the former allows each class to be more focused, but requires maintaining them all separately. +It would also introduce a slightly different user experience for each different type of plasma. + +The proposed solution is a compromise between these two methods, similar to that used by [SunPy](sunpy.org) for its core [Map](http://docs.sunpy.org/en/stable/code_ref/map.html) object. +In this model each kind of plasma would have its own subclass, allowing these to provide functionality specific to that plasma. +The user interface to these classes would be handled exclusively by a `Plasma` metaclass which would also define common or default functionality. +When instantiated, the metaclass would create and return the appropriate subclass based on the input. + +This approach gives the advantages of reducing the development and maintenance burden compared to using multiple completely separate classes by centralising common functionality, while also allowing arbitrarily specific plasma subclasses. +In addition to these development benefits, presenting the user with a single interface for any plasma reduces cognitive overhead for learners and increases the reusability of code. + # Implementation *Describe the steps necessary to implement this PLEP, if necessary.* From b03366dedc6b078f08f68b20c19486f93e80dd90 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Tue, 23 Jan 2018 14:50:53 +0000 Subject: [PATCH 09/18] Better heading for that section --- PLEP-0007.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PLEP-0007.md b/PLEP-0007.md index 83d3564..91d1cc7 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -29,7 +29,7 @@ This is largely because it was originally intended for use with an entirely diff So far no major problems have arisen from this lack of flexibility, but as PlasmaPy grows its user-base and its functionality it will have to be able to load, store and analyse a wide variety of different kinds of plasma. The `Plasma` class as it is currently written will not be able to do these things. -## Intentions for new Plasma object +## Proposed solution There are a few ways in which PlasmaPy might deal with multiple different kinds of plasma. One would be to implement multiple classes with different methods of instantiation and with attributes and methods appropriate for the kind of plasma. From e2f671f8b121860b15975bebf11309fac4b9d862 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Tue, 23 Jan 2018 14:51:16 +0000 Subject: [PATCH 10/18] Tweak description --- PLEP-0007.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PLEP-0007.md b/PLEP-0007.md index 91d1cc7..6ad3534 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -24,7 +24,7 @@ changes, including usage examples when needed.* ## Issues with current Plasma object -The existing Plasma class was written primarily for use in simulations and is instantiated with direct input of data arrays. +The existing Plasma class was written primarily for use in simulations and can only be instantiated with `astropy` Quantities as input. This is largely because it was originally intended for use with an entirely different package and flexibility was not a significant issue. So far no major problems have arisen from this lack of flexibility, but as PlasmaPy grows its user-base and its functionality it will have to be able to load, store and analyse a wide variety of different kinds of plasma. The `Plasma` class as it is currently written will not be able to do these things. From 66b2eb3301834d5a5358bc4e3033f9de251e9ad1 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Tue, 23 Jan 2018 14:57:02 +0000 Subject: [PATCH 11/18] Remove redundant sections --- PLEP-0007.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/PLEP-0007.md b/PLEP-0007.md index 6ad3534..262824a 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -52,20 +52,10 @@ In addition to these development benefits, presenting the user with a single int *Describe the steps necessary to implement this PLEP, if necessary.* -# Issues, Pull Requests, and Branches - -*Provide repository links related to this PLEP, and include -descriptions.* - # Backward Compatibility This PLEP will not maintain backward compatibility. -# Alternatives - -*Summarize alternative possibilities to address (or not address) the -problem described in this PLEP, if necessary.* - # Decision Rationale *Summarize the discussion on this PLEP and describe the reasoning From 260dfc1ba992bb5fc611fa7eff7a27ea51ea83b0 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Wed, 24 Jan 2018 14:14:49 +0000 Subject: [PATCH 12/18] Tidy up more stuff --- PLEP-0007.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/PLEP-0007.md b/PLEP-0007.md index 262824a..92b4820 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -19,9 +19,6 @@ This PLEP therefore presents a new more general framework for the `Plasma` objec # Detailed Description -*Provide an extended description of the problem and the proposed -changes, including usage examples when needed.* - ## Issues with current Plasma object The existing Plasma class was written primarily for use in simulations and can only be instantiated with `astropy` Quantities as input. @@ -56,11 +53,7 @@ In addition to these development benefits, presenting the user with a single int This PLEP will not maintain backward compatibility. -# Decision Rationale - -*Summarize the discussion on this PLEP and describe the reasoning -behind the decision, if necessary.* + -*Not all PLEPs require all of these sections, and occasionally -additional sections may be necessary. Emphasized text should be -deleted.* + + From b9be48866662d28f29709d10e0b35532482b9764 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Wed, 31 Jan 2018 14:45:00 +0000 Subject: [PATCH 13/18] Take out placeholder text and replace with real text --- PLEP-0007.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PLEP-0007.md b/PLEP-0007.md index 92b4820..1cf0503 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -47,7 +47,7 @@ In addition to these development benefits, presenting the user with a single int # Implementation -*Describe the steps necessary to implement this PLEP, if necessary.* +This section will describe the suggested approach to implement the above structure. # Backward Compatibility From 025627e6dc7f17cb74b91137e782c00512ddbff4 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Wed, 31 Jan 2018 14:45:45 +0000 Subject: [PATCH 14/18] Add section on metaclass and subclasses --- PLEP-0007.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/PLEP-0007.md b/PLEP-0007.md index 1cf0503..fe657b5 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -49,6 +49,18 @@ In addition to these development benefits, presenting the user with a single int This section will describe the suggested approach to implement the above structure. +## `Plasma` metaclass and subclasses + +At the core of this implementation will be the main `Plasma` metaclass. +This metaclass should inherit from Python's [abstract base class](https://docs.python.org/3/library/abc.html), which allows a class definition to include abstract methods and properties. +The presence of these definitions in the metaclass enforces them in any class which inherits from it. +Such an arrangement lets us use the `Plasma` metaclass to determine the desired default structure for any `Plasma` subclasses. +For instance, if we decide every type of plasma needs coordinate information, we would define the relevant attributes in the `Plasma` metaclass as abstract properties. +Different types of plasma would then be represented by subclasses of `Plasma`, which would be required to define these coordinate properties as well. + +The metaclass's properties can define default behaviour which can then be replaced or expanded on by the subclass, or they can contain no functionality and serve only to determine structure. +In either case the metaclass allows us to define things which _must_ be present for all plasmas, and so fulfils the aim of defining a consistent user experience across different plasma types in an easily maintainable way. + # Backward Compatibility This PLEP will not maintain backward compatibility. From 2b91dd298225aa72eeeb2224f1843b762abc3bec Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Wed, 31 Jan 2018 14:46:14 +0000 Subject: [PATCH 15/18] Add section on class factory --- PLEP-0007.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/PLEP-0007.md b/PLEP-0007.md index fe657b5..f5f2f90 100644 --- a/PLEP-0007.md +++ b/PLEP-0007.md @@ -61,6 +61,16 @@ Different types of plasma would then be represented by subclasses of `Plasma`, w The metaclass's properties can define default behaviour which can then be replaced or expanded on by the subclass, or they can contain no functionality and serve only to determine structure. In either case the metaclass allows us to define things which _must_ be present for all plasmas, and so fulfils the aim of defining a consistent user experience across different plasma types in an easily maintainable way. +## Class factory + +The instantiation of a plasma subclass should be handled by a class factory. +This is a function or a method of a class which takes user input and returns an instance of the appropriate class. +Again, this furthers the aim of unifying user experience, since the user only ever needs to use the class factory rather than directly instantiating any particular subclass. + +To achieve this, the metaclass should keep a registry of valid subclasses, which can be instantiated by the factory. +Each subclass in this registry is checked by some validation function which selects a single subclass based on the user's input, then uses that input to instantiate that subclass and return the instance. +Alternatively the registry can be kept by the factory rather than the metaclass. + # Backward Compatibility This PLEP will not maintain backward compatibility. From 55e56a3568729812bbf7ac32f607610cd29f0350 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 26 Sep 2018 21:14:42 -0400 Subject: [PATCH 16/18] Renumber Plasma object to PLEP 6 (formerly PLEP 7) --- PLEP-0000.rst | 8 +++----- PLEP-0007.md => PLEP-0006.md | 4 ++-- README.rst | 3 +++ 3 files changed, 8 insertions(+), 7 deletions(-) rename PLEP-0007.md => PLEP-0006.md (98%) diff --git a/PLEP-0000.rst b/PLEP-0000.rst index 7e100ae..2cc4b99 100644 --- a/PLEP-0000.rst +++ b/PLEP-0000.rst @@ -47,7 +47,9 @@ Accepted PLEPs | 4 | `Licensing of PlasmaPy Repositories | Nicholas A. Murphy | process | `10.5281/zenodo.1435990 | | | `__ | | | `__ | +--------+---------------------------------------------------------------------------+---------------------------+---------------+---------------------------------------------+ - +| 6 | `A New General-Purpose Plasma Object | Andrew J. Leonard | standard | | +| | `__ | | | | ++--------+---------------------------------------------------------------------------+---------------------------+---------------+---------------------------------------------+ Declined PLEPs ============== @@ -67,10 +69,6 @@ PLEPs in preparation or under consideration | 5 | `PlasmaPy Versioning and Releases | Nicholas A. Murphy and | process | | | `__ | Stuart J. Mumford | | +--------+---------------------------------------------------------------------------+---------------------------+---------------+ -| 6 | `A New General-Purpose Plasma Object | Andrew J. Leonard | standard | -| | `__ | | | -+--------+---------------------------------------------------------------------------+---------------------------+---------------+ - Tentatively Reserved PLEPs ========================== diff --git a/PLEP-0007.md b/PLEP-0006.md similarity index 98% rename from PLEP-0007.md rename to PLEP-0006.md index f5f2f90..9c93a94 100644 --- a/PLEP-0007.md +++ b/PLEP-0006.md @@ -1,6 +1,6 @@ -# PLEP-0007 -- A New General-Purpose Plasma Object +# PLEP-0006 -- A New General-Purpose Plasma Object -| PLEP | 7 | +| PLEP | 6 | |-------------------|-------------------------------------| | title | A New General-Purpose Plasma Object | | author(s) | Drew Leonard | diff --git a/README.rst b/README.rst index b4cf9d6..04c8dab 100644 --- a/README.rst +++ b/README.rst @@ -29,3 +29,6 @@ convenience, an abbreviated index of PLEPs is provided below. | 4 | `Licensing of PlasmaPy Repositories <./PLEP-0004.rst>`__ | .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1435990.svg | | | | :target: https://doi.org/10.5281/zenodo.1435990 | +--------+----------------------------------------------------------------------------------+--------------------------------------------------------------------+ +| 6 | `A New General-Purpose Plasma Object <./PLEP-0006.rst>`__ | | +| | | | ++--------+----------------------------------------------------------------------------------+--------------------------------------------------------------------+ From 955d018ec6eb7aa923dae8963742d65bcd1bfcf3 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 26 Sep 2018 21:21:40 -0400 Subject: [PATCH 17/18] Rename PLEP-0006.md to PLEP-0006.rst Co-authored-by: Drew Leonard --- PLEP-0006.md => PLEP-0006.rst | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename PLEP-0006.md => PLEP-0006.rst (100%) diff --git a/PLEP-0006.md b/PLEP-0006.rst similarity index 100% rename from PLEP-0006.md rename to PLEP-0006.rst From 7e620af613a0adaf3b0d435f7ee67a478411b644 Mon Sep 17 00:00:00 2001 From: Nick Murphy Date: Wed, 26 Sep 2018 21:31:49 -0400 Subject: [PATCH 18/18] Convert PLEP 6 from Markdown to ReST The changes I'm making are entirely formatting and metadata. I did not change any of the content written by Drew Leonard for this PLEP. Co-authored-by: Drew Leonard --- PLEP-0006.rst | 195 +++++++++++++++++++++++++++++++++----------------- 1 file changed, 129 insertions(+), 66 deletions(-) diff --git a/PLEP-0006.rst b/PLEP-0006.rst index 9c93a94..2e77354 100644 --- a/PLEP-0006.rst +++ b/PLEP-0006.rst @@ -1,81 +1,144 @@ -# PLEP-0006 -- A New General-Purpose Plasma Object +=============================================== +PLEP-0006 – A New General-Purpose Plasma Object +=============================================== ++-------------------+-------------------------------------+ | PLEP | 6 | -|-------------------|-------------------------------------| -| title | A New General-Purpose Plasma Object | ++===================+=====================================+ | author(s) | Drew Leonard | ++-------------------+-------------------------------------+ | contact email | andy.j.leonard@gmail.com | ++-------------------+-------------------------------------+ | date created | 2017-01-16 | ++-------------------+-------------------------------------+ | date last revised | 2017-01-16 | ++-------------------+-------------------------------------+ | type | standard | ++-------------------+-------------------------------------+ | status | discussion | ++-------------------+-------------------------------------+ + +Abstract +-------- + +The current implementation of PlasmaPy's ``Plasma`` object does not +adequately fulfill the intended use case. Plasma physics is a broad +discipline which makes use of many different kinds of data structure +from a variety of sources and a variety of purposes. If PlasmaPy is to +provide useful tools for all plasma physicists, its core data object +therefore needs to be appropriately flexible. This PLEP therefore +presents a new more general framework for the ``Plasma`` object. + +Detailed Description +-------------------- + +Issues with current Plasma object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The existing Plasma class was written primarily for use in simulations +and can only be instantiated with ``astropy`` Quantities as input. This +is largely because it was originally intended for use with an entirely +different package and flexibility was not a significant issue. So far no +major problems have arisen from this lack of flexibility, but as +PlasmaPy grows its user-base and its functionality it will have to be +able to load, store and analyse a wide variety of different kinds of +plasma. The ``Plasma`` class as it is currently written will not be able +to do these things. + +Proposed solution +~~~~~~~~~~~~~~~~~ + +There are a few ways in which PlasmaPy might deal with multiple +different kinds of plasma. One would be to implement multiple classes +with different methods of instantiation and with attributes and methods +appropriate for the kind of plasma. Another would be to continue using a +single class but to build in all functionality needed for every kind of +plasma we would wish to be able to work with. + +Of these options, both have some drawbacks. The latter would result in +the class being extremely difficult to develop and maintain, and likely +also problematic to use productively. On the other hand, the former +allows each class to be more focused, but requires maintaining them all +separately. It would also introduce a slightly different user experience +for each different type of plasma. + +The proposed solution is a compromise between these two methods, similar +to that used by `SunPy `__ for its core +`Map `__ object. In +this model each kind of plasma would have its own subclass, allowing +these to provide functionality specific to that plasma. The user +interface to these classes would be handled exclusively by a ``Plasma`` +metaclass which would also define common or default functionality. When +instantiated, the metaclass would create and return the appropriate +subclass based on the input. + +This approach gives the advantages of reducing the development and +maintenance burden compared to using multiple completely separate +classes by centralising common functionality, while also allowing +arbitrarily specific plasma subclasses. In addition to these development +benefits, presenting the user with a single interface for any plasma +reduces cognitive overhead for learners and increases the reusability of +code. + +Implementation +-------------- + +This section will describe the suggested approach to implement the above +structure. + +``Plasma`` metaclass and subclasses +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +At the core of this implementation will be the main ``Plasma`` +metaclass. This metaclass should inherit from Python's `abstract base +class `__, which allows a +class definition to include abstract methods and properties. The +presence of these definitions in the metaclass enforces them in any +class which inherits from it. Such an arrangement lets us use the +``Plasma`` metaclass to determine the desired default structure for any +``Plasma`` subclasses. For instance, if we decide every type of plasma +needs coordinate information, we would define the relevant attributes in +the ``Plasma`` metaclass as abstract properties. Different types of +plasma would then be represented by subclasses of ``Plasma``, which +would be required to define these coordinate properties as well. + +The metaclass's properties can define default behaviour which can then +be replaced or expanded on by the subclass, or they can contain no +functionality and serve only to determine structure. In either case the +metaclass allows us to define things which *must* be present for all +plasmas, and so fulfils the aim of defining a consistent user experience +across different plasma types in an easily maintainable way. + +Class factory +~~~~~~~~~~~~~ + +The instantiation of a plasma subclass should be handled by a class +factory. This is a function or a method of a class which takes user +input and returns an instance of the appropriate class. Again, this +furthers the aim of unifying user experience, since the user only ever +needs to use the class factory rather than directly instantiating any +particular subclass. + +To achieve this, the metaclass should keep a registry of valid +subclasses, which can be instantiated by the factory. Each subclass in +this registry is checked by some validation function which selects a +single subclass based on the user's input, then uses that input to +instantiate that subclass and return the instance. Alternatively the +registry can be kept by the factory rather than the metaclass. + +Backward Compatibility +---------------------- -# Abstract - -The current implementation of PlasmaPy's `Plasma` object does not adequately fulfill the intended use case. -Plasma physics is a broad discipline which makes use of many different kinds of data structure from a variety of sources and a variety of purposes. -If PlasmaPy is to provide useful tools for all plasma physicists, its core data object therefore needs to be appropriately flexible. -This PLEP therefore presents a new more general framework for the `Plasma` object. - -# Detailed Description - -## Issues with current Plasma object - -The existing Plasma class was written primarily for use in simulations and can only be instantiated with `astropy` Quantities as input. -This is largely because it was originally intended for use with an entirely different package and flexibility was not a significant issue. -So far no major problems have arisen from this lack of flexibility, but as PlasmaPy grows its user-base and its functionality it will have to be able to load, store and analyse a wide variety of different kinds of plasma. -The `Plasma` class as it is currently written will not be able to do these things. - -## Proposed solution - -There are a few ways in which PlasmaPy might deal with multiple different kinds of plasma. -One would be to implement multiple classes with different methods of instantiation and with attributes and methods appropriate for the kind of plasma. -Another would be to continue using a single class but to build in all functionality needed for every kind of plasma we would wish to be able to work with. - -Of these options, both have some drawbacks. -The latter would result in the class being extremely difficult to develop and maintain, and likely also problematic to use productively. -On the other hand, the former allows each class to be more focused, but requires maintaining them all separately. -It would also introduce a slightly different user experience for each different type of plasma. - -The proposed solution is a compromise between these two methods, similar to that used by [SunPy](sunpy.org) for its core [Map](http://docs.sunpy.org/en/stable/code_ref/map.html) object. -In this model each kind of plasma would have its own subclass, allowing these to provide functionality specific to that plasma. -The user interface to these classes would be handled exclusively by a `Plasma` metaclass which would also define common or default functionality. -When instantiated, the metaclass would create and return the appropriate subclass based on the input. - -This approach gives the advantages of reducing the development and maintenance burden compared to using multiple completely separate classes by centralising common functionality, while also allowing arbitrarily specific plasma subclasses. -In addition to these development benefits, presenting the user with a single interface for any plasma reduces cognitive overhead for learners and increases the reusability of code. - -# Implementation - -This section will describe the suggested approach to implement the above structure. - -## `Plasma` metaclass and subclasses - -At the core of this implementation will be the main `Plasma` metaclass. -This metaclass should inherit from Python's [abstract base class](https://docs.python.org/3/library/abc.html), which allows a class definition to include abstract methods and properties. -The presence of these definitions in the metaclass enforces them in any class which inherits from it. -Such an arrangement lets us use the `Plasma` metaclass to determine the desired default structure for any `Plasma` subclasses. -For instance, if we decide every type of plasma needs coordinate information, we would define the relevant attributes in the `Plasma` metaclass as abstract properties. -Different types of plasma would then be represented by subclasses of `Plasma`, which would be required to define these coordinate properties as well. - -The metaclass's properties can define default behaviour which can then be replaced or expanded on by the subclass, or they can contain no functionality and serve only to determine structure. -In either case the metaclass allows us to define things which _must_ be present for all plasmas, and so fulfils the aim of defining a consistent user experience across different plasma types in an easily maintainable way. - -## Class factory +This PLEP will not maintain backward compatibility. -The instantiation of a plasma subclass should be handled by a class factory. -This is a function or a method of a class which takes user input and returns an instance of the appropriate class. -Again, this furthers the aim of unifying user experience, since the user only ever needs to use the class factory rather than directly instantiating any particular subclass. +.. raw:: html -To achieve this, the metaclass should keep a registry of valid subclasses, which can be instantiated by the factory. -Each subclass in this registry is checked by some validation function which selects a single subclass based on the user's input, then uses that input to instantiate that subclass and return the instance. -Alternatively the registry can be kept by the factory rather than the metaclass. + -# Backward Compatibility +.. raw:: html -This PLEP will not maintain backward compatibility. + - +.. raw:: html - - +