SDyPy Enhancement Proposals
SEP 0 — Purpose and Process
- Author:
Janko Slavič <janko.slavic@fs.uni-lj.si>
- Status:
Active
- Type:
Process
- Created:
2-Nov-2020
What is a SEP?
SEP stands for SDyPy Enhancement Proposal. A SEP is a design document providing information to the SDyPy community, or describing a new feature for SDyPy or its processes or environment. The SEP should provide a concise technical specification of the feature and a rationale for the feature. SEPs follow the idea of NEPs (NumPy Enhancement Proposals) and PEPs (Python Enhancement Proposals).
Acknowledgement: this SEP heavily based on NEP0 (by Jarrod Millman <millman@berkeley.edu>)! Good practices from the Python ecosystem should be applied wherever possible!
We intend SEPs to be the primary mechanisms for proposing major new features, for collecting community input on an issue, and for documenting the design decisions that have gone into SDyPy. The SEP author is responsible for building consensus within the community and documenting dissenting opinions.
Because the SEPs are maintained as text files in a versioned repository, their revision history is the historical record of the feature proposal [1]_.
Types
There are three kinds of SEPs:
A Standards Track SEP describes a new feature or implementation for SDyPy.
An Informational SEP describes a SDyPy design issue, or provides general guidelines or information to the Python community, but does not propose a new feature. Informational SEPs do not necessarily represent a SDyPy community consensus or recommendation, so users and implementers are free to ignore Informational SEPs or follow their advice.
A Process SEP describes a process surrounding SDyPy, or proposes a change to (or an event in) a process. Process SEPs are like Standards Track SEPs but apply to areas other than the SDyPy language itself. They may propose an implementation, but not to SDyPy’s codebase; they require community consensus. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in SDyPy development. Any meta-SEP is also considered a Process SEP.
SEP Workflow
The SEP process begins with a new idea for SDyPy. It is highly recommended that a single SEP contain a single key proposal or new idea. Small enhancements or patches often don’t need a SEP and can be injected into the SDyPy development workflow with a pull request to the SDyPy repo. The more focused the SEP, the more successful it tends to be. If in doubt, split your SEP into several well-focused ones.
Each SEP must have a champion—someone who writes the SEP using the style and format described below, shepherds the discussions in the appropriate forums, and attempts to build community consensus around the idea. The SEP champion (a.k.a. Author) should first attempt to ascertain whether the idea is suitable for a SEP. Writting to the sdypy-discussion mailing list with the SEP tag is the best way to doing this mailing list.
The proposal should be submitted as a draft SEP via a GitHub pull
request to the docs/seps
directory with the name sep-<n>.rst
where <n>
is an appropriately assigned four-digit number (e.g.,
sep-0000.rst
). The draft must use the :docs:`sep-template` file.
Once the PR for the SEP is in place, a post should be made to the mailing list containing the sections up to “Backward compatibility”, with the purpose of limiting discussion there to usage and impact. Discussion on the pull request will have a broader scope, also including details of implementation.
At the earliest convenience, the PR should be merged (regardless of whether it is accepted during discussion). Additional PRs may be made by the Author to update or expand the SEP, or by maintainers to set its status, discussion URL, etc.
Standards Track SEPs consist of two parts, a design document and a reference implementation. It is generally recommended that at least a prototype implementation be co-developed with the SEP, as ideas that sound good in principle sometimes turn out to be impractical when subjected to the test of implementation. Often it makes sense for the prototype implementation to be made available as PR to the SDyPy repo (making sure to appropriately mark the PR as a WIP).
Review and Resolution
SEPs are discussed as issues SEP. The possible paths of the status of SEPs are as follows:
All SEPs should be created with the Draft
status.
Eventually, after discussion, there may be a consensus that the SEP
should be accepted – see the next section for details. At this point
the status becomes Accepted
.
Once a SEP has been Accepted
, the reference implementation must be
completed. When the reference implementation is complete and incorporated
into the main source code repository, the status will be changed to Final
.
To allow gathering of additional design and interface feedback before committing to long term stability for a language feature or standard library API, a SEP may also be marked as “Provisional”. This is short for “Provisionally Accepted”, and indicates that the proposal has been accepted for inclusion in the reference implementation, but additional user feedback is needed before the full design can be considered “Final”. Unlike regular accepted SEPs, provisionally accepted SEPs may still be Rejected or Withdrawn even after the related changes have been included in a Python release.
Wherever possible, it is considered preferable to reduce the scope of a proposal to avoid the need to rely on the “Provisional” status (e.g. by deferring some features to later SEPs), as this status can lead to version compatibility challenges in the wider NumPy ecosystem.
A SEP can also be assigned status Deferred
. The SEP author or a
core developer can assign the SEP this status when no progress is being made
on the SEP.
A SEP can also be Rejected
. Perhaps after all is said and done it
was not a good idea. It is still important to have a record of this
fact. The Withdrawn
status is similar—it means that the SEP author
themselves has decided that the SEP is actually a bad idea, or has
accepted that a competing proposal is a better alternative.
When a SEP is Accepted
, Rejected
, or Withdrawn
, the SEP should be
updated accordingly. In addition to updating the status field, at the very
least the Resolution
header should be added with a link to the relevant
thread in the mailing list archives.
SEPs can also be Superseded
by a different SEP, rendering the
original obsolete. The Replaced-By
and Replaces
headers
should be added to the original and new SEPs respectively.
Process SEPs may also have a status of Active
if they are never
meant to be completed, e.g. SEP 0 (this SEP).
How a SEP becomes Accepted
A SEP is Accepted
by consensus of all interested contributors. We
need a concrete way to tell whether consensus has been reached. When
you think a SEP is ready to accept, send an email to the
sdypy-discussion mailing list with a subject like:
Proposal to accept SEP #<number>: <title>
In the body of your email, you should:
link to the latest version of the SEP,
briefly describe any major points of contention and how they were resolved,
include a sentence like: “If there are no substantive objections within 7 days from this email, then the SEP will be accepted; see SEP 0 for more details.”
After you send the email, you should make sure to link to the email
thread from the Discussion
section of the SEP, so that people can
find it later.
Generally the SEP author will be the one to send this email, but anyone can do it – the important thing is to make sure that everyone knows when a SEP is on the verge of acceptance, and give them a final chance to respond. If there’s some special reason to extend this final comment period beyond 7 days, then that’s fine, just say so in the email. You shouldn’t do less than 7 days, because sometimes people are travelling or similar and need some time to respond.
In general, the goal is to make sure that the community has consensus, not provide a rigid policy for people to try to game. When in doubt, err on the side of asking for more feedback and looking for opportunities to compromise.
If the final comment period passes without any substantive objections,
then the SEP can officially be marked Accepted
. You should send a
followup email notifying the list (celebratory emoji optional but
encouraged 🎉✨), and then update the SEP by setting its :Status:
to Accepted
, and its :Resolution:
header to a link to your
followup email.
If there are substantive objections, then the SEP remains in
Draft
state, discussion continues as normal, and it can be
proposed for acceptance again later once the objections are resolved.
In unusual cases, the `SDyPy Steering Council`_ may be asked to decide
whether a controversial SEP is Accepted
.
Maintenance
In general, Standards track SEPs are no longer modified after they have reached the Final state as the code and project documentation are considered the ultimate reference for the implemented feature. However, finalized Standards track SEPs may be updated as needed.
Process SEPs may be updated over time to reflect changes to development practices and other details. The precise process followed in these cases will depend on the nature and purpose of the NEP being updated.
Format and Template
SEPs are UTF-8 encoded text files using the reStructuredText format. Please see the sep-template file and the reStructuredTextPrimer for more information. We use Sphinx to convert SEPs to HTML for viewing on the web [2].
Header Preamble
Each SEP must begin with a header preamble. The headers
must appear in the following order. Headers marked with *
are
optional. All other headers are required.
:Author: <list of authors' real names and optionally, email addresses>
:Status: <Draft | Active | Accepted | Deferred | Rejected |
Withdrawn | Final | Superseded>
:Type: <Standards Track | Process>
:Created: <date created on, in dd-mmm-yyyy format>
* :Requires: <sep numbers>
* :SDyPy-Version: <version number>
* :Replaces: <sep number>
* :Replaced-By: <sep number>
* :Resolution: <url>
The Author header lists the names, and optionally the email addresses of all the authors of the SEP. The format of the Author header value must be
Random J. User <address@dom.ain>
if the email address is included, and just
Random J. User
if the address is not given. If there are multiple authors, each should be on a separate line.
Discussion
References and Footnotes
Copyright
This document has been placed in the public domain.
SEP 1 — Integration of packages into SDyPy
- Authors:
Janko Slavič <janko.slavic@fs.uni-lj.si>, Klemen Zaletelj <klemen.zaletelj@fs.uni-lj.si>
- Status:
Draft
- Type:
Process
- Created:
2021-02-11
Abstract
A four level scale of integration of a package into SDyPy is proposed to enable the connectivity of the existing projects. The levels differ in consistency of nomenclature with SDyPy, developed documentation and testing. The levels of integration enable quick association of a project with SDyPy, without extended efforts from the developers. Higher levels of integration can be achieved by developing the project in agreement with SDyPy guidelines.
Motivation
The SDyPy project was created to unify the effort in structural dynamics and associate the relevant projects; however, the existing packages were developed independently, with various degrees of compatibility. To minimize the efforts of the developers, the four levels of integration are proposed, enabling the developers to choose the level of the desired independency of their project and level of integration into SDyPy.
Detailed description
The four levels of integration:
- 4th level:
External packages dealing with structural dynamics, listed as related projects.
These packages are developed completely independently but might be useful for 3rd, 2nd and 1st level packages.
- 3rd level:
Testing and documentation corresponds to the SDyPy template.
Package has an MIT or similar licence which enables free use for any purpose (incl. commercial).
PIP supported installation (wheels).
- 2nd level, all of 3rd level, but additionally:
Automatic tests of interoperability to other 1st and 2nd level packages are prepared.
Corresponds to nomenclature guidelines of SDyPy.
Package has the same licence as SDyPy.
This packages are namespace packages under SDyPy namespace (see SEP3).
Packages are still developed in a separate repository.
- 1st level, all of 2nd level, but one of the following:
These packages are developed in the SDyPy repository.
Are namespace packages (see SEP3) in separate repositories under the SDyPy organization.
Discussion
This section may just be a bullet list including links to any discussions regarding the SEP:
This includes links to mailing list threads or relevant GitHub issues.
References and Footnotes
Each SEP must either be explicitly labeled as placed in the public domain (see this SEP as an example) or licensed under the Open Publication License.
Copyright
This document has been placed in the public domain. [1]_
SEP 2 — Nomenclature guidelines
- Authors:
Klemen Zaletelj <klemen.zaletelj@fs.uni-lj.si>, Janko Slavič <janko.slavic@fs.uni-lj.si>
- Status:
Draft
- Type:
Process
- Created:
2021-03-15
Abstract
The nomenclature guidelines for SDyPy are presented for better interoperability of the packages/modules.
Motivation
The nomenclature is often not consistent for different packages which affects the user experience when combining the use of multiple packages.
Detailed description
SDyPy nomenclature follows the python guidelines, presented in PEP 8.
General guidelines
As is stated in PEP 8, the code is read much more often than it is written. The names of the variables should therefore be as descriptive as possible. Examples:
a = 4 # Not good rectangle_height = 4 # Good
With most code editors enabling the use of autocomplete, the length of the variables does not present a major issue for code writing.
When combining multiple words into a variable name, the term with a broader meaning should be on the first place. The more defining term comes next. This improves the readability of the code, enabling the reader to immediately understand what the main purpose of the variable is. Examples:
freq_upper freq_lower damping_viscous damping_hysteretic
It should be said, that the it is up to the user to determine what is the more broader term.
Common variables in structural dynamics
Despite the general guidelines written above, the variables which are broadly used in structural dynamics can be an exception. To avoid different variable names (e.g. sampling_frequency, freq_sampling), the conventions given below should be used.
Parameter |
Symbol |
Unit |
Description |
Frequency limits |
|
||
Frequency Response Function |
|
Different forms of the frequency response function are possible (receptance, mobility, accelerance) and can be given other names. When the frequency response function is referenced in arbitrary form, this variable name should be given. |
|
Frequency vector |
|
Hz |
|
Frequency vector in rad/s |
|
rad/s |
|
Natural frequency |
|
Hz |
|
Sampling frequency |
|
Hz |
This name is not descriptive; however, it is commonly used in other packages (e.g. scipy) |
Time step |
|
second |
Discussion
This section may just be a bullet list including links to any discussions regarding the SEP:
This includes links to mailing list threads or relevant GitHub issues.
References and Footnotes
Each SEP must either be explicitly labeled as placed in the public domain (see this SEP as an example) or licensed under the Open Publication License.
Copyright
This document has been placed in the public domain. [1]_
SEP 3 — Including packages into the SDyPy namespace
- Authors:
Domen Gorjup <domen.gorjup@fs.uni-lj.si>, Janko Slavič <janko.slavic@fs.uni-lj.si>
- Status:
Draft
- Type:
Process
- Created:
2021-03-25
Abstract
SDyPy uses Python’s namespace package mechanism to include packages with a high level of integration into its namespace while allowing for an independently development processes. The use of namespace packages in SDyPy is described in this document.
Motivation
As SDyPy aims to integrate multiple open-source Python packages in the structural dynamics field to provide a coherent workflow, it may be beneficial to include some packages into the SDyPy namespace. However, it is reasonable that some of these packages keep a high level of independence in their development and distribution (e.g. their repositories with a wealth of existing resources, issues and commit histories…). To achieve this, Python’s namespace package mechanism is used.
Detailed description
The four levels of integration, described in SEP1, define two types of packages that are included in the SDyPy namespace, but are developed in independent repositories:
2nd level packages are namespace packages with a high level of integration with SDyPy, that are developed by a separate organization.
1st level packages are hosted by the SDyPy organization, but can be developed in a repository, separate from the `core SDyPy package`_.
To integrate these two types of packages into the SDyPy namespace, Python’s namespace package mechanism is used. A native support for namespace packages has been introduced with Python 3.3 and is defined by PEP 420. When a package has reached a high level of integration with SDyPy, it can be included into the SDyPy namespace by adhering to Python’s namespace package file structure
example_project/
setup.py
SDyPy/
example_project/
__init__.py
As stated in Python’s namespace package documentation, it is important that the namespace directory (SDyPy/) omits an __init__.py file. It is also necessary to alter an existing package’s setup script to adhere to the changed file structure.
When a package, developed by a separate organization is defined to be part of the SDyPy namespace, as shown in the above example, it becomes a Level 2 SDyPy package. If it’s ownership is also transferred to the SDyPy organization it becomes a Level 1 SDyPy package.
SDyPy packages should follow the The Zen of Python, presented in PEP 20.
Discussion
This section may just be a bullet list including links to any discussions regarding the SEP:
This includes links to mailing list threads or relevant GitHub issues.
References and Footnotes
Each SEP must either be explicitly labeled as placed in the public domain (see this SEP as an example) or licensed under the Open Publication License.
Copyright
This document has been placed in the public domain. [1]_
SEP 4 — SDyPy package content roadmap
- Authors:
Janko Slavič <janko.slavic@fs.uni-lj.si>, Klemen Zaletelj <klemen.zaletelj@fs.uni-lj.si>, Domen Gorjup <domen.gorjup@fs.uni-lj.si>
- Status:
Draft
- Type:
Process
- Created:
2021-04-12
Abstract
This roadmap should be clear about what should be the core capabilities of the SDyPy (namespace) packages. This roadmap should also serve as a radar of packages which could be integrated (if this is suggested by the autors) into SDyPy.
Motivation and Scope
SDyPy is supporting individual user(s) driven packages. However, for long-term stability of the effort it is better that the development and governance is transfered to an independent, multi-institution, open and transparent organisation. SDyPy organisation was established to provide this long-term stability. If individual packages are based on the SDyPy project template then they can easily transition from level 4 or 3 to level 2 or 1 namespace packages. The integration to the SDyPy package/organisation is made if:
the authors propose such integration and
the functionalities of the package extend the capabilities of the sdypy package as written in this SEP (this SEP is open always for discussion and extensions).
The transition to SDyPy should preserve as much of development history as possible (git).
Detailed description
The structure of SDyPy is defined with this SEP and should reflect the scientific topics typically researched. It is prefered that general numerical methods, applicable to different fields of science, should be developed elsewhere, e.g. in Scipy.
The long-term functionalities the sdypy package should have are:
sdypy.excitation
: Excitation signal generationshort term goal inclusion of
pyExSi
as a namespace packagecurrently prefered package:
pyExSi
sdypy.control
: Control of dynamic systemslooking for contributors
sdypy.model
: System modeling (FEM,…)lumped mass system generator
looking for contributors
sdypy.system
: System identification methodsmethods for damping identification
methods for joint identification
looking for contributors
sdypy.FRF
: Frequency Response Function computationshort/long term goal is to develop a new package (based on pyFRF or any other package(s)) with MIMO, windowing, units, delay handling, etc.
currently prefered package:
pyFRF
sdypy.view
: Visualisation of data (models, time/frequency domain)2D/3D model support, probably based on
pyVista
2D ploting
looking for contributors
sdypy.EMA
: Experimental Modal Analysisimplemented as
sdypy.EMA
, further development required (e.g. MIMO identification)
sdypy.OMA
: Operational Modal Analysisprobably OMA will be integrated under EMA with specific parameters. This issue is open.
sdypy.reduction
: Model reduction and couplinglooking for contributors
sdypy.fatigue
: Vibration fatigue in frequency-domainshort term goal inclusion of
FLife
as a namespace packagecurrently prefered package:
FLife
sdypy.holography
: Methods to identify vibrational response using acoustic holographylooking for contributors
sdypy.image
: Methods to identify vibrational response from image dataimage based methods, pyIDI a good candidate
looking for contributors
sdypy.io
: Input/Output methodsshort term goal is importing
pyUFF
andlvm_read
into thesdypy.io
package.long term goal is the implementation of various input/output methods into the
sdypy.io
package.currently prefered package:
pyUFF
Discussion
This section may just be a bullet list including links to any discussions regarding the SEP:
This includes links to mailing list threads or relevant GitHub issues.
References and Footnotes
Each SEP must either be explicitly labeled as placed in the public domain (see this SEP as an example) or licensed under the Open Publication License.
Copyright
This document has been placed in the public domain. [1]_