Update public API, and internal naming conventions for DM to eliminate use of "default" (previously refered to default sections)

Commit-type: style-fix, documentation

Merge branch 'jed/deprecate-dmgetdefaultsection' [PR #1969]

* jed/deprecate-dmgetdefaultsection:
DMGetDefaultSection et al: add PETSC_DEPRECATED_FUNCTION
These functions were deprecated in v3.9, but

Merge branch 'jed/deprecate-dmgetdefaultsection' [PR #1969]

* jed/deprecate-dmgetdefaultsection:
DMGetDefaultSection et al: add PETSC_DEPRECATED_FUNCTION
These functions were deprecated in v3.9, but no PETSC_DEPRECATED_FUNCTION was added at that time so many uses crept back into the source code. Here we mark it deprecated and fix all existing uses in PETSc.

DMGetLocalSection/DMSetLocalSection: add explicit names for DMGetSection/DMSetSection
These names are for symmetry with DMGetLocalVector() versus DMGetGlobalVector().

DMGetSection: replace all internal usage with DMGetLocalSection
Same for DMSetSection -> DMSetLocalSection. We retain the interface for DMGetSection/DMSetSection without deprecation warnings (for now).

show more ...

DMGetSection: replace all internal usage with DMGetLocalSection

Same for DMSetSection -> DMSetLocalSection. We retain the interface
for DMGetSection/DMSetSection without deprecation warnings (for n

DMGetSection: replace all internal usage with DMGetLocalSection

Same for DMSetSection -> DMSetLocalSection. We retain the interface
for DMGetSection/DMSetSection without deprecation warnings (for now).

Suggested-by: Barry Smith <bsmith@mcs.anl.gov>

show more ...

Merged in knepley/fix-plex-layout-submesh (pull request #1704)

Plex: Handle data layout over submeshes

Merged in psanan/man-pages-remove-keywords (pull request #1717)

Man pages: Remove .keywords fields

Approved-by: BarryFSmith <bsmith@mcs.anl.gov>

Man pages: remove .keywords: fields

This field is recognized by doctext from Sowing (http://wgropp.cs.illinois.edu/projects/software/sowing/doctext/node20.htm#Node20),
but it doesn't seem to be unif

Man pages: remove .keywords: fields

This field is recognized by doctext from Sowing (http://wgropp.cs.illinois.edu/projects/software/sowing/doctext/node20.htm#Node20),
but it doesn't seem to be uniformly used or maintained.

Thus, remove all .keywords: fields, and a following blank line, if present.

This is accomplished with GNU sed (gsed on OS X), with the following commands.
*Warning* that this type of command can corrupt a .git directory,
so be cautious in reusing or modifying these commands. They first look
for and delete matching lines with a following line consisting of only whitespace,
and then delete any remaining matching lines.

find src/ -type f -exec gsed -i '/keywords:/ {N; /\n\s*$/d}' {} +
find src/ -type f -exec gsed -i '/keywords:/d' {} +
find include/ -type f -exec gsed -i '/keywords:/ {N; /\n\s*$/d}' {} +
find include/ -type f -exec gsed -i '/keywords:/d' {} +

Hints on the sed command obtained from: https://unix.stackexchange.com/questions/100754/how-to-delete-a-specific-line-and-the-following-blank-line-using-gnu-sed

show more ...

Plex: Handle data layout over submeshes

Merge branch 'master' of bitbucket.org:petsc/petsc

Merged in knepley/allow-fe-with-lower-dimension-than-the-t-1552326361934 (pull request #1434)

Allow FE with lower dimension than the target mesh

Plex: When getting dog layout from a discretization, check that we only ask for dimensions that the FE supports

Allow FE with lower dimension than the target mesh

Merge branch 'master' into wence/feature-patch-all-at-once

Merge branch 'master' into jpusztay/feature-swarm-symplectic-example

Merged petsc/petsc into master

Merged petsc/petsc into master

Merge branch 'knepley/feature-multiple-ds' [PR #1309]

Merge branch 'master' into knepley/feature-snes-patch

Merge branch 'knepley/feature-section-label'

DM+DS: Reorganized DS handling completely do that multiple regions can be supported
- A region is labeled portion of the mesh which has the same approximation space for the solution. Note that this i

DM+DS: Reorganized DS handling completely do that multiple regions can be supported
- A region is labeled portion of the mesh which has the same approximation space for the solution. Note that this is NOT the same as the label indicating the support of a field. Regions are the refinement of the field supports into unique approximation space pieces. Right now, we only support a single strategy, namely one space on the regular mesh and one on the hybrid cells, but we only have to change DMCreateDS() to extend the capability.
- Now instead of using PetscDSSetDiscretization() and DMSetDS(), you use DMSetField() and DMCreateDS(). Also, you now must use DMCopyDisc(), instead of DMSetDS(), which copies both the field and DS structure to another DM. These changes have been made in all examples.
- DMGetCellDS() returns the approximation space for that cell
- DMGetDS() return the default space since most people will not use regions. There is still a lot of work left t generalize all methods to multiple DSes, but all old code still functions.
- DMGetRegion/RegionNumDS() gets spaces by label and region number
- DMCreateDS() is the setup method which makes the regions and corresponding DSes. With some work, this could be converted to a lazy initialization.
- Cleaned up access to DS since now we can have more than one
- Projection was improved to extract the DS for the particular cells it is iterating over
- The DS are set from options during Section creation. The idea is that people using DS would also use automatic Section creation, or they would manage things themselves and call SetFromOptions manually.
- I updated the subDM and superDM constructors, but they only work for a single region

show more ...

DM: Reorganized DM fields
- A field is defined by a discretization (PetscFE or PetscFV) and a region (DMLabel or NULL)
- This will feed into the creation of PetscDS for every different cell system
-

DM: Reorganized DM fields
- A field is defined by a discretization (PetscFE or PetscFV) and a region (DMLabel or NULL)
- This will feed into the creation of PetscDS for every different cell system
- Changed interface for Get/SetField to add the region

show more ...

Plex: Bad merge
reported-by: Barry Smith <bsmith@mcs.anl.gov>

Merge remote-tracking branch 'origin/knepley/feature-section-label' into knepley/feature-multiple-ds

* origin/knepley/feature-section-label:
Plex: Changed interface for DMPlexCreateSection() - Now

Merge remote-tracking branch 'origin/knepley/feature-section-label' into knepley/feature-multiple-ds

* origin/knepley/feature-section-label:
Plex: Changed interface for DMPlexCreateSection() - Now get dim and numFields from the DM - Can give a label indicating where a field is supported - Updated use in examples
Plex: Move section calculation into another file

show more ...

Plex: Changed interface for DMPlexCreateSection()
- Now get dim and numFields from the DM
- Can give a label indicating where a field is supported
- Updated use in examples

Plex: Move section calculation into another file