sphere — Generate or plot unit-sphere coordinate grids with MATLAB-compatible sphere syntax.
sphere creates X, Y, and Z coordinate matrices for a unit sphere. With no outputs it renders the sphere in the current axes; with explicit outputs it returns coordinate grids sized (n+1)-by-(n+1), where n is the number of faces per dimension and defaults to 20.
Syntax
sphere()
sphere(n)
X = sphere()
X = sphere(n)
[X,Y] = sphere()
[X,Y] = sphere(n)
[X,Y,Z] = sphere()
[X,Y,Z] = sphere(n)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
n | IntegerScalar | No | 20 | Number of surface faces per dimension; outputs have size (n+1)-by-(n+1). |
Returns
| Name | Type | Description |
|---|---|---|
X | NumericArray | X coordinates on the unit sphere. |
Y | NumericArray | Y coordinates on the unit sphere. |
Z | NumericArray | Z coordinates on the unit sphere. |
Returned values from sphere depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:sphere:OutputCount | More than three outputs are requested. | sphere: too many output arguments; maximum is 3 |
RunMat:sphere:InvalidArgument | More than one input argument is supplied. | sphere: expected zero or one input argument |
RunMat:sphere:InvalidArgument | The n argument is not a finite non-negative integer scalar. | sphere: n must be a finite non-negative integer scalar |
RunMat:sphere:OutOfMemory | The requested coordinate grid is too large for RunMat's bounded allocation policy. | sphere: requested grid is too large |
RunMat:sphere:Internal | Coordinate tensor construction or plotting fails unexpectedly. | sphere: internal operation failed |
How sphere works
sphereandsphere(n)in statement form plot a unit sphere in the current axes.X = sphere(n)returns the X-coordinate grid.[X, Y] = sphere(n)returns the X and Y coordinate grids.[X, Y, Z] = sphere(n)returns all coordinate grids for use withsurf,mesh, or other 3-D plotting functions.- The default grid uses
n = 20, producing 21-by-21 coordinate tensors. nmust be a finite non-negative integer scalar.sphere(0)returns a single unit-sphere point.- Typed integer storage for
nis a RunMat-only extension because the compatibility target specifies an integer value without enumerating storage classes. RunMat decodes it structurally without floating-point conversion.
Does RunMat run sphere on the GPU?
Coordinate generation is CPU-side and deterministic.
The coordinate outputs can be passed to surf(X, Y, Z), which supports full parametric coordinate matrices for this workflow.
GPU memory and residency
sphere returns host tensors. Statement-form rendering builds a host-side 3-D mesh and follows the normal plotting fallback behavior.
Examples
Plot the default unit sphere
sphere;
axis equal;
view(45, 25);Return coordinate grids and plot them manually
[X, Y, Z] = sphere(40);
surf(X, Y, Z);
axis equal;
shading interp;
colormap('parula');Use sphere coordinates in another expression
[X, Y, Z] = sphere(30);
R = sqrt(X.^2 + Y.^2 + Z.^2);
max(abs(R(:) - 1))Using sphere with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how sphere changes the result.
Run a small sphere example, explain the result, then change one input and compare the output.
FAQ
What size are the outputs?⌄
sphere(n) returns coordinate tensors with size (n+1)-by-(n+1). The default sphere uses n = 20, so the default output size is 21-by-21.
How do I get the coordinates without plotting?⌄
Request outputs explicitly, for example [X, Y, Z] = sphere(50). Statement-form calls with no outputs render directly into the current axes.
Does sphere return GPU tensors?⌄
No. sphere constructs host coordinate tensors. Use gpuArray on the outputs if a subsequent numeric pipeline needs GPU residency.
Related Plotting functions
2D Charts
area · bar · errorbar · heatmap · hist · histogram · loglog · pie · plot · scatter · semilogx · semilogy · stairs · stem
Other
addpoints · ancestor · animatedline · axes · barh · caxis · cla · clf · clim · colorcube · colororder · copyobj · daspect · datacursormode · dataTipTextRow · fcontour · figure · fill · fill3 · findobj · fsurf · gobjects · groot · hgload · hgsave · hidden · histogram2 · hold · line · linkaxes · openfig · opengl · pan · parula · patch · plotmatrix · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · stackedplot · subtitle · suptitle · text · textscatter · textscatter3 · triplot · waitbar · wordcloud · xlabel · xlim · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · ylabel · ylim · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zlim · zoom
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how sphere is executed, line by line, in Rust.
- View the source for sphere in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.